# FastAPI → Hyperia Bridge

Transform any **FastAPI** application into a live **Hyperia MCP server** with a single call—unlocking LLM‑ready tools and resources while preserving your existing Python business logic.

> **Prerequisite**  Install FastAPI & an ASGI runtime: `pip install fastapi uvicorn[standard]`.

***

### 1  Hello‑World Conversion

```python
from fastapi import FastAPI
from hyperia import Hyperia

api = FastAPI()

@api.get("/ping")
def ping():
    return {"pong": True}

mcp = Hyperia.from_fastapi(app=api, name="PingAPI")

if __name__ == "__main__":
    mcp.run(transport="streamable-http", port=9100)
```

Now any Hyperia client (or Claude Desktop) can `read_resource("resource://ping")`.

***

### 2  How the Converter Works

1. **Inspects** the FastAPI app’s router (`app.openapi()` behind the scenes).
2. Applies **route‑mapping** rules (see §3).
3. Builds wrappers that:
   * Extract path/query/body args from the MCP call.
   * Invoke the FastAPI dependency graph (including `Depends`, auth, middle‑ ware).
   * Serialise the Starlette `Response` → MCP contents.
4. Registers the new callable with the Hyperia server.

> Because we bypass the network, calls execute **in‑process** with the same Python interpreter—zero HTTP overhead.

***

### 3  Default Route Mapping

| FastAPI Decorator                     | Example               | Hyperia Component    | Name / URI result                 |
| ------------------------------------- | --------------------- | -------------------- | --------------------------------- |
| `@api.get("/stats")`                  | no params             | **Resource**         | `resource://stats`                |
| `@api.get("/users/{id}")`             | has path param        | **ResourceTemplate** | `users://{id}`                    |
| any non‑GET (`post/put/patch/delete`) | `@api.post("/users")` | **Tool**             | `createUser` (from op id or path) |

Customise with `route_maps` (same structure as OpenAPI integration):

```python
from hyperia.server.openapi import RouteMap, RouteType
maps = [RouteMap(methods=["GET"], pattern=r"^/export/.*", route_type=RouteType.TOOL)]

mcp = Hyperia.from_fastapi(app, route_maps=maps)
```

**all\_routes\_as\_tools=True** forces everything to be a Tool—nice for agent back‑ends.

***

### 4  Timeout & Concurrency Control

```python
mcp = Hyperia.from_fastapi(app, timeout=4.0, max_concurrency=50)
```

* `timeout` – per‑request ceiling (seconds) for tool/resource execution.
* `max_concurrency` – semaphore protecting the underlying FastAPI app when hit via MCP (does *not* affect external HTTP calls to the same FastAPI app).

***

### 5  Advanced Examples

#### 5.1  CRUD Service with Pydantic Models

```python
from pydantic import BaseModel
from fastapi import FastAPI, HTTPException
from hyperia import Hyperia

class Item(BaseModel): name: str; price: float
api = FastAPI(); db: dict[int, Item] = {}

@api.get("/items", response_model=list[Item])
def list_items(): return list(db.values())

@api.post("/items", response_model=Item, status_code=201)
def new(item: Item):
    idx = len(db)+1; db[idx] = item; return item

@api.get("/items/{idx}")
def get(idx: int):
    if idx not in db: raise HTTPException(404)
    return db[idx]

mcp = Hyperia.from_fastapi(api, name="Shop")
```

Generated components:

* **Tool** `new` (calls POST /items)
* **Resource** `items` (GET /items)
* **Template** `items://{idx}` (GET /items/{idx})

#### 5.2  Streaming Responses

FastAPI `StreamingResponse` → Hyperia **chunked** `TextContent`. Supports SSE or incremental JSON.

#### 5.3  Auth Propagation

If your FastAPI endpoints use `Depends(get_current_user)`, they still work—Hyperia just runs the dependency call chain.

For agent scenarios supply a *dummy* user via `DependencyOverrides` before wrapping:

```python
api.dependency_overrides[get_current_user] = lambda: User(id=1, name="agent")
```

***

### 6  Why Use FastAPI→Hyperia Instead of OpenAPI→Hyperia?

| Criteria                            | FastAPI wrapper | OpenAPI wrapper   |
| ----------------------------------- | --------------- | ----------------- |
| Same‑process calls                  | ✔               | ✖ (HTTP)          |
| Re‑use FastAPI dependencies & state | ✔               | ✖                 |
| No existing spec file               | ✔               | ✖                 |
| You only have OpenAPI description   | ✖               | ✔                 |
| Need multi‑language SDKs            | ✖               | ✔ (just use spec) |

You can even **combine**: expose some endpoints through HTTP (OpenAPI) and mount a FastAPI‑wrapped MCP for internal operations.

***

### 7  Limitations & Caveats

* FastAPI middlewares that modify the *raw* ASGI send/receive flow (e.g. WebSocket) are ignored for MCP calls.
* Background tasks run inside the MCP event‑loop—monitor memory.
* Proprietary Response classes (FileResponse, RedirectResponse) map to simple `TextContent` with their `.body` string or URL.
* Multipart form file uploads require the client to supply base64 blobs; binary passthrough coming in v2.6.

***

### 8  Troubleshooting

| Symptom                               | Cause                                         | Fix                                                        |
| ------------------------------------- | --------------------------------------------- | ---------------------------------------------------------- |
| `RuntimeError: FastAPI not installed` | dependency missing                            | `pip install fastapi`                                      |
| 422 errors when tool called           | Validation failed on pydantic model           | check arg names & types; they must match FastAPI signature |
| Tool returns `null`                   | Endpoint returned `Response(status_code=204)` | Upgrade to v2.5 (maps 204 → empty list)                    |


---

# 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/extend-hyperia-protocol/fastapi-hyperia-bridge.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.