Mcp Rest Sample

使用 MCP Streamable HTTP 的 FastAPI 后端模板。

描述

此仓库是一个小型后端模板，适用于同时需要以下能力的服务：

• 通过 REST 端点供人员和 API 客户端访问
• 通过 MCP（Model Context Protocol）工具、资源和提示词供 Agent 访问

此应用通过两种接口暴露一个模拟领域：

• REST：/health、/projects、/projects/{project_id}、工单分流、发布说明
• MCP：使用 Streamable HTTP 的 /mcp，提供对应的项目和工单工具及资源

模拟数据有意保存在内存中。只有在明确 REST 和 MCP 的边界后，才添加数据库。

MCP 状态

此模板面向 MCP Python SDK v2 beta 版，以及 2026-07-28 发布候选版的方向。这意味着：

• Streamable HTTP 是主要传输方式。
• 在此示例中，/mcp 使用无状态 HTTP。
• SDK 版本被精确锁定，因为 v2 仍是预发布版本。
• 这是一个模板和学习示例，并不声称可在生产环境中兼容 MCP。

身份验证发现

此示例未实现 OAuth 或 OpenID Connect 发现。某些 MCP 客户端可能会在调用 /mcp 前探测 .well-known URL，例如：

• /.well-known/oauth-protected-resource/mcp
• /mcp/.well-known/oauth-protected-resource
• /.well-known/oauth-authorization-server/mcp
• /.well-known/openid-configuration/mcp

在此本地示例中，这些请求可能会返回 404 Not Found。只要发往 /mcp 的 JSON-RPC 请求返回 200 OK 或 202 Accepted，这种情况就是预期行为。

要将其改造为经过身份验证的 HTTP MCP 服务，请添加：

• 针对 MCP 资源服务的 OAuth 2.0 受保护资源元数据。
• 授权服务元数据，或有文档说明的外部授权服务。
• 在 401 Unauthorized 响应中添加 WWW-Authenticate 标头，引导客户端访问受保护资源元数据。
• 对每个 MCP HTTP 请求验证持有者令牌，包括受众检查，以确保令牌的作用范围限定于此 MCP 服务。
• 针对匿名访问、无效令牌、有效令牌、元数据发现和令牌受众验证失败编写测试。

目录结构

app/
  main.py              # FastAPI app and /mcp route wiring
  mcp_server.py        # MCP tools, resources, prompts
  schemas.py           # Pydantic request/response models
  config.py            # pydantic-settings config
  internal/
    catalog.py         # mock domain logic
  routers/
    health.py
    projects.py
  tests/

本地运行

cd app
uv sync --python 3.14 --prerelease allow
uv run uvicorn main:app --reload --host 127.0.0.1 --port 8001

打开：

• REST 文档：http://127.0.0.1:8001/docs
• MCP 端点：http://127.0.0.1:8001/mcp

检查

使用 uv 直接运行公开检查：

cd app
uv run ruff check .
uv run ruff format --check .
uv run mypy .
uv run pytest
uv audit

uv audit 是用于检查锁文件依赖健康状况的现代命令。请保留此命令，但应将上游安全公告的可用性和当前 uv 版本状态视为运行环境背景信息。

关键说明

• 保持 REST/MCP 层精简：验证传输输入，调用内部逻辑，返回类型化模型。
• 创建用于不可逆或破坏性操作的 MCP 工具时务必谨慎。
• 将身份验证、数据库、后台工作和外部客户端作为独立层添加。