django-admin-fastmcp 0.1.0__py3-none-any.whl

django_admin_fastmcp/__init__.py

@@ -0,0 +1,3 @@
+"""Expose the Django admin as an MCP server, gated by each user's own admin permissions."""
+
+__version__ = "0.1.0"

django_admin_fastmcp/admin.py

@@ -0,0 +1,59 @@
+"""Read-only audit changelists for McpClient and McpToken (SPEC.md section 8).
+
+Who authorized which client, with which scopes, last used when. Revocation is
+an admin action. Nothing is created by hand: tokens are issued only by the
+OAuth flow. Staff see their own grants, superusers see all.
+"""
+
+from django.contrib import admin
+
+from django_admin_fastmcp.models import McpClient, McpToken
+
+
+class ReadOnlyAdmin(admin.ModelAdmin):
+    mcp_expose = False  # belt and suspenders on top of the built-in denylist
+
+    def has_add_permission(self, request):
+        return False
+
+    def has_change_permission(self, request, obj=None):
+        return False
+
+
+@admin.register(McpClient)
+class McpClientAdmin(ReadOnlyAdmin):
+    list_display = ("name", "client_id", "created_at")
+    search_fields = ("name", "client_id")
+
+
+@admin.register(McpToken)
+class McpTokenAdmin(ReadOnlyAdmin):
+    list_display = (
+        "client",
+        "user",
+        "scope_list",
+        "access_expires_at",
+        "refresh_expires_at",
+        "revoked_at",
+        "last_used_at",
+    )
+    list_filter = ("revoked_at",)
+    actions = ("revoke_grants",)
+
+    @admin.display(description="scopes")
+    def scope_list(self, obj):
+        return ", ".join(obj.scopes)
+
+    def get_queryset(self, request):
+        queryset = super().get_queryset(request).select_related("user", "client")
+        if request.user.is_superuser:
+            return queryset
+        return queryset.filter(user=request.user)
+
+    @admin.action(description="Revoke selected grants", permissions=["view"])
+    def revoke_grants(self, request, queryset):
+        count = 0
+        for grant in queryset:
+            grant.revoke()
+            count += 1
+        self.message_user(request, f"Revoked {count} grant(s).")

django_admin_fastmcp/apps.py

@@ -0,0 +1,11 @@
+from django.apps import AppConfig
+
+
+class DjangoAdminFastmcpConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "django_admin_fastmcp"
+    verbose_name = "Admin MCP"
+
+    def ready(self):
+        # Import registers the system checks (SPEC.md section 3).
+        from django_admin_fastmcp import checks  # noqa: F401

django_admin_fastmcp/auth.py

@@ -0,0 +1,135 @@
+"""DjangoAdminTokenVerifier, RemoteAuthProvider wiring, current_user() (SPEC.md section 8).
+
+The MCP server side of auth: a FastMCP `RemoteAuthProvider` composes the
+verifier with RFC 9728 protected-resource metadata naming the Django site as
+the authorization server.
+"""
+
+import contextvars
+from datetime import timedelta
+
+from asgiref.sync import sync_to_async
+from django.contrib.auth import get_user_model
+from django.utils import timezone
+from fastmcp.server.auth import AccessToken, RemoteAuthProvider, TokenVerifier
+from fastmcp.server.dependencies import get_access_token
+
+from django_admin_fastmcp import conf
+from django_admin_fastmcp.errors import denied
+from django_admin_fastmcp.models import (
+    ACCESS_TOKEN_MARKER,
+    McpToken,
+    constant_time_compare,
+    hash_secret,
+    split_wire_token,
+)
+
+LAST_USED_THROTTLE = timedelta(minutes=1)
+
+# Test hook: the in-memory MCP transport carries no HTTP bearer token, so the
+# test suite impersonates a user here. Production calls never set it.
+_impersonated: contextvars.ContextVar = contextvars.ContextVar(
+    "django_admin_fastmcp_user", default=None
+)
+
+
+class impersonate:
+    """Context manager for tests: run tool calls as `user`."""
+
+    def __init__(self, user):
+        self.user = user
+
+    def __enter__(self):
+        self._token = _impersonated.set(self.user)
+        return self
+
+    def __exit__(self, *exc_info):
+        _impersonated.reset(self._token)
+
+
+class DjangoAdminTokenVerifier(TokenVerifier):
+    """Verify a wire token against McpToken. Every failure path denies."""
+
+    async def verify_token(self, token: str) -> AccessToken | None:
+        return await sync_to_async(self.verify_token_sync)(token)
+
+    def verify_token_sync(self, token: str) -> AccessToken | None:
+        parts = split_wire_token(token)
+        if parts is None or parts[0] != ACCESS_TOKEN_MARKER:
+            return None
+        _, prefix, secret = parts
+        grant = McpToken.objects.filter(access_prefix=prefix).select_related("user").first()
+        if grant is None:
+            return None
+        if not constant_time_compare(hash_secret(secret, grant.salt), grant.access_hash):
+            return None
+        now = timezone.now()
+        if grant.is_revoked or grant.access_expires_at < now:
+            return None
+        if not (grant.user.is_active and grant.user.is_staff):
+            return None
+        expected_resource = conf.get("MCP_URL").rstrip("/")
+        if grant.resource and grant.resource.rstrip("/") != expected_resource:
+            return None
+        if grant.last_used_at is None or now - grant.last_used_at > LAST_USED_THROTTLE:
+            grant.last_used_at = now
+            grant.save(update_fields=["last_used_at"])
+        return AccessToken(
+            token=token,
+            client_id=str(grant.user.pk),
+            scopes=list(grant.scopes),
+            expires_at=int(grant.access_expires_at.timestamp()),
+            resource=grant.resource or None,
+            claims={"user_pk": grant.user.pk, "mcp_client": grant.client.name},
+        )
+
+
+def build_auth() -> RemoteAuthProvider:
+    """Compose the verifier with RFC 9728 protected-resource metadata.
+
+    `base_url` is the origin only. FastMCP appends the mount path to it when
+    the app is built, so the advertised resource comes out equal to MCP_URL,
+    which is what the verifier compares each token's audience against.
+    """
+    return RemoteAuthProvider(
+        token_verifier=DjangoAdminTokenVerifier(),
+        authorization_servers=[conf.get("SITE_URL")],
+        base_url=conf.mcp_origin(),
+        resource_name=conf.get("SERVER_NAME"),
+        scopes_supported=["admin"],
+    )
+
+
+def _access_token():
+    try:
+        return get_access_token()
+    except Exception:
+        return None
+
+
+def current_user():
+    """The Django user behind the current tool call. Denies when absent.
+
+    Runs inside a sync tool, so the ORM is legal here.
+    """
+    override = _impersonated.get()
+    if override is not None:
+        return override
+    access_token = _access_token()
+    if access_token is None:
+        raise denied("no authenticated user on this call")
+    claims = access_token.claims or {}
+    user = get_user_model().objects.filter(pk=claims.get("user_pk")).first()
+    if user is None or not (user.is_active and user.is_staff):
+        raise denied("not a staff user")
+    return user
+
+
+def client_name() -> str:
+    """The OAuth client name, for LogEntry change messages."""
+    if _impersonated.get() is not None:
+        return "test"
+    access_token = _access_token()
+    if access_token is None:
+        return "unknown"
+    return str((access_token.claims or {}).get("mcp_client", "unknown"))

django_admin_fastmcp/checks.py

@@ -0,0 +1,121 @@
+"""Startup validation of the ADMIN_FASTMCP settings (SPEC.md section 3).
+
+A bad value is an error, not a warning. Exceptions: auth.Permission and
+auth.Group exposed and writable is a warning (SPEC.md section 7), because it
+is dangerous rather than broken.
+"""
+
+from urllib.parse import urlsplit
+
+from django.apps import apps
+from django.conf import settings
+from django.core.checks import Error, Warning, register
+from django.utils.module_loading import import_string
+
+from django_admin_fastmcp import conf
+
+PERMISSION_MODELS = ("auth.permission", "auth.group")
+
+
+def _resolves(label: str) -> bool:
+    if label.endswith(".*"):
+        return apps.is_installed(label[:-2]) or bool(
+            [m for m in apps.get_models() if m._meta.app_label == label[:-2]]
+        )
+    try:
+        apps.get_model(label)
+    except (LookupError, ValueError):
+        return False
+    return True
+
+
+@register()
+def check_settings(app_configs, **kwargs):
+    from django_admin_fastmcp.server import all_tools
+
+    errors = []
+    configured = getattr(settings, "ADMIN_FASTMCP", {})
+
+    for key in configured:
+        if key not in conf.DEFAULTS:
+            errors.append(
+                Error(
+                    f"unknown ADMIN_FASTMCP key: {key!r}",
+                    hint=f"known keys: {sorted(conf.DEFAULTS)}",
+                    id="django_admin_fastmcp.E001",
+                )
+            )
+
+    for setting in ("MODELS", "EXCLUDE_MODELS", "WRITABLE_MODELS"):
+        for label in conf.get(setting):
+            if not _resolves(label):
+                errors.append(
+                    Error(
+                        f"ADMIN_FASTMCP[{setting!r}] names {label!r}, "
+                        "which is not an installed model",
+                        id="django_admin_fastmcp.E002",
+                    )
+                )
+
+    known_tools = set(all_tools())
+    for name in conf.get("DISABLED_TOOLS"):
+        if name not in known_tools:
+            errors.append(
+                Error(
+                    f"ADMIN_FASTMCP['DISABLED_TOOLS'] names {name!r}, "
+                    f"which is not a tool. Tools: {sorted(known_tools)}",
+                    id="django_admin_fastmcp.E003",
+                )
+            )
+
+    try:
+        import_string(conf.get("ADMIN_SITE"))
+    except ImportError:
+        errors.append(
+            Error(
+                f"ADMIN_FASTMCP['ADMIN_SITE'] does not import: {conf.get('ADMIN_SITE')!r}",
+                id="django_admin_fastmcp.E004",
+            )
+        )
+
+    # MCP_URL is the path the endpoint is served on and the audience every
+    # token is bound to. A URL with no path would advertise the whole origin
+    # as the protected resource, and the served path would collapse to "/".
+    mcp_parts = urlsplit(conf.get("MCP_URL"))
+    if (
+        mcp_parts.scheme not in ("http", "https")
+        or not mcp_parts.netloc
+        or not mcp_parts.path.strip("/")
+    ):
+        errors.append(
+            Error(
+                f"ADMIN_FASTMCP['MCP_URL'] must be an absolute http(s) URL with a path, "
+                f"got {conf.get('MCP_URL')!r}",
+                hint="for example https://admin.example.com/admin/mcp",
+                id="django_admin_fastmcp.E005",
+            )
+        )
+
+    site_parts = urlsplit(conf.get("SITE_URL"))
+    if site_parts.scheme not in ("http", "https") or not site_parts.netloc:
+        errors.append(
+            Error(
+                f"ADMIN_FASTMCP['SITE_URL'] must be an absolute http(s) URL, "
+                f"got {conf.get('SITE_URL')!r}",
+                hint="it is the OAuth issuer, the Django site that serves the admin login",
+                id="django_admin_fastmcp.E006",
+            )
+        )
+
+    writable = [w.lower() for w in conf.get("WRITABLE_MODELS")]
+    for label in PERMISSION_MODELS:
+        if label in writable:
+            errors.append(
+                Warning(
+                    f"{label} is writable over MCP. An agent that can grant "
+                    "permissions can escape the permission model.",
+                    hint="remove it from ADMIN_FASTMCP['WRITABLE_MODELS']",
+                    id="django_admin_fastmcp.W001",
+                )
+            )
+    return errors

django_admin_fastmcp/conf.py

@@ -0,0 +1,63 @@
+"""One accessor over the ADMIN_FASTMCP settings dict (SPEC.md section 3).
+
+`get(key)` reads a knob from the consumer's `ADMIN_FASTMCP` dict, with the
+defaults below. It raises `KeyError` on an unknown key, which catches typos in
+this package at development time. Typos in consumer settings are caught by
+`checks.py` at startup.
+"""
+
+from typing import Any
+from urllib.parse import urlsplit
+
+from django.conf import settings
+
+DEFAULTS: dict[str, Any] = {
+    "SERVER_NAME": "django-admin",
+    "ADMIN_SITE": "django.contrib.admin.site",
+    "MODELS": (),
+    "EXCLUDE_MODELS": (),
+    "WRITABLE_MODELS": (),
+    "DISABLED_TOOLS": (),
+    "REDACT_FIELDS": ("password", "token", "secret", "api_key", "private_key"),
+    "MAX_PAGE_SIZE": 200,
+    "MAX_PKS": 1000,
+    "ACCESS_TOKEN_TTL_MINUTES": 60,
+    "REFRESH_TOKEN_TTL_DAYS": 90,
+    # Base URL of the Django site, the OAuth issuer. Used in discovery
+    # metadata and advertised by the MCP server as its authorization server.
+    "SITE_URL": "http://127.0.0.1:8000",
+    # Public URL of the MCP endpoint, the OAuth resource. Tokens are
+    # audience-bound to it, and it is the single source of truth for the path
+    # the endpoint is served on. The admin owns "/admin/mcp", next to the
+    # OAuth endpoints at "/admin/mcp/authorize" and friends.
+    "MCP_URL": "http://127.0.0.1:8765/admin/mcp",
+}
+
+
+def get(key: str) -> Any:
+    if key not in DEFAULTS:
+        raise KeyError(f"unknown ADMIN_FASTMCP key: {key}")
+    configured = getattr(settings, "ADMIN_FASTMCP", {})
+    return configured.get(key, DEFAULTS[key])
+
+
+def mcp_origin() -> str:
+    """Scheme and host of MCP_URL, without the path.
+
+    FastMCP builds the resource URL it advertises as `base_url` plus the mount
+    path, so `base_url` must not already carry the path. A `base_url` that
+    includes it makes discovery advertise the path twice, and then the audience
+    the client asks for no longer matches the one the verifier expects.
+    """
+    parts = urlsplit(get("MCP_URL"))
+    return f"{parts.scheme}://{parts.netloc}"
+
+
+def mcp_path() -> str:
+    """The path MCP_URL points at, which is the path the endpoint is served on.
+
+    Always leading-slashed and never trailing-slashed, because FastMCP and
+    Starlette both treat "/admin/mcp" and "/admin/mcp/" as different routes.
+    `checks.py` refuses an MCP_URL with no path at startup.
+    """
+    return "/" + urlsplit(get("MCP_URL")).path.strip("/")

django_admin_fastmcp/errors.py

@@ -0,0 +1,24 @@
+"""ToolError and the denial vocabulary (SPEC.md sections 3 and 5).
+
+Fail closed: every unresolved lookup, missing ModelAdmin, unknown action,
+unknown field, and unknown tool denies the call. `ToolError` is FastMCP's own
+exception, so the message reaches the MCP client verbatim while everything
+else stays masked.
+"""
+
+from fastmcp.exceptions import ToolError
+
+__all__ = ["ToolError", "denied", "not_found"]
+
+
+def denied(reason: str) -> ToolError:
+    """A permission denial. Raise the return value."""
+    return ToolError(f"denied: {reason}")
+
+
+def not_found(label: str, pk: str) -> ToolError:
+    """An object that does not exist or is hidden by get_queryset.
+
+    One message for both cases, so a caller cannot probe for hidden rows.
+    """
+    return ToolError(f"not found: {label} with pk {pk!r}")

django_admin_fastmcp/exposure.py

@@ -0,0 +1,98 @@
+"""Which models are visible, which fields are redacted (SPEC.md section 7).
+
+Default: every model in `admin_site._registry`. Narrowed by EXCLUDE_MODELS
+(with "app_label.*" support), the MODELS allowlist, and `mcp_expose = False`
+on a ModelAdmin. A built-in denylist cannot be overridden: every
+`django_admin_fastmcp` model, `sessions.Session`, and `authtoken.Token`.
+"""
+
+from functools import cache
+
+from django.apps import apps
+from django.contrib.admin import AdminSite, ModelAdmin
+from django.db.models import Model
+from django.utils.module_loading import import_string
+
+from django_admin_fastmcp import conf
+
+# Written through MCP, these would let an agent escalate outside the audit
+# trail. Never exposed, whatever the settings say.
+BUILTIN_DENY_APPS = frozenset({"django_admin_fastmcp"})
+BUILTIN_DENY_MODELS = frozenset({"sessions.session", "authtoken.token"})
+
+
+@cache
+def admin_site() -> AdminSite:
+    return import_string(conf.get("ADMIN_SITE"))
+
+
+def label_of(model: type[Model]) -> str:
+    return f"{model._meta.app_label}.{model.__name__}"
+
+
+def _normalize(label: str) -> str:
+    return label.lower()
+
+
+def _matches(label: str, patterns) -> bool:
+    """True when `label` matches an exact "app.Model" or an "app.*" pattern."""
+    norm = _normalize(label)
+    app_label = norm.split(".", 1)[0]
+    for pattern in patterns:
+        pattern = _normalize(pattern)
+        if pattern == norm:
+            return True
+        if pattern.endswith(".*") and pattern[:-2] == app_label:
+            return True
+    return False
+
+
+def is_exposed(label: str) -> bool:
+    """Fail closed: an unresolvable label is not exposed."""
+    try:
+        model = apps.get_model(label)
+    except (LookupError, ValueError):
+        return False
+    norm = _normalize(label_of(model))
+    if norm.split(".", 1)[0] in BUILTIN_DENY_APPS or norm in BUILTIN_DENY_MODELS:
+        return False
+    if _matches(norm, conf.get("EXCLUDE_MODELS")):
+        return False
+    allowlist = conf.get("MODELS")
+    if allowlist and not _matches(norm, allowlist):
+        return False
+    model_admin = admin_site()._registry.get(model)
+    if model_admin is None:
+        return False
+    return getattr(model_admin, "mcp_expose", True) is not False
+
+
+def exposed_models() -> list[tuple[type[Model], ModelAdmin]]:
+    return [
+        (model, model_admin)
+        for model, model_admin in admin_site()._registry.items()
+        if is_exposed(label_of(model))
+    ]
+
+
+def is_writable(label: str) -> bool:
+    """Both gates: the model is exposed and named in WRITABLE_MODELS."""
+    return is_exposed(label) and _matches(label, conf.get("WRITABLE_MODELS"))
+
+
+def visible_field_names(model_admin: ModelAdmin, all_names: list[str]) -> list[str]:
+    """Apply the per-ModelAdmin `mcp_fields` allowlist and
+    `mcp_exclude_fields` denylist to a list of field names."""
+    allow = getattr(model_admin, "mcp_fields", None)
+    deny = getattr(model_admin, "mcp_exclude_fields", ())
+    names = all_names
+    if allow is not None:
+        names = [n for n in names if n in allow]
+    return [n for n in names if n not in deny]
+
+
+def is_redacted(field_name: str) -> bool:
+    """Substring match against REDACT_FIELDS. An explicit `mcp_fields` entry
+    does not defeat redaction (SPEC.md section 7)."""
+    name = field_name.lower()
+    return any(marker in name for marker in conf.get("REDACT_FIELDS"))

django_admin_fastmcp/management/commands/admin_mcp_serve.py

@@ -0,0 +1,49 @@
+"""Run the FastMCP app under its own uvicorn with lifespan enabled (SPEC.md section 12).
+
+Phase 1: a separate process next to the Django project. Nothing about the
+host application's serving configuration changes. `stateless_http=True`, so
+any instance behind a load balancer can serve any request.
+
+The served path comes from ADMIN_FASTMCP["MCP_URL"], which defaults to
+"/admin/mcp". One setting drives the path, the discovery metadata, and the
+audience the verifier expects, so the three cannot drift apart.
+"""
+
+from urllib.parse import urlsplit
+
+from django.core.management.base import BaseCommand
+
+from django_admin_fastmcp import conf
+
+
+class Command(BaseCommand):
+    help = "Serve the admin MCP server over streamable HTTP."
+
+    def add_arguments(self, parser):
+        parser.add_argument(
+            "--host",
+            default="127.0.0.1",
+            help="Address to bind. Defaults to loopback: put a reverse proxy in front.",
+        )
+        parser.add_argument(
+            "--port",
+            type=int,
+            default=None,
+            help="Port to bind. Defaults to the port in MCP_URL, or 8765.",
+        )
+
+    def handle(self, *args, **options):
+        import uvicorn
+
+        from django_admin_fastmcp.server import BodySizeLimit, build_server
+
+        path = conf.mcp_path()
+        host = options["host"]
+        port = options["port"] or urlsplit(conf.get("MCP_URL")).port or 8765
+
+        app = build_server().http_app(stateless_http=True, path=path)
+        self.stdout.write(
+            f"Serving {conf.get('SERVER_NAME')} on http://{host}:{port}{path}\n"
+            f"Clients must reach it as {conf.get('MCP_URL')}"
+        )
+        uvicorn.run(BodySizeLimit(app), host=host, port=port, lifespan="on")