fastapi-gql-mcp 0.4.0__py3-none-any.whl

fastapi_gql_mcp/__init__.py

@@ -0,0 +1,21 @@
+"""fastapi-gql-mcp: turn any FastAPI router into a GraphQL query layer + MCP server."""
+
+from fastapi_gql_mcp.handler import GQLMCPConfigError, RouterGraphQLHandler
+from fastapi_gql_mcp.invoker import RouteInvoker, filter_passthrough_headers
+from fastapi_gql_mcp.mcp.errors import GQLMCPErrors
+from fastapi_gql_mcp.mcp.server import RouterMCP
+from fastapi_gql_mcp.scanner import RouteInfo, RouterScanner
+
+__version__ = "0.4.0"
+
+__all__ = [
+    "RouteInfo",
+    "RouteInvoker",
+    "RouterGraphQLHandler",
+    "RouterMCP",
+    "GQLMCPConfigError",
+    "GQLMCPErrors",
+    "RouterScanner",
+    "filter_passthrough_headers",
+    "__version__",
+]

fastapi_gql_mcp/depth_guard.py

@@ -0,0 +1,94 @@
+"""Reject overly deep GraphQL documents before execution.
+
+Recursive models (a Node whose children are Nodes) make query depth
+unbounded: graphql-core happily executes a thousand nested selections, and
+an MCP caller is an LLM that can emit such a document. The guard measures
+selection-set nesting (the root selection set is depth 1) with fragments
+resolved inline and cycles rejected — spreading a deep query across
+fragments cannot hide it.
+
+Introspection meta-fields (``__``-prefixed) do not count: standard tooling
+(GraphiQL, codegen, IDE plugins) ships a fixed, deep introspection document
+— depth ~15 — whose shape is bounded by the schema itself, not by the
+caller. The guard targets runaway DATA selections.
+"""
+
+from __future__ import annotations
+
+from graphql import GraphQLError
+from graphql.language import (
+    DocumentNode,
+    FieldNode,
+    FragmentDefinitionNode,
+    FragmentSpreadNode,
+    InlineFragmentNode,
+    OperationDefinitionNode,
+    SelectionSetNode,
+    parse,
+)
+
+
+class _FragmentCycle(Exception):
+    """A fragment spread referencing itself (illegal GraphQL anyway)."""
+
+
+def document_depth(document: DocumentNode) -> int:
+    """Deepest selection-set nesting across all operations (root = 1).
+
+    Fragment spreads resolve into their definition's selection set without
+    adding a level of their own (``{ ...F }`` with ``fragment F on T
+    { a { b } }`` is depth 2, same as the inlined form); a spread cycle
+    raises, since the real document would recurse forever.
+    """
+    fragments = {
+        d.name.value: d
+        for d in document.definitions
+        if isinstance(d, FragmentDefinitionNode)
+    }
+
+    def selection_depth(sel_set: SelectionSetNode, active: frozenset[str]) -> int:
+        best = 1
+        for sel in sel_set.selections:
+            if isinstance(sel, FieldNode):
+                if sel.name.value.startswith("__"):
+                    # introspection meta-fields don't count toward depth —
+                    # see module docstring
+                    continue
+                if sel.selection_set is not None:
+                    best = max(best, 1 + selection_depth(sel.selection_set, active))
+            elif isinstance(sel, InlineFragmentNode):
+                if sel.selection_set is not None:
+                    best = max(best, selection_depth(sel.selection_set, active))
+            elif isinstance(sel, FragmentSpreadNode):
+                name = sel.name.value
+                if name in active:
+                    raise _FragmentCycle
+                frag = fragments.get(name)
+                if frag is not None:
+                    best = max(best, selection_depth(frag.selection_set, active | {name}))
+        return best
+
+    deepest = 0
+    for defn in document.definitions:
+        if isinstance(defn, OperationDefinitionNode) and defn.selection_set is not None:
+            deepest = max(deepest, selection_depth(defn.selection_set, frozenset()))
+    return deepest
+
+
+def depth_error(query: str, max_depth: int) -> GraphQLError | None:
+    """A GraphQLError rejecting the document — too deep, cyclic fragments,
+    or unparsable (syntax errors surface through the same envelope graphql()
+    would use) — or None when the document is within bounds."""
+    try:
+        document = parse(query)
+    except GraphQLError as exc:
+        return exc
+    try:
+        depth = document_depth(document)
+    except _FragmentCycle:
+        return GraphQLError(
+            f"Document has cyclic fragment spreads (max_depth={max_depth})."
+        )
+    if depth > max_depth:
+        return GraphQLError(f"Query depth {depth} exceeds max_depth={max_depth}.")
+    return None

fastapi_gql_mcp/domains.py

@@ -0,0 +1,146 @@
+"""Tag-based domain grouping for progressive disclosure.
+
+Domains form a tree via the ``"a:b"`` separator convention (``tags=["billing:invoice"]``
+→ ``("billing", "invoice")``). The tree only shapes *discovery* (which slice of
+the schema an agent looks at); execution always runs against the full schema.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Sequence
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from fastapi_gql_mcp.scanner import RouteInfo
+
+_GENERAL: tuple[str, ...] = ("general",)
+_CAMEL_BOUNDARY = re.compile(r"(?<=[a-z0-9])(?=[A-Z])")
+
+
+def _sanitize_segment(segment: str) -> str:
+    snake = _CAMEL_BOUNDARY.sub("_", segment).replace("-", "_").lower()
+    return re.sub(r"[^a-z0-9_]", "_", snake) or "_"
+
+
+def domains_for(tags: Sequence[str], path: str) -> frozenset[tuple[str, ...]]:
+    """Compute the domain paths a route belongs to.
+
+    Rules (in order):
+    1. Each tag becomes one domain path, split on ``:``.
+    2. Without tags, the first non-parameter path segment is the domain.
+    3. Fallback: ``general``.
+    """
+    if tags:
+        return frozenset(
+            tuple(_sanitize_segment(seg) for seg in tag.split(":")) for tag in tags
+        )
+    for segment in path.split("/"):
+        if segment and not (segment.startswith("{") and segment.endswith("}")):
+            return frozenset({(_sanitize_segment(segment),)})
+    return frozenset({_GENERAL})
+
+
+class DomainNode:
+    """One node of the domain tree aggregating its routes' field names.
+
+    Field names are keyed as ``(domain_path, field_name)`` pairs: names only
+    need to be unique WITHIN one domain group (GraphQL: within one object
+    type), so two domains may each carry their own ``get_user``.
+    """
+
+    def __init__(self, path: tuple[str, ...]) -> None:
+        self.path = path
+        self.query_fields: set[tuple[tuple[str, ...], str]] = set()
+        self.mutation_fields: set[tuple[tuple[str, ...], str]] = set()
+
+    @property
+    def name(self) -> str:
+        return self.path[-1]
+
+    def add(self, route: RouteInfo) -> None:
+        key = (self.path, route.field_name)
+        if route.is_mutation:
+            self.mutation_fields.add(key)
+        else:
+            self.query_fields.add(key)
+
+    def summary(self) -> dict[str, object]:
+        return {
+            "name": self.name,
+            "path": list(self.path),
+            "queries": len(self.query_fields),
+            "mutations": len(self.mutation_fields),
+        }
+
+
+class DomainRegistry:
+    """Indexes routes by domain path and answers tree-shaped queries.
+
+    A route with several tags (or whose tag path has depth) is registered at
+    every level of each of its domain paths, so ``list_domains`` can expose
+    both coarse and fine groupings.
+    """
+
+    def __init__(self, routes: Sequence[RouteInfo]) -> None:
+        self._nodes: dict[tuple[str, ...], DomainNode] = {}
+        self._children: dict[tuple[str, ...], set[str]] = {}
+        for route in routes:
+            for domain in route.domains:
+                for depth in range(1, len(domain) + 1):
+                    node = self._node(domain[:depth])
+                    # Only the leaf level carries the field; parents aggregate
+                    # counts through their subtree at query time.
+                    if depth == len(domain):
+                        node.add(route)
+        # Precomputed child index: children() answers in O(1) instead of
+        # scanning every node per list_domains call. Single-segment paths
+        # parent to () — the root's direct children are indexed too.
+        for node_path in self._nodes:
+            self._children.setdefault(node_path[:-1], set()).add(node_path[-1])
+
+    def _node(self, path: tuple[str, ...]) -> DomainNode:
+        node = self._nodes.get(path)
+        if node is None:
+            node = DomainNode(path)
+            self._nodes[path] = node
+        return node
+
+    def node(self, path: tuple[str, ...]) -> DomainNode | None:
+        return self._nodes.get(path)
+
+    def children(self, path: tuple[str, ...] = ()) -> list[str]:
+        """Direct child segment names under ``path``."""
+        return sorted(self._children.get(tuple(path), ()))
+
+    def subtree_fields(
+        self, path: tuple[str, ...]
+    ) -> tuple[set[tuple[tuple[str, ...], str]], set[tuple[tuple[str, ...], str]]]:
+        """All (domain path, field name) pairs at or below ``path``."""
+        queries: set[tuple[tuple[str, ...], str]] = set()
+        mutations: set[tuple[tuple[str, ...], str]] = set()
+        for node_path, node in self._nodes.items():
+            if node_path[: len(path)] == path:
+                queries |= node.query_fields
+                mutations |= node.mutation_fields
+        return queries, mutations
+
+    def summary(self) -> list[dict[str, object]]:
+        """Top-level domain summaries (for the ``list_domains`` MCP tool)."""
+        roots: set[tuple[str, ...]] = set()
+        for node_path in self._nodes:
+            roots.add(node_path[:1])
+        result: list[dict[str, object]] = []
+        for root in sorted(roots):
+            queries, mutations = self.subtree_fields(root)
+            children = self.children(root)
+            result.append(
+                {
+                    "name": root[0],
+                    "path": list(root),
+                    "queries": len(queries),
+                    "mutations": len(mutations),
+                    **({"subdomains": children} if children else {}),
+                }
+            )
+        return result

fastapi_gql_mcp/graphiql.py

@@ -0,0 +1,82 @@
+"""GraphiQL HTML template for fastapi-gql-mcp (CDN-loaded, no build step)."""
+
+GRAPHIQL_HTML = """
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>GraphiQL - fastapi-gql-mcp</title>
+  <style>
+    body { margin: 0; }
+    #graphiql { height: 100dvh; }
+    .loading {
+      height: 100%;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      font-size: 2rem;
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+    }
+  </style>
+  <link rel="stylesheet" href="https://esm.sh/graphiql/dist/style.css" />
+  <link rel="stylesheet" href="https://esm.sh/@graphiql/plugin-explorer/dist/style.css" />
+  <script type="importmap">
+    {
+      "imports": {
+        "react": "https://esm.sh/react@19.1.0",
+        "react/jsx-runtime": "https://esm.sh/react@19.1.0/jsx-runtime",
+        "react-dom": "https://esm.sh/react-dom@19.1.0",
+        "react-dom/client": "https://esm.sh/react-dom@19.1.0/client",
+        "@emotion/is-prop-valid": "data:text/javascript,",
+        "graphiql": "https://esm.sh/graphiql?standalone&external=react,react-dom,@graphiql/react,graphql",
+        "graphiql/": "https://esm.sh/graphiql/",
+        "@graphiql/plugin-explorer": "https://esm.sh/@graphiql/plugin-explorer?standalone&external=react,@graphiql/react,graphql",
+        "@graphiql/react": "https://esm.sh/@graphiql/react?standalone&external=react,react-dom,graphql,@emotion/is-prop-valid",
+        "@graphiql/toolkit": "https://esm.sh/@graphiql/toolkit?standalone&external=graphql",
+        "graphql": "https://esm.sh/graphql@16.11.0"
+      }
+    }
+  </script>
+</head>
+<body>
+  <div id="graphiql">
+    <div class="loading">Loading GraphiQL...</div>
+  </div>
+  <script>
+    // Offline/intranet notice: the imports below come from the esm.sh CDN;
+    // when it is unreachable the loading placeholder would hang forever.
+    // If GraphiQL has not rendered after 10s, say so and point at the raw
+    // endpoint (which never depended on the CDN).
+    window.setTimeout(function () {
+      var el = document.querySelector('#graphiql .loading');
+      if (el) {
+        el.textContent = 'GraphiQL failed to load — esm.sh CDN unreachable ' +
+          '(offline or restricted network?). The GraphQL API itself is fine: ' +
+          'POST {graphql_url} directly.';
+      }
+    }, 10000);
+  </script>
+  <script type="module">
+    import React from 'react';
+    import ReactDOM from 'react-dom/client';
+    import { GraphiQL } from 'graphiql';
+    import { createGraphiQLFetcher } from '@graphiql/toolkit';
+    import { explorerPlugin } from '@graphiql/plugin-explorer';
+
+    const fetcher = createGraphiQLFetcher({ url: '{graphql_url}' });
+
+    function App() {
+      return React.createElement(GraphiQL, {
+        fetcher: fetcher,
+        plugins: [explorerPlugin()]
+      });
+    }
+
+    const container = document.getElementById('graphiql');
+    const root = ReactDOM.createRoot(container);
+    root.render(React.createElement(App));
+  </script>
+</body>
+</html>
+"""

fastapi_gql_mcp/handler.py

@@ -0,0 +1,183 @@
+"""The non-MCP entry point: a GraphQL handler over a FastAPI app.
+
+Constructing the handler scans the app and builds the schema eagerly, so
+configuration problems surface at startup, not at first query.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+from graphql import GraphQLSchema, graphql, print_schema
+from opentelemetry import trace
+
+from fastapi_gql_mcp.depth_guard import depth_error
+from fastapi_gql_mcp.invoker import InvocationContext, RouteInvoker
+from fastapi_gql_mcp.scanner import RouteInfo, RouterScanner, SkipRecord
+from fastapi_gql_mcp.schema_builder import GQLMCPConfigError, SchemaBuilder
+from fastapi_gql_mcp.type_builder import TypeBuilder
+
+
+class RouterGraphQLHandler:
+    """Exposes a FastAPI app as an executable GraphQL schema."""
+
+    def __init__(
+        self,
+        app: Any,
+        *,
+        include: Sequence[str] | None = None,
+        exclude: Sequence[str] | None = None,
+        allow_mutation: bool = False,
+        include_hidden: bool = False,
+        mutation_include: Sequence[str] | None = None,
+        passthrough_headers: Sequence[str] | None = None,
+        request_timeout: float | None = 30.0,
+        max_concurrency: int | None = 16,
+        max_depth: int | None = 10,
+        validation_rules: Sequence[Any] | None = None,
+    ) -> None:
+        if max_depth is not None and max_depth < 1:
+            raise ValueError("max_depth must be >= 1, or None to disable")
+        self._invoker = RouteInvoker(
+            app, timeout=request_timeout, max_concurrency=max_concurrency
+        )
+        self._max_depth = max_depth
+        self._validation_rules = tuple(validation_rules) if validation_rules else ()
+        # Whitelist of inbound header names untrusted callers may forward into
+        # route calls, lowercased at construction. None = the default
+        # ("authorization",): same-app bridges speak for the caller, so the
+        # caller's own credential travels by default. An explicitly empty
+        # sequence disables passthrough entirely.
+        if passthrough_headers is None:
+            self._passthrough_headers: tuple[str, ...] = ("authorization",)
+        else:
+            self._passthrough_headers = tuple(
+                h.strip().lower() for h in passthrough_headers if h.strip()
+            )
+        self._types = TypeBuilder()
+        routes, skips = RouterScanner(
+            app,
+            include=include,
+            exclude=exclude,
+            allow_mutation=allow_mutation,
+            include_hidden=include_hidden,
+            mutation_include=mutation_include,
+        ).scan(self._types)
+        self._builder = SchemaBuilder(routes, self._invoker, self._types)
+        self._schema = self._builder.build()
+        self._routes: list[RouteInfo] = routes
+        self._skips: list[SkipRecord] = skips
+
+    @property
+    def schema(self) -> GraphQLSchema:
+        return self._schema
+
+    @property
+    def routes(self) -> list[RouteInfo]:
+        return list(self._routes)
+
+    @property
+    def skips(self) -> list[SkipRecord]:
+        """Routes excluded from the schema, with reasons — the scanner's
+        report, so callers can assert nothing disappeared unexpectedly
+        (e.g. a new endpoint silently failing to map in CI)."""
+        return list(self._skips)
+
+    @property
+    def invoker(self) -> RouteInvoker:
+        return self._invoker
+
+    @property
+    def passthrough_headers(self) -> tuple[str, ...]:
+        """Lowercased header names callers may forward (default: authorization only)."""
+        return self._passthrough_headers
+
+    @property
+    def query_fields(self) -> dict[tuple[tuple[str, ...], str], Any]:
+        """(domain path, field name) -> GraphQLField index (the schema's leaves)."""
+        return self._builder.query_fields
+
+    @property
+    def mutation_fields(self) -> dict[tuple[tuple[str, ...], str], Any]:
+        return self._builder.mutation_fields
+
+    def get_sdl(self) -> str:
+        """Full schema in SDL form (the MCP ``get_schema`` payload)."""
+        return print_schema(self._schema)
+
+    async def execute(
+        self,
+        query: str,
+        *,
+        variables: dict[str, Any] | None = None,
+        operation_name: str | None = None,
+        headers: Mapping[str, str] | None = None,
+    ) -> dict[str, Any]:
+        """Execute a GraphQL query against the app's routes.
+
+        ``headers`` are TRUSTED per-call headers — the single credential
+        channel (there is no server-side provider). Callers sourcing them
+        from an untrusted origin (MCP request, /graphql endpoint) must filter
+        them through ``filter_passthrough_headers`` first.
+        """
+        if self._max_depth is not None:
+            error = depth_error(query, self._max_depth)
+            if error is not None:
+                return {"errors": [error.formatted]}
+        await self._invoker.start()
+        # The span that makes the middle layer visible: fastmcp's tool span
+        # covers the call, FastAPI's route spans cover execution — this one
+        # wraps the GraphQL orchestration between them (and the invoker
+        # injects its trace context FROM here, so route spans nest under
+        # it). No-op without an SDK installed.
+        with trace.get_tracer("fastapi_gql_mcp").start_as_current_span(
+            "graphql.execute"
+        ) as span:
+            span.set_attribute(
+                "graphql.operation_name", operation_name or "_anonymous"
+            )
+            result = await graphql(
+                self._schema,
+                query,
+                variable_values=variables or {},
+                operation_name=operation_name,
+                context_value=InvocationContext(headers=headers),
+                rules=self._validation_rules or None,
+            )
+            if result.errors:
+                span.set_attribute("graphql.error_count", len(result.errors))
+        payload: dict[str, Any] = {}
+        if result.data is not None:
+            payload["data"] = result.data
+        if result.errors:
+            payload["errors"] = [error.formatted for error in result.errors]
+        return payload
+
+    async def aclose(self) -> None:
+        """Release the invoker's HTTP client and app lifespan."""
+        await self._invoker.aclose()
+
+    def mount_graphql(
+        self,
+        app: Any,
+        *,
+        graphql_path: str = "/graphql",
+        graphiql_path: str = "/graphiql",
+    ) -> None:
+        """Serve a GraphiQL playground + GraphQL HTTP endpoint on a FastAPI app.
+
+        Mounting into the SAME app that fastapi-gql-mcp wraps disables the invoker's
+        lifespan management (the app's own server lifespan drives it once).
+        """
+        from fastapi_gql_mcp.http_api import create_graphql_router
+
+        if app is self._invoker.app:
+            self._invoker.disable_lifespan_management()
+        router = create_graphql_router(
+            self, graphql_path=graphql_path, graphiql_path=graphiql_path
+        )
+        app.include_router(router)
+
+
+__all__ = ["RouterGraphQLHandler", "GQLMCPConfigError"]

fastapi_gql_mcp/http_api.py

@@ -0,0 +1,89 @@
+"""GraphQL-over-HTTP endpoints: a GraphiQL playground + a POST executor."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from fastapi import APIRouter, Request
+from fastapi.responses import HTMLResponse, JSONResponse
+
+from fastapi_gql_mcp.graphiql import GRAPHIQL_HTML
+from fastapi_gql_mcp.invoker import filter_passthrough_headers
+
+logger = logging.getLogger(__name__)
+
+
+def create_graphql_router(
+    handler: Any,
+    *,
+    graphql_path: str = "/graphql",
+    graphiql_path: str = "/graphiql",
+) -> APIRouter:
+    """Build an APIRouter serving GraphiQL and a GraphQL HTTP endpoint.
+
+    Args:
+        handler: A ``RouterGraphQLHandler``.
+        graphql_path: POST endpoint executing GraphQL documents. Body:
+            ``{"query": str, "variables"?: dict, "operationName"?: str}``.
+        graphiql_path: GET endpoint serving the playground, wired to
+            ``graphql_path``.
+
+    The endpoint shares the handler's ``passthrough_headers`` whitelist with
+    the MCP face: incoming credentials travel to the routes under the same
+    rules. Want browser sessions through GraphiQL? Configure
+    ``passthrough_headers=["authorization", "cookie"]``.
+    """
+    router = APIRouter()
+
+    @router.get(graphiql_path, include_in_schema=False)
+    async def graphiql() -> HTMLResponse:
+        html = GRAPHIQL_HTML.replace("{graphql_url}", graphql_path)
+        return HTMLResponse(html)
+
+    @router.post(graphql_path)
+    async def execute_graphql(request: Request) -> JSONResponse:
+        try:
+            body: dict[str, Any] = await request.json()
+        except Exception:
+            return JSONResponse(
+                {"errors": [{"message": "Request body must be JSON."}]}, status_code=400
+            )
+        query = body.get("query")
+        if not isinstance(query, str) or not query.strip():
+            return JSONResponse(
+                {"errors": [{"message": "Missing 'query' in request body."}]},
+                status_code=400,
+            )
+        variables = body.get("variables")
+        operation_name = body.get("operationName")
+        # The invoker re-issues a fresh ASGI request, so the inbound request's
+        # headers do NOT travel with it — extract and whitelist them here
+        # (same filter, same whitelist as the MCP face).
+        allowed = handler.passthrough_headers
+        headers = filter_passthrough_headers(request.headers, allowed) if allowed else None
+        result = await handler.execute(
+            query,
+            variables=variables if isinstance(variables, dict) else None,
+            operation_name=operation_name if isinstance(operation_name, str) else None,
+            headers=headers,
+        )
+        status = 200 if result.get("data") is not None else 400
+        return JSONResponse(result, status_code=status)
+
+    @router.get(graphql_path, include_in_schema=False)
+    async def graphql_usage() -> JSONResponse:
+        return JSONResponse(
+            {
+                "error": "GraphQL over HTTP is POST-only.",
+                "usage": {
+                    "method": "POST",
+                    "path": graphql_path,
+                    "body": {"query": "...", "variables": {}, "operationName": None},
+                    "playground": graphiql_path,
+                },
+            },
+            status_code=405,
+        )
+
+    return router