fastapi-gql-mcp 0.4.0__tar.gz

fastapi_gql_mcp-0.4.0/.github/workflows/ci-skip.yml

@@ -0,0 +1,26 @@
+# Companion to ci.yml. The real CI is path-filtered, so a PR that changes
+# only non-code files (README, CHANGELOG, Comparison, etc.) skips ci.yml
+# entirely — leaving the required "CI All Green" check stuck in "Expected"
+# forever and blocking the PR. This workflow runs on the INVERSE path filter
+# and reports the same "CI All Green" check as passing, so such PRs can
+# merge. On a mixed PR both workflows run; both report green, and a real
+# failure still fails the same-named check, so nothing is masked.
+name: Test
+
+on:
+  pull_request:
+    paths-ignore:
+      - 'src/fastapi_gql_mcp/**'
+      - 'tests/**'
+      - 'demo/**'
+      - 'examples/**'
+      - 'pyproject.toml'
+      - 'uv.lock'
+
+jobs:
+  ci-all-green:
+    name: CI All Green
+    runs-on: ubuntu-latest
+    steps:
+      - name: No code paths changed
+        run: echo "No code paths changed — real CI skipped; reporting green."

fastapi_gql_mcp-0.4.0/.github/workflows/ci.yml

@@ -0,0 +1,107 @@
+name: Test
+
+on:
+  pull_request:
+    paths:
+      - 'src/fastapi_gql_mcp/**'
+      - 'tests/**'
+      - 'demo/**'
+      - 'examples/**'
+      - 'pyproject.toml'
+      - 'uv.lock'
+  push:
+    branches: [master]
+    paths:
+      - 'src/fastapi_gql_mcp/**'
+      - 'tests/**'
+      - 'demo/**'
+      - 'examples/**'
+      - 'pyproject.toml'
+      - 'uv.lock'
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      # One version failing must not cancel the others: a canceled job shows
+      # as failed even when its tests passed (observed: 3.13 finished green,
+      # then got canceled by 3.10's failure with fail-fast's default true).
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Run linter
+        run: uv run ruff check src tests
+
+      - name: Run type checker
+        run: uv run mypy src
+
+      - name: Test with pytest
+        run: uv run pytest tests/ -v
+
+  # Guards the demo (and examples' syntax) against framework API drift. The
+  # demo is the framework's first real consumer; if a public API is renamed or
+  # removed, this job fails on the PR instead of shipping a demo that only
+  # breaks at run time. Critical: uv sync installs the WORKING-COPY framework
+  # (editable), so the demo is verified against the code in this PR — not the
+  # PyPI release. examples/notes_oauth is a standalone project with its own
+  # dependency set, so it is guarded here by compileall (syntax) and by
+  # tests/test_example_public_api.py in the test job (public-API-only imports).
+  demo-guard:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Install working-copy framework + extras
+        run: uv sync --all-extras
+
+      - name: Demo app builds against working-copy framework
+        run: |
+          uv run python -c "import demo.app; print(f'demo builds: {len(demo.app.app.routes)} routes')"
+
+      - name: Compile all example sources
+        run: uv run python -m compileall -q examples
+
+  # Single required-status gate. Branch protection should require this ONE
+  # check ("CI All Green") instead of each job (the matrix makes per-job names
+  # awkward). It aggregates the real jobs and fails if any did not succeed.
+  # A mirror job of the same name lives in ci-skip.yml: when a PR touches no
+  # code paths this workflow is skipped entirely, so the mirror reports the
+  # same check as green and docs-only PRs are never blocked on a check that
+  # path filtering skipped.
+  ci-all-green:
+    name: CI All Green
+    if: always()
+    needs: [test, demo-guard]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Verify required jobs succeeded
+        run: |
+          echo "test=${{ needs.test.result }} demo-guard=${{ needs.demo-guard.result }}"
+          [ "${{ needs.test.result }}" = "success" ] && [ "${{ needs.demo-guard.result }}" = "success" ]

fastapi_gql_mcp-0.4.0/.github/workflows/gh-pages.yml

@@ -0,0 +1,42 @@
+# Deploys the Comparison page (benchmark visualizations) as a static GitHub
+# Pages site. nexusx deploys mkdocs docs the same way; here the "site" is a
+# single self-contained Comparison/index.html, so the native Pages actions
+# are enough — no build step. Requires Pages enabled in repo settings with
+# source "GitHub Actions".
+name: GH Pages Deploy
+
+on:
+  push:
+    branches: [master]
+    paths:
+      - 'Comparison/**'
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Configure Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload Comparison page
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: Comparison
+
+      - name: Deploy
+        id: deployment
+        uses: actions/deploy-pages@v4

fastapi_gql_mcp-0.4.0/.github/workflows/publish.yml

@@ -0,0 +1,41 @@
+name: Publish to PyPI via uv
+
+on:
+  workflow_dispatch:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v5
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+
+      - name: Build the package
+        run: uv build
+
+      - name: Publish to PyPI
+        run: uv publish --token ${{ secrets.PYPI_PUBLISHER }}
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          body: See [CHANGELOG](https://github.com/klr-pattern/fastapi-gql-mcp/blob/master/CHANGELOG.md) for details.
+          generate_release_notes: true
+          files: |
+            dist/*.tar.gz
+            dist/*.whl

fastapi_gql_mcp-0.4.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.pyc
+.venv/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+dist/
+.DS_Store
+.claude/
+
+# consumer example: local env + resolved lock stay untracked
+examples/*/.env
+examples/*/uv.lock
+examples/*/.venv/
+Comparison/bench/*/uv.lock

fastapi_gql_mcp-0.4.0/CHANGELOG.md

@@ -0,0 +1,262 @@
+# Changelog
+
+## 0.4.0 (2026-10-04)
+
+### Added
+
+- **Observability (OpenTelemetry), one waterfall per query**: the bridge
+  injects W3C trace context (`traceparent`/`tracestate`/`baggage`) into
+  every in-process route call — bridge-generated, so it flows regardless of
+  `passthrough_headers`, and is a no-op without an SDK (new core dependency
+  `opentelemetry-api`, non-recording by default). A `graphql.execute` span
+  covers the GraphQL orchestration layer; route-call timeouts and
+  concurrency queue waits surface as span events (`route.timeout`,
+  `route.queue`). With fastmcp's tool spans and FastAPI >= 0.142's native
+  route spans, one MCP query now lands as
+  `tools/call > graphql.execute > GET /route` in a single trace (previously
+  the route spans were orphan traces). Regression-locked by
+  `tests/test_otel_propagation.py`; walkthrough in
+  `examples/otel_smoke.md`.
+
+- **`max_depth` (default 10, `None` disables)** on
+  `RouterGraphQLHandler` / `RouterMCP`: recursive models make selection-set
+  nesting unbounded and an MCP caller is an LLM that can emit runaway
+  documents — overly deep ones are now rejected before execution with a
+  validation-style error. Fragment spreads resolve inline (spreading a
+  deep query across fragments cannot hide it; cyclic spreads are
+  rejected), inline fragments are transparent, and the root selection set
+  counts as depth 1. `validation_rules=` on the handler passes extra
+  graphql-core validation rules through to `graphql()` for anything
+  policy-shaped. README gained a "Hardening the bridge" section covering
+  these knobs plus the fastmcp rate-limiting / response-limiting
+  middleware (per-client by default) for the MCP face.
+
+- **`max_concurrency` (default 16, `None` disables)** on
+  `RouterGraphQLHandler` / `RouterMCP`: a bound on in-flight route calls
+  across all queries. Sibling GraphQL fields resolve concurrently, so one
+  wide query fans out into parallel ASGI calls that could hammer the
+  wrapped app's upstream (DB, external APIs); the invoker-global semaphore
+  bounds that fan-out. The slot is acquired inside the timeout window, so
+  queueing time counts against `request_timeout` — a call waiting for a
+  slot cannot outlive its own deadline.
+
+- **`request_timeout` (default 30s, `None` disables)** on
+  `RouterGraphQLHandler` / `RouterMCP`, threaded to the invoker. Enforced
+  with `asyncio.wait_for` and surfaced as a field-level `TIMEOUT` error
+  (http_status 504) — see Fixed below for why the httpx timeout alone
+  could never fire.
+
+- **`handler.skips`**: the scanner's skip report (path/method/reason per
+  excluded route) is now caller-visible instead of log-only — CI can
+  assert `skips == []` (or an expected set) so a route silently falling
+  out of the schema fails the build. Completes the scanner's day-one
+  "the caller decides whether skips are acceptable" contract.
+
+- GraphiQL shows an actionable offline notice (10s) when the esm.sh CDN
+  is unreachable, pointing at the raw `POST /graphql` endpoint.
+
+### Fixed
+
+- **max_depth no longer rejects introspection**: `__`-prefixed meta-fields
+  don't count toward the depth guard — GraphiQL/codegen/IDE plugins ship a
+  fixed ~15-deep introspection document, which the default `max_depth=10`
+  rejected ("Error fetching schema" on a stock GraphiQL page). The guard
+  still bounds runaway DATA selections.
+
+- `RouteInvoker(timeout=...)` was dead configuration: httpx's
+  `ASGITransport` never enforces timeouts (in-process calls bypass
+  httpcore) — a route could hang forever regardless of the setting.
+  Enforcement now lives in `asyncio.wait_for` inside `invoke()`.
+
+- `content-type` / `accept` are refused by `filter_passthrough_headers`
+  even when whitelisted: a forwarded `content-type` would retype the JSON
+  body request (text/plain + json body → FastAPI 422). Custom headers
+  still forward as before.
+
+### Changed
+
+- Progressive disclosure caches each domain's SDL fragment (the schema is
+  immutable after build; agents re-explore the same domain often), and
+  `DomainRegistry` answers `children()` from a precomputed index instead
+  of a full node scan per `list_domains` call.
+
+- `mount_to(auth_at_root=True)` now carries an explicit checklist comment
+  of the fastmcp private surface it relies upon (per-route auth guard,
+  app-level auth/request-context middleware, well-known routes) — the
+  things to re-verify on any fastmcp major bump.
+
+- **JSON pass-through for dynamic shapes**: endpoints and fields annotated
+  `dict`, `dict[K, V]`, `Any` (and `list`s / model fields thereof) bridge
+  as the `JSON` scalar instead of being skipped — an author declaring a
+  dynamic shape gets reachability, not invisibility. The line drawn: an
+  explicit `dict`/`Any` annotation passes through; a route with no
+  annotation and no `response_model` still skips (no contract). Both
+  directions: a `JSON` input argument lands as the raw request body.
+
+- **`RouterMCP(auth=...)`**: optional fastmcp auth provider (e.g.
+  `GitHubProvider`) passed through to `FastMCP` untouched — the MCP
+  endpoint then speaks OAuth 2.1 (401 discovery, DCR, PKCE) and clients'
+  Bearer tokens travel into route calls via `passthrough_headers` like any
+  other caller's. The bridge verifies nothing. When `auth` is set,
+  `mount_to` also re-exposes the provider's `/.well-known/*` discovery
+  routes at the host app's root — the 401 challenge advertises them there
+  (RFC 8414), but the mount alone would shift them under the mount path.
+  `mount_to(..., auth_at_root=True)` goes further: MCP endpoint at `path`,
+  OAuth/discovery routes at the host root — for reusing an IdP app whose
+  registered callback URL lives at the root domain (subdirectory
+  redirect_path). Implemented by splicing the wrapped app's routes (host
+  routes keep precedence) and copying its middleware stack wholesale — a
+  plain `Mount("")` catch-all would silently shadow host routes added
+  later, and dropping the app-level middleware (auth verification,
+  request-context capture) silently 401s every request.
+
+- **Consumer example `examples/notes_oauth`**: a full Notes app behind
+  GitHub OAuth — browser session cookie, `POST /auth/token` Bearer, and
+  MCP OAuth 2.1 login (Claude Code) as three interchangeable credential
+  carriers, with the fastmcp GitHub proxy reusing the app's OAuth callback
+  via a redirect subdirectory (`auth_at_root`). Guarded by
+  `tests/test_example_public_api.py`: examples import the public API only.
+
+### Fixed
+
+- Python 3.10 support for recursive Pydantic models: CPython < 3.11 leaves
+  ``list["Node"]`` with the plain string inside the PEP 585 generic (only
+  ``typing.Union`` converts str args to ``ForwardRef``), and every evaluator
+  only evaluates ``ForwardRef`` — so ``FieldInfo.annotation`` stayed
+  unresolved and recursive models were skipped as unsupported types on 3.10
+  while working on 3.11+. The type builder now rewraps string args as
+  ``ForwardRef`` (leaving ``Literal`` values untouched — those strings are
+  values, not types) and evaluates them against the model's namespaces,
+  seeding the namespace with the model's own name (the enclosing scope binds
+  a class name only after the class body runs, so neither module globals
+  nor pydantic's parent-namespace snapshot can resolve a self-reference).
+
+- The demo app imported ``datetime.UTC`` (Python 3.11+), failing import on
+  3.10; it now uses ``timezone.utc``.
+
+- A leaf field colliding with a child domain segment inside the same group
+  (e.g. a `catalog` endpoint tagged `shop` plus routes tagged
+  `shop:catalog`) was silently dropped: the child group field overwrote
+  it in the object type, with no warning — and the progressive-disclosure
+  index kept advertising the ghost field. Same-named leaves already failed
+  fast with `DuplicateFieldError`; leaf-vs-subdomain collisions now fail
+  fast the same way, naming both claimants.
+
+- `mode="auto"` counted routes via `isinstance(app.routes, APIRoute)`,
+  which counts ZERO on FastAPI >= 0.142 (include_router results are
+  wrapped in `_IncludedRouter`) — a 30-route app stayed in simple mode,
+  handing agents one giant SDL. It also ignored `include`/`exclude`: an
+  app narrowed to 3 schema routes still switched to progressive. The
+  threshold decision now uses the scanned route count (what actually
+  enters the schema).
+
+- Single non-model body parameters (e.g. `payload: dict[str, Any]`) were
+  wrongly wrapped as `{"payload": ...}` — FastAPI gives a lone body param
+  the WHOLE body unless `Body(embed=True)` or multiple body params are
+  involved. `_body_embeds` now replicates FastAPI's predicate exactly.
+
+### Changed
+
+- **`headers_provider` removed; `passthrough_headers` defaults to
+  `("authorization",)`** (breaking). Credentials now have a single source —
+  the caller: each MCP/GraphQL client connects with its own credentials and
+  the bridge forwards them (case-insensitive whitelist; an explicitly empty
+  list disables forwarding). The server-side provider (and the
+  credential-amplification risk it created when mounted publicly) is gone;
+  machines without a user context configure the service credential on the
+  MCP client side, or use `handler.execute(..., headers=...)` directly.
+  With no HTTP request context (in-memory client) protected routes simply
+  answer 401.
+
+- **`RouterMCP.run()` is HTTP-only** (streamable HTTP with `host`/`port`
+  parameters, default `127.0.0.1:8000`). The wrapped FastAPI app is a
+  service whose routes speak HTTP, and per-caller credential passthrough
+  needs an HTTP request context that stdio has no notion of — so the stdio
+  transport and the `demo.mcp_stdio` entry point are removed (breaking).
+  Use `mount_to(app, "/mcp")` to serve MCP on the app's own port.
+
+## 0.3.0 (2026-10-03)
+
+Schema shape + documentation wave (breaking).
+
+### Changed
+
+- **Renamed from `routerql` to `fastapi-gql-mcp`** (package
+  `fastapi_gql_mcp`): the distribution name now carries both FastAPI and MCP.
+  Exception prefixes `RouterQL*` became `GQLMCP*`; `RouterMCP` /
+  `RouterGraphQLHandler` keep their Router-based names.
+
+### Changed
+
+- **Domain-grouped schema (UseCaseService-style hierarchy)**: fields live
+  under their tag domain tree — a route tagged `shop:catalog` answers at
+  `{ shop { catalog { list_products } } }`. Untagged routes join the domain of
+  their first path segment. Domain SDL fragments now show the exact grouped
+  address an agent should query.
+- **GraphQL field names now come from the endpoint function name** (e.g.
+  `async def get_user` → `get_user`) instead of being reconstructed from the
+  URL path + verb. Path/query/body parameters still become the field's
+  arguments. Two routes sharing a function name fail fast with
+  `DuplicateFieldError` (previously the `_by_{param}` suffix silently
+  disambiguated collection/item pairs).
+
+### Added
+
+- Upgraded the optional `mcp` extra to **fastmcp 4.x** (from 3.1): zero code
+  changes needed — `FastMCP` construction, tool registration, `http_app`
+  mounting and `run()` all carried over. Verified end-to-end (tools, queries,
+  mutations over streamable HTTP) on 4.0.10.
+- Mutation execution semantics pinned by tests: cross-domain writes are
+  serial (spec-guaranteed at the mutation root); same-domain writes run in
+  parallel. Mutation-only schemas now fail fast with guidance (GraphQL
+  requires a Query root).
+- **Argument descriptions**: `Query()/Path()/Body(description=...)` metadata
+  maps onto GraphQL argument descriptions, completing the doc chain
+  (model docstrings → types, `Field(description)` → fields, endpoint
+  docstrings/`summary=` → fields).
+- Runnable demo suite: `python -m demo` (all-in-one server, progressive mode),
+  `demo.mcp_stdio`, `demo.mcp_walkthrough`; full documentation coverage in the
+  demo app for inspection.
+
+## 0.2.0 (2026-10-03)
+
+Feature wave over the 0.1 core.
+
+### Added
+
+- **Progressive disclosure MCP tools** (4 layers over the tag tree):
+  `list_domains` → `list_queries(domain)` / `list_mutations(domain)` →
+  `get_query_schema(domain)` → `graphql_query`. Domain SDL fragments are
+  filtered sub-schemas (only reachable types). Discovery is scoped per domain;
+  execution always runs against the full schema. `mode="auto"` switches to
+  progressive above `progressive_threshold` (default 25, configurable).
+- **Query Parameter Models**: a lone `Annotated[Model, Query()]` flattens into
+  individual alias-aware query arguments. Models mixed with plain query params
+  are skipped with a reason.
+- **GraphiQL playground + GraphQL-over-HTTP**: `handler.mount_graphql(app)`
+  serves `/graphiql` (CDN build, explorer plugin) wired to `POST /graphql`
+  accepting `{query, variables, operationName}`.
+- **`mutation_include`** glob whitelist: with `allow_mutation=True`, write
+  routes must match to become mutations.
+- Restructured `demo/` nexusx-style.
+
+### Fixed
+
+- Type descriptions no longer inherit BaseModel's docstring when a model has
+  none of its own.
+
+## 0.1.0 (2026-10-03)
+
+Initial release.
+
+- RouterScanner: routes → field metadata (verb mapping, dependency-tree param
+  flattening, SkipRecord taxonomy, tag domains).
+- TypeBuilder: Pydantic → graphql-core (custom DateTime/Date/Time/UUID/Decimal
+  scalars, Literal/Enum, cycle-safe registries, alias-first naming).
+- RouteInvoker: in-process ASGI execution with lazy lifespan management and
+  `headers_provider` credential passthrough; HTTP ≥ 400 → `GraphQLError`
+  with `extensions.code=HTTP_{status}`.
+- SchemaBuilder + RouterGraphQLHandler on graphql-core standard execution;
+  route responses nullable per field so sibling results survive failures.
+- RouterMCP: stdio/mount MCP server, `get_schema` + `graphql_query` /
+  `graphql_mutation` with operation-type guards and hint-chain envelopes.

fastapi_gql_mcp-0.4.0/Comparison/README.md

@@ -0,0 +1,104 @@
+# fastapi-gql-mcp vs fastapi-mcp 对照分析
+
+> 对照对象：**fastapi-gql-mcp 0.3.0**（本仓库，FastAPI → GraphQL → MCP）vs
+> **fastapi-mcp 0.4.0**（[tadata-org/fastapi_mcp](https://github.com/tadata-org/fastapi_mcp) ⭐12k，FastAPI → MCP 直暴露）
+>
+> 完整可视化报告：[index.html](./index.html) · 基准数据与复现方法：[bench/](./bench/)
+> 所有数字均为本机实测（2026-10-04），非估算。
+
+## 一句话结论
+
+两条路线解决同一个问题的不同侧面：**fastapi-mcp 把端点变成工具**（端点 = 工具，最小心智负担），
+**fastapi-gql-mcp 把 API 变成一张可组合的类型化查询图**（schema = 契约，上下文经济性 + 组合能力）。
+小而稳的 API 用前者足够；API 规模增长、需要给 agent 省上下文、需要组合查询/字段投影/写操作门禁/OAuth 登录体验时，后者的架构优势开始兑现。
+
+## 架构差异（根源）
+
+| | fastapi-mcp | fastapi-gql-mcp |
+|---|---|---|
+| 中间层 | 无（OpenAPI schema → 工具清单） | GraphQL schema（域树、类型、描述链） |
+| 工具模型 | **每个端点一个工具**（N 工具） | **固定 2–6 个工具** + schema 即契约（simple/progressive 两模式） |
+| 工具命名 | FastAPI operationId：`list_notes_api_notes_get` | 端点函数名：`list_notes` |
+| 调用执行 | OpenAPI 参数 → 还原 HTTP 请求（ASGI 进程内） | GraphQL 执行 → 路由调用（ASGI 进程内） |
+| 组合能力 | 无，一次调用 = 一个端点 | 一次 `graphql_query` 组合多域多字段、别名、字段投影 |
+
+## 实测关键数字（共享同一个 notes 应用，双环境对称驱动）
+
+### 上下文经济性（agent 需要吞下的工具目录 + schema，字节/4 ≈ tokens）
+
+| 端点数 | fastapi-mcp 工具目录 | fastapi-gql-mcp 全量（工具+SDL） | fastapi-gql-mcp 渐进式（单域发现） |
+|---|---|---|---|
+| 5 | 685 tok | 796 tok | 1,239 tok |
+| 10 | 1,219 tok | 943 tok | 1,280 tok |
+| 25 | 2,835 tok | 1,181 tok | 1,281 tok |
+| 50 | 5,542 tok | 1,581 tok | **1,281 tok（持平）** |
+| 100 | **10,954 tok** | 2,381 tok | **1,281 tok（持平）** |
+
+- fastapi-mcp 随端点数**线性增长**（100 端点 ≈ 11k tokens 只算工具目录）
+- fastapi-gql-mcp simple 模式缓增（SDL 很紧凑），**渐进式模式上下文恒定**（单域按需发现）
+- 诚实反例：**5 端点的小 API，fastapi-mcp 反而更省**（685 vs 796）—— 没有 N+1 组合需求时它的简单就是优势
+
+### 往返与响应体积
+
+| 任务 | fastapi-mcp | fastapi-gql-mcp |
+|---|---|---|
+| "过滤笔记 + 统计" 组合任务 | **2 次工具调用**（2 个 agent 轮次） | **1 次** `graphql_query` |
+| 同一列表（20 条笔记）响应 | 2,875 B（全量 + indent=2） | 全量 2,341 B / **投影后 610 B（4.7×↓）** |
+
+### 延迟（进程内微基准，200 次迭代）
+
+| | p50 | p95 |
+|---|---|---|
+| fastapi-mcp 单调用 | **0.91 ms** | 1.00 ms |
+| fastapi-gql-mcp 单查询 | 1.36 ms | 1.93 ms |
+
+诚实结论：**单次平凡调用他们更快**（无 GraphQL 执行层）。但真实 agent 成本由**轮次**主导
+（每轮含 LLM 推理，秒级），1ms 级差距远小于"1 轮 vs 2 轮"的差别 —— 组合能力才是省时间的杠杆。
+
+## 定性差异（详见 index.html）
+
+| 维度 | fastapi-mcp | fastapi-gql-mcp |
+|---|---|---|
+| 错误语义 | HTTP ≥400 → **整个工具调用失败** | **字段级置空** + `extensions.code=HTTP_401/404`，兄弟字段照常返回 |
+| 写操作门禁 | 无概念（全部端点可写） | `allow_mutation` + `mutation_include` 白名单 + 工具级操作类型守卫 |
+| 认证 | OAuth 发现/授权**代理** + 假 DCR；端点防护靠自带 FastAPI `Depends`；不验 token | `auth=` 完整 OAuth 2.1 代理（DCR+PKCE+consent+引用型 token+**端点门禁**）；`passthrough_headers` 按调用者透传 |
+| 传输 | SSE / streamable HTTP / stdio（可分离部署） | streamable HTTP（按调用者凭据透传需要 HTTP 上下文，stdio 已移除） |
+| 人的入口 | 无 | GraphiQL + `POST /graphql`（同一 schema 服务人和 agent） |
+| 生态兼容 | `mcp>=1.12` **无上界**，但在 mcp 2.x 上**直接崩溃**（`Server` 签名变更）——本基准被迫双环境 | `fastmcp<5` 锁上界，4.0.10 端到端验证 |
+| 代码规模 | ~2.0k LOC，直接基于 mcp SDK | ~2.6k LOC，基于 graphql-core + fastmcp |
+
+## 规范演进：MCP 的 lazy 机制与本对照的关系（2026-10 核实）
+
+用户容易把几层东西混为一谈，分层核实如下（依据：本地 mcp SDK 2.3.0 内嵌协议类型 + 生态检索）：
+
+| 层 | 机制 | 状态 | 省不省 agent 上下文 |
+|---|---|---|---|
+| 核心规范 | `tools/list` 分页（`nextCursor`，2025-06-18 起） | 已发布 | **不省** —— 分页只是传输分块，agent 选工具仍需全量目录 |
+| 核心规范 | `server/discover` + `cacheScope`（2026-07-28 修订） | 已发布 | 不减体积 —— 帮的是 **prompt cache 复用**（public/private 缓存语义） |
+| 规范扩展 | **Tool Search 扩展**（`tools/search`，只留名称/摘要、按需拉取完整定义） | **draft，需客户端+服务端双边支持**，生态采纳进行中 | **省** —— 这是真正的"lazy 工具加载" |
+| 库层 | fastmcp 4.x `SearchTransform`（Regex/BM25）：整个目录折叠成 `search_tools` + `call_tool` 两个普通工具 | **今天可用**，任意 MCP 客户端（纯工具实现，无需扩展） | 省 |
+
+**对本对照的含义（诚实修正）**：
+
+1. fastapi-mcp 的"目录线性增长"是**开箱即用的现状**，不是永久死刑 —— 他们可以自己实现 search 折叠（其裸 mcp SDK 1.x 无现成件），或等 Tool Search 扩展普及且客户端支持
+2. 我们库的**渐进式披露与上述 lazy 模式同型**，且是 plain-tools 实现 —— 不依赖任何扩展，今天在任何客户端上工作；即便工具目录问题未来被扩展彻底解决，**组合查询、字段投影、字段级错误隔离、写门禁仍只有 GraphQL 路线能给** —— 工具目录体积只是本对照的一个维度，不是全部
+3. fastmcp 的 `SearchTransform` 对我们属于"备用弹药"：我们的目录本来就恒定在 2–6 个工具，无需折叠；若未来 simple 模式想给超小上下文选项，可叠加
+
+## 选型建议
+
+- **选 fastapi-mcp**：端点少（<10）且稳定、只给 agent 用、想要零配置最快接入、认证已有 FastAPI 依赖兜底
+- **选 fastapi-gql-mcp**：API 会长大；上下文预算紧；agent 需要一次拿到组合视图；需要字段投影控制响应体积；需要细粒度写门禁；需要 OAuth 登录的完整体验；顺便想让人类也用 GraphQL
+
+## 复现
+
+前提：把对照库克隆到本仓库旁边（`env_theirs` 以 path 依赖引用它）：
+
+```bash
+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   # fastapi-mcp 侧
+python3 merge_results.py                             # 合并 → results.json
+```
+
+共享目标应用在 `shared_app.py`（同一份代码接入两个框架 —— 这也是"对接两个框架"的桥接代码本体）。

fastapi_gql_mcp-0.4.0/Comparison/bench/env_ours/pyproject.toml

@@ -0,0 +1,14 @@
+[project]
+name = "bench-env-ours"
+version = "0.0.0"
+description = "fastapi-gql-mcp side of the comparison benchmark"
+requires-python = ">=3.10"
+dependencies = [
+    "fastapi>=0.115",
+    "httpx>=0.27",
+    "asgi-lifespan>=2.1",
+    "fastapi-gql-mcp[mcp]>=0.3",
+]
+
+[tool.uv.sources]
+fastapi-gql-mcp = { path = "../../..", editable = true }

fastapi_gql_mcp-0.4.0/Comparison/bench/env_theirs/pyproject.toml

@@ -0,0 +1,16 @@
+[project]
+name = "bench-env-theirs"
+version = "0.0.0"
+description = "fastapi-mcp (tadata) side of the comparison benchmark"
+requires-python = ">=3.10"
+dependencies = [
+    "fastapi>=0.115",
+    "httpx>=0.27",
+    "fastapi-mcp>=0.4",
+    # fastapi-mcp 0.4.0 pins mcp>=1.12 with NO upper bound but breaks on
+    # mcp 2.x (lowlevel Server signature change) — pinned here so it runs.
+    "mcp>=1.12,<2",
+]
+
+[tool.uv.sources]
+fastapi-mcp = { path = "../../../../fastapi-mcp", editable = true }