AI导哈

REST与MCP后端模板

一个提供REST端点和MCP（模型上下文协议）工具访问的后端模板，适用于需要同时支持人类/API客户端和代理访问的服务。

  • by BeaverHouse
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 BeaverHouse/mcp-rest-sample

使用说明

FastAPI backend template with MCP Streamable HTTP.

描述

此存储库是一个小型后端模板，用于需要以下两者的服务：

  • 通过REST端点的人工/API-客户端访问
  • 通过MCP（模型上下文协议）工具、资源和提示进行代理访问

该应用程序通过两个表面暴露一个模拟域：

  • 休息： /health, /projects, /projects/{project_id}、票务分流、放行通知
  • MCP： /mcp 使用Streamable HTTP，并使用匹配的项目/工单工具和资源

模拟数据有意存储在内存中。仅在REST之后添加数据库 MCP边界清晰。

MCP状态

此模板针对MCP Python SDK v2测试版和 2026-07-28发布候选方向这意味着：

  • 流式HTTP是主要的传输方式。
  • /mcp 在这个示例中是无状态HTTP。
  • SDK版本被固定，因为v2仍然是预发布版本。
  • 这是一个模板和学习示例，而不是生产MCP兼容性声明。

身份验证发现

此示例不实现OAuth或OpenID连接发现。一些MCP 客户可能会进行调查 .well-known 调用前的URL /mcp例如：

  • /.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 在这个本地样本中。这是预料之中的 只要JSON-RPC请求 /mcp 返回 200 OK 或 202 Accepted.

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

  • MCP资源服务器的OAuth 2.0受保护资源元数据。
  • 授权服务器元数据或记录在案的外部授权服务器。
  • WWW-Authenticate 页眉打开 401 Unauthorized 指向客户的响应 到受保护的资源元数据。
  • 对每个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 作为现代依赖健康命令运行 锁文件。保持可见，但要注意上游咨询的可用性和 当前紫外线释放状态作为操作背景。

关键注意事项

  • 保持REST/MCP层的精简：验证传输输入、调用内部逻辑、返回类型化模型。
  • 当你为不可逆转或破坏性的行为制作MCP时，要小心。
  • 将身份验证、数据库、后台工作和外部客户端添加为单独的层。

相关 MCP