django-admin-mcp-api 0.1.0a0__py3-none-any.whl

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 django-admin-mcp 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.

django_admin_mcp_api/README.md

@@ -0,0 +1,30 @@
+# `django_admin_mcp_api/`
+
+The shipped package. A Django app + an MCP wire-protocol adapter over
+[`django-admin-rest-api`](https://github.com/MartinCastroAlvarez/django-admin-rest-api).
+
+## What lives here
+
+| File / dir            | Purpose                                                       |
+| --------------------- | ------------------------------------------------------------- |
+| `__init__.py`         | Version + default app config pointer.                          |
+| `apps.py`             | `DjangoAdminMcpApiConfig` — registered via `INSTALLED_APPS`.   |
+| `conf.py`             | The one place to read `DJANGO_ADMIN_MCP_API` settings from.    |
+| `urls.py`             | Two URLs: `POST /` (MCP JSON-RPC) and `GET /manifest/`.         |
+| [`server/`](server/)  | The wire layer (views, JSON-RPC, dispatcher, manifest).         |
+| [`tools/`](tools/)    | One module per MCP tool (16 tools total).                        |
+
+## What must NOT live here
+
+- Database queries.
+- Permission checks (the staff gate in `server/views.py` is the only
+  exception, and it is a baseline — the real check is in rest-api).
+- Serialization.
+- Any new admin behaviour.
+
+## Pointers
+
+- [`../README.md`](../README.md) — user-facing docs.
+- [`../ARCHITECTURE.md`](../ARCHITECTURE.md) — request flow + dispatcher seam.
+- [`../SECURITY.md`](../SECURITY.md) — security invariants.
+- [`../CLAUDE.md`](../CLAUDE.md) — agent contract.

django_admin_mcp_api/__init__.py

@@ -0,0 +1,22 @@
+"""django-admin-mcp-api: an MCP (Model Context Protocol) server for the Django admin.
+
+The package exposes every operation of a consumer's ``ModelAdmin`` as an MCP
+tool, reusing Django's session + CSRF auth and the consumer's existing
+``AdminSite`` registry. See ``ARCHITECTURE.md`` for the full design and
+``SECURITY.md`` for the non-negotiable security rules.
+
+This is the public surface; everything else under ``server/`` and
+``tools/`` is implementation. The Django app config is auto-discovered
+via ``apps.py`` once ``"django_admin_mcp_api"`` is added to
+``INSTALLED_APPS``.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0a0"
+
+# Default Django app config — consumers add ``"django_admin_mcp_api"`` to
+# INSTALLED_APPS and Django picks this up automatically.
+default_app_config = "django_admin_mcp_api.apps.DjangoAdminMcpApiConfig"
+
+__all__ = ["__version__", "default_app_config"]

django_admin_mcp_api/apps.py

@@ -0,0 +1,30 @@
+"""Django app config for django-admin-mcp-api."""
+
+from __future__ import annotations
+
+from django.apps import AppConfig
+
+
+class DjangoAdminMcpApiConfig(AppConfig):
+    """App config for ``django_admin_mcp_api``.
+
+    Registered via ``INSTALLED_APPS``. We deliberately do not perform any
+    side-effects in ``ready()`` other than configuration validation —
+    every endpoint is opt-in through the consumer's URL conf.
+    """
+
+    name = "django_admin_mcp_api"
+    label = "django_admin_mcp_api"
+    verbose_name = "Django Admin MCP API"
+    default_auto_field = "django.db.models.BigAutoField"
+
+    def ready(self) -> None:
+        """Validate settings on app startup.
+
+        Kept light to avoid slow Django boot in test suites. Any future
+        signal wiring goes here.
+        """
+        # Importing the conf module triggers settings validation via
+        # ``django.core.checks``-friendly accessors. See
+        # ``django_admin_mcp_api.conf`` for the actual checks.
+        from django_admin_mcp_api import conf  # noqa: F401

django_admin_mcp_api/conf.py

@@ -0,0 +1,57 @@
+"""Settings accessors for django-admin-mcp-api.
+
+Every consumer-tunable knob is read through this module, never directly
+from ``django.conf.settings``. That keeps defaults and validation in one
+place and makes the surface easy to enumerate in docs.
+
+All settings live under the ``DJANGO_ADMIN_MCP_API`` namespace:
+
+.. code-block:: python
+
+    DJANGO_ADMIN_MCP_API = {
+        "PROTOCOL_VERSION": "2024-11-05",   # MCP spec version we speak
+        "SERVER_NAME": "django-admin",     # advertised via initialize
+        "ADMIN_SITE": "django.contrib.admin.site",  # dotted path
+        "ALLOW_ANONYMOUS": False,          # MUST stay False in production
+    }
+
+Anything not present in the consumer's settings falls back to the
+defaults in :data:`DEFAULTS` below.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from django.conf import settings
+
+# Public settings namespace.
+NAMESPACE = "DJANGO_ADMIN_MCP_API"
+
+# Defaults — the one place to read these from.
+DEFAULTS: dict[str, Any] = {
+    "PROTOCOL_VERSION": "2024-11-05",
+    "SERVER_NAME": "django-admin",
+    "SERVER_VERSION": None,  # falls back to the package __version__
+    "ADMIN_SITE": "django.contrib.admin.site",
+    "ALLOW_ANONYMOUS": False,
+    # The dotted path to a callable returning a Dispatcher. ``None``
+    # means use the built-in default (which raises NotImplementedError
+    # until django-admin-rest-api is wired — tracked in the integration
+    # issue).
+    "DISPATCHER_FACTORY": None,
+}
+
+
+def get(key: str) -> Any:
+    """Return the value for ``key``, falling back to :data:`DEFAULTS`.
+
+    Unknown keys raise :class:`KeyError` rather than silently returning
+    ``None`` — that catches typos in consumer settings during startup.
+    """
+    if key not in DEFAULTS:
+        raise KeyError(f"Unknown {NAMESPACE} setting: {key!r}")
+    bag = getattr(settings, NAMESPACE, {}) or {}
+    if key in bag:
+        return bag[key]
+    return DEFAULTS[key]

django_admin_mcp_api/server/README.md

@@ -0,0 +1,33 @@
+# `django_admin_mcp_api/server/`
+
+The MCP protocol layer. Speaks MCP JSON-RPC and forwards to
+**django-admin-rest-api**. Owns *zero* admin logic.
+
+## What lives here
+
+| Module       | Purpose                                                          |
+| ------------ | ---------------------------------------------------------------- |
+| `views.py`   | `McpEndpointView` (POST → JSON-RPC), `ManifestView` (GET → manifest). |
+| `jsonrpc.py` | JSON-RPC 2.0 request/response envelopes + parse helpers.          |
+| `errors.py`  | MCP / JSON-RPC error code constants.                              |
+| `manifest.py`| Builds the tool catalogue from the `tools/` registry.             |
+| `dispatch.py`| The single forward point into django-admin-rest-api.              |
+
+## What must NOT live here
+
+- Database queries.
+- Permission checks (Django session + CSRF + `ModelAdmin.has_*_permission`
+  are the only auth signals, and they belong to django-admin-rest-api).
+- Field serialization. The rest-api response is forwarded as-is in the
+  MCP `result.content`.
+- Any feature that is not already present in django-admin-rest-api.
+
+If you find yourself reaching for `objects.all()`, `user.has_perm`, or a
+serializer, you are in the wrong package — open the change against
+django-admin-rest-api instead.
+
+## Pointers
+
+- [`../../ARCHITECTURE.md`](../../ARCHITECTURE.md) — the wire shape.
+- [`../../SECURITY.md`](../../SECURITY.md) — the non-negotiables.
+- [`../tools/README.md`](../tools/README.md) — the tool catalogue.

django_admin_mcp_api/server/__init__.py

@@ -0,0 +1,17 @@
+"""MCP server layer.
+
+This package owns the wire protocol (MCP JSON-RPC over HTTP) and nothing
+else. All admin business logic — permissions, querysets, forms,
+serialization, validation — lives in **django-admin-rest-api**. Code here
+must never:
+
+- query the database directly
+- call ``user.has_perm`` or any other permission check
+- serialize or deserialize a model
+- mutate any data
+
+Every MCP tool call is reshaped into the equivalent django-admin-rest-api
+HTTP request and forwarded through the dispatcher (see ``dispatch.py``).
+The response is reshaped back into an MCP JSON-RPC payload. That is all
+this package does.
+"""

django_admin_mcp_api/server/dispatch.py

@@ -0,0 +1,223 @@
+"""The single forward point into django-admin-rest-api.
+
+``Dispatcher`` is the only seam between this package and the underlying
+REST API. Everything else in ``django_admin_mcp_api`` — views, manifest,
+tools — talks to the dispatcher and nothing else. That keeps the
+"protocol-only, no admin logic" invariant easy to enforce: this file is
+the *only* place where the integration shape lives.
+
+## The shape
+
+Each MCP tool call carries ``(tool_name, arguments)``. The dispatcher
+translates that into a ``DispatchTarget`` (HTTP method + path + body)
+against django-admin-rest-api, forwards it through the rest-api view
+matching that path, and returns the ``HttpResponseBase`` for the view
+layer to shape back into a JSON-RPC envelope.
+
+The default implementation is :class:`RestApiDispatcher`, which uses
+Django's URL resolver against ``django_admin_rest_api.api.urls`` to
+find the target view and calls it with a synthetic request that carries
+the original session, user, cookies, and CSRF state.
+
+Consumers can override the dispatcher via the
+``DJANGO_ADMIN_MCP_API["DISPATCHER_FACTORY"]`` setting (a dotted path
+to a zero-arg callable that returns a :class:`Dispatcher`). Tests use
+this seam to swap in a :class:`FakeDispatcher` that records the
+forwards instead of executing them.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from importlib import import_module
+from typing import Any
+from typing import Protocol
+from typing import runtime_checkable
+from urllib.parse import urlencode
+
+from django.http import HttpRequest
+from django.http import HttpResponseBase
+from django.test import RequestFactory
+from django.urls import Resolver404
+from django.urls import resolve
+
+from django_admin_mcp_api import conf
+
+
+@dataclass(frozen=True)
+class DispatchTarget:
+    """A translated MCP tool call, ready to forward to rest-api.
+
+    ``path`` is rooted at the rest-api API root (e.g.
+    ``/<app>/<model>/<pk>/`` — *not* including the ``api/v1/`` prefix or
+    the consumer's mount point; those are handled by the dispatcher).
+    ``body`` is a JSON-serialisable object; the dispatcher encodes it.
+    """
+
+    method: str  # "GET", "POST", "PATCH", "DELETE"
+    path: str
+    body: dict[str, Any] | None = None
+    query: dict[str, str] | None = None
+
+
+@runtime_checkable
+class Dispatcher(Protocol):
+    """The seam to django-admin-rest-api.
+
+    Implementations forward ``target`` against the rest-api views,
+    propagating the consumer's authenticated ``HttpRequest`` (session +
+    CSRF) untouched. They must not mutate the original ``request``.
+    """
+
+    def dispatch(
+        self,
+        *,
+        request: HttpRequest,
+        target: DispatchTarget,
+    ) -> HttpResponseBase: ...
+
+
+class RestApiDispatcher:
+    """Forward a :class:`DispatchTarget` to django-admin-rest-api views.
+
+    Resolves the target's path against ``django_admin_rest_api.api.urls``
+    to find the view function, then constructs a synthetic
+    :class:`HttpRequest` that carries the original request's
+    ``user``, ``session``, cookies, messages backend, and CSRF state.
+    The synthetic request is what rest-api's view sees — auth therefore
+    matches the MCP caller exactly, and rest-api's permission +
+    queryset checks run unchanged.
+
+    The dispatcher does not mutate ``request`` or query the database.
+    """
+
+    URLCONF = "django_admin_rest_api.api.urls"
+
+    def dispatch(
+        self,
+        *,
+        request: HttpRequest,
+        target: DispatchTarget,
+    ) -> HttpResponseBase:
+        synthetic = self._build_synthetic_request(request, target)
+        try:
+            match = resolve(target.path, urlconf=self.URLCONF)
+        except Resolver404 as exc:
+            raise UnknownRestApiPath(target.path) from exc
+        return match.func(synthetic, *match.args, **match.kwargs)
+
+    def _build_synthetic_request(
+        self,
+        request: HttpRequest,
+        target: DispatchTarget,
+    ) -> HttpRequest:
+        factory = RequestFactory()
+        method = target.method.lower()
+        builder = getattr(factory, method, None)
+        if builder is None:
+            raise UnsupportedDispatchMethod(target.method)
+
+        path = target.path
+        if target.query:
+            path = f"{path}?{urlencode(target.query, doseq=True)}"
+
+        kwargs: dict[str, Any] = {}
+        if target.body is not None and target.method.upper() in {"POST", "PATCH", "PUT", "DELETE"}:
+            kwargs["data"] = json.dumps(target.body)
+            kwargs["content_type"] = "application/json"
+
+        synthetic = builder(path, **kwargs)
+
+        # Carry over auth-bearing attributes so rest-api sees the same
+        # caller that the MCP endpoint saw. We do not mutate the
+        # original ``request`` — the synthetic gets its own attributes.
+        synthetic.user = request.user
+        if hasattr(request, "session"):
+            synthetic.session = request.session
+        synthetic.COOKIES = request.COOKIES
+        if hasattr(request, "_messages"):
+            synthetic._messages = request._messages
+        if hasattr(request, "_dont_enforce_csrf_checks"):
+            synthetic._dont_enforce_csrf_checks = request._dont_enforce_csrf_checks
+        return synthetic
+
+
+class PendingDispatcher:
+    """Fallback used when the consumer has not installed rest-api.
+
+    Every call raises :class:`NotImplementedError` with a pointer to the
+    rest-api install step. The :func:`get_dispatcher` factory only
+    falls back to this if importing rest-api fails, so a normal install
+    never sees it.
+    """
+
+    REASON = (
+        "django-admin-rest-api is required at runtime. "
+        "Install it (``pip install django-admin-rest-api``) and add "
+        '"django_admin_rest_api" to INSTALLED_APPS.'
+    )
+
+    def dispatch(
+        self,
+        *,
+        request: HttpRequest,
+        target: DispatchTarget,
+    ) -> HttpResponseBase:
+        del request, target
+        raise NotImplementedError(self.REASON)
+
+
+class UnknownRestApiPath(Exception):
+    """Raised when a tool's path does not resolve against rest-api's URL conf."""
+
+    def __init__(self, path: str) -> None:
+        super().__init__(f"No rest-api view matches {path!r}")
+        self.path = path
+
+
+class UnsupportedDispatchMethod(Exception):
+    """Raised when the target HTTP method is not supported by RequestFactory."""
+
+    def __init__(self, method: str) -> None:
+        super().__init__(f"Unsupported HTTP method {method!r}")
+        self.method = method
+
+
+class ImproperConfiguredDispatcher(Exception):
+    """Raised when ``DISPATCHER_FACTORY`` resolves to something invalid."""
+
+
+def get_dispatcher() -> Dispatcher:
+    """Return the active dispatcher.
+
+    Resolution order:
+
+    1. ``DJANGO_ADMIN_MCP_API["DISPATCHER_FACTORY"]`` — dotted path to
+       a zero-arg callable. Used by tests and by consumers who want to
+       swap in their own forwarder.
+    2. The built-in :class:`RestApiDispatcher`, provided
+       ``django_admin_rest_api`` is importable.
+    3. :class:`PendingDispatcher` — only reached if rest-api is not
+       installed; every call raises :class:`NotImplementedError`.
+    """
+    dotted = conf.get("DISPATCHER_FACTORY")
+    if dotted:
+        module_name, _, attr = dotted.rpartition(".")
+        if not module_name:
+            raise ImproperConfiguredDispatcher(
+                f"DISPATCHER_FACTORY must be a dotted path, got {dotted!r}"
+            )
+        factory = getattr(import_module(module_name), attr)
+        instance = factory()
+        if not isinstance(instance, Dispatcher):
+            raise ImproperConfiguredDispatcher(
+                f"DISPATCHER_FACTORY {dotted!r} returned {type(instance).__name__}, "
+                "which does not satisfy the Dispatcher protocol"
+            )
+        return instance
+    try:
+        import_module("django_admin_rest_api.api.urls")
+    except ImportError:
+        return PendingDispatcher()
+    return RestApiDispatcher()

django_admin_mcp_api/server/errors.py

@@ -0,0 +1,41 @@
+"""JSON-RPC 2.0 + MCP error code constants.
+
+Reference: https://www.jsonrpc.org/specification#error_object and the
+MCP spec error vocabulary. Keeping these in one place means views and
+the dispatcher emit identical codes for identical conditions.
+"""
+
+from __future__ import annotations
+
+# JSON-RPC 2.0 reserved codes (-32768 to -32000).
+PARSE_ERROR = -32700
+INVALID_REQUEST = -32600
+METHOD_NOT_FOUND = -32601
+INVALID_PARAMS = -32602
+INTERNAL_ERROR = -32603
+
+# Implementation-defined server errors (-32000 to -32099). We use a few
+# of these to carry rest-api-layer signals out to the MCP client.
+SERVER_ERROR_UNAUTHENTICATED = -32001
+SERVER_ERROR_FORBIDDEN = -32002
+SERVER_ERROR_NOT_FOUND = -32003
+SERVER_ERROR_CSRF = -32004
+SERVER_ERROR_VALIDATION = -32005
+SERVER_ERROR_UPSTREAM = -32099
+
+
+# Human-readable defaults paired with each code; senders can override the
+# ``message`` field when they have a more specific signal to surface.
+DEFAULT_MESSAGES: dict[int, str] = {
+    PARSE_ERROR: "Parse error",
+    INVALID_REQUEST: "Invalid Request",
+    METHOD_NOT_FOUND: "Method not found",
+    INVALID_PARAMS: "Invalid params",
+    INTERNAL_ERROR: "Internal error",
+    SERVER_ERROR_UNAUTHENTICATED: "Authentication required",
+    SERVER_ERROR_FORBIDDEN: "Permission denied",
+    SERVER_ERROR_NOT_FOUND: "Not found",
+    SERVER_ERROR_CSRF: "CSRF verification failed",
+    SERVER_ERROR_VALIDATION: "Validation error",
+    SERVER_ERROR_UPSTREAM: "Upstream rest-api error",
+}

django_admin_mcp_api/server/jsonrpc.py

@@ -0,0 +1,98 @@
+"""JSON-RPC 2.0 envelope helpers.
+
+The MCP spec rides on JSON-RPC 2.0. These helpers parse incoming
+envelopes and shape outgoing ones; they do not know anything about MCP
+*methods* or *tools* — that's the view's job.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from dataclasses import field
+from typing import Any
+
+from django_admin_mcp_api.server import errors
+
+
+class JsonRpcError(Exception):
+    """Raised by parse helpers; carries a JSON-RPC error code + data.
+
+    Views catch this and shape the response envelope.
+    """
+
+    def __init__(
+        self,
+        code: int,
+        message: str | None = None,
+        data: Any | None = None,
+        *,
+        request_id: Any = None,
+    ) -> None:
+        self.code = code
+        self.message = message or errors.DEFAULT_MESSAGES.get(code, "Error")
+        self.data = data
+        self.request_id = request_id
+        super().__init__(self.message)
+
+
+@dataclass(frozen=True)
+class JsonRpcRequest:
+    """A parsed JSON-RPC 2.0 request envelope."""
+
+    method: str
+    params: dict[str, Any] = field(default_factory=dict)
+    id: Any = None  # noqa: A003 — JSON-RPC field name; not a builtin shadow here.
+    jsonrpc: str = "2.0"
+
+
+def parse_request(payload: Any) -> JsonRpcRequest:
+    """Parse and validate a single JSON-RPC 2.0 request envelope.
+
+    Raises :class:`JsonRpcError` on any structural problem.
+
+    Batch requests (a JSON array) are not supported — the MCP spec uses
+    one request per HTTP POST. If a batch arrives we reject with
+    ``INVALID_REQUEST``.
+    """
+    if not isinstance(payload, dict):
+        raise JsonRpcError(errors.INVALID_REQUEST, "Envelope must be a JSON object")
+    if payload.get("jsonrpc") != "2.0":
+        raise JsonRpcError(errors.INVALID_REQUEST, 'jsonrpc field must be "2.0"')
+    method = payload.get("method")
+    if not isinstance(method, str) or not method:
+        raise JsonRpcError(
+            errors.INVALID_REQUEST,
+            "method must be a non-empty string",
+            request_id=payload.get("id"),
+        )
+    params = payload.get("params", {})
+    if params is None:
+        params = {}
+    if not isinstance(params, dict):
+        raise JsonRpcError(
+            errors.INVALID_PARAMS,
+            "params must be an object",
+            request_id=payload.get("id"),
+        )
+    return JsonRpcRequest(method=method, params=params, id=payload.get("id"))
+
+
+def success(request_id: Any, result: Any) -> dict[str, Any]:
+    """Shape a successful JSON-RPC response envelope."""
+    return {"jsonrpc": "2.0", "id": request_id, "result": result}
+
+
+def failure(
+    request_id: Any,
+    code: int,
+    message: str | None = None,
+    data: Any | None = None,
+) -> dict[str, Any]:
+    """Shape a JSON-RPC error response envelope."""
+    err: dict[str, Any] = {
+        "code": code,
+        "message": message or errors.DEFAULT_MESSAGES.get(code, "Error"),
+    }
+    if data is not None:
+        err["data"] = data
+    return {"jsonrpc": "2.0", "id": request_id, "error": err}

django_admin_mcp_api/server/manifest.py

@@ -0,0 +1,51 @@
+"""Build the MCP server descriptor + tool catalogue."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from django_admin_mcp_api import __version__
+from django_admin_mcp_api import conf
+from django_admin_mcp_api import tools
+
+
+def server_info() -> dict[str, str]:
+    """Return the MCP ``initialize`` server-info block."""
+    return {
+        "name": conf.get("SERVER_NAME"),
+        "version": conf.get("SERVER_VERSION") or __version__,
+    }
+
+
+def initialize_result() -> dict[str, Any]:
+    """Build the result payload for the MCP ``initialize`` method."""
+    return {
+        "protocolVersion": conf.get("PROTOCOL_VERSION"),
+        "serverInfo": server_info(),
+        # We expose tools but no resources/prompts/sampling — those are
+        # not in scope for this adapter (and would require new code in
+        # django-admin-rest-api, which is out of bounds for this package).
+        "capabilities": {
+            "tools": {"listChanged": False},
+        },
+    }
+
+
+def tools_catalogue() -> list[dict[str, Any]]:
+    """Build the ``tools/list`` result payload."""
+    return [tool.to_manifest_entry() for tool in tools.all_tools()]
+
+
+def manifest() -> dict[str, Any]:
+    """Build the read-only GET /manifest/ document.
+
+    This is *not* part of the MCP spec — it's a curl-friendly view of
+    the same content for humans and dashboards. The MCP-spec-correct
+    catalogue is what ``tools/list`` returns; this endpoint wraps it
+    with server metadata so a single GET gives the full picture.
+    """
+    return {
+        "server": server_info(),
+        "protocolVersion": conf.get("PROTOCOL_VERSION"),
+        "tools": tools_catalogue(),
+    }