# 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).