fastapi-gql-mcp vs fastapi-mcp

0 · 三十秒结论

1 · 架构对照

flowchart LR
  A[FastAPI app] -->|"get_openapi()"| O[OpenAPI schema]
  O -->|每个 operation 一个工具| T["N 个工具
(name = operationId)"]
  T --> C1[工具调用 1]
  T --> C2[工具调用 2]
  T --> C3[工具调用 3]
  C1 -.->|还原 HTTP 请求
ASGI 进程内| A
  C2 -.-> A
  C3 -.-> A
      

flowchart LR
  A[FastAPI app] -->|tag 域树 + 函数名字段| G[GraphQL schema SDL]
  G --> T["固定 2–6 个工具
get_schema / graphql_query
graphql_mutation / 渐进式发现"]
  T -->|一次组合查询| Q["{ a… b… c… }
多域多字段"]
  Q -->|GraphQL 执行| A
  G --> H["GraphiQL + POST /graphql
同一 schema 服务人类"]
      

2 · 上下文经济性（核心分水岭）

agent 可用之前必须吞下「它有什么可调」。测法：tools/list 载荷 JSON 字节（fastapi-gql-mcp 另计 get_schema 的 SDL， 渐进式另计单域发现路径全程），token 估算 = 字节 ÷ 4。

3 · 组合与往返（agent 真实的成本单位）

响应体积：字段投影

4 · 延迟（进程内微基准，200 次迭代）

5 · 错误语义：整调用失败 vs 字段级隔离

同一场景：一次请求里既有好数据（stats）又有坏请求（不存在的 note 9999）。

❌ Error calling get_note_api_notes__note_id__get.
   Status code: 404.
   Response: {"detail":"note not found"}

— 整个工具调用标记为错误；
— 想拿 stats 需要再发一次调用；
— 失败原因与结果混在一行文本里。

✅ {
  "data": {
    "meta":  { "stats": { "notes": 20 } },   ← 好数据照常返回
    "notes": { "mine": { "get_note": null } } ← 坏字段置空
  },
  "errors": [{
    "message": "GET /api/notes/{note_id} -> 404: …",
    "path": ["notes","mine","get_note"],
    "extensions": { "code": "HTTP_404",
                    "http_status": 404 }     ← 结构化错误码
  }]
}

6 · 契约保真：同一个 list_notes，agent 看到什么

type NotesMineQuery {
  """
  List YOUR notes.

  ``q`` filters by substring over title and body.
  """
  list_notes(
    """substring over title/body"""
    q: String = null
    active: Boolean = true
  ): [NoteOut!]

  """Fetch one of YOUR notes by id."""
  get_note(note_id: Int!): NoteOut
}

"""A note owned by the logged-in user."""
type NoteOut { … }   ← 类型只定义一次，处处复用

List Notes

List YOUR notes.

``q`` filters by substring over title and body.

### Responses:
**200**: Successful Response
Content-Type: application/json

**Example Response:**
```json
[{"id":1,"title":"Title","body":"Body","owner":"Owner"}]
```

inputSchema: { "properties": { "q": {"type":"string", …},
  "active": {"type":"boolean"} }, … }
— NoteOut 的形状在每个相关工具里以示例形式重复出现

7 · 能力矩阵

8 · 认证模型对照

9 · 生态与工程化

10 · 规范演进：MCP 的 lazy 机制与本对照的关系

2026-10 核实 · 依据本地 mcp SDK 2.3.0 内嵌协议类型（最新修订 2026-07-28）+ 生态检索。 "lazy 省 context"常被混为一谈，实际分四层：

11 · 选型建议

· API 小（~10 端点内）且稳定
· 只给 agent 用，没有组合查询需求
· 想零配置最快接入（pip install 即用）
· 认证已有 FastAPI Depends 兜底
· 需要 stdio / 分离部署形态

· API 会长大（上下文预算随规模恒定）
· agent 需要一次拿到组合视图（省轮次）
· 需要字段投影控制响应体积
· 需要细粒度写操作门禁
· 需要 OAuth 登录的完整体验（consent/PKCE/端点门禁）
· 顺便想让人类也用 GraphQL（GraphiQL）

12 · 方法与复现

Comparison/bench/
├── shared_app.py     # 同一 notes 应用（5 业务端点 + 可扩容 filler），接入两个框架 —— 桥接代码本体
├── env_ours/         # fastapi-gql-mcp[mcp] 环境（fastmcp 4 / mcp 2）
├── env_theirs/       # fastapi-mcp 环境（mcp 钉 <2 才能运行）
├── run_ours.py       # 本库侧测量 → results_ours.json
├── run_theirs.py     # fastapi-mcp 侧测量 → results_theirs.json
├── merge_results.py  # 合并 → results.json
└── results.json      # 本报告全部数字的来源

复现：gh repo clone tadata-org/fastapi_mcp ../fastapi-mcp   # 前提：对照组源码克隆在本仓库旁
      cd Comparison/bench
      uv run --project env_ours   python run_ours.py
      uv run --project env_theirs python run_theirs.py
      python3 merge_results.py

测量口径：工具目录 = tools/list 载荷 JSON 字节；token 估算 = 字节÷4；延迟为进程内内存会话（无网络）， 本库侧用 fastmcp Client、对方用 mcp SDK ClientSession（各自原生客户端栈）； 延迟数字的绝对值受本机状态影响，相对关系（≈0.5ms 差距）稳定。