model-context-api 0.1.0__tar.gz

model_context_api-0.1.0/PKG-INFO

@@ -0,0 +1,30 @@
+Metadata-Version: 2.3
+Name: model-context-api
+Version: 0.1.0
+Summary: Model Context API for AI Agents
+Requires-Dist: pydantic>=2.13.5
+Requires-Dist: mcp>=2.2,<3 ; extra == 'mcp'
+Requires-Dist: django>=6.1.1 ; extra == 'ninja'
+Requires-Dist: django-ninja>=1.7.0 ; extra == 'ninja'
+Requires-Python: >=3.13
+Provides-Extra: mcp
+Provides-Extra: ninja
+Description-Content-Type: text/markdown
+
+# MCA
+
+Reusable Model Context API routers for Django Ninja and Pydantic applications.
+
+Install optional integrations only when needed:
+
+```bash
+pip install mca
+pip install "mca[ninja]"
+pip install "mca[mcp]"
+```
+
+Import adapter classes from `mca.pydantic`, `mca.ninja`, and `mca.mcp`; import
+discovery models from `mca.models`. Routers receive a filesystem path to their
+Markdown guides through `guides_dir` and optionally accept `title` and `version`
+for discovery metadata. Route decorators can also receive `guides=[...]` to list
+relevant guide names in operation discovery.

model_context_api-0.1.0/README.md

@@ -0,0 +1,17 @@
+# MCA
+
+Reusable Model Context API routers for Django Ninja and Pydantic applications.
+
+Install optional integrations only when needed:
+
+```bash
+pip install mca
+pip install "mca[ninja]"
+pip install "mca[mcp]"
+```
+
+Import adapter classes from `mca.pydantic`, `mca.ninja`, and `mca.mcp`; import
+discovery models from `mca.models`. Routers receive a filesystem path to their
+Markdown guides through `guides_dir` and optionally accept `title` and `version`
+for discovery metadata. Route decorators can also receive `guides=[...]` to list
+relevant guide names in operation discovery.

model_context_api-0.1.0/mca/__init__.py

@@ -0,0 +1,7 @@
+"""Reusable Model Context API routers and MCP hosting utilities."""
+
+from .base import BaseMCARouter, GuideCatalog, MCAError
+
+__version__ = "0.1.0"
+
+__all__ = ["BaseMCARouter", "GuideCatalog", "MCAError", "__version__"]

model_context_api-0.1.0/mca/base.py

@@ -0,0 +1,346 @@
+"""Framework-neutral MCA route registration and discovery."""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Callable, Iterable, Mapping
+from dataclasses import dataclass, field, replace
+from pathlib import Path
+from typing import Any, TypeVar
+from urllib.parse import unquote
+
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+METHOD_PREFIXES = {
+    "get_": "GET",
+    "make_": "POST",
+    "set_": "PUT",
+    "update_": "PATCH",
+    "remove_": "DELETE",
+}
+_DISCOVERY_OPTIONS = {"guides", "include_in_discovery"}
+
+
+class MCAError(Exception):
+    def __init__(self, code: str, detail: str, field: str | None = None, status: int = 400):
+        super().__init__(detail)
+        self.code = code
+        self.detail = detail
+        self.field = field
+        self.status = status
+
+
+class GuideCatalog:
+    def __init__(self, guides_dir: str | Path):
+        self.root = Path(guides_dir)
+
+    def available(self) -> list[str]:
+        return sorted(path.name for path in self.root.glob("*.md") if path.is_file()) if self.root.is_dir() else []
+
+    def read(self, names: str) -> dict[str, str]:
+        requested, available = [item.strip() for item in names.split(",")], set(self.available())
+        missing = [item for item in requested if not item or item not in available]
+        if missing:
+            raise MCAError(
+                "unknown_guides",
+                f"Unavailable guide(s): {', '.join(missing)}.",
+                "guide",
+                404,
+            )
+        return {name: self.root.joinpath(name).read_text(encoding="utf-8") for name in requested}
+
+
+@dataclass(frozen=True, slots=True)
+class RegisteredRoute:
+    method: str
+    path: str
+    operation: str
+    endpoint: Callable[..., Any]
+    description: str = ""
+    metadata: Mapping[str, Any] = field(default_factory=dict)
+
+    @property
+    def relative_route(self) -> str:
+        return f"{self.method} {self.path}"
+
+    @property
+    def discovery_route(self) -> str:
+        return f"{self.method} {self.path.lstrip('/') or '.'}"
+
+    def meta(self, name: str, default: Any = None) -> Any:
+        return self.metadata.get(name, default)
+
+
+class BaseMCARouter:
+    def __init__(
+        self,
+        *,
+        guides_dir: str | Path,
+        mca_path: str = "/",
+        title: str = "Model Context API",
+        version: float = 1.0,
+    ):
+        self.guide_catalog = GuideCatalog(guides_dir)
+        self.mca_path = mca_path
+        self.title = title
+        self.version = version
+        self._routes: dict[str, RegisteredRoute] = {}
+        for path, operation_id, endpoint, options in self._discovery_endpoints():
+            self._register_endpoint(path, operation_id, endpoint, options)
+
+    def _discovery_endpoints(self) -> Iterable[tuple[str, str, F, Mapping[str, Any]]]:
+        raise NotImplementedError
+
+    def _register_transport_route(
+        self,
+        route: RegisteredRoute,
+        endpoint: F,
+        options: Mapping[str, Any],
+        *,
+        path: str | None = None,
+        operation_id: str | None = None,
+        include_in_schema: bool | None = None,
+    ) -> F:
+        raise NotImplementedError
+
+    def _route_metadata(self, endpoint: F, options: Mapping[str, Any]) -> Mapping[str, Any]:
+        return {}
+
+    @staticmethod
+    def _transport_options(options: Mapping[str, Any]) -> dict[str, Any]:
+        return {key: value for key, value in options.items() if key not in _DISCOVERY_OPTIONS}
+
+    def _route(
+        self,
+        path: str,
+        method: str,
+        operation: str,
+        endpoint: F,
+        options: Mapping[str, Any],
+    ) -> F:
+        metadata = dict(self._route_metadata(endpoint, options))
+        if options.get("guides") is not None:
+            metadata["guides"] = options["guides"]
+        if options.get("include_in_discovery") is False:
+            metadata["include_in_discovery"] = False
+        route = RegisteredRoute(method, path, operation, endpoint,
+            options.get("description") or inspect.getdoc(endpoint) or operation.replace("_", " ").capitalize(),
+            metadata)
+        transport_options = self._transport_options(options)
+        registered_endpoint = self._register_transport_route(route, endpoint, transport_options)
+        self._register_route_variant(route, registered_endpoint, transport_options)
+        self._routes[operation] = replace(route, endpoint=registered_endpoint)
+        return registered_endpoint
+
+    def _register_endpoint(self, path: str, operation: str, endpoint: F, options: Mapping[str, Any]) -> F:
+        method = self._method_for_endpoint(endpoint)
+        self._validate_route_registration(path, method, operation)
+        return self._route(path, method, operation, endpoint, options)
+
+    def _register_route_variant(self, route: RegisteredRoute, endpoint: F, options: Mapping[str, Any]) -> None:
+        canonical_path = route.path.rstrip("/") or "/"
+        if canonical_path == "/":
+            return
+        variant_path = canonical_path[:-1] if route.path.endswith("/") else f"{canonical_path}/"
+        variant_options = dict(options)
+        variant_options["include_in_schema"] = False
+        self._register_transport_route(
+            route,
+            endpoint,
+            variant_options,
+            path=variant_path,
+            operation_id=f"{route.operation}__slash_variant",
+            include_in_schema=False,
+        )
+
+    @staticmethod
+    def _method_for_endpoint(endpoint: Callable[..., Any]) -> str:
+        method = next(
+            (method for prefix, method in METHOD_PREFIXES.items() if endpoint.__name__.startswith(prefix)),
+            None,
+        )
+        if method is None:
+            prefixes = ", ".join(f"{prefix[:-1]}_" for prefix in METHOD_PREFIXES.values())
+            raise ValueError(
+                f"MCA endpoint {endpoint.__name__!r} must start with one of: {prefixes}."
+            )
+        return method
+
+    def register(self, path: str, *, operation_id: str | None = None, **options: Any) -> Callable[[F], F]:
+        def decorator(endpoint: F) -> F:
+            return self._register_endpoint(path, operation_id or endpoint.__name__, endpoint, options)
+        return decorator
+
+    def register_all(
+        self,
+        path: str,
+        *,
+        operation_id: str | None = None,
+        methods: Iterable[str] | None = None,
+        **options: Any,
+    ) -> Callable[[F], F]:
+        def decorator(endpoint: F) -> F:
+            base_operation = operation_id or endpoint.__name__
+            selected_methods = tuple(
+                method.upper()
+                for method in (methods if methods is not None else METHOD_PREFIXES.values())
+            )
+            method_prefixes = {method: prefix for prefix, method in METHOD_PREFIXES.items()}
+            unknown_methods = [method for method in selected_methods if method not in method_prefixes]
+            if unknown_methods:
+                supported_methods = ", ".join(method_prefixes)
+                raise ValueError(f"MCA methods must be selected from: {supported_methods}.")
+            if len(set(selected_methods)) != len(selected_methods):
+                raise ValueError("MCA methods cannot contain duplicates.")
+            if not selected_methods:
+                raise ValueError("MCA register_all requires at least one method.")
+
+            registrations = [
+                (method, f"{method_prefixes[method]}{base_operation}")
+                for method in selected_methods
+            ]
+            for method, operation in registrations:
+                self._validate_route_registration(path, method, operation)
+
+            for method, operation in registrations:
+                self._route(path, method, operation, endpoint, options)
+            return endpoint
+
+        return decorator
+
+    def _validate_route_registration(self, path: str, method: str, operation: str) -> None:
+        if operation in self._routes:
+            raise ValueError(f"MCA operation {operation!r} is already registered.")
+        if any(route.method == method and route.path == path for route in self._routes.values()):
+            raise ValueError(f"MCA route {method} {path!r} is already registered.")
+
+    def routes(self) -> tuple[RegisteredRoute, ...]: return tuple(self._routes.values())
+
+    def route(self, operation: str) -> RegisteredRoute:
+        route = self._routes.get(operation)
+        if route is None:
+            raise MCAError(
+                "unknown_endpoint",
+                f"No endpoint is registered for operation '{operation}'.",
+                "endpoint",
+                404,
+            )
+        return route
+
+    def public_routes(self) -> tuple[tuple[str, str], ...]:
+        return tuple((route.operation, route.relative_route) for route in self._routes.values())
+
+    def resolve(self, method: str, route_path: str) -> tuple[str, dict[str, str]] | None:
+        """Resolve an HTTP method and route path to an operation."""
+        parts = lambda value: (value.rstrip("/") or "/").strip("/").split("/") if value.strip("/") else []
+        path_parts = parts(route_path)
+        routes = sorted(self._routes.values(), key=lambda route: route.path.count("{"))
+
+        for route in routes:
+            if route.method != method.upper():
+                continue
+            route_parts = parts(route.path)
+            if len(route_parts) != len(path_parts):
+                continue
+
+            path_params: dict[str, str] = {}
+            for route_part, path_part in zip(route_parts, path_parts):
+                if route_part.startswith("{") and route_part.endswith("}"):
+                    name = route_part[1:-1].split(":")[-1]
+                    path_params[name] = unquote(path_part)
+                elif route_part != path_part:
+                    break
+            else:
+                return route.operation, path_params
+
+        return None
+
+    def dispatch(
+        self,
+        operation: str | None = None,
+        params: dict[str, Any] | None = None,
+        data: Any = None,
+        *,
+        method: str = "GET",
+    ) -> Any:
+        if operation is None:
+            return self._error("invalid_request", "An operation or route path is required.", "operation")
+
+        if operation.startswith("/"):
+            route_path = operation
+            resolved = self.resolve(method, route_path)
+            if resolved is None:
+                return self._error("unknown_route", f"No route matches {method.upper()} {route_path}.", "path", 404)
+            operation, path_params = resolved
+            params = {**(params or {}), **path_params}
+
+        try:
+            route = self.route(operation)
+            return self._dispatch_registered(route, params, data)
+        except MCAError as exc:
+            return self._dispatch_error(exc)
+
+    def _dispatch_registered(
+        self,
+        route: RegisteredRoute,
+        params: dict[str, Any] | None,
+        data: Any,
+    ) -> Any:
+        raise NotImplementedError
+
+    def _dispatch_error(self, error: MCAError) -> Any:
+        raise error
+
+    def _error(self, code: str, detail: str, field: str | None = None, status: int = 400) -> Any:
+        return self._dispatch_error(MCAError(code, detail, field, status))
+
+    def discovery(
+        self,
+        guide: str | None,
+        operation_name: str | None,
+        schema_factory: Callable[[RegisteredRoute], Any],
+    ) -> dict[str, Any]:
+        if guide is None and operation_name is None:
+            index = self.guide_catalog.read("index.md")["index.md"]
+            return {
+                "title": self.title,
+                "version": self.version,
+                "index": index,
+                "help": (
+                    "Use GET /?guide={names} and/or GET /?operation={names} with "
+                    "comma-separated names to read available guides and operation schemas."
+                ),
+                "available_guides": self.guide_catalog.available(),
+                "available_operations": dict(
+                    sorted(
+                        (
+                            route.operation,
+                            f"{route.discovery_route} - {route.description}",
+                        )
+                        for route in self._routes.values()
+                        if route.operation != "get_mca"
+                        and route.meta("include_in_discovery", True)
+                    )
+                ),
+            }
+
+        result: dict[str, Any] = {}
+        if guide is not None:
+            result["guides"] = self.guide_catalog.read(guide)
+        if operation_name is not None:
+            names = [item.strip() for item in operation_name.split(",")]
+            route_map = dict(self._routes)
+            missing = [name for name in names if not name or name not in route_map]
+            if missing:
+                raise MCAError(
+                    "unknown_operation",
+                    f"Unavailable operation(s): {', '.join(missing)}.",
+                    "operation",
+                    404,
+                )
+            result["operations"] = {
+                name: schema_factory(route_map[name])
+                for name in names
+            }
+        return result

model_context_api-0.1.0/mca/mcp.py

@@ -0,0 +1,270 @@
+"""MCP hosting for applications that publish MCA Ninja routers."""
+
+from __future__ import annotations
+
+from contextlib import AsyncExitStack, asynccontextmanager
+from dataclasses import dataclass
+import json
+from typing import Any
+from urllib.parse import parse_qs, urlsplit
+
+from mcp.server import MCPServer
+from mcp.server.mcpserver.exceptions import ToolError
+
+from .base import MCAError
+from .ninja import NinjaMCARouter
+
+
+BODY_METHODS = {"POST", "PUT", "PATCH"}
+
+
+@dataclass(frozen=True)
+class MCPRoute:
+    app_label: str
+    path: str
+    server: MCPServer
+    application: Any
+
+
+class MCPHost:
+    def __init__(self):
+        self._django_application: Any | None = None
+        self._routes: tuple[MCPRoute, ...] = ()
+
+    @staticmethod
+    def _json_response(response: Any) -> Any:
+        if response.status_code == 204 or not response.content:
+            return None
+        return json.loads(response.content)
+
+    @staticmethod
+    def _tool_error(response: Any) -> ToolError:
+        try:
+            payload = json.loads(response.content)
+        except (TypeError, ValueError, UnicodeDecodeError):
+            payload = {
+                "code": "mcp_endpoint_error",
+                "detail": response.reason_phrase,
+            }
+        if isinstance(payload, dict):
+            payload = {"status": response.status_code, **payload}
+        return ToolError(json.dumps(payload, ensure_ascii=False))
+
+    @staticmethod
+    def _parse_route(route: str) -> tuple[str, str, dict[str, Any]]:
+        if not isinstance(route, str) or not route.strip():
+            raise MCAError("invalid_route", "Route must be a non-empty HTTP method and path.", "route")
+
+        value = route.strip()
+        parts = value.split(None, 1)
+        if len(parts) != 2:
+            raise MCAError("invalid_route", "Route must use the form 'METHOD path'.", "route")
+
+        method, target = parts[0].upper(), parts[1]
+        if not method.isalpha() or any(character.isspace() for character in target):
+            raise MCAError("invalid_route", "Route must use the form 'METHOD path'.", "route")
+
+        try:
+            parsed = urlsplit(target)
+        except ValueError as exc:
+            raise MCAError("invalid_route", "Route must be a valid HTTP method and path.", "route") from exc
+        if parsed.scheme or parsed.netloc or parsed.fragment or not parsed.path:
+            raise MCAError(
+                "invalid_route",
+                "Route must be an API-relative path without a scheme, host, or fragment.",
+                "route",
+            )
+
+        path = parsed.path if parsed.path.startswith("/") else f"/{parsed.path}"
+        values = parse_qs(parsed.query, keep_blank_values=True)
+        query_params = {
+            key: values[0] if len(values) == 1 else values
+            for key, values in values.items()
+        }
+        return method, path, query_params
+
+    def _call_operation(
+        self,
+        registry: NinjaMCARouter,
+        operation: str,
+        path_params: dict[str, Any],
+        query_params: dict[str, Any],
+        body: Any,
+    ) -> str:
+        response = registry.execute_http_request(
+            operation,
+            path_params=path_params,
+            query_params=query_params,
+            body=body,
+            allow_anonymous=True,
+        )
+        if response.status_code >= 400:
+            raise self._tool_error(response)
+        return json.dumps(self._json_response(response), ensure_ascii=False)
+
+    def _call_route(
+        self,
+        registry: NinjaMCARouter,
+        route: str,
+        body: Any,
+        api_base_path: str,
+    ) -> str:
+        method, path, query_params = self._parse_route(route)
+        if path == api_base_path or path.startswith(f"{api_base_path}/"):
+            raise MCAError(
+                "invalid_route",
+                f"Route must be relative to {api_base_path}; omit the API prefix.",
+                "route",
+            )
+        if body is not None and method not in BODY_METHODS:
+            raise MCAError(
+                "invalid_body",
+                f"HTTP {method} routes cannot receive a JSON body.",
+                "body",
+            )
+
+        resolved = registry.resolve(method, path)
+        if resolved is None:
+            raise MCAError(
+                "unknown_route",
+                f"No route matches {method} {path}.",
+                "route",
+                404,
+            )
+
+        operation, path_params = resolved
+        return self._call_operation(registry, operation, path_params, query_params, body)
+
+    def build_server(self, registry: NinjaMCARouter, app_label: str) -> MCPServer:
+        server = MCPServer(f"{app_label} API")
+        tool_name = f"{app_label}_api"
+        rest_base_path = f"/api/{app_label}"
+
+        @server.tool(
+            name=tool_name,
+            description=(
+                f"Call the {app_label} API with an HTTP-style route relative to {rest_base_path}. "
+                "Start with route='GET /' to discover operations, guides and schemas. "
+                "Pass body for JSON request data. Results are JSON text; "
+                "HTTP 204 responses return null. Direct REST access with "
+                f"HTTP/curl at {rest_base_path} is also possible."
+            ),
+            structured_output=False,
+        )
+        def call_api(
+            route: str,
+            body: Any = None,
+        ) -> str:
+            try:
+                return self._call_route(registry, route, body, rest_base_path)
+            except MCAError as exc:
+                raise ToolError(json.dumps({"code": exc.code, "detail": exc.detail, "field": exc.field, "status": exc.status}, ensure_ascii=False)) from exc
+
+        call_api.__name__ = tool_name
+        return server
+
+    def discover_routes(self) -> tuple[MCPRoute, ...]:
+        from django.apps import apps
+        from importlib import import_module
+
+        routes: list[MCPRoute] = []
+        paths: set[str] = set()
+        tool_names: set[str] = set()
+        for app_config in apps.get_app_configs():
+            module_name = f"{app_config.name}.api"
+            try:
+                module = import_module(module_name)
+            except ModuleNotFoundError as exc:
+                if exc.name == module_name:
+                    continue
+                raise
+
+            registry = getattr(module, "mca_registry", None)
+            if registry is None:
+                continue
+            if not isinstance(registry, NinjaMCARouter):
+                raise RuntimeError(
+                    f"MCA application '{app_config.label}' must expose a NinjaMCARouter "
+                    "named 'mca_registry' from its api module."
+                )
+
+            app_label = app_config.label
+            path = f"/api/{app_label}/mcp"
+            tool_name = f"{app_label}_api"
+            if path in paths:
+                raise RuntimeError(f"MCA MCP path '{path}' is registered more than once.")
+            if tool_name in tool_names:
+                raise RuntimeError(f"MCA MCP tool '{tool_name}' is registered more than once.")
+
+            server = self.build_server(registry, app_label)
+            application = server.streamable_http_app(
+                streamable_http_path="/",
+                stateless_http=True,
+            )
+            routes.append(MCPRoute(app_label, path, server, application))
+            paths.add(path)
+            tool_names.add(tool_name)
+
+        return tuple(routes)
+
+    async def _dispatch(self, scope: dict[str, Any], receive: Any, send: Any):
+        self._initialize()
+        if scope.get("type") == "http":
+            path = scope.get("path", "")
+            normalized_path = path.rstrip("/") or "/"
+            for route in self._routes:
+                if normalized_path != route.path:
+                    continue
+
+                mcp_scope = dict(scope)
+                mcp_scope["path"] = "/"
+                mcp_scope["raw_path"] = b"/"
+                mcp_scope["root_path"] = ""
+                return await route.application(mcp_scope, receive, send)
+
+        return await self._django_application(scope, receive, send)
+
+    def _initialize(self) -> None:
+        if self._django_application is not None:
+            return
+
+        from django.core.asgi import get_asgi_application
+
+        self._django_application = get_asgi_application()
+        self._routes = self.discover_routes()
+
+    @asynccontextmanager
+    async def _mcp_lifespan(self):
+        self._initialize()
+        async with AsyncExitStack() as stack:
+            for route in self._routes:
+                await stack.enter_async_context(route.server.session_manager.run())
+            yield
+
+    async def _handle_lifespan(self, receive: Any, send: Any):
+        startup_complete = False
+        try:
+            message = await receive()
+            if message.get("type") != "lifespan.startup":
+                raise RuntimeError("Expected lifespan.startup message.")
+
+            async with self._mcp_lifespan():
+                await send({"type": "lifespan.startup.complete"})
+                startup_complete = True
+                message = await receive()
+                if message.get("type") != "lifespan.shutdown":
+                    raise RuntimeError("Expected lifespan.shutdown message.")
+
+            await send({"type": "lifespan.shutdown.complete"})
+        except Exception as exc:
+            event_type = (
+                "lifespan.shutdown.failed"
+                if startup_complete
+                else "lifespan.startup.failed"
+            )
+            await send({"type": event_type, "message": str(exc)})
+
+    async def __call__(self, scope: dict[str, Any], receive: Any, send: Any):
+        if scope.get("type") == "lifespan":
+            return await self._handle_lifespan(receive, send)
+        return await self._dispatch(scope, receive, send)

model_context_api-0.1.0/mca/models.py

@@ -0,0 +1,61 @@
+"""Shared Pydantic models used by MCA transports."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ErrorOut(BaseModel):
+    code: str = Field(..., description="Stable machine-readable error code.")
+    detail: str = Field(..., description="Human-readable explanation of the error.")
+    field: str | None = Field(None, description="Related input field, when applicable.")
+
+
+class MCAResponseOut(BaseModel):
+    title: str = Field(..., description="Title of the Model Context API discovery document.")
+    version: float = Field(..., description="Version of the discovery document format.")
+    index: str = Field(..., description="Markdown index describing the available API guides.")
+    help: str = Field(..., description="Instructions for requesting guide and schema details.")
+    available_guides: list[str] = Field(..., description="Available packaged Markdown guide names.")
+    available_operations: dict[str, str] = Field(
+        ...,
+        description="Map from operation name to relative route and description.",
+    )
+
+
+class APIRouteSchemaOut(BaseModel):
+    route: str = Field(..., description="HTTP method and relative route template.")
+    description: str = Field(..., description="Human-readable operation description.")
+    guides: list[str] | None = Field(
+        None,
+        exclude_if=lambda value: value is None,
+        description="Relevant guide names for this operation.",
+    )
+    request_schema: dict[str, Any] | None = Field(None, description="Logical operation input schema.")
+    response_schema: dict[str, Any] | None = Field(None, description="Successful response schema.")
+
+
+class MCADiscoveryOut(BaseModel):
+    guides: dict[str, str] | None = Field(
+        None,
+        exclude_if=lambda value: value is None,
+        description="Requested guide names and Markdown content.",
+    )
+    operations: dict[str, APIRouteSchemaOut] | None = Field(
+        None,
+        exclude_if=lambda value: value is None,
+        description="Requested operation schemas.",
+    )
+
+
+class DiscoveryParams(BaseModel):
+    model_config = ConfigDict(populate_by_name=True)
+
+    guide: str | None = Field(None, description="Comma-separated guide names to read.")
+    operation_name: str | None = Field(
+        None,
+        alias="operation",
+        description="Comma-separated operation names whose schemas should be read.",
+    )

model_context_api-0.1.0/mca/ninja.py

@@ -0,0 +1,341 @@
+"""Reusable Model Context API support for Django Ninja APIs."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from copy import deepcopy
+import json
+import inspect
+import re
+from pathlib import Path
+from typing import Any, Callable, TypeVar
+from urllib.parse import quote, urlencode
+
+from django.http import HttpRequest
+from django.http.response import HttpResponseBase
+from ninja import Query
+
+from .base import BaseMCARouter, MCAError, RegisteredRoute
+from .models import APIRouteSchemaOut, MCAResponseOut, MCADiscoveryOut
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+_PATH_PARAMETER = re.compile(r"\{([^}]+)\}")
+
+
+def _request_path(path_template: str, path_params: Mapping[str, Any]) -> str:
+    return _PATH_PARAMETER.sub(
+        lambda match: quote(
+            str(path_params.get(match.group(1), match.group(0))),
+            safe="",
+        ),
+        path_template,
+    )
+
+
+class MCAExecutionError(Exception):
+    def __init__(self, operation: str, detail: str, response: HttpResponseBase | None = None):
+        super().__init__(detail)
+        self.operation = operation
+        self.detail = detail
+        self.response = response
+
+
+class NinjaMCARouter(BaseMCARouter):
+    def __init__(
+        self,
+        api: Any,
+        *,
+        guides_dir: str | Path,
+        mca_path: str = "/",
+        title: str = "Model Context API",
+        version: float = 1.0,
+        error_responses: Mapping[int, Any] | None = None,
+    ):
+        self.api = api
+        self.error_responses = error_responses or {}
+        super().__init__(guides_dir=guides_dir, mca_path=mca_path, title=title, version=version)
+
+    def _discovery_endpoints(self) -> Iterable[tuple[str, str, F, Mapping[str, Any]]]:
+        response = {
+            **self.error_responses,
+            200: MCAResponseOut | MCADiscoveryOut,
+        }
+
+        def get_mca(
+            request: HttpRequest,
+            guide: str | None = Query(None, description="Comma-separated names of Markdown guides to read."),
+            operation_name: str | None = Query(
+                None,
+                alias="operation",
+                description="Comma-separated API operation names whose schemas should be read.",
+            ),
+        ):
+            return self._get_mca(guide, operation_name)
+
+        return (
+            (
+                self.mca_path,
+                "get_mca",
+                get_mca,
+                {"response": response, "description": "Discover API guides and read route schemas."},
+            ),
+        )
+
+    def _register_transport_route(self, route: RegisteredRoute, endpoint: F, options: Mapping[str, Any], **variant: Any) -> F:
+        api_register = getattr(self.api, route.method.lower())
+        route_options = dict(options)
+        route_options.update({key: variant[key] for key in ("include_in_schema",) if key in variant})
+        return api_register(
+            variant.get("path", route.path),
+            operation_id=variant.get("operation_id", route.operation),
+            **route_options,
+        )(endpoint)
+
+    def execute_http(
+        self,
+        operation: str,
+        request: HttpRequest,
+        path_params: Mapping[str, Any] | None = None,
+        *,
+        allow_anonymous: bool = False,
+    ) -> HttpResponseBase:
+        route = self.route(operation)
+        ninja_operation = self._ninja_operation(route.operation)
+        if inspect.iscoroutinefunction(ninja_operation.view_func):
+            raise MCAExecutionError(
+                operation,
+                "Asynchronous endpoints require an asynchronous executor.",
+            )
+
+        if allow_anonymous:
+            request._mca_allow_anonymous = True
+            request._dont_enforce_csrf_checks = True
+
+        return ninja_operation.run(request, **dict(path_params or {}))
+
+    def execute_http_request(
+        self,
+        operation: str,
+        source_request: HttpRequest | None = None,
+        path_params: Mapping[str, Any] | None = None,
+        query_params: Mapping[str, Any] | None = None,
+        body: Any = None,
+        *,
+        allow_anonymous: bool = False,
+    ) -> HttpResponseBase:
+        from django.contrib.auth.models import AnonymousUser
+        from django.test import RequestFactory
+
+        route = self.route(operation)
+        path_values = dict(path_params or {})
+        query_string = urlencode(dict(query_params or {}), doseq=True)
+        path = _request_path(route.path, path_values)
+        if query_string:
+            path = f"{path}?{query_string}"
+
+        request_factory = RequestFactory()
+        if body is None:
+            request = request_factory.generic(route.method, path)
+        else:
+            request = request_factory.generic(
+                route.method,
+                path,
+                data=json.dumps(body).encode("utf-8"),
+                content_type="application/json",
+            )
+
+        if source_request is None:
+            request.user = AnonymousUser()
+        else:
+            request.user = source_request.user
+            request.COOKIES = source_request.COOKIES.copy()
+            if hasattr(source_request, "session"):
+                request.session = source_request.session
+            if getattr(source_request, "_dont_enforce_csrf_checks", False):
+                request._dont_enforce_csrf_checks = True
+            request.META.update(
+                {
+                    key: value
+                    for key, value in source_request.META.items()
+                    if key not in {
+                        "CONTENT_LENGTH",
+                        "CONTENT_TYPE",
+                        "PATH_INFO",
+                        "QUERY_STRING",
+                        "RAW_URI",
+                        "REQUEST_URI",
+                    }
+                }
+            )
+
+        return self.execute_http(
+            operation,
+            request,
+            path_values,
+            allow_anonymous=allow_anonymous,
+        )
+
+    def _ninja_operation(self, operation: str) -> Any:
+        for bound_router in self.api._get_bound_routers():
+            for path_view in bound_router.path_operations.values():
+                for ninja_operation in path_view.operations:
+                    if ninja_operation.operation_id == operation:
+                        return ninja_operation
+        raise MCAExecutionError(
+            operation,
+            f"Ninja has no bound operation for '{operation}'.",
+        )
+
+    def _get_mca(self, guide: str | None, operation_name: str | None):
+        return self.discovery(guide, operation_name, self._route_schema)
+
+    def _openapi_operation(self, name: str) -> dict[str, Any] | None:
+        schema = self.api.get_openapi_schema()
+        for path_data in schema.get("paths", {}).values():
+            for operation in path_data.values():
+                if isinstance(operation, dict) and operation.get("operationId") == name:
+                    return operation
+        return None
+
+    def _route_schema(self, route: RegisteredRoute) -> dict[str, Any]:
+        name = route.operation
+        discovery_route = route.discovery_route
+        operation = self._openapi_operation(name)
+        if operation is None:
+            raise MCAError(
+                "unknown_operation",
+                f"No schema is available for operation '{name}'.",
+                "operation",
+                404,
+            )
+
+        openapi_schema = self.api.get_openapi_schema()
+        components = openapi_schema.get("components", {}).get("schemas", {})
+        path_properties: dict[str, Any] = {}
+        path_required: list[str] = []
+        query_properties: dict[str, Any] = {}
+        query_required: list[str] = []
+        route_path = route.path
+        template_path_parameters = re.findall(r"\{([^}]+)\}", route_path)
+        openapi_path_parameters = [
+            parameter["name"]
+            for parameter in operation.get("parameters", [])
+            if parameter.get("in") == "path"
+        ]
+        path_parameter_names = dict(zip(openapi_path_parameters, template_path_parameters))
+        for parameter in operation.get("parameters", []):
+            parameter_name = path_parameter_names.get(parameter["name"], parameter["name"])
+            parameter_schema = deepcopy(parameter.get("schema", {}))
+            parameter_schema["description"] = parameter.get("description") or f"{parameter_name} request parameter."
+            if parameter.get("in") == "path":
+                properties = path_properties
+                required = path_required
+            else:
+                properties = query_properties
+                required = query_required
+            properties[parameter_name] = parameter_schema
+            if parameter.get("required"):
+                required.append(parameter_name)
+
+        body_schema = (
+            operation.get("requestBody", {})
+            .get("content", {})
+            .get("application/json", {})
+            .get("schema")
+        )
+        request_properties: dict[str, Any] = {}
+        request_required: list[str] = []
+        if path_properties:
+            request_properties["path_params"] = {
+                "description": "Values captured from the operation route.",
+                "type": "object",
+                "properties": path_properties,
+                "required": path_required,
+            }
+            if path_required:
+                request_required.append("path_params")
+        if query_properties:
+            request_properties["query_params"] = {
+                "description": "Values supplied as operation query parameters.",
+                "type": "object",
+                "properties": query_properties,
+                "required": query_required,
+            }
+            if query_required:
+                request_required.append("query_params")
+        if body_schema is not None:
+            request_properties["body"] = {
+                "description": "JSON request body.",
+                **deepcopy(body_schema),
+            }
+            if operation.get("requestBody", {}).get("required"):
+                request_required.append("body")
+
+        request_schema = None
+        if request_properties:
+            request_shape = {
+                "type": "object",
+                "properties": request_properties,
+                "required": request_required,
+            }
+            request_schema = {**request_shape}
+            request_components = self._referenced_components(request_shape, components)
+            if request_components:
+                request_schema["components"] = {"schemas": request_components}
+
+        response_schema = None
+        for status in (200, 201):
+            response_schema = (
+                operation.get("responses", {})
+                .get(status, {})
+                .get("content", {})
+                .get("application/json", {})
+                .get("schema")
+            )
+            if response_schema is not None:
+                break
+        if response_schema is not None:
+            response_schema = deepcopy(response_schema)
+            response_components = self._referenced_components(response_schema, components)
+            if response_components:
+                response_schema["components"] = {"schemas": response_components}
+
+        schema = {
+            "route": discovery_route,
+            "description": operation.get("description") or operation.get("summary") or name,
+            "request_schema": request_schema,
+            "response_schema": response_schema,
+        }
+        if route.meta("guides") is not None:
+            schema["guides"] = route.meta("guides")
+        return schema
+
+    @staticmethod
+    def _referenced_components(
+        schema: Any,
+        components: Mapping[str, Any],
+    ) -> dict[str, Any]:
+        pending = list(NinjaMCARouter._component_references(schema))
+        selected: dict[str, Any] = {}
+        while pending:
+            name = pending.pop()
+            if name in selected or name not in components:
+                continue
+            component = deepcopy(components[name])
+            selected[name] = component
+            pending.extend(NinjaMCARouter._component_references(component))
+        return selected
+
+    @staticmethod
+    def _component_references(value: Any):
+        if isinstance(value, dict):
+            reference = value.get("$ref")
+            prefix = "#/components/schemas/"
+            if isinstance(reference, str) and reference.startswith(prefix):
+                yield reference.removeprefix(prefix)
+            for child in value.values():
+                yield from NinjaMCARouter._component_references(child)
+        elif isinstance(value, list):
+            for child in value:
+                yield from NinjaMCARouter._component_references(child)

model_context_api-0.1.0/mca/pydantic.py

@@ -0,0 +1,260 @@
+"""Reusable Pydantic MCA route registration, discovery, and dispatch."""
+
+from __future__ import annotations
+
+import inspect
+import re
+from collections.abc import Iterable, Mapping
+from copy import deepcopy
+from typing import Any, Callable, TypeVar, get_type_hints
+
+from pydantic import BaseModel, TypeAdapter, ValidationError
+
+from .base import BaseMCARouter, MCAError, RegisteredRoute
+from .models import (
+    APIRouteSchemaOut,
+    DiscoveryParams,
+    ErrorOut,
+    MCAResponseOut,
+    MCADiscoveryOut,
+)
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+class DispatchValidationError(ValueError):
+    """Raised when dispatch input or output does not match its route schema."""
+
+    def __init__(self, source: str, errors: list[dict[str, Any]]):
+        self.source = source
+        self.errors = errors
+        super().__init__(f"Invalid {source}.")
+
+
+def _validate_for_dispatch(annotation: Any, value: Any, source: str) -> Any:
+    if annotation is None:
+        return value
+    try:
+        return TypeAdapter(annotation).validate_python(value)
+    except ValidationError as exc:
+        raise DispatchValidationError(source, exc.errors()) from exc
+
+
+def _validation_error_response(exc: DispatchValidationError) -> ErrorOut:
+    first_error = exc.errors[0] if exc.errors else {}
+    location = first_error.get("loc", ())
+    field = ".".join(str(part) for part in location) or exc.source
+    code = "invalid_response" if exc.source == "response" else "invalid_request"
+    return ErrorOut(
+        code=code,
+        detail=str(first_error.get("msg", "Validation failed.")),
+        field=field,
+    )
+
+
+class PydanticMCARouter(BaseMCARouter):
+    def _discovery_endpoints(self) -> Iterable[tuple[str, str, F, Mapping[str, Any]]]:
+        def get_mca(params: DiscoveryParams) -> MCAResponseOut | MCADiscoveryOut:
+            return self._get_mca(params)
+
+        return (
+            (
+                self.mca_path,
+                "get_mca",
+                get_mca,
+                {"description": "Discover engine guides and read operation schemas."},
+            ),
+        )
+
+    def _register_transport_route(self, route: RegisteredRoute, endpoint: F, options: Mapping[str, Any], **_: Any) -> F:
+        return endpoint
+
+    def _route_metadata(self, endpoint: F, options: Mapping[str, Any]) -> Mapping[str, Any]:
+        parameters = inspect.signature(endpoint).parameters
+        type_hints = get_type_hints(endpoint)
+        params_parameter = parameters.get("params")
+        body_parameter = parameters.get("data")
+        return {
+            "params_type": type_hints.get("params") if "params" in parameters else None,
+            "body_type": type_hints.get("data") if "data" in parameters else None,
+            "response_type": type_hints.get("return"),
+            "params_required": (
+                params_parameter is not None
+                and params_parameter.default is inspect.Parameter.empty
+            ),
+            "body_required": (
+                body_parameter is not None
+                and body_parameter.default is inspect.Parameter.empty
+            ),
+        }
+
+    @staticmethod
+    def _schema_parts(annotation: Any) -> tuple[dict[str, Any], dict[str, Any]]:
+        if annotation is None or annotation is Any:
+            return {}, {}
+        schema = TypeAdapter(annotation).json_schema(
+            ref_template="#/components/schemas/{model}"
+        )
+        components = schema.pop("$defs", {})
+        return schema, components
+
+    @staticmethod
+    def _is_model_type(annotation: Any) -> bool:
+        return isinstance(annotation, type) and issubclass(annotation, BaseModel)
+
+    @classmethod
+    def _referenced_schema(
+        cls,
+        annotation: Any,
+    ) -> tuple[dict[str, Any], dict[str, Any]]:
+        schema, components = cls._schema_parts(annotation)
+        if cls._is_model_type(annotation):
+            name = annotation.__name__
+            components[name] = schema
+            return {"$ref": f"#/components/schemas/{name}"}, components
+        return schema, components
+
+    @staticmethod
+    def _path_parameter_names(route: str) -> set[str]:
+        return {
+            parameter.split(":")[-1]
+            for parameter in re.findall(r"\{([^}]+)\}", route)
+        }
+
+    def _route_schema(self, route: RegisteredRoute) -> APIRouteSchemaOut:
+        request_properties: dict[str, Any] = {}
+        request_required: list[str] = []
+        components: dict[str, Any] = {}
+
+        params_type = route.meta("params_type")
+        body_type = route.meta("body_type")
+        response_type = route.meta("response_type")
+        params_schema, params_components = self._schema_parts(params_type)
+        components.update(params_components)
+        params_properties = params_schema.get("properties", {})
+        params_required = set(params_schema.get("required", []))
+        path_names = self._path_parameter_names(route.path)
+
+        path_properties: dict[str, Any] = {}
+        path_required: list[str] = []
+        query_properties: dict[str, Any] = {}
+        query_required: list[str] = []
+        for name, property_schema in params_properties.items():
+            property_schema = deepcopy(property_schema)
+            property_schema.setdefault("description", f"{name} request parameter.")
+            if name in path_names:
+                path_properties[name] = property_schema
+                path_required.append(name)
+            else:
+                query_properties[name] = property_schema
+                if name in params_required:
+                    query_required.append(name)
+
+        if path_properties:
+            request_properties["path_params"] = {
+                "description": "Values captured from the selected operation route.",
+                "type": "object",
+                "properties": path_properties,
+                "required": path_required,
+            }
+            request_required.append("path_params")
+        if query_properties:
+            request_properties["query_params"] = {
+                "description": "Values supplied as operation query parameters.",
+                "type": "object",
+                "properties": query_properties,
+                "required": query_required,
+            }
+            if query_required:
+                request_required.append("query_params")
+
+        body_required = bool(route.meta("body_required"))
+        if body_type is not None and body_type is not Any:
+            body_schema, body_components = self._referenced_schema(body_type)
+            components.update(body_components)
+            request_properties["body"] = {
+                "description": "JSON request body.",
+                **body_schema,
+            }
+            if body_required:
+                request_required.append("body")
+
+        request_schema = None
+        if request_properties:
+            request_schema = {
+                "type": "object",
+                "properties": request_properties,
+                "required": request_required,
+            }
+            if components:
+                request_schema["components"] = {"schemas": components}
+
+        response_schema = None
+        if response_type is not None and response_type is not Any:
+            response_schema, response_components = self._referenced_schema(response_type)
+            if response_components:
+                response_schema["components"] = {"schemas": response_components}
+
+        return APIRouteSchemaOut(
+            route=route.discovery_route,
+            description=route.description,
+            guides=route.meta("guides"),
+            request_schema=request_schema,
+            response_schema=response_schema,
+        )
+
+    def _get_mca(self, params: DiscoveryParams) -> MCAResponseOut | MCADiscoveryOut:
+        result = self.discovery(params.guide, params.operation_name, self._route_schema)
+        if params.guide is None and params.operation_name is None:
+            return MCAResponseOut(**result)
+        return MCADiscoveryOut(**result)
+
+    def _dispatch_registered(
+        self,
+        route: RegisteredRoute,
+        params: dict[str, Any] | None,
+        data: Any,
+    ) -> Any:
+        params_type = route.meta("params_type")
+        body_type = route.meta("body_type")
+        validated_params = _validate_for_dispatch(params_type, {} if params is None else params, "params")
+        validated_body = _validate_for_dispatch(body_type, data, "data")
+
+        kwargs: dict[str, Any] = {}
+        if params_type is not None:
+            kwargs["params"] = validated_params
+        if body_type is not None:
+            kwargs["data"] = validated_body
+
+        result = route.endpoint(**kwargs)
+        return _validate_for_dispatch(route.meta("response_type"), result, "response")
+
+    def _dispatch_error(self, error: MCAError) -> ErrorOut:
+        code = "unknown_operation" if error.code == "unknown_endpoint" else error.code
+        field = "operation" if error.code == "unknown_endpoint" else error.field
+        return ErrorOut(code=code, detail=error.detail, field=field)
+
+    def dispatch(
+        self,
+        operation: str | None = None,
+        params: dict[str, Any] | None = None,
+        data: Any = None,
+        *,
+        method: str = "GET",
+    ) -> Any:
+        try:
+            return super().dispatch(
+                operation,
+                params,
+                data,
+                method=method,
+            )
+        except DispatchValidationError as exc:
+            return _validation_error_response(exc)
+        except MCAError as exc:
+            return self._dispatch_error(exc)
+        except Exception:
+            return ErrorOut(
+                code="internal_error",
+                detail="The endpoint could not complete the operation.",
+                field="operation",
+            )

model_context_api-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[project]
+name = "model-context-api"
+version = "0.1.0"
+description = "Model Context API for AI Agents"
+readme = "README.md"
+requires-python = ">=3.13"
+
+dependencies = [
+    "pydantic>=2.13.5",
+]
+
+[project.optional-dependencies]
+ninja = [
+    "django>=6.1.1",
+    "django-ninja>=1.7.0",
+]
+mcp = [
+    "mcp>=2.2,<3",
+]
+
+[build-system]
+requires = ["uv_build>=0.10.8,<0.11.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "mca"
+module-root = ""
+
+[dependency-groups]
+dev = [
+    "pre-commit>=4.6.2",
+]