thin-mcp 0.1.0__py3-none-any.whl

thin_mcp/__init__.py

@@ -0,0 +1,38 @@
+"""Reusable MCP protocol and tool registration infrastructure."""
+
+from thin_mcp.enums import McpHeaderName, McpMethodName
+from thin_mcp.error_codes import JsonRpcErrorCode
+from thin_mcp.protocol import McpRequestHeaders
+from thin_mcp.responses import McpHttpResult
+from thin_mcp.schemas import (
+    EmptyToolArguments,
+    McpRequest,
+    ToolAnnotations,
+    ToolCallParams,
+)
+from thin_mcp.server import McpServer
+from thin_mcp.tools import (
+    ToolContext,
+    ToolExecutionError,
+    ToolPermission,
+    ToolPermissionDenied,
+    ToolRegistry,
+)
+
+__all__ = (
+    "EmptyToolArguments",
+    "JsonRpcErrorCode",
+    "McpHeaderName",
+    "McpHttpResult",
+    "McpMethodName",
+    "McpRequest",
+    "McpRequestHeaders",
+    "McpServer",
+    "ToolAnnotations",
+    "ToolCallParams",
+    "ToolContext",
+    "ToolExecutionError",
+    "ToolPermission",
+    "ToolPermissionDenied",
+    "ToolRegistry",
+)

thin_mcp/django_ninja.py

@@ -0,0 +1,178 @@
+import logging
+import math
+from typing import Any
+
+from django.http import HttpRequest, HttpResponse
+from ninja import NinjaAPI
+from ninja.errors import (
+    AuthenticationError,
+    AuthorizationError,
+    HttpError,
+    Throttled,
+    ValidationError,
+)
+
+from thin_mcp.error_codes import JsonRpcErrorCode
+from thin_mcp.responses import McpHttpResult
+
+logger = logging.getLogger(__name__)
+
+
+def exception_instance[ExceptionT: Exception](
+    exc: ExceptionT | type[ExceptionT],
+) -> ExceptionT:
+    if isinstance(exc, type):
+        raise TypeError("Django Ninja passed an exception type instead of an instance.")
+    return exc
+
+
+class McpAPI(NinjaAPI):
+    """Ninja API with MCP error envelopes and exact transport responses."""
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self.add_exception_handler(AuthenticationError, self.authentication_error)
+        self.add_exception_handler(AuthorizationError, self.authorization_error)
+        self.add_exception_handler(ValidationError, self.validation_error)
+        self.add_exception_handler(Throttled, self.throttled_error)
+        self.add_exception_handler(HttpError, self.http_error)
+        self.add_exception_handler(Exception, self.internal_error)
+
+    def error_response(
+        self,
+        request: HttpRequest,
+        *,
+        status: int,
+        code: int,
+        message: str,
+    ) -> HttpResponse:
+        result = McpHttpResult.error(None, code, message, status=status)
+        if result.body is None:  # pragma: no cover - error always has a body
+            raise RuntimeError("MCP error response has no body.")
+        return self.create_response(
+            request,
+            result.body.model_dump(mode="json", by_alias=True),
+            status=status,
+        )
+
+    def authentication_error(
+        self,
+        request: HttpRequest,
+        exc: AuthenticationError | type[AuthenticationError],
+    ) -> HttpResponse:
+        error = exception_instance(exc)
+        response = self.error_response(
+            request,
+            status=error.status_code,
+            code=JsonRpcErrorCode.SERVER_ERROR,
+            message="Authentication required.",
+        )
+        response["WWW-Authenticate"] = "Bearer"
+        return response
+
+    def authorization_error(
+        self,
+        request: HttpRequest,
+        exc: AuthorizationError | type[AuthorizationError],
+    ) -> HttpResponse:
+        error = exception_instance(exc)
+        return self.error_response(
+            request,
+            status=error.status_code,
+            code=JsonRpcErrorCode.SERVER_ERROR,
+            message=str(error),
+        )
+
+    def validation_error(
+        self,
+        request: HttpRequest,
+        exc: ValidationError | type[ValidationError],
+    ) -> HttpResponse:
+        exception_instance(exc)
+        return self.error_response(
+            request,
+            status=400,
+            code=JsonRpcErrorCode.INVALID_REQUEST,
+            message="Invalid Request.",
+        )
+
+    def http_error(
+        self,
+        request: HttpRequest,
+        exc: HttpError | type[HttpError],
+    ) -> HttpResponse:
+        error = exception_instance(exc)
+        return self.error_response(
+            request,
+            status=error.status_code,
+            code=JsonRpcErrorCode.SERVER_ERROR,
+            message=str(error),
+        )
+
+    def throttled_error(
+        self,
+        request: HttpRequest,
+        exc: Throttled | type[Throttled],
+    ) -> HttpResponse:
+        error = exception_instance(exc)
+        response = self.error_response(
+            request,
+            status=error.status_code,
+            code=JsonRpcErrorCode.SERVER_ERROR,
+            message=str(error),
+        )
+        if error.wait is not None:
+            response["Retry-After"] = str(max(math.ceil(error.wait), 1))
+        return response
+
+    def internal_error(
+        self,
+        request: HttpRequest,
+        exc: Exception | type[Exception],
+    ) -> HttpResponse:
+        error = exception_instance(exc)
+        logger.error("Unhandled MCP request error", exc_info=error)
+        return self.error_response(
+            request,
+            status=500,
+            code=JsonRpcErrorCode.INTERNAL_ERROR,
+            message="Internal error.",
+        )
+
+    def on_exception(
+        self,
+        request: HttpRequest,
+        exc: Exception | type[Exception],
+    ) -> HttpResponse:
+        error = exception_instance(exc)
+        if (
+            isinstance(error, HttpError)
+            and error.status_code == 400
+            and error.__cause__ is not None
+        ):
+            response = render_mcp_result(
+                McpHttpResult.error(
+                    None,
+                    JsonRpcErrorCode.PARSE_ERROR,
+                    "Parse error.",
+                    status=400,
+                )
+            )
+        else:
+            response = super().on_exception(request, error)
+        if hasattr(request, "request_id"):
+            response["X-Request-ID"] = request.request_id
+        return response
+
+
+def render_mcp_result(result: McpHttpResult) -> HttpResponse:
+    if result.body is None:
+        response = HttpResponse(status=result.status)
+    else:
+        response = HttpResponse(
+            result.body.model_dump_json(by_alias=True),
+            content_type="application/json",
+            status=result.status,
+        )
+    response["Cache-Control"] = "no-store"
+    return response

thin_mcp/enums.py

@@ -0,0 +1,17 @@
+from enum import StrEnum
+
+
+class McpHeaderName(StrEnum):
+    PROTOCOL_VERSION = "MCP-Protocol-Version"
+    METHOD = "Mcp-Method"
+    NAME = "Mcp-Name"
+
+
+class McpMethodName(StrEnum):
+    SERVER_DISCOVER = "server/discover"
+    INITIALIZE = "initialize"
+    PING = "ping"
+    TOOLS_LIST = "tools/list"
+    TOOLS_CALL = "tools/call"
+    PROMPTS_GET = "prompts/get"
+    RESOURCES_READ = "resources/read"

thin_mcp/error_codes.py

@@ -0,0 +1,17 @@
+from enum import IntEnum
+
+
+class JsonRpcErrorCode(IntEnum):
+    """JSON-RPC 2.0 error codes used by the MCP server.
+
+    See https://www.jsonrpc.org/specification#error_object.
+    """
+
+    PARSE_ERROR = -32700
+    INVALID_REQUEST = -32600
+    METHOD_NOT_FOUND = -32601
+    INVALID_PARAMS = -32602
+    INTERNAL_ERROR = -32603
+    SERVER_ERROR = -32000
+    HEADER_MISMATCH = -32020
+    UNSUPPORTED_PROTOCOL_VERSION = -32022

thin_mcp/protocol.py

@@ -0,0 +1,119 @@
+"""Per-request MCP metadata and Streamable HTTP header validation."""
+
+import base64
+import re
+from collections.abc import Mapping
+
+from pydantic import BaseModel, ValidationError
+
+from thin_mcp.enums import McpHeaderName, McpMethodName
+from thin_mcp.error_codes import JsonRpcErrorCode
+from thin_mcp.responses import McpHttpResult
+from thin_mcp.schemas import (
+    McpRequest,
+    RequestMetadata,
+    UnsupportedProtocolVersionData,
+)
+
+MODERN_PROTOCOL_VERSION = "2026-07-28"
+PROTOCOL_VERSION_META_KEY = "io.modelcontextprotocol/protocolVersion"
+
+
+class McpRequestHeaders(BaseModel):
+    protocol_version: str | None = None
+    method: str | None = None
+    name: str | None = None
+
+    @classmethod
+    def from_mapping(cls, headers: Mapping[str, str]) -> "McpRequestHeaders":
+        normalized = {key.lower(): value for key, value in headers.items()}
+        return cls(
+            protocol_version=normalized.get(McpHeaderName.PROTOCOL_VERSION.lower()),
+            method=normalized.get(McpHeaderName.METHOD.lower()),
+            name=normalized.get(McpHeaderName.NAME.lower()),
+        )
+
+
+def has_protocol_metadata(request: McpRequest) -> bool:
+    meta = request.params.get("_meta")
+    return isinstance(meta, dict) and PROTOCOL_VERSION_META_KEY in meta
+
+
+def is_modern_version(version: str | None) -> bool:
+    return bool(
+        version
+        and re.fullmatch(r"[0-9]{4}-[0-9]{2}-[0-9]{2}", version)
+        and version >= MODERN_PROTOCOL_VERSION
+    )
+
+
+def uses_modern_protocol(request: McpRequest, headers: McpRequestHeaders) -> bool:
+    if has_protocol_metadata(request):
+        return True
+    # Initialization proposes a version in its params and negotiates a
+    # handshake-era revision even when the HTTP header is newer.
+    return request.method != McpMethodName.INITIALIZE and is_modern_version(
+        headers.protocol_version
+    )
+
+
+def decode_name_header(value: str) -> str:
+    if not re.fullmatch(r"[\x20-\x7e\t]*", value) or value != value.strip():
+        raise ValueError("Invalid header characters.")
+    if value.startswith("=?base64?") and value.endswith("?="):
+        return base64.b64decode(value[9:-2], validate=True).decode("utf-8")
+    return value
+
+
+def validate_modern_request(
+    request: McpRequest,
+    headers: McpRequestHeaders,
+    supported_versions: tuple[str, ...],
+) -> McpHttpResult | None:
+    try:
+        metadata = RequestMetadata.model_validate(request.params.get("_meta"))
+    except ValidationError:
+        return McpHttpResult.error(
+            request.id,
+            JsonRpcErrorCode.INVALID_PARAMS,
+            "Required protocol metadata is missing or invalid.",
+            status=400,
+        )
+
+    mismatched_header: McpHeaderName | None = None
+    if headers.protocol_version != metadata.protocol_version:
+        mismatched_header = McpHeaderName.PROTOCOL_VERSION
+    elif headers.method != request.method:
+        mismatched_header = McpHeaderName.METHOD
+    elif request.method in {
+        McpMethodName.TOOLS_CALL,
+        McpMethodName.PROMPTS_GET,
+        McpMethodName.RESOURCES_READ,
+    }:
+        source = "uri" if request.method == McpMethodName.RESOURCES_READ else "name"
+        try:
+            if headers.name is None or decode_name_header(
+                headers.name
+            ) != request.params.get(source):
+                mismatched_header = McpHeaderName.NAME
+        except ValueError:
+            mismatched_header = McpHeaderName.NAME
+
+    if mismatched_header is not None:
+        return McpHttpResult.error(
+            request.id,
+            JsonRpcErrorCode.HEADER_MISMATCH,
+            f"Missing, malformed, or mismatched {mismatched_header} header.",
+            status=400,
+        )
+    if metadata.protocol_version not in supported_versions:
+        return McpHttpResult.error(
+            request.id,
+            JsonRpcErrorCode.UNSUPPORTED_PROTOCOL_VERSION,
+            "Unsupported protocol version.",
+            status=400,
+            data=UnsupportedProtocolVersionData(
+                supported=list(supported_versions), requested=metadata.protocol_version
+            ),
+        )
+    return None

thin_mcp/py.typed

@@ -0,0 +1 @@
+

thin_mcp/responses.py

@@ -0,0 +1,61 @@
+from dataclasses import dataclass
+
+from pydantic import BaseModel
+
+from thin_mcp.schemas import (
+    JsonRpcError,
+    JsonRpcErrorResponse,
+    JsonRpcResultResponse,
+    McpRequestId,
+    ToolResult,
+)
+
+
+@dataclass(frozen=True)
+class McpHttpResult:
+    """A protocol response together with its HTTP transport status."""
+
+    status: int = 200
+    body: JsonRpcErrorResponse | JsonRpcResultResponse | None = None
+
+    @classmethod
+    def success(
+        cls,
+        request_id: McpRequestId | None,
+        result: BaseModel,
+    ) -> "McpHttpResult":
+        return cls(body=JsonRpcResultResponse(id=request_id, result=result))
+
+    @classmethod
+    def error(
+        cls,
+        request_id: McpRequestId | None,
+        code: int,
+        message: str,
+        *,
+        status: int = 200,
+        data: BaseModel | None = None,
+    ) -> "McpHttpResult":
+        return cls(
+            status=status,
+            body=JsonRpcErrorResponse(
+                id=request_id,
+                error=JsonRpcError(code=code, message=message, data=data),
+            ),
+        )
+
+    @classmethod
+    def accepted(cls) -> "McpHttpResult":
+        return cls(status=202)
+
+    @property
+    def is_error(self) -> bool:
+        return (
+            self.status >= 400
+            or isinstance(self.body, JsonRpcErrorResponse)
+            or (
+                isinstance(self.body, JsonRpcResultResponse)
+                and isinstance(self.body.result, ToolResult)
+                and self.body.result.is_error
+            )
+        )

thin_mcp/schemas.py

@@ -0,0 +1,206 @@
+from typing import Annotated, Any, Literal
+
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    Field,
+    SerializeAsAny,
+    StringConstraints,
+    model_validator,
+)
+
+McpRequestId = str | int
+McpMethod = Annotated[
+    str,
+    StringConstraints(
+        strip_whitespace=True,
+        min_length=1,
+        max_length=128,
+        pattern=r"^[A-Za-z0-9_.\-/]+$",
+    ),
+]
+McpToolName = Annotated[
+    str,
+    StringConstraints(
+        strip_whitespace=True,
+        min_length=1,
+        max_length=128,
+        pattern=r"^[A-Za-z0-9_.\-]+$",
+    ),
+]
+
+
+class McpRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid", strict=True)
+
+    jsonrpc: Literal["2.0"]
+    id: McpRequestId | None = None
+    method: McpMethod
+    params: dict[str, Any] = Field(default_factory=dict)
+
+    @model_validator(mode="after")
+    def validate_request_id(self) -> "McpRequest":
+        if "id" in self.model_fields_set and (
+            self.id is None or isinstance(self.id, bool)
+        ):
+            raise ValueError("Request id must be a string or integer.")
+        return self
+
+    @property
+    def is_notification(self) -> bool:
+        return "id" not in self.model_fields_set
+
+
+class EmptyToolArguments(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+
+class ToolCallParams(BaseModel):
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+
+    name: McpToolName
+    arguments: dict[str, Any] = Field(default_factory=dict)
+    meta: dict[str, Any] = Field(default_factory=dict, alias="_meta")
+
+
+class ImplementationInfo(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+    name: str = Field(min_length=1, max_length=255)
+    version: str = Field(min_length=1, max_length=100)
+
+
+class InitializeParams(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+    protocol_version: str = Field(alias="protocolVersion")
+    capabilities: dict[str, Any]
+    client_info: ImplementationInfo = Field(alias="clientInfo")
+
+
+class RequestMetadata(BaseModel):
+    model_config = ConfigDict(extra="allow", strict=True)
+
+    protocol_version: str = Field(alias="io.modelcontextprotocol/protocolVersion")
+    client_capabilities: dict[str, Any] = Field(
+        alias="io.modelcontextprotocol/clientCapabilities"
+    )
+    client_info: ImplementationInfo | None = Field(
+        default=None, alias="io.modelcontextprotocol/clientInfo"
+    )
+
+
+class ResultMetadata(BaseModel):
+    model_config = ConfigDict(populate_by_name=True)
+
+    server_info: ImplementationInfo = Field(alias="io.modelcontextprotocol/serverInfo")
+
+
+class McpResult(BaseModel):
+    model_config = ConfigDict(populate_by_name=True)
+
+    result_type: Literal["complete"] | None = Field(
+        default=None, alias="resultType", exclude_if=lambda value: value is None
+    )
+    meta: ResultMetadata | None = Field(
+        default=None, alias="_meta", exclude_if=lambda value: value is None
+    )
+
+
+class CacheableResult(McpResult):
+    ttl_ms: int | None = Field(
+        default=None, alias="ttlMs", ge=0, exclude_if=lambda value: value is None
+    )
+    cache_scope: Literal["private", "public"] | None = Field(
+        default=None, alias="cacheScope", exclude_if=lambda value: value is None
+    )
+
+
+class ToolAnnotations(BaseModel):
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    read_only_hint: bool = Field(default=False, alias="readOnlyHint")
+    destructive_hint: bool = Field(default=True, alias="destructiveHint")
+    idempotent_hint: bool = Field(default=False, alias="idempotentHint")
+    open_world_hint: bool = Field(default=True, alias="openWorldHint")
+
+
+class ToolDefinition(BaseModel):
+    model_config = ConfigDict(populate_by_name=True)
+
+    name: McpToolName
+    description: str
+    input_schema: dict[str, Any] = Field(alias="inputSchema")
+    output_schema: dict[str, Any] = Field(alias="outputSchema")
+    annotations: ToolAnnotations = Field(default_factory=ToolAnnotations)
+
+
+class ToolsListResult(CacheableResult):
+    tools: list[ToolDefinition]
+
+
+class TextContent(BaseModel):
+    type: Literal["text"] = "text"
+    text: str
+
+
+class ToolResult(McpResult):
+    model_config = ConfigDict(populate_by_name=True)
+
+    content: list[TextContent]
+    structured_content: SerializeAsAny[BaseModel] | None = Field(
+        default=None,
+        alias="structuredContent",
+        exclude_if=lambda value: value is None,
+    )
+    is_error: bool = Field(default=False, alias="isError")
+
+
+class EmptyResult(McpResult):
+    model_config = ConfigDict(extra="forbid")
+
+
+class ToolCapabilities(BaseModel):
+    list_changed: bool = Field(default=False, alias="listChanged")
+
+
+class ServerCapabilities(BaseModel):
+    tools: ToolCapabilities = Field(default_factory=ToolCapabilities)
+
+
+class InitializeResult(McpResult):
+    model_config = ConfigDict(populate_by_name=True)
+
+    protocol_version: str = Field(alias="protocolVersion")
+    capabilities: ServerCapabilities = Field(default_factory=ServerCapabilities)
+    server_info: ImplementationInfo = Field(alias="serverInfo")
+
+
+class DiscoverResult(CacheableResult):
+    supported_versions: list[str] = Field(alias="supportedVersions")
+    capabilities: ServerCapabilities = Field(default_factory=ServerCapabilities)
+
+
+class UnsupportedProtocolVersionData(BaseModel):
+    supported: list[str]
+    requested: str
+
+
+class JsonRpcError(BaseModel):
+    code: int
+    message: str
+    data: SerializeAsAny[BaseModel] | None = Field(
+        default=None, exclude_if=lambda value: value is None
+    )
+
+
+class JsonRpcErrorResponse(BaseModel):
+    jsonrpc: Literal["2.0"] = "2.0"
+    id: McpRequestId | None
+    error: JsonRpcError
+
+
+class JsonRpcResultResponse(BaseModel):
+    jsonrpc: Literal["2.0"] = "2.0"
+    id: McpRequestId | None
+    result: SerializeAsAny[BaseModel]

thin_mcp/server.py

@@ -0,0 +1,233 @@
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+from pydantic import ValidationError
+
+from thin_mcp.enums import McpMethodName
+from thin_mcp.error_codes import JsonRpcErrorCode
+from thin_mcp.protocol import (
+    McpRequestHeaders,
+    has_protocol_metadata,
+    is_modern_version,
+    uses_modern_protocol,
+    validate_modern_request,
+)
+from thin_mcp.responses import McpHttpResult
+from thin_mcp.schemas import (
+    CacheableResult,
+    DiscoverResult,
+    EmptyResult,
+    ImplementationInfo,
+    InitializeParams,
+    InitializeResult,
+    JsonRpcResultResponse,
+    McpRequest,
+    McpResult,
+    ResultMetadata,
+    ServerCapabilities,
+    ToolCallParams,
+    ToolDefinition,
+    ToolsListResult,
+)
+from thin_mcp.tools import ToolRegistry
+
+
+@dataclass(frozen=True)
+class McpServer:
+    """Configured MCP protocol dispatcher independent of application policy."""
+
+    name: str
+    version: str
+    protocol_versions: tuple[str, ...]
+    tools: ToolRegistry
+
+    def __post_init__(self) -> None:
+        if not self.protocol_versions:
+            raise ValueError("At least one MCP protocol version is required.")
+
+    @property
+    def latest_protocol_version(self) -> str:
+        return self.protocol_versions[-1]
+
+    @property
+    def legacy_protocol_versions(self) -> tuple[str, ...]:
+        return tuple(v for v in self.protocol_versions if not is_modern_version(v))
+
+    @property
+    def modern_protocol_versions(self) -> tuple[str, ...]:
+        return tuple(v for v in self.protocol_versions if is_modern_version(v))
+
+    def get_tool_definitions(self) -> list[ToolDefinition]:
+        return [tool.definition() for tool in self.tools.all()]
+
+    def validate_http_request(
+        self,
+        request: McpRequest,
+        headers: McpRequestHeaders,
+    ) -> McpHttpResult | None:
+        if uses_modern_protocol(request, headers):
+            if self.modern_protocol_versions:
+                return validate_modern_request(
+                    request, headers, self.modern_protocol_versions
+                )
+            return McpHttpResult.error(
+                request.id,
+                JsonRpcErrorCode.SERVER_ERROR,
+                "Unsupported MCP-Protocol-Version.",
+                status=400,
+            )
+        if request.method == McpMethodName.INITIALIZE and self.legacy_protocol_versions:
+            return None
+        if (
+            headers.protocol_version or "2025-03-26"
+        ) not in self.legacy_protocol_versions:
+            return McpHttpResult.error(
+                request.id,
+                JsonRpcErrorCode.SERVER_ERROR,
+                "Unsupported MCP-Protocol-Version.",
+                status=400,
+            )
+        return None
+
+    def format_result(
+        self, request: McpRequest, result: McpHttpResult
+    ) -> McpHttpResult:
+        """Add modern metadata to successful results for modern requests."""
+        if has_protocol_metadata(request) and isinstance(
+            result.body, JsonRpcResultResponse
+        ):
+            if not isinstance(result.body.result, McpResult):
+                raise TypeError("MCP results must inherit McpResult.")
+            body = result.body.result.model_copy(
+                update={
+                    "result_type": "complete",
+                    "meta": ResultMetadata(
+                        **{
+                            "io.modelcontextprotocol/serverInfo": ImplementationInfo(
+                                name=self.name, version=self.version
+                            )
+                        }
+                    ),
+                }
+            )
+            if isinstance(body, CacheableResult):
+                body = body.model_copy(update={"ttl_ms": 0, "cache_scope": "private"})
+            return McpHttpResult(
+                status=result.status,
+                body=result.body.model_copy(update={"result": body}),
+            )
+        return result
+
+    def discover(self, request: McpRequest) -> McpHttpResult:
+        return McpHttpResult.success(
+            request.id,
+            DiscoverResult(supportedVersions=list(self.modern_protocol_versions)),
+        )
+
+    def call_tool(
+        self,
+        user: Any,
+        request: McpRequest,
+        *,
+        resources: tuple[object, ...] = (),
+    ) -> McpHttpResult:
+        try:
+            tool_call = ToolCallParams.model_validate(request.params)
+        except ValidationError:
+            return McpHttpResult.error(
+                request.id,
+                JsonRpcErrorCode.INVALID_PARAMS,
+                "Tool name and arguments are required.",
+            )
+
+        tool = self.tools.get(tool_call.name)
+        if tool is None:
+            return McpHttpResult.error(
+                request.id,
+                JsonRpcErrorCode.INVALID_PARAMS,
+                f"Unknown tool: {tool_call.name}",
+            )
+
+        result = tool.execute(
+            user,
+            tool_call.arguments,
+            resources=resources,
+        )
+        return McpHttpResult.success(request.id, result)
+
+    def initialize(self, request: McpRequest) -> McpHttpResult:
+        if not self.legacy_protocol_versions:
+            return self.method_not_found(request)
+        try:
+            params = InitializeParams.model_validate(request.params)
+        except ValidationError:
+            return McpHttpResult.error(
+                request.id,
+                JsonRpcErrorCode.INVALID_PARAMS,
+                "Invalid initialize parameters.",
+            )
+
+        protocol_version = (
+            params.protocol_version
+            if params.protocol_version in self.legacy_protocol_versions
+            else self.legacy_protocol_versions[-1]
+        )
+        result = InitializeResult(
+            protocolVersion=protocol_version,
+            capabilities=ServerCapabilities(),
+            serverInfo=ImplementationInfo(name=self.name, version=self.version),
+        )
+        return McpHttpResult.success(request.id, result)
+
+    def ping(self, request: McpRequest) -> McpHttpResult:
+        return McpHttpResult.success(request.id, EmptyResult())
+
+    def list_tools(self, request: McpRequest) -> McpHttpResult:
+        result = ToolsListResult(tools=self.get_tool_definitions())
+        return McpHttpResult.success(request.id, result)
+
+    def method_not_found(self, request: McpRequest) -> McpHttpResult:
+        status = 404 if has_protocol_metadata(request) else 200
+        return McpHttpResult.error(
+            request.id,
+            JsonRpcErrorCode.METHOD_NOT_FOUND,
+            "Method not found.",
+            status=status,
+        )
+
+    def dispatch_request(
+        self,
+        user: Any,
+        request: McpRequest,
+        *,
+        resources: tuple[object, ...] = (),
+    ) -> McpHttpResult:
+        return self.format_result(
+            request, self.dispatch_method(user, request, resources=resources)
+        )
+
+    def dispatch_method(
+        self,
+        user: Any,
+        request: McpRequest,
+        *,
+        resources: tuple[object, ...] = (),
+    ) -> McpHttpResult:
+        if request.is_notification:
+            return McpHttpResult.accepted()
+
+        handlers: dict[str, Callable[[], McpHttpResult]] = {
+            McpMethodName.PING: lambda: self.ping(request),
+            McpMethodName.TOOLS_LIST: lambda: self.list_tools(request),
+            McpMethodName.TOOLS_CALL: lambda: self.call_tool(
+                user, request, resources=resources
+            ),
+        }
+        if has_protocol_metadata(request):
+            handlers[McpMethodName.SERVER_DISCOVER] = lambda: self.discover(request)
+        else:
+            handlers[McpMethodName.INITIALIZE] = lambda: self.initialize(request)
+
+        handler = handlers.get(request.method)
+        return handler() if handler is not None else self.method_not_found(request)

thin_mcp/tools.py

@@ -0,0 +1,161 @@
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Any, Protocol, TypeVar
+
+from pydantic import BaseModel, ValidationError
+
+from thin_mcp.schemas import (
+    TextContent,
+    ToolAnnotations,
+    ToolDefinition,
+    ToolResult,
+)
+
+ArgumentsT = TypeVar("ArgumentsT", bound=BaseModel)
+ResultT = TypeVar("ResultT", bound=BaseModel)
+ResourceT = TypeVar("ResourceT")
+ToolHandler = Callable[["ToolContext", ArgumentsT], ResultT]
+
+
+class ToolExecutionError(Exception):
+    """Raised for an expected tool failure that a client can act on."""
+
+
+class ToolPermissionDenied(ToolExecutionError):
+    """Raised when a tool permission rejects the authenticated caller."""
+
+
+@dataclass
+class ToolContext:
+    user: Any
+    resources: dict[type[Any], Any] = field(default_factory=dict)
+
+    def set_resource(self, resource: object) -> None:
+        self.resources[type(resource)] = resource
+
+    def require_resource(self, resource_type: type[ResourceT]) -> ResourceT:
+        try:
+            resource = self.resources[resource_type]
+        except KeyError:
+            raise RuntimeError(
+                f"{resource_type.__name__} permission was not evaluated."
+            ) from None
+        if not isinstance(resource, resource_type):
+            raise TypeError(f"Invalid resource type for {resource_type.__name__}.")
+        return resource
+
+
+class ToolPermission(Protocol):
+    def check(self, context: ToolContext, arguments: BaseModel) -> None:
+        """Raise ToolPermissionDenied when access should be rejected."""
+
+
+def tool_result[ResultT: BaseModel](
+    data: ResultT,
+) -> ToolResult:
+    """Format a structured tool result with a concise text fallback."""
+    return ToolResult(
+        content=[TextContent(text=data.model_dump_json(by_alias=True))],
+        structuredContent=data,
+    )
+
+
+def tool_error_result(message: str) -> ToolResult:
+    """Format an actionable tool failure without violating its output schema."""
+    return ToolResult(
+        content=[TextContent(text=message)],
+        isError=True,
+    )
+
+
+@dataclass(frozen=True)
+class McpTool[ArgumentsT: BaseModel, ResultT: BaseModel]:
+    """One typed, permission-checked MCP tool declaration."""
+
+    name: str
+    description: str
+    arguments_model: type[ArgumentsT]
+    result_model: type[ResultT]
+    handler: ToolHandler[ArgumentsT, ResultT]
+    invalid_arguments_message: str
+    permissions: tuple[ToolPermission, ...] = ()
+    annotations: ToolAnnotations = field(default_factory=ToolAnnotations)
+
+    def definition(self) -> ToolDefinition:
+        return ToolDefinition(
+            name=self.name,
+            description=self.description,
+            inputSchema=self.arguments_model.model_json_schema(),
+            outputSchema=self.result_model.model_json_schema(),
+            annotations=self.annotations,
+        )
+
+    def execute(
+        self,
+        user: Any,
+        raw_arguments: dict[str, Any],
+        *,
+        resources: tuple[object, ...] = (),
+    ) -> ToolResult:
+        try:
+            arguments = self.arguments_model.model_validate(raw_arguments)
+        except ValidationError:
+            return tool_error_result(self.invalid_arguments_message)
+
+        context = ToolContext(user=user)
+        for resource in resources:
+            context.set_resource(resource)
+        try:
+            for permission in self.permissions:
+                permission.check(context, arguments)
+            raw_result = self.handler(context, arguments)
+        except ToolExecutionError as exc:
+            return tool_error_result(str(exc))
+
+        result = self.result_model.model_validate(raw_result)
+        return tool_result(result)
+
+
+class ToolRegistry:
+    """Own an explicit, deterministic set of MCP tool declarations."""
+
+    def __init__(self) -> None:
+        self.tools: dict[str, McpTool[Any, Any]] = {}
+
+    def register(
+        self,
+        *,
+        name: str,
+        description: str,
+        arguments_model: type[ArgumentsT],
+        result_model: type[ResultT],
+        permissions: tuple[ToolPermission, ...] = (),
+        invalid_arguments_message: str = "Invalid tool arguments.",
+        annotations: ToolAnnotations | None = None,
+    ) -> Callable[[ToolHandler[ArgumentsT, ResultT]], ToolHandler[ArgumentsT, ResultT]]:
+        def decorator(
+            handler: ToolHandler[ArgumentsT, ResultT],
+        ) -> ToolHandler[ArgumentsT, ResultT]:
+            if name in self.tools:
+                raise ValueError(f"Duplicate MCP tool name: {name}")
+            self.tools[name] = McpTool(
+                name=name,
+                description=description,
+                arguments_model=arguments_model,
+                result_model=result_model,
+                handler=handler,
+                invalid_arguments_message=invalid_arguments_message,
+                permissions=permissions,
+                annotations=(
+                    annotations if annotations is not None else ToolAnnotations()
+                ),
+            )
+            return handler
+
+        return decorator
+
+    def all(self) -> tuple[McpTool[Any, Any], ...]:
+        return tuple(self.tools.values())
+
+    def get(self, name: str) -> McpTool[Any, Any] | None:
+        return self.tools.get(name)

thin_mcp-0.1.0.dist-info/METADATA

@@ -0,0 +1,206 @@
+Metadata-Version: 2.5
+Name: thin-mcp
+Version: 0.1.0
+Summary: A small typed framework for building MCP tool servers
+Project-URL: Changelog, https://github.com/wild-edge/thin-mcp/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/wild-edge/thin-mcp/issues
+Project-URL: Repository, https://github.com/wild-edge/thin-mcp
+Author: Wild Edge contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: json-rpc,mcp,model-context-protocol,pydantic
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Django
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: pydantic<3,>=2.12
+Provides-Extra: django
+Requires-Dist: django-ninja>=1.5.1; extra == 'django'
+Requires-Dist: django>=4.2; extra == 'django'
+Description-Content-Type: text/markdown
+
+# thin-mcp
+
+`thin-mcp` is a small, typed framework for implementing the tool-serving
+surface of the [Model Context Protocol](https://modelcontextprotocol.io/).
+It connects strict Pydantic models to an explicit tool registry and a
+transport-independent protocol dispatcher.
+
+![How thin-mcp fits into a host application](docs/architecture.svg)
+
+The package deliberately does not own authentication, application permissions,
+throttling, auditing, Django models, or business logic. A Django application
+should provide a small integration package—typically named `mcp_server/`—that
+registers tools from its application domains and connects the framework to its
+HTTP and security layers.
+
+## Why Django Ninja?
+
+Django API projects are often built with Django REST Framework (DRF). For this
+project, I wanted Pydantic models to define and validate the MCP-facing data,
+so I chose Django Ninja for the optional Django HTTP adapter. The protocol
+dispatcher and typed tool registry remain framework-neutral; applications can
+also connect them to another framework, such as FastAPI, with a small route
+adapter.
+
+## Installation
+
+Install the core package:
+
+```bash
+pip install thin-mcp
+```
+
+Install the optional Django Ninja adapter:
+
+```bash
+pip install "thin-mcp[django]"
+```
+
+Python 3.12 or newer and Pydantic 2.12 or newer are required.
+
+## Recommended Django integration
+
+Keep the MCP integration in the host application, separate from both
+`thin_mcp` and the domain applications it exposes:
+
+```text
+my_project/
+├── accounts/
+│   └── services.py
+├── projects/
+│   └── services.py
+└── mcp_server/
+    ├── api.py
+    ├── core.py
+    ├── permissions.py
+    ├── schemas.py
+    ├── tools_registry.py
+    └── tools/
+        ├── __init__.py
+        ├── accounts.py
+        └── projects.py
+```
+
+The recommended pattern is registration-driven:
+
+1. `tools_registry.py` owns one `ToolRegistry` and, when needed, a host-specific
+   `register_tool` wrapper that requires every tool to declare application
+   policy such as token access.
+2. Each `tools/<domain>.py` module defines typed adapters for one Django domain.
+3. `tools/__init__.py` explicitly imports every domain module in stable order.
+   Importing this package populates the shared registry.
+4. `core.py` constructs one `McpServer` with that populated registry.
+5. `api.py` handles HTTP, authentication, throttling, and auditing, then delegates
+   the validated request to `core.py`.
+
+This makes `tools/list` deterministic and ensures the schema advertised for a
+tool is the schema enforced when that tool runs. Avoid filesystem auto-discovery
+or registration hidden in Django app startup hooks.
+
+See [GUIDE.md](GUIDE.md) for a complete generic Django example, permission
+patterns, tests, and migration steps.
+
+## Minimal framework example
+
+```python
+from pydantic import BaseModel, ConfigDict
+
+from thin_mcp import McpRequest, McpServer, ToolContext, ToolRegistry
+
+
+class EchoArguments(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    text: str
+
+
+class EchoResult(BaseModel):
+    text: str
+
+
+registry = ToolRegistry()
+
+
+@registry.register(
+    name="echo",
+    description="Echo typed text.",
+    arguments_model=EchoArguments,
+    result_model=EchoResult,
+)
+def echo(context: ToolContext, arguments: EchoArguments) -> EchoResult:
+    return EchoResult(text=arguments.text)
+
+
+server = McpServer(
+    name="example",
+    version="1.0.0",
+    protocol_versions=("2025-11-25",),
+    tools=registry,
+)
+
+request = McpRequest.model_validate(
+    {
+        "jsonrpc": "2.0",
+        "id": 1,
+        "method": "tools/call",
+        "params": {"name": "echo", "arguments": {"text": "hello"}},
+    }
+)
+response = server.dispatch_request(user=None, request=request)
+```
+
+The host validates transport input into `McpRequest`, supplies its authenticated
+user and request-scoped resources, and serializes the returned `McpHttpResult`.
+Django Ninja hosts can use `thin_mcp.django_ninja.McpAPI` and
+`render_mcp_result` for exception mapping and HTTP serialization.
+
+## Supported MCP surface
+
+The dispatcher currently supports:
+
+- `initialize`
+- `server/discover` for the modern protocol flow
+- `ping`
+- `tools/list`
+- `tools/call`
+- notifications that require no response body
+
+Legacy handshake protocol versions and the modern `2026-07-28` request metadata
+flow are supported. For modern Streamable HTTP requests, the host builds
+`McpRequestHeaders` from the incoming headers, calls
+`server.validate_http_request(request, headers)`, returns any validation result,
+and otherwise dispatches the request. Modern responses include protocol result
+metadata and disable caching for discovery and tool listings.
+
+Resources, prompts, sampling, elicitation, tasks, sessions, server-initiated
+notifications, and streaming are not implemented.
+
+## Development
+
+```bash
+uv sync --extra django --group dev
+uv run ruff check .
+uv run mypy
+uv run pytest
+uv build
+```
+
+Repository contributors should also read [AGENTS.md](AGENTS.md).
+Maintainers can follow [Publishing to PyPI](docs/releasing.md) to configure
+Trusted Publishing and release from GitHub Actions.
+
+## Versioning and license
+
+`thin-mcp` follows Semantic Versioning. Before `1.0.0`, incompatible public API
+changes may be released in a new minor version. After `1.0.0`, incompatible
+changes require a major version.
+
+The package is distributed under the [MIT License](LICENSE).

thin_mcp-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+thin_mcp/__init__.py,sha256=nnJFeKxeSz_vB7xyAvuwP9uwbx2xcAH-Y9WbQrDdgLc,902
+thin_mcp/django_ninja.py,sha256=AkZ1P437r4bXV6XnLloF8bPphfVopSjV7khPMeYxFSs,5480
+thin_mcp/enums.py,sha256=D2e5mMtuP0D_zhT0M5ctDQ8p_KqNfNc3wGuOaB7PREo,401
+thin_mcp/error_codes.py,sha256=DljeLD1S1tq_s71JjFxa7ZjY3mczS5U6dXs8bd5f4zo,423
+thin_mcp/protocol.py,sha256=VNuGLcb-JJH5aYKpDagiQEedfMUdUzeCmazC5UoWigM,4131
+thin_mcp/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+thin_mcp/responses.py,sha256=uubsIeFXu3dqFPNLgiYGPXzbEUqwGCaBcDnk_0S5csg,1536
+thin_mcp/schemas.py,sha256=fMJ4CziCiNHWwenoS-HvH91V8b08PBMM6qqS4YRj8iQ,5772
+thin_mcp/server.py,sha256=xghs2z1bXJnC8L1GD63l05pgCrsOiNsPBU-tws33w0E,7854
+thin_mcp/tools.py,sha256=17FpTvbo94MerGZ_Jmfh8viCP3U4tCpadngvy_xxviY,5262
+thin_mcp-0.1.0.dist-info/METADATA,sha256=juPGqcmSMmqQ0OVL1qZhxrFhq0DstmoqdMkvSunLgZk,6590
+thin_mcp-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+thin_mcp-0.1.0.dist-info/licenses/LICENSE,sha256=i_QprAm_jrQJ6uwQw-4ydj_6XSiCbwqw4HEVe7egVMU,1079
+thin_mcp-0.1.0.dist-info/RECORD,,

thin_mcp-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

thin_mcp-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wild Edge contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.