django-mcp-kit 0.1.0__py3-none-any.whl

django_mcp_kit/__init__.py

@@ -0,0 +1,47 @@
+"""django-mcp-kit -- turn Django/Wagtail code into MCP tools for Claude clients.
+
+Public API: import tools, schema, permissions, and the registry from here.
+"""
+
+from .errors import (
+    BadRequest,
+    Invalid,
+    MCPError,
+    NotAuthenticated,
+    NotFound,
+    PermissionDenied,
+    RateLimited,
+)
+from .permissions import AllowAny, BasePermission, HasDjangoPerm, IsAuthenticated
+from .registry import resource_registry, tool_registry
+from .registry import tool_registry as registry
+from .resources import Resource, resource
+from .schema import Schema
+from .tools import Content, Image, RateLimitedMixin, Tool, tool
+
+__all__ = [
+    "Tool",
+    "tool",
+    "Schema",
+    "Image",
+    "Content",
+    "RateLimitedMixin",
+    "Resource",
+    "resource",
+    "registry",
+    "tool_registry",
+    "resource_registry",
+    "BasePermission",
+    "AllowAny",
+    "IsAuthenticated",
+    "HasDjangoPerm",
+    "MCPError",
+    "BadRequest",
+    "NotFound",
+    "PermissionDenied",
+    "RateLimited",
+    "Invalid",
+    "NotAuthenticated",
+]
+
+default_app_config = "django_mcp_kit.apps.DjangoMCPKitConfig"

django_mcp_kit/apps.py

@@ -0,0 +1,13 @@
+from django.apps import AppConfig
+
+
+class DjangoMCPKitConfig(AppConfig):
+    name = "django_mcp_kit"
+    verbose_name = "Django MCP Kit"
+    default_auto_field = "django.db.models.BigAutoField"
+
+    def ready(self):
+        # Import every app's mcp_tools.py so tools/resources self-register.
+        from .registry import autodiscover
+
+        autodiscover()

django_mcp_kit/asgi.py

@@ -0,0 +1,41 @@
+"""ASGI entrypoints.
+
+``get_application()`` builds the standalone MCP ASGI app from the configured transport
+(``DJANGO_MCP_KIT["TRANSPORT"]``). ``mount()`` composes the MCP app beside an existing
+Django ASGI app for the co-located topology (A).
+"""
+
+from __future__ import annotations
+
+from importlib import import_module
+
+from . import conf
+
+
+def get_application(dispatcher=None):
+    """Build the MCP ASGI app from the configured transport module."""
+    module = import_module(conf.get_setting("TRANSPORT"))
+    return module.build_application(dispatcher)
+
+
+def mount(django_asgi_app, prefix="/mcp"):
+    """Route ``prefix`` (and the MCP app's discovery/health) to the MCP app, and
+    everything else to ``django_asgi_app`` (topology A -- one ASGI process).
+
+    The combined app forwards the ASGI ``lifespan`` to the MCP app so the
+    Streamable-HTTP session manager starts; HTTP requests are dispatched by path.
+    """
+    mcp_app = get_application()
+    mcp_paths = (prefix, "/healthz", "/.well-known/oauth-protected-resource")
+
+    async def application(scope, receive, send):
+        if scope["type"] == "lifespan":
+            await mcp_app(scope, receive, send)
+            return
+        path = scope.get("path", "")
+        if any(path == p or path.startswith(p + "/") or path.startswith(prefix) for p in mcp_paths):
+            await mcp_app(scope, receive, send)
+        else:
+            await django_asgi_app(scope, receive, send)
+
+    return application

django_mcp_kit/auth/__init__.py

@@ -0,0 +1,22 @@
+from .base import (
+    Authenticator,
+    authenticate_request,
+    bearer_token,
+    get_backends,
+    resource_metadata_path,
+    resource_metadata_url,
+)
+from .bearer import StaticBearer
+from .oauth import OAuthResourceServer, protected_resource_metadata
+
+__all__ = [
+    "Authenticator",
+    "StaticBearer",
+    "OAuthResourceServer",
+    "authenticate_request",
+    "bearer_token",
+    "get_backends",
+    "protected_resource_metadata",
+    "resource_metadata_path",
+    "resource_metadata_url",
+]

django_mcp_kit/auth/base.py

@@ -0,0 +1,73 @@
+"""Pluggable authentication for the resource server.
+
+An :class:`Authenticator` validates the incoming request and returns a Django
+``User`` (or ``None``). Backends listed in ``DJANGO_MCP_KIT["AUTH_BACKENDS"]`` are
+tried in order, so a deployment can support OAuth *and* static bearer at once.
+"""
+
+from __future__ import annotations
+
+from urllib.parse import urlparse
+
+from .. import conf
+from ..utils import import_object
+
+
+class Authenticator:
+    def authenticate(self, request):  # pragma: no cover - interface
+        """Return a Django ``User`` or ``None``."""
+        raise NotImplementedError
+
+    def challenge(self):
+        """Optional ``(status, headers)`` to send when no backend authenticates."""
+        return None
+
+
+def bearer_token(request):
+    """Extract a ``Bearer`` token from a Django request or a header-mapping shim."""
+    header = ""
+    headers = getattr(request, "headers", None)
+    if headers is not None:
+        header = headers.get("Authorization") or headers.get("authorization") or ""
+    else:
+        header = getattr(request, "META", {}).get("HTTP_AUTHORIZATION", "")
+    prefix = "Bearer "
+    if header.startswith(prefix):
+        return header[len(prefix):].strip()
+    return None
+
+
+def get_backends():
+    return [import_object(path)() for path in conf.get_setting("AUTH_BACKENDS")]
+
+
+def authenticate_request(request, backends=None):
+    """Try each backend in order.
+
+    Returns ``(user, None)`` on success, or ``(None, (status, headers))`` with the
+    first backend's challenge when nothing authenticates.
+    """
+    backends = backends if backends is not None else get_backends()
+    for backend in backends:
+        user = backend.authenticate(request)
+        if user is not None:
+            return user, None
+    for backend in backends:
+        challenge = backend.challenge()
+        if challenge:
+            return None, challenge
+    return None, (401, {"WWW-Authenticate": "Bearer"})
+
+
+def resource_metadata_path():
+    """RFC 9728 well-known path."""
+    return "/.well-known/oauth-protected-resource"
+
+
+def resource_metadata_url():
+    """Absolute URL of the protected-resource metadata document."""
+    resource = conf.get_setting("RESOURCE_SERVER_URL") or ""
+    parsed = urlparse(resource)
+    if parsed.scheme and parsed.netloc:
+        return f"{parsed.scheme}://{parsed.netloc}{resource_metadata_path()}"
+    return resource_metadata_path()

django_mcp_kit/auth/bearer.py

@@ -0,0 +1,36 @@
+"""Static bearer-token authentication.
+
+Resolves a token to a user via a project-supplied callable, configured as a dotted
+path in ``DJANGO_MCP_KIT["STATIC_BEARER_RESOLVER"]`` (e.g.
+``"myapp.models:UserProfile.user_for_token"``). Keeps the per-user token model that
+Claude Code / Desktop use today.
+"""
+
+from __future__ import annotations
+
+from .. import conf
+from ..utils import import_object
+from .base import Authenticator, bearer_token
+
+
+class StaticBearer(Authenticator):
+    def __init__(self):
+        self._resolver = None
+
+    def resolver(self):
+        if self._resolver is None:
+            path = conf.get_setting("STATIC_BEARER_RESOLVER")
+            self._resolver = import_object(path) if path else False
+        return self._resolver or None
+
+    def authenticate(self, request):
+        token = bearer_token(request)
+        if not token:
+            return None
+        resolve = self.resolver()
+        if resolve is None:
+            return None
+        user = resolve(token)
+        if user is None or not getattr(user, "is_active", False):
+            return None
+        return user

django_mcp_kit/auth/oauth.py

@@ -0,0 +1,53 @@
+"""OAuth 2.1 resource server (django-oauth-toolkit).
+
+Validate a DOT access token, resolve the Django user, and check required scopes. Also provides the RFC 9728
+protected-resource metadata and the ``401 + WWW-Authenticate`` challenge -- these are
+*ours*, not the SDK's.
+
+``oauth2_provider`` is imported lazily, so it's only loaded when this backend is used.
+"""
+
+from __future__ import annotations
+
+from .. import conf
+from .base import Authenticator, bearer_token, resource_metadata_url
+
+
+class OAuthResourceServer(Authenticator):
+    def authenticate(self, request):
+        token = bearer_token(request)
+        if not token:
+            return None
+
+        from oauth2_provider.models import AccessToken as OAuthToken
+
+        oauth_token = (
+            OAuthToken.objects.filter(token=token).select_related("user").first()
+        )
+        if oauth_token is None or not oauth_token.is_valid():
+            return None
+        if oauth_token.user_id is None or not oauth_token.user.is_active:
+            return None
+
+        required = set(conf.get_setting("REQUIRED_SCOPES") or [])
+        granted = set(oauth_token.scope.split() if oauth_token.scope else [])
+        if required and not required <= granted:
+            return None
+
+        return oauth_token.user
+
+    def challenge(self):
+        meta = resource_metadata_url()
+        return 401, {"WWW-Authenticate": f'Bearer resource_metadata="{meta}"'}
+
+
+def protected_resource_metadata():
+    """RFC 9728 metadata document served at /.well-known/oauth-protected-resource."""
+    issuer = conf.get_setting("OAUTH_ISSUER_URL")
+    resource = conf.get_setting("RESOURCE_SERVER_URL")
+    return {
+        "resource": resource,
+        "authorization_servers": [issuer] if issuer else [],
+        "scopes_supported": list(conf.get_setting("REQUIRED_SCOPES") or []),
+        "bearer_methods_supported": ["header"],
+    }

django_mcp_kit/conf.py

@@ -0,0 +1,44 @@
+"""Single access point for the ``DJANGO_MCP_KIT`` settings dict.
+
+Keeping every setting read in one place means the rest of the library never reaches
+into ``django.conf.settings`` directly for its own config.
+"""
+
+from __future__ import annotations
+
+from django.conf import settings
+
+DEFAULTS = {
+    "SERVER_NAME": "django-mcp-kit",
+    "SERVER_VERSION": "0.1.0",
+    "AUTH_BACKENDS": ["django_mcp_kit.auth.StaticBearer"],
+    "TRANSPORT": "django_mcp_kit.transports.sdk",
+    # OAuth resource-server params (see auth/oauth.py):
+    "OAUTH_ISSUER_URL": None,
+    "RESOURCE_SERVER_URL": None,
+    "REQUIRED_SCOPES": ["mcp"],
+    # Name shown on the OAuth consent page (the DOT Application.name).
+    "OAUTH_APP_NAME": "MCP connector",
+    # Transport security: opt-in, off by default.
+    "DNS_REBINDING_PROTECTION": False,
+    "STATELESS": True,
+    "REQUIRE_AUTH": True,
+    # Deployment:
+    "TOPOLOGY": "separate",
+    "PORT": 8810,
+    # StaticBearer token -> user resolver (dotted path to a callable taking a token
+    # string and returning a User or None). e.g. "myapp.models.UserProfile.user_for_token".
+    "STATIC_BEARER_RESOLVER": None,
+    # Per-user write rate limit used by RateLimitedMixin (count, window-seconds).
+    "WRITE_RATE_LIMIT": (30, 60),
+}
+
+
+def get_setting(name, default=None):
+    """Return ``DJANGO_MCP_KIT[name]``, falling back to the built-in default."""
+    cfg = getattr(settings, "DJANGO_MCP_KIT", {}) or {}
+    if name in cfg:
+        return cfg[name]
+    if name in DEFAULTS:
+        return DEFAULTS[name]
+    return default

django_mcp_kit/dispatcher.py

@@ -0,0 +1,155 @@
+"""The transport-neutral MCP dispatcher.
+
+``MCPDispatcher`` owns ``initialize`` / ``tools.list`` / ``tools.call`` and the
+resource methods. It imports **no transport and no MCP SDK** -- transports drive it
+by calling these coroutines and the dispatcher hands back plain dicts. User
+resolution, permission checks, sync/async execution, and result/error formatting all
+live here in one reusable loop.
+
+The authenticated ``user`` is resolved by the transport/auth layer and passed in;
+the dispatcher never authenticates.
+"""
+
+from __future__ import annotations
+
+import inspect
+
+from asgiref.sync import sync_to_async
+
+from . import conf
+from .errors import MCPError, PermissionDenied, from_service_error
+from .registry import resource_registry, tool_registry
+from .resources import match_uri
+from .tools import Content, Image
+
+PROTOCOL_VERSION = "2025-06-18"
+
+
+def _instantiate(perm):
+    """Permission entries may be classes or instances; normalise to instances."""
+    return perm() if isinstance(perm, type) else perm
+
+
+def _content_block(value):
+    """Map a tool's return value to an MCP content block (rich output)."""
+    if isinstance(value, Image):
+        return {"type": "image", "data": value.data, "mimeType": f"image/{value.format}"}
+    if isinstance(value, Content):
+        return {"type": "blob", "blob": value.data, "mimeType": value.mime_type}
+    if isinstance(value, str):
+        return {"type": "text", "text": value}
+    # Default: JSON-serialise into a text block (clients parse it back).
+    import json
+
+    return {"type": "text", "text": json.dumps(value, default=str)}
+
+
+class MCPDispatcher:
+    def __init__(self, *, tools=None, resources=None):
+        self.tools = tools or tool_registry
+        self.resources = resources or resource_registry
+
+    # -- initialize ------------------------------------------------------------
+    def initialize(self):
+        return {
+            "protocolVersion": PROTOCOL_VERSION,
+            "serverInfo": {
+                "name": conf.get_setting("SERVER_NAME"),
+                "version": conf.get_setting("SERVER_VERSION"),
+            },
+            "capabilities": {"tools": {"listChanged": False}, "resources": {}},
+        }
+
+    # -- tools -----------------------------------------------------------------
+    def list_tools(self):
+        out = []
+        for tool in self.tools.all():
+            entry = {
+                "name": tool.name,
+                "description": tool.get_description(),
+                "inputSchema": tool.get_input_schema(),
+            }
+            output_schema = tool.get_output_schema()
+            if output_schema is not None:
+                entry["outputSchema"] = output_schema
+            out.append(entry)
+        return out
+
+    async def call_tool(self, name, arguments=None, *, user=None):
+        """Validate args -> check permissions -> run -> format result.
+
+        Returns ``(content_blocks, is_error)`` so a transport can build either a
+        normal or error tool result without re-deriving the shape.
+        """
+        tool = self.tools.get(name)
+        if tool is None or not tool.is_enabled():
+            return [self._error_text(f"Unknown tool: {name}")], True
+
+        try:
+            kwargs = self._validate(tool, arguments)
+            # Permission classes may hit the ORM (user.has_perm, Wagtail
+            # permissions_for_user), so run them off the event loop too.
+            await sync_to_async(self._check_permissions, thread_sensitive=True)(tool, user, kwargs)
+            await self._maybe_async(tool.pre_run, user, **kwargs)
+            result = await self._maybe_async(tool.run, user, **kwargs)
+        except MCPError as exc:
+            return [self._error_text(exc.message)], True
+        except Exception as exc:  # service-layer / unexpected errors
+            return [self._error_text(from_service_error(exc).message)], True
+
+        return [_content_block(result)], False
+
+    # -- resources -------------------------------------------------------------
+    def list_resources(self):
+        out = []
+        for res in self.resources.all():
+            entry = {
+                "uri": res.uri,
+                "name": res.get_name(),
+                "description": res.get_description(),
+                "mimeType": res.mime_type,
+            }
+            out.append(entry)
+        return out
+
+    async def read_resource(self, uri, *, user=None):
+        res, params = self._resolve_resource(uri)
+        if res is None:
+            raise from_service_error(MCPError(f"Unknown resource: {uri}", status=404))
+        await sync_to_async(self._check_permissions, thread_sensitive=True)(res, user, params)
+        value = await self._maybe_async(res.read, user, **params)
+        block = _content_block(value)
+        text = block.get("text", "")
+        return [{"uri": uri, "mimeType": res.mime_type, "text": text}]
+
+    # -- internals -------------------------------------------------------------
+    def _validate(self, tool, arguments):
+        return tool.validate(arguments)
+
+    def _check_permissions(self, obj, user, kwargs):
+        for perm in getattr(obj, "permission_classes", []):
+            perm = _instantiate(perm)
+            if not perm.has_permission(user, obj, **kwargs):
+                raise PermissionDenied(getattr(perm, "message", "Permission denied."))
+
+    def _resolve_resource(self, uri):
+        # Exact match first, then template match.
+        exact = self.resources.get(uri)
+        if exact is not None:
+            return exact, {}
+        for res in self.resources.all():
+            if res.is_template:
+                params = match_uri(res.uri, uri)
+                if params is not None:
+                    return res, params
+        return None, {}
+
+    async def _maybe_async(self, fn, *args, **kwargs):
+        """Run a tool hook/body: await if async, else off-loop via sync_to_async
+        (so Django's ORM is safe)."""
+        if inspect.iscoroutinefunction(fn):
+            return await fn(*args, **kwargs)
+        return await sync_to_async(fn, thread_sensitive=True)(*args, **kwargs)
+
+    def _error_text(self, message):
+        return {"type": "text", "text": message}