fastapi-mcp-router 0.1.0__tar.gz

fastapi_mcp_router-0.1.0/.codannaignore

@@ -0,0 +1,70 @@
+# Codanna ignore patterns (gitignore syntax)
+# https://git-scm.com/docs/gitignore
+#
+# This file tells codanna which files to exclude from indexing.
+# Each line specifies a pattern. Patterns follow the same rules as .gitignore.
+
+# Build artifacts
+target/
+build/
+dist/
+*.o
+*.so
+*.dylib
+*.exe
+*.dll
+
+# Test files (uncomment to exclude tests from indexing)
+# tests/
+# *_test.rs
+# *.test.js
+# *.spec.ts
+# test_*.py
+
+# Temporary files
+*.tmp
+*.temp
+*.bak
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Codanna's own directory
+.codanna/
+
+# Dependency directories
+node_modules/
+vendor/
+.venv/
+venv/
+__pycache__/
+*.egg-info/
+.cargo/
+
+# IDE and editor directories
+.idea/
+.vscode/
+*.iml
+.project
+.classpath
+.settings/
+
+# Documentation (uncomment if you don't want to index docs)
+# docs/
+# *.md
+
+# Generated files
+*.generated.*
+*.auto.*
+*_pb2.py
+*.pb.go
+
+# Version control
+.git/
+.svn/
+.hg/
+
+# Example of including specific files from ignored directories:
+# !target/doc/
+# !vendor/specific-file.rs

fastapi_mcp_router-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,61 @@
+name: Release
+
+on:
+  workflow_dispatch:
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Run tests
+        run: uv run pytest
+
+      - name: Build package
+        run: uv run python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      - name: Create git tag
+        run: |
+          git config --global user.name "github-actions[bot]"
+          git config --global user.email "github-actions[bot]@users.noreply.github.com"
+
+          VERSION=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+
+          if git tag -l "v${VERSION}" | grep -q "v${VERSION}"; then
+            echo "Tag v${VERSION} already exists, skipping"
+          else
+            git tag -a "v${VERSION}" -m "Release v${VERSION}"
+            git push --tags
+          fi
+
+          echo "RELEASE_VERSION=${VERSION}" >> "$GITHUB_ENV"
+
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          if gh release view "v${RELEASE_VERSION}" &>/dev/null; then
+            echo "Release v${RELEASE_VERSION} already exists, skipping"
+          else
+            gh release create "v${RELEASE_VERSION}" \
+              --title "v${RELEASE_VERSION}" \
+              --generate-notes \
+              dist/*
+          fi

fastapi_mcp_router-0.1.0/.gitignore

@@ -0,0 +1,49 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg-info/
+*.egg
+dist/
+build/
+
+# Virtual environments
+.venv/
+venv/
+
+# Testing & coverage
+.coverage
+coverage/
+reports/
+.pytest_cache/
+htmlcov/
+
+# Linting
+.ruff_cache/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Claude Code
+.claude/
+
+# Conduct workflow artifacts
+conduct/
+
+# Code intelligence
+.codanna/
+.fastembed_*
+
+# Generated docs
+ARCHITECTURE.md
+
+# uv lock (library — consumers pin their own deps)
+uv.lock

fastapi_mcp_router-0.1.0/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-03-01
+
+Initial release.
+
+### Added
+
+- `MCPRouter` — `APIRouter` subclass with `@mcp.tool()`, `@mcp.resource()`, `@mcp.prompt()` decorators
+- `create_mcp_router()` factory for external registry composition
+- Full MCP 2025-06-18 protocol coverage (17 methods)
+- Streamable HTTP transport (JSON and SSE responses via `Accept` header)
+- Legacy SSE compatibility via `legacy_sse=True`
+- `MCPToolRegistry` with auto-generated JSON schemas from function signatures
+- FastAPI `Depends()`, `Request`, and `BackgroundTasks` injection in tool handlers
+- `ToolFilter` callback for per-connection tool filtering
+- `ResourceRegistry` with decorator and provider patterns
+- `FileResourceProvider` with path traversal protection and 10 MB size limit
+- `PromptRegistry` with auto-generated argument metadata
+- Streaming tools via `AsyncGenerator` return type
+- `ProgressCallback` injection for long-running tools
+- `SessionStore` ABC with `InMemorySessionStore` and `RedisSessionStore`
+- `SamplingManager` and `RootsManager` for server-to-client requests
+- Resource subscriptions with per-session URI change tracking
+- `auth_validator` callback for API key and Bearer token authentication
+- `create_prm_router()` for OAuth 2.1 Protected Resource Metadata (RFC 9728)
+- `MCPError` (protocol-level) and `ToolError` (LLM-visible) error separation
+- Optional OpenTelemetry spans and counters via `fastapi-mcp-router[otel]`
+- Stateless mode for AWS Lambda deployment via Mangum
+- Documentation: quick start, narrative guide, API reference

fastapi_mcp_router-0.1.0/CLAUDE.md

@@ -0,0 +1,81 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project
+
+fastapi-mcp-router is a lightweight FastAPI integration for the Model Context Protocol (MCP). It exposes MCP tools, resources, and prompts through FastAPI endpoints using decorator-based registration and JSON-RPC 2.0 transport. Supports stateless HTTP (Lambda-compatible) and Streamable HTTP with SSE streaming.
+
+## Commands
+
+```bash
+# Run all tests (includes coverage, enforces 80% minimum)
+uv run pytest
+
+# Run a single test
+uv run pytest tests/test_registry.py::test_register_tool_default_name -v
+
+# Run tests by marker
+uv run pytest -m unit
+uv run pytest -m integration
+
+# Run tests without coverage (faster iteration)
+uv run pytest --no-cov
+
+# Build package
+uv run python -m build
+```
+
+No separate lint or format commands are configured. No Makefile exists. The venv is managed by `uv` — use `uv run` to execute commands.
+
+## Architecture
+
+The package has 10 modules across 5,909 LOC with this dependency flow:
+
+```
+router.py → registry.py → exceptions.py
+    ↓            ↓
+protocol.py   types.py
+    ↓
+telemetry.py (leaf, zero internal imports)
+    ↓
+session.py, resources.py, prompts.py
+```
+
+**router.py** — `create_mcp_router()` factory and `MCPRouter` class. Handles 17 MCP methods. Streamable HTTP POST returns `JSONResponse` or `StreamingResponse` based on `Accept` header. `legacy_sse=True` registers GET endpoint for backward compatibility. OTel instrumentation via `telemetry.py`.
+
+**registry.py** — `MCPToolRegistry` stores tool definitions registered via `@registry.tool()` decorator. Auto-generates JSON schemas from function signatures using Pydantic `TypeAdapter`. Filters out FastAPI `Depends()`, `Request`, and `BackgroundTasks` parameters from schemas.
+
+**telemetry.py** — Leaf module with zero internal imports. Wraps optional `opentelemetry-api` behind try/except ImportError. Exports `get_tracer()` and `get_meter()`.
+
+**protocol.py** — Pure functions for formatting JSON-RPC 2.0 responses and errors.
+
+**types.py** — Pydantic models: `TextContent`, `ToolResponse`, `ServerInfo`, `ServerIcon`, `McpSessionData`.
+
+**exceptions.py** — `MCPError` (protocol-level, JSON-RPC error codes -32700 to -32603) vs `ToolError` (business logic, returns `isError: true` so LLM can recover).
+
+**session.py** — `SessionStore` ABC, `InMemorySessionStore`, `RedisSessionStore`, `SamplingManager`, `RootsManager`.
+
+**resources.py** — `ResourceRegistry`, `ResourceProvider` ABC, `FileResourceProvider`.
+
+**prompts.py** — `PromptRegistry` with auto-generated argument metadata.
+
+## Key Patterns
+
+- Streamable HTTP: POST with `Accept: text/event-stream` returns `StreamingResponse`; without returns `JSONResponse`.
+- `legacy_sse=True` registers SSE GET endpoint alongside Streamable HTTP POST. Default is `False`.
+- All JSON-RPC responses use HTTP 200. Errors are at the protocol level, not HTTP status codes.
+- Tool handlers can be sync or async. Registry detects and handles both.
+- `ToolFilter` callback enables per-connection tool filtering (e.g., OAuth vs API key scopes).
+- Auth validation uses `auth_validator` callback passed to `create_mcp_router()`.
+- Protocol versions supported: `2025-06-18` (primary), `2025-03-26` (fallback).
+- Public API is defined in `__init__.py` via `__all__` (17 exports).
+- OTel tracing is optional: `enable_telemetry=True` (default) emits spans when `opentelemetry-api` is installed. Install via `pip install fastapi-mcp-router[otel]`.
+
+## Testing
+
+- 544 tests across 33 files using pytest + pytest-asyncio.
+- Integration tests use `httpx.AsyncClient` with FastAPI `TestClient`.
+- Tests use `@pytest.mark.unit` and `@pytest.mark.integration` markers.
+- Async test functions use explicit `@pytest.mark.asyncio` decorator (`asyncio_mode = "auto"` is NOT configured).
+- Key test files: `test_streamable_http.py` (Streamable HTTP transport), `test_telemetry.py` (OTel), `test_sse_streaming.py` (legacy SSE).

fastapi_mcp_router-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andre Bremer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fastapi_mcp_router-0.1.0/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: fastapi-mcp-router
+Version: 0.1.0
+Summary: Lightweight FastAPI integration for Model Context Protocol (MCP)
+Project-URL: Homepage, https://github.com/rcrsr/fastapi-mcp-router
+Project-URL: Repository, https://github.com/rcrsr/fastapi-mcp-router
+Project-URL: Issues, https://github.com/rcrsr/fastapi-mcp-router/issues
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,fastapi,llm,mcp,model-context-protocol
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: fastapi>=0.134.0
+Requires-Dist: pydantic>=2.12.5
+Provides-Extra: dev
+Requires-Dist: build>=1.4.0; extra == 'dev'
+Requires-Dist: httpx>=0.28.1; extra == 'dev'
+Requires-Dist: pytest-asyncio>=1.3.0; extra == 'dev'
+Requires-Dist: pytest-cov>=7.0.0; extra == 'dev'
+Requires-Dist: pytest>=9.0.2; extra == 'dev'
+Requires-Dist: ruff>=0.15.4; extra == 'dev'
+Requires-Dist: twine>=6.2.0; extra == 'dev'
+Requires-Dist: ty>=0.0.19; extra == 'dev'
+Provides-Extra: otel
+Requires-Dist: opentelemetry-api>=1.0; extra == 'otel'
+Description-Content-Type: text/markdown
+
+# fastapi-mcp-router
+
+Add MCP to your existing FastAPI app. Register tools, resources, and prompts with decorators. Use `Depends()`, `Request`, and `BackgroundTasks` the same way you already do.
+
+## Why fastapi-mcp-router
+
+- **It's just an `APIRouter`.** Mount it like any other router. No separate framework, no new server process.
+- **Your DI still works.** `Depends()`, `Request`, `BackgroundTasks` — same patterns, same middleware.
+- **2 dependencies.** FastAPI and Pydantic. Nothing else.
+- **No lock-in.** Tools are regular async functions. Call them from tests, CLI scripts, or other endpoints without MCP.
+- **Lambda-ready.** Stateless mode + Mangum. No adapter layer.
+
+**Use FastMCP instead** if you need STDIO transport, OpenAPI spec imports, or managed hosting.
+
+## Install
+
+```bash
+pip install fastapi-mcp-router
+```
+
+## Quick Start
+
+```python
+from fastapi import FastAPI
+from fastapi_mcp_router import MCPRouter
+
+app = FastAPI()
+mcp = MCPRouter()
+
+@mcp.tool()
+async def write_message(payload: str) -> dict:
+    """Write coordination message."""
+    return {"success": True, "message_id": "msg-123"}
+
+@mcp.resource("project://{project_id}/config")
+async def project_config(project_id: str) -> dict:
+    return {"project_id": project_id, "env": "production"}
+
+@mcp.prompt()
+async def review_code(file_path: str, language: str = "python") -> list[dict]:
+    return [{"role": "user", "content": f"Review {file_path} ({language})"}]
+
+app.include_router(mcp, prefix="/mcp")
+```
+
+That's it. Your FastAPI app now speaks MCP over Streamable HTTP.
+
+## What You Get
+
+- **Full MCP 2025-06-18 spec** — tools, resources, prompts, sampling, logging, completions, elicitation
+- **Streamable HTTP** — JSON or SSE response based on `Accept` header
+- **Streaming tools** — return `AsyncGenerator` for incremental results
+- **Session management** — in-memory and Redis stores for stateful connections
+- **Progress reporting** — inject `ProgressCallback` into tool signatures
+- **Auth** — `auth_validator` callback + OAuth 2.1 PRM (RFC 9728)
+- **OpenTelemetry** — opt-in spans and counters via `pip install fastapi-mcp-router[otel]`
+- **Lambda-ready** — stateless mode works with Mangum, no adapter overhead
+
+## Documentation
+
+- [Quick Start](docs/quickstart.md) — installation, first tool, stateful mode, auth, Lambda
+- [Guide](docs/guide.md) — resources, prompts, streaming, sessions, telemetry
+- [API Reference](docs/reference.md) — all exports, types, and configuration options
+
+## License
+
+MIT

fastapi_mcp_router-0.1.0/README.md

@@ -0,0 +1,67 @@
+# fastapi-mcp-router
+
+Add MCP to your existing FastAPI app. Register tools, resources, and prompts with decorators. Use `Depends()`, `Request`, and `BackgroundTasks` the same way you already do.
+
+## Why fastapi-mcp-router
+
+- **It's just an `APIRouter`.** Mount it like any other router. No separate framework, no new server process.
+- **Your DI still works.** `Depends()`, `Request`, `BackgroundTasks` — same patterns, same middleware.
+- **2 dependencies.** FastAPI and Pydantic. Nothing else.
+- **No lock-in.** Tools are regular async functions. Call them from tests, CLI scripts, or other endpoints without MCP.
+- **Lambda-ready.** Stateless mode + Mangum. No adapter layer.
+
+**Use FastMCP instead** if you need STDIO transport, OpenAPI spec imports, or managed hosting.
+
+## Install
+
+```bash
+pip install fastapi-mcp-router
+```
+
+## Quick Start
+
+```python
+from fastapi import FastAPI
+from fastapi_mcp_router import MCPRouter
+
+app = FastAPI()
+mcp = MCPRouter()
+
+@mcp.tool()
+async def write_message(payload: str) -> dict:
+    """Write coordination message."""
+    return {"success": True, "message_id": "msg-123"}
+
+@mcp.resource("project://{project_id}/config")
+async def project_config(project_id: str) -> dict:
+    return {"project_id": project_id, "env": "production"}
+
+@mcp.prompt()
+async def review_code(file_path: str, language: str = "python") -> list[dict]:
+    return [{"role": "user", "content": f"Review {file_path} ({language})"}]
+
+app.include_router(mcp, prefix="/mcp")
+```
+
+That's it. Your FastAPI app now speaks MCP over Streamable HTTP.
+
+## What You Get
+
+- **Full MCP 2025-06-18 spec** — tools, resources, prompts, sampling, logging, completions, elicitation
+- **Streamable HTTP** — JSON or SSE response based on `Accept` header
+- **Streaming tools** — return `AsyncGenerator` for incremental results
+- **Session management** — in-memory and Redis stores for stateful connections
+- **Progress reporting** — inject `ProgressCallback` into tool signatures
+- **Auth** — `auth_validator` callback + OAuth 2.1 PRM (RFC 9728)
+- **OpenTelemetry** — opt-in spans and counters via `pip install fastapi-mcp-router[otel]`
+- **Lambda-ready** — stateless mode works with Mangum, no adapter overhead
+
+## Documentation
+
+- [Quick Start](docs/quickstart.md) — installation, first tool, stateful mode, auth, Lambda
+- [Guide](docs/guide.md) — resources, prompts, streaming, sessions, telemetry
+- [API Reference](docs/reference.md) — all exports, types, and configuration options
+
+## License
+
+MIT