# Hyperia Protocol Overview

## Welcome to **Hyperia Protocol**

**Hyperia** is the fast, Pythonic way to build Model Context Protocol (MCP) servers and clients.

MCP is a new, standardized method for supplying context, data, and tools to large‑language models. **Hyperia** removes the boilerplate: create tools, expose resources, define prompts, and more with clean, readable Python.

```python
from hyperia import Hyperia

mcp = Hyperia("Demo 🚀")

@mcp.tool()
def add(a: int, b: int) -> int:
    """Add two numbers"""
    return a + b

if __name__ == "__main__":
    mcp.run()
```

***

## Hyperia Protocol & the Official MCP SDK

Two pillars, one ecosystem.

|                     | **Hyperia Protocol**                                                                             | **Official MCP SDK**                                                                  |
| ------------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------- |
| Maintainer          | Hyperia Labs Inc.                                                                                | MCP Foundation (spec reference impl)                                                  |
| Primary Goal        | *Developer ergonomics* – rapid, high‑level binding of existing code, APIs, and data into MCP.    | *Specification fidelity* – low‑level, one‑to‑one mapping of the core MCP wire format. |
| Abstraction Level   | High: decorators, automatic route mapping, generators (OpenAPI, FastAPI, SQLAlchemy, etc.).      | Low: you implement message handlers, transports, serialization manually.              |
| Performance Focus   | Async, zero‑copy in‑process calls; optional HTTP layer.                                          | Reference‑grade correctness, not optimised.                                           |
| Extra Capabilities: | Progress events                                                                                  |                                                                                       |
|                     | Chunk streaming                                                                                  |                                                                                       |
|                     | Auto‑retry/back‑off                                                                              |                                                                                       |
|                     | Codecs registry                                                                                  |                                                                                       |
|                     | Proxy & composition helpers                                                                      |                                                                                       |
|                     | ASGI/Starlette adapters                                                                          | Minimal extras (kept generic to remain specification neutral).                        |
| Ideal Users         | Product teams, ML engineers, plugin authors needing to expose back‑ends to LLMs fast.            | Researchers, alt‑language ports, edge cases needing full control.                     |
| Inter‑operability   | 100% wire‑compatible – Hyperia servers & clients speak the exact MCP frames defined by the spec. | N/A                                                                                   |

***

### How They Work Together

* **Hyperia ≈ "Rails"**, Official SDK ≈ "C library". Both compile to the same MCP bytes.
* Hyperia actually **contributes** upstream: several transport & context improvements first landed here, then merged into SDK v1.6.
* You can **mix**: implement a custom component in raw SDK and mount it into a Hyperia server, or proxy an SDK server behind Hyperia’s richer transports.

```mermaid
graph LR
    subgraph Raw SDK Server
        A[tools/call handler]<--MCP-->B(Hyperia Proxy)
    end
    B-->C(Client Apps)
```

***

### Migration Path

| Scenario                                                                                     | Recommendation                                                           |
| -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| New project, wants speed                                                                     | **Start with Hyperia**; drop to SDK only for exotic needs.               |
| Existing SDK 1.x server                                                                      | `pip install hyperia` → `from hyperia import Hyperia as mcp`             |
| Swap imports or proxy via `Hyperia.as_proxy(sdk_server)` to gain progress/logging instantly. |                                                                          |
| Contributing to the spec                                                                     | Prototype in Hyperia (faster dev cycle), then port minimal patch to SDK. |

***

### Version Sync Table

| MCP Spec Date       | Official SDK | Hyperia Tag | Notes                           |
| ------------------- | ------------ | ----------- | ------------------------------- |
| 2025‑03‑26 (latest) | 1.9.0        | 2.4.0       | OAuth 2.1 auth, chunk streaming |
| 2024‑11‑05          | 1.7.1        | 2.2.3       | Wildcard resource templates     |
| 2024‑07‑18          | 1.6.0        | 2.0.0       | Initial sync; Hyperia born      |

Hyperia tracks spec releases within **72 h**; patch versions follow semver.

***

### Choosing One (or Both)

> *If you crave control ➜ official SDK. If you crave velocity ➜ Hyperia.* Most teams end up using **both**: Hyperia for day‑to‑day features, raw SDK for critical, performance‑tuned modules.

***

### `llms.txt`

This documentation is also distributed in **llms.txt** format—a lightweight Markdown profile that LLMs can ingest directly.

* **`llms.txt`**  – a sitemap of every page.
* **`llms-full.txt`**  – the complete docs in a single file (may exceed some model context windows).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.hyperiaprotocol.io/get-started/hyperia-protocol-overview.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.