fastapi-webmcp 0.3.0__py3-none-any.whl

fastapi_webmcp/__init__.py

@@ -0,0 +1,26 @@
+from .application import FastAPIWebMCP
+from .decorators import webmcp_tool
+from .exceptions import FastAPIWebMCPError, RouteConversionError
+from .models import (
+    ClientTool,
+    RequestTool,
+    StaticTool,
+    WebMCPManifest,
+    client_tool,
+    static_tool,
+)
+
+__all__ = [
+    "FastAPIWebMCP",
+    "FastAPIWebMCPError",
+    "ClientTool",
+    "RequestTool",
+    "RouteConversionError",
+    "StaticTool",
+    "WebMCPManifest",
+    "client_tool",
+    "static_tool",
+    "webmcp_tool",
+]
+
+__version__ = "0.3.0"

fastapi_webmcp/application.py

@@ -0,0 +1,237 @@
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable, Collection, Mapping, Sequence
+from importlib.resources import files
+from typing import Any, TypeAlias
+
+from fastapi import Depends, FastAPI, Request, Response, params
+
+from .discovery import AUTHENTICATION_HEADERS, TOOL_NAME_PATTERN, ToolDiscovery
+from .exceptions import FastAPIWebMCPError, RouteConversionError
+from .models import (
+    BrowserTool,
+    ClientTool,
+    RequestTool,
+    StaticTool,
+    ToolCredentials,
+    WebMCPManifest,
+)
+
+ManifestProviderResult: TypeAlias = WebMCPManifest | Collection[BrowserTool]
+ManifestProvider: TypeAlias = Callable[
+    ..., ManifestProviderResult | Awaitable[ManifestProviderResult]
+]
+
+
+class FastAPIWebMCP:
+    """Expose selected FastAPI routes and page tools to browser agents."""
+
+    def __init__(
+        self,
+        app: FastAPI,
+        *,
+        include_operations: Collection[str] = (),
+        include_tags: Collection[str] = (),
+        exclude_operations: Collection[str] = (),
+        expose_all: bool = False,
+        credentials: ToolCredentials = "omit",
+    ) -> None:
+        if credentials not in {"omit", "same-origin"}:
+            raise FastAPIWebMCPError("credentials must be either 'omit' or 'same-origin'")
+        self.app = app
+        self.credentials = credentials
+        self.discovery = ToolDiscovery(
+            app,
+            include_operations=include_operations,
+            include_tags=include_tags,
+            exclude_operations=exclude_operations,
+            expose_all=expose_all,
+        )
+        self._additional_tools: list[BrowserTool] = []
+        self._page_path: str | None = None
+
+    @classmethod
+    def from_fastapi(
+        cls,
+        app: FastAPI,
+        *,
+        include_operations: Collection[str] = (),
+        include_tags: Collection[str] = (),
+        exclude_operations: Collection[str] = (),
+        expose_all: bool = False,
+        credentials: ToolCredentials = "omit",
+    ) -> FastAPIWebMCP:
+        return cls(
+            app,
+            include_operations=include_operations,
+            include_tags=include_tags,
+            exclude_operations=exclude_operations,
+            expose_all=expose_all,
+            credentials=credentials,
+        )
+
+    def add_tool(self, tool: BrowserTool) -> BrowserTool:
+        """Add a static or client tool to every default manifest."""
+
+        candidate = [*self._additional_tools, tool]
+        self._validate_tools(candidate)
+        self._additional_tools.append(tool)
+        return tool
+
+    def tools(self) -> list[BrowserTool]:
+        tools: list[BrowserTool] = [*self.discovery.discover(), *self._additional_tools]
+        self._validate_tools(tools)
+        return tools
+
+    def manifest(
+        self,
+        *,
+        root_path: str = "",
+        tools: Collection[BrowserTool] | None = None,
+        context: Mapping[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        selected = list(self.tools() if tools is None else tools)
+        self._validate_tools(selected)
+        result: dict[str, Any] = {
+            "version": 1,
+            "basePath": self._normalize_root_path(root_path),
+            "credentials": self.credentials,
+            "tools": [tool.as_dict() for tool in selected],
+        }
+        if context:
+            result["context"] = dict(context)
+        return result
+
+    def mount(
+        self,
+        *,
+        page: str = "/webmcp",
+        manifest_provider: ManifestProvider | None = None,
+        dependencies: Sequence[params.Depends] = (),
+    ) -> None:
+        """Mount the packaged page, runtime, and a possibly protected dynamic manifest."""
+
+        if self._page_path is not None:
+            raise FastAPIWebMCPError(f"fastapi-webmcp is already mounted at {self._page_path}")
+        if not hasattr(self.app, "frontend"):
+            raise FastAPIWebMCPError("FastAPI.app.frontend() is required; install fastapi>=0.141.1")
+
+        page_path = self._normalize_page_path(page)
+        manifest_path = f"{page_path}/manifest.json"
+
+        def manifest_payload(
+            request: Request,
+            page_manifest: WebMCPManifest | None = None,
+        ) -> dict[str, Any]:
+            return self.manifest(
+                root_path=request.scope.get("root_path", ""),
+                tools=page_manifest.tools if page_manifest is not None else None,
+                context=page_manifest.context if page_manifest is not None else None,
+            )
+
+        manifest_endpoint: Callable[..., Awaitable[dict[str, Any]]]
+        if manifest_provider is None:
+
+            async def serve_default_manifest(
+                request: Request,
+                response: Response,
+            ) -> dict[str, Any]:
+                response.headers["Cache-Control"] = "no-store"
+                return manifest_payload(request)
+
+            manifest_endpoint = serve_default_manifest
+        else:
+            provider = manifest_provider
+            provider_dependency: Any = Depends(provider)
+
+            async def serve_dynamic_manifest(
+                request: Request,
+                response: Response,
+                provided: ManifestProviderResult = provider_dependency,
+            ) -> dict[str, Any]:
+                if provided is None:
+                    raise FastAPIWebMCPError("manifest provider returned None")
+                response.headers["Cache-Control"] = "no-store"
+                return manifest_payload(request, self._page_manifest(provided))
+
+            manifest_endpoint = serve_dynamic_manifest
+
+        self.app.add_api_route(
+            manifest_path,
+            manifest_endpoint,
+            methods=["GET"],
+            dependencies=list(dependencies),
+            include_in_schema=False,
+            name="fastapi_webmcp_manifest",
+        )
+        static_directory = files("fastapi_webmcp").joinpath("static")
+        self.app.frontend(
+            page_path,
+            directory=str(static_directory),
+            fallback="index.html",
+        )
+        self._page_path = page_path
+
+    def _page_manifest(
+        self,
+        provided: ManifestProviderResult,
+    ) -> WebMCPManifest:
+        if isinstance(provided, WebMCPManifest):
+            return provided
+        return WebMCPManifest(tools=provided)
+
+    def _validate_tools(self, tools: Collection[BrowserTool]) -> None:
+        names: set[str] = set()
+        for tool in tools:
+            if not TOOL_NAME_PATTERN.fullmatch(tool.name):
+                raise RouteConversionError(
+                    f"tool name {tool.name!r} must match {TOOL_NAME_PATTERN.pattern}"
+                )
+            if tool.name in names:
+                raise RouteConversionError(f"duplicate WebMCP tool name: {tool.name}")
+            names.add(tool.name)
+            schema = tool.input_schema
+            if schema.get("type") != "object":
+                raise RouteConversionError(f"tool {tool.name!r} input schema must be an object")
+            properties = schema.get("properties")
+            required = schema.get("required")
+            if not isinstance(properties, Mapping) or not isinstance(required, list):
+                raise RouteConversionError(
+                    f"tool {tool.name!r} input schema needs properties and required"
+                )
+            unknown_required = [
+                name for name in required if not isinstance(name, str) or name not in properties
+            ]
+            if unknown_required:
+                required_names = ", ".join(sorted(str(name) for name in unknown_required))
+                raise RouteConversionError(
+                    f"tool {tool.name!r} requires unknown input properties: {required_names}"
+                )
+            if isinstance(tool, ClientTool) and not TOOL_NAME_PATTERN.fullmatch(tool.action):
+                raise RouteConversionError(
+                    f"client action {tool.action!r} must match {TOOL_NAME_PATTERN.pattern}"
+                )
+            if isinstance(tool, RequestTool):
+                authentication_headers = sorted(
+                    header_name
+                    for _, header_name in tool.request.header_params
+                    if header_name.casefold() in AUTHENTICATION_HEADERS
+                )
+                if authentication_headers:
+                    header_names = ", ".join(authentication_headers)
+                    raise RouteConversionError(
+                        f"tool {tool.name!r} cannot expose authentication headers "
+                        f"as tool inputs: {header_names}"
+                    )
+            if isinstance(tool, StaticTool) and not isinstance(tool.text, str):
+                raise RouteConversionError(f"static tool {tool.name!r} text must be a string")
+
+    def _normalize_page_path(self, page: str) -> str:
+        normalized = "/" + page.strip("/")
+        if normalized == "/":
+            raise FastAPIWebMCPError("the WebMCP page cannot replace the application root")
+        return normalized
+
+    def _normalize_root_path(self, root_path: str) -> str:
+        stripped = root_path.strip("/")
+        return f"/{stripped}" if stripped else ""

fastapi_webmcp/decorators.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from typing import TypeVar
+
+from .models import ToolMetadata
+
+F = TypeVar("F", bound=Callable[..., object])
+METADATA_ATTRIBUTE = "__fastapi_webmcp_tool__"
+
+
+def webmcp_tool(
+    *,
+    name: str | None = None,
+    description: str | None = None,
+    read_only: bool | None = None,
+    untrusted_content: bool = True,
+    headers: Mapping[str, str] | None = None,
+) -> Callable[[F], F]:
+    """Mark a FastAPI endpoint for exposure as an in-page WebMCP tool.
+
+    Place this below the FastAPI route decorator so it is applied to the
+    endpoint before FastAPI registers the function::
+
+        @app.get("/items", operation_id="list_items")
+        @webmcp_tool(read_only=True)
+        async def list_items(): ...
+    """
+
+    metadata = ToolMetadata(
+        name=name,
+        description=description,
+        read_only=read_only,
+        untrusted_content=untrusted_content,
+        header_params=tuple((headers or {}).items()),
+    )
+
+    def decorator(function: F) -> F:
+        setattr(function, METADATA_ATTRIBUTE, metadata)
+        return function
+
+    return decorator
+
+
+def metadata_for(function: Callable[..., object]) -> ToolMetadata | None:
+    value = getattr(function, METADATA_ATTRIBUTE, None)
+    return value if isinstance(value, ToolMetadata) else None

fastapi_webmcp/discovery.py

@@ -0,0 +1,368 @@
+from __future__ import annotations
+
+import re
+from collections.abc import Collection, Mapping
+from copy import deepcopy
+from typing import Any
+
+from fastapi import FastAPI
+from fastapi.routing import APIRoute
+
+from .decorators import metadata_for
+from .exceptions import RouteConversionError
+from .models import RequestMapping, RequestTool, ToolMetadata
+
+HTTP_METHODS = ("get", "post", "put", "patch", "delete")
+TOOL_NAME_PATTERN = re.compile(r"^[A-Za-z0-9_.-]{1,128}$")
+AUTHENTICATION_HEADERS = frozenset({"authorization", "cookie", "proxy-authorization"})
+
+
+class ToolDiscovery:
+    def __init__(
+        self,
+        app: FastAPI,
+        *,
+        include_operations: Collection[str] = (),
+        include_tags: Collection[str] = (),
+        exclude_operations: Collection[str] = (),
+        expose_all: bool = False,
+    ) -> None:
+        self.app = app
+        self.include_operations = frozenset(include_operations)
+        self.include_tags = frozenset(include_tags)
+        self.exclude_operations = frozenset(exclude_operations)
+        self.expose_all = expose_all
+
+    def discover(self) -> list[RequestTool]:
+        specification = self.app.openapi()
+        route_index = self._route_index()
+        tools: list[RequestTool] = []
+        names: set[str] = set()
+
+        for path, path_item in specification.get("paths", {}).items():
+            if not isinstance(path_item, Mapping):
+                continue
+            for method in HTTP_METHODS:
+                operation = path_item.get(method)
+                if not isinstance(operation, Mapping):
+                    continue
+                operation_id = operation.get("operationId")
+                if not isinstance(operation_id, str):
+                    continue
+                route = route_index.get((path, method.upper()))
+                metadata = metadata_for(route.endpoint) if route is not None else None
+                if not self._selected(operation_id, operation, metadata):
+                    continue
+
+                tool = self._build_tool(
+                    specification=specification,
+                    path=path,
+                    path_item=path_item,
+                    method=method.upper(),
+                    operation_id=operation_id,
+                    operation=operation,
+                    metadata=metadata,
+                )
+                if tool.name in names:
+                    raise RouteConversionError(f"duplicate WebMCP tool name: {tool.name}")
+                names.add(tool.name)
+                tools.append(tool)
+
+        return tools
+
+    def _route_index(self) -> dict[tuple[str, str], APIRoute]:
+        index: dict[tuple[str, str], APIRoute] = {}
+        for route in self.app.routes:
+            if not isinstance(route, APIRoute) or not route.include_in_schema:
+                continue
+            for method in route.methods or ():
+                index[(route.path_format, method.upper())] = route
+        return index
+
+    def _selected(
+        self,
+        operation_id: str,
+        operation: Mapping[str, Any],
+        metadata: ToolMetadata | None,
+    ) -> bool:
+        if operation_id in self.exclude_operations:
+            return False
+        tags = {tag for tag in operation.get("tags", []) if isinstance(tag, str)}
+        return (
+            metadata is not None
+            or self.expose_all
+            or operation_id in self.include_operations
+            or bool(tags & self.include_tags)
+        )
+
+    def _build_tool(
+        self,
+        *,
+        specification: Mapping[str, Any],
+        path: str,
+        path_item: Mapping[str, Any],
+        method: str,
+        operation_id: str,
+        operation: Mapping[str, Any],
+        metadata: ToolMetadata | None,
+    ) -> RequestTool:
+        name = metadata.name if metadata and metadata.name else operation_id
+        if not TOOL_NAME_PATTERN.fullmatch(name):
+            raise RouteConversionError(f"tool name {name!r} must match {TOOL_NAME_PATTERN.pattern}")
+
+        description = self._description(operation_id, operation, metadata)
+        input_schema, mapping = self._input_contract(
+            specification=specification,
+            path=path,
+            path_item=path_item,
+            method=method,
+            operation=operation,
+            metadata=metadata,
+        )
+        read_only = (
+            metadata.read_only
+            if metadata is not None and metadata.read_only is not None
+            else method in {"GET", "HEAD"}
+        )
+        untrusted_content = metadata.untrusted_content if metadata is not None else True
+        return RequestTool(
+            name=name,
+            description=description,
+            input_schema=input_schema,
+            read_only=read_only,
+            untrusted_content=untrusted_content,
+            request=mapping,
+        )
+
+    def _description(
+        self,
+        operation_id: str,
+        operation: Mapping[str, Any],
+        metadata: ToolMetadata | None,
+    ) -> str:
+        if metadata is not None and metadata.description:
+            return metadata.description
+        summary = operation.get("summary")
+        if isinstance(summary, str) and summary.strip():
+            return summary.strip()
+        description = operation.get("description")
+        if isinstance(description, str) and description.strip():
+            return description.strip().split("\n\n", 1)[0]
+        return operation_id.replace("_", " ").strip().capitalize()
+
+    def _input_contract(
+        self,
+        *,
+        specification: Mapping[str, Any],
+        path: str,
+        path_item: Mapping[str, Any],
+        method: str,
+        operation: Mapping[str, Any],
+        metadata: ToolMetadata | None,
+    ) -> tuple[dict[str, Any], RequestMapping]:
+        properties: dict[str, Any] = {}
+        required: list[str] = []
+        path_params: list[str] = []
+        query_params: list[str] = []
+        body_params: list[str] = []
+        body_value_param: str | None = None
+        header_params: list[tuple[str, str]] = []
+        configured_headers = dict(metadata.header_params) if metadata is not None else {}
+        authentication_headers = sorted(
+            header_name
+            for header_name in configured_headers.values()
+            if header_name.casefold() in AUTHENTICATION_HEADERS
+        )
+        if authentication_headers:
+            names = ", ".join(authentication_headers)
+            raise RouteConversionError(
+                f"{method} {path} cannot expose authentication headers as tool inputs: {names}"
+            )
+        matched_headers: set[str] = set()
+
+        parameters = [*path_item.get("parameters", []), *operation.get("parameters", [])]
+        for raw_parameter in parameters:
+            parameter = self._resolve_object(raw_parameter, specification)
+            name = parameter.get("name")
+            location = parameter.get("in")
+            if not isinstance(name, str) or not isinstance(location, str):
+                continue
+            if location == "cookie":
+                # Browser credentials own cookies; agents must never supply them.
+                continue
+            if location == "header":
+                if name.casefold() in AUTHENTICATION_HEADERS:
+                    # Application code supplies authentication headers at runtime.
+                    continue
+                tool_name = next(
+                    (
+                        input_name
+                        for input_name, header_name in configured_headers.items()
+                        if header_name.casefold() == name.casefold()
+                    ),
+                    None,
+                )
+                if tool_name is not None:
+                    schema = self._resolve_schema(parameter.get("schema", {}), specification)
+                    if isinstance(parameter.get("description"), str):
+                        schema.setdefault("description", parameter["description"])
+                    self._add_property(
+                        properties,
+                        tool_name,
+                        schema,
+                        method=method,
+                        path=path,
+                    )
+                    if parameter.get("required") and tool_name not in required:
+                        required.append(tool_name)
+                    header_params.append((tool_name, name))
+                    matched_headers.add(tool_name)
+                    continue
+            if location not in {"path", "query"}:
+                if parameter.get("required"):
+                    raise RouteConversionError(
+                        f"{method} {path} requires unsupported {location} parameter {name!r}"
+                    )
+                continue
+            schema = self._resolve_schema(parameter.get("schema", {}), specification)
+            if isinstance(parameter.get("description"), str):
+                schema.setdefault("description", parameter["description"])
+            self._add_property(properties, name, schema, method=method, path=path)
+            if parameter.get("required") and name not in required:
+                required.append(name)
+            (path_params if location == "path" else query_params).append(name)
+
+        unmatched_headers = set(configured_headers) - matched_headers
+        if unmatched_headers:
+            names = ", ".join(sorted(unmatched_headers))
+            raise RouteConversionError(
+                f"{method} {path} declares WebMCP header inputs not found in OpenAPI: {names}"
+            )
+
+        request_body = operation.get("requestBody")
+        if request_body is not None:
+            body = self._resolve_object(request_body, specification)
+            media_type = self._json_media_type(body.get("content", {}))
+            if media_type is None:
+                raise RouteConversionError(f"{method} {path} has no application/json request body")
+            body_schema = self._resolve_schema(media_type.get("schema", {}), specification)
+            if body_schema.get("type") == "object" and isinstance(
+                body_schema.get("properties"), Mapping
+            ):
+                for name, schema in body_schema["properties"].items():
+                    if not isinstance(name, str) or not isinstance(schema, Mapping):
+                        continue
+                    self._add_property(
+                        properties,
+                        name,
+                        deepcopy(dict(schema)),
+                        method=method,
+                        path=path,
+                    )
+                    body_params.append(name)
+                for name in body_schema.get("required", []):
+                    if isinstance(name, str) and name not in required:
+                        required.append(name)
+            else:
+                body_value_param = "body"
+                self._add_property(
+                    properties,
+                    body_value_param,
+                    body_schema,
+                    method=method,
+                    path=path,
+                )
+                if body.get("required"):
+                    required.append(body_value_param)
+
+        return (
+            {
+                "type": "object",
+                "properties": properties,
+                "required": required,
+                "additionalProperties": False,
+            },
+            RequestMapping(
+                method=method,
+                path=path,
+                path_params=tuple(path_params),
+                query_params=tuple(query_params),
+                body_params=tuple(body_params),
+                body_value_param=body_value_param,
+                header_params=tuple(header_params),
+            ),
+        )
+
+    def _add_property(
+        self,
+        properties: dict[str, Any],
+        name: str,
+        schema: dict[str, Any],
+        *,
+        method: str,
+        path: str,
+    ) -> None:
+        if name in properties:
+            raise RouteConversionError(
+                f"{method} {path} maps more than one input to property {name!r}"
+            )
+        properties[name] = schema
+
+    def _json_media_type(self, content: Any) -> Mapping[str, Any] | None:
+        if not isinstance(content, Mapping):
+            return None
+        direct = content.get("application/json")
+        if isinstance(direct, Mapping):
+            return direct
+        for media_type, value in content.items():
+            if (
+                isinstance(media_type, str)
+                and media_type.endswith("+json")
+                and isinstance(value, Mapping)
+            ):
+                return value
+        return None
+
+    def _resolve_object(self, value: Any, specification: Mapping[str, Any]) -> dict[str, Any]:
+        resolved = self._resolve_schema(value, specification)
+        if not isinstance(resolved, dict):
+            raise RouteConversionError("OpenAPI object did not resolve to a mapping")
+        return resolved
+
+    def _resolve_schema(
+        self,
+        value: Any,
+        specification: Mapping[str, Any],
+        stack: tuple[str, ...] = (),
+    ) -> Any:
+        if isinstance(value, list):
+            return [self._resolve_schema(item, specification, stack) for item in value]
+        if not isinstance(value, Mapping):
+            return deepcopy(value)
+
+        reference = value.get("$ref")
+        if isinstance(reference, str):
+            if not reference.startswith("#/"):
+                raise RouteConversionError(
+                    f"external OpenAPI reference is unsupported: {reference}"
+                )
+            if reference in stack:
+                raise RouteConversionError(f"cyclic OpenAPI schema is unsupported: {reference}")
+            target: Any = specification
+            for part in reference[2:].split("/"):
+                key = part.replace("~1", "/").replace("~0", "~")
+                if not isinstance(target, Mapping) or key not in target:
+                    raise RouteConversionError(f"unresolved OpenAPI reference: {reference}")
+                target = target[key]
+            resolved = self._resolve_schema(target, specification, (*stack, reference))
+            if not isinstance(resolved, dict):
+                raise RouteConversionError(f"OpenAPI reference is not an object: {reference}")
+            siblings = {key: item for key, item in value.items() if key != "$ref"}
+            resolved.update(self._resolve_schema(siblings, specification, stack))
+            return resolved
+
+        return {
+            key: self._resolve_schema(item, specification, stack)
+            for key, item in value.items()
+            if key not in {"$defs", "definitions"}
+        }

fastapi_webmcp/exceptions.py

@@ -0,0 +1,6 @@
+class FastAPIWebMCPError(RuntimeError):
+    """Base error raised by fastapi-webmcp."""
+
+
+class RouteConversionError(FastAPIWebMCPError):
+    """A selected FastAPI route cannot be represented as a browser tool."""