drf-react-by-schema-mcp 0.3.6__py3-none-any.whl

drf_react_by_schema_mcp/__init__.py

@@ -0,0 +1,27 @@
+"""
+drf-react-by-schema-mcp
+=======================
+
+Generic, schema-driven **MCP server** for `drf-react-by-schema
+<https://gitlab.com/eita/drf-react-by-schema>`_ (DRBS) projects.
+
+It exposes any DRBS project's DRF API (``/api/...``) to MCP clients such as
+`opencode <https://opencode.ai>`_ through a small set of generic tools —
+``consultar``, ``resumo``, ``criar``, ``editar``, ``minha_conta`` — plus the
+schema-aware ``knowledge`` tool and per-project shortcuts.
+
+The server is a **stateless proxy**: it takes the caller's OAuth 2.1 Bearer
+token (issued by ``drf-react-by-schema-oauth``), forwards it to the project's
+``/api/...`` and lets the project's own DRF permissions scope the data. It
+stores **no credentials**.
+
+Adding ``drbs_mcp`` to ``INSTALLED_APPS``, including this package's URLs and
+setting ``DRBS_MCP`` is enough to mount the server; reads are enabled by default
+and writes are opt-in.
+"""
+
+__version__ = "0.3.6"
+
+from .settings import get_setting  # noqa: E402
+
+__all__ = ["__version__", "get_setting"]

drf_react_by_schema_mcp/apps.py

@@ -0,0 +1,30 @@
+from django.apps import AppConfig
+from django.core.exceptions import ImproperlyConfigured
+
+
+class DrbsMcpConfig(AppConfig):
+    """AppConfig for the generic DRBS MCP server.
+
+    ``name`` is the import module (``drf_react_by_schema_mcp``); the Django
+    **app label** is kept as ``drbs_mcp`` per the frozen interface contract.
+    """
+
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "drf_react_by_schema_mcp"
+    label = "drbs_mcp"
+
+    def ready(self):
+        # The MCP server authenticates with the OAuth tokens issued by
+        # drf-react-by-schema-oauth and consumes its PRM helper. Fail loudly and
+        # early if the consumer forgot to install/enable it.
+        from django.apps import apps
+
+        try:
+            apps.get_app_config("drbs_oauth")
+        except LookupError as exc:
+            raise ImproperlyConfigured(
+                "drf-react-by-schema-mcp requires drf-react-by-schema-oauth. Add "
+                "'oauth2_provider' and 'drf-react-by-schema-oauth' to "
+                "INSTALLED_APPS before 'drf_react_by_schema_mcp', and make sure "
+                "the 'drf-react-by-schema-oauth' package is installed."
+            ) from exc

drf_react_by_schema_mcp/auth.py

@@ -0,0 +1,141 @@
+"""Bearer-token plumbing for the MCP resource server.
+
+The server is a **stateless proxy**: it never stores credentials. It:
+
+1. reads the caller's ``Authorization: Bearer <token>`` at the transport
+   (:class:`BearerAuthMiddleware`) and answers ``401`` with a
+   ``WWW-Authenticate`` challenge pointing at the Protected Resource Metadata
+   (see :mod:`drf_react_by_schema_mcp.metadata`) when it is missing — which is
+   what makes ``opencode mcp auth`` start the OAuth flow;
+2. optionally validates the token against the project's API (the project's own
+   ``OAuth2Authentication`` is the authority), so an expired token also yields
+   ``401``; and
+3. forwards the token verbatim on every ``/api/...`` call (see
+   :mod:`drf_react_by_schema_mcp.tools`), letting the project's DRF permissions
+   enforce scopes (``read`` on safe methods, ``write`` on unsafe ones).
+"""
+
+from __future__ import annotations
+
+import logging
+
+import httpx
+from starlette.datastructures import Headers
+from starlette.responses import JSONResponse
+
+from .metadata import www_authenticate_for
+from .settings import get_setting
+
+logger = logging.getLogger(__name__)
+
+# Test seam: an ``httpx`` transport so the suite (and in-process e2e) can reach
+# the API without a real socket. Shared with :mod:`drf_react_by_schema_mcp.tools`.
+_async_transport: httpx.AsyncBaseTransport | None = None
+
+
+def set_async_transport(transport: httpx.AsyncBaseTransport | None) -> None:
+    """Override the HTTP transport used to reach the API (tests only)."""
+    global _async_transport
+    _async_transport = transport
+
+
+def get_async_transport() -> httpx.AsyncBaseTransport | None:
+    return _async_transport
+
+
+def bearer_token(headers: Headers) -> str | None:
+    """Return the Bearer token from ``headers``, or ``None`` if absent."""
+    value = headers.get("authorization", "")
+    if not value.lower().startswith("bearer "):
+        return None
+    return value.split(" ", 1)[1].strip() or None
+
+
+def _api_base_from_scope(scope) -> str:
+    configured = get_setting("API_URL")
+    if configured:
+        return str(configured).rstrip("/")
+    headers = Headers(scope=scope)
+    scheme = scope.get("scheme", "http")
+    host = headers.get("host", "")
+    return f"{scheme}://{host}"
+
+
+async def _token_is_valid(token: str, base_url: str) -> bool:
+    """Ask the API whether ``token`` is acceptable.
+
+    Only a ``401`` means "invalid" (reject); a missing validation endpoint
+    (``404``) or any other status is treated as "cannot tell" (accept), because
+    the project's DRF permissions remain authoritative on the actual calls.
+    """
+    path = get_setting("VALIDATE_PATH") or "/api/my_account/"
+    async with httpx.AsyncClient(
+        base_url=base_url,
+        transport=get_async_transport(),
+        timeout=get_setting("TIMEOUT"),
+        follow_redirects=True,
+    ) as client:
+        response = await client.get(path, headers={"Authorization": f"Bearer {token}"})
+    return response.status_code != 401
+
+
+class BearerAuthMiddleware:
+    """ASGI middleware requiring (and optionally validating) a Bearer token."""
+
+    def __init__(self, app, *, resource_path: str | None = None):
+        self.app = app
+        self.resource_path = resource_path
+
+    async def __call__(self, scope, receive, send):
+        if scope["type"] != "http":
+            await self.app(scope, receive, send)
+            return
+
+        headers = Headers(scope=scope)
+        token = bearer_token(headers)
+        challenge = www_authenticate_for(
+            scope.get("scheme", "http"),
+            headers.get("host", ""),
+            self.resource_path,
+        )
+
+        if token is None:
+            await self._reject(
+                scope,
+                receive,
+                send,
+                "invalid_request",
+                "Authorization: Bearer token required.",
+                challenge,
+            )
+            return
+
+        if get_setting("VALIDATE_TOKEN"):
+            try:
+                valid = await _token_is_valid(token, _api_base_from_scope(scope))
+            except httpx.HTTPError as exc:
+                # Fail open on transport errors: the API still enforces the token
+                # on the actual calls.
+                logger.warning("Token validation skipped (transport error): %s", exc)
+                valid = True
+            if not valid:
+                await self._reject(
+                    scope,
+                    receive,
+                    send,
+                    "invalid_token",
+                    "The access token is invalid or expired.",
+                    challenge,
+                )
+                return
+
+        await self.app(scope, receive, send)
+
+    @staticmethod
+    async def _reject(scope, receive, send, error, description, challenge):
+        response = JSONResponse(
+            {"error": error, "error_description": description}, status_code=401
+        )
+        if challenge:
+            response.headers["WWW-Authenticate"] = challenge
+        await response(scope, receive, send)

drf_react_by_schema_mcp/client.py

@@ -0,0 +1,147 @@
+"""Shared HTTP plumbing for the MCP proxy.
+
+The server is a **stateless proxy**: it never stores credentials. Every request
+forwards the caller's ``Authorization: Bearer`` token to the project's API, which
+identifies the user and enforces scopes. These helpers centralize token
+extraction, base-URL resolution, the ``httpx`` call and response decoding so the
+generic tools (:mod:`drf_react_by_schema_mcp.tools`) and the schema fetcher
+(:mod:`drf_react_by_schema_mcp.schema`) share one set of conventions.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+import httpx
+from mcp.server.fastmcp import Context
+
+from .auth import get_async_transport
+from .settings import get_setting
+
+#: Methods that may be retried after a transport error (they are idempotent).
+#: ``POST``/``PATCH`` are never retried: the API might have applied them.
+_RETRY_METHODS = frozenset({"GET", "HEAD", "OPTIONS"})
+
+#: Transport failures worth one retry — a dropped connection, a reset mid-body
+#: or a connect that never completed. A ``ReadTimeout`` is deliberately *not*
+#: here: a slow-but-alive API must not be retried (it would only double latency).
+_RETRY_EXCEPTIONS = (
+    httpx.ConnectError,
+    httpx.ConnectTimeout,
+    httpx.ReadError,
+    httpx.WriteError,
+    httpx.RemoteProtocolError,
+)
+
+#: Attempts for a retryable request (``2`` = one retry).
+_RETRY_ATTEMPTS = 2
+
+
+def request_object(ctx: Context) -> Any:
+    """Return the underlying Starlette request carried by the MCP context."""
+    return getattr(ctx.request_context, "request", None)
+
+
+def token(ctx: Context) -> str:
+    """Extract the caller's Bearer token, or raise a clear error."""
+    request = request_object(ctx)
+    headers = getattr(request, "headers", None)
+    authorization = headers.get("authorization", "") if headers else ""
+    if not authorization.lower().startswith("bearer "):
+        raise ValueError(
+            "OAuth token missing. Authenticate the MCP client so it sends "
+            "'Authorization: Bearer <token>'."
+        )
+    return authorization.split(" ", 1)[1].strip()
+
+
+def api_base(ctx: Context) -> str:
+    """Base URL of the project's API (``DRBS_MCP["API_URL"]`` or this origin)."""
+    configured = get_setting("API_URL")
+    if configured:
+        return str(configured).rstrip("/")
+    request = request_object(ctx)
+    url = request.url
+    host = request.headers.get("host") or url.hostname
+    return f"{url.scheme}://{host}"
+
+
+async def request(ctx: Context, method: str, path: str, **kwargs) -> httpx.Response:
+    """Send an authenticated request to the project's API and return the response.
+
+    An idempotent request (``GET``/``HEAD``/``OPTIONS``) that fails at the
+    transport layer (a dropped/reset connection) is retried once, so a transient
+    blip does not surface as a tool error; ``POST``/``PATCH`` are sent once.
+    """
+    headers = {"Authorization": f"Bearer {token(ctx)}"}
+    headers.update(kwargs.pop("headers", {}) or {})
+    base = api_base(ctx)
+    attempts = _RETRY_ATTEMPTS if method.upper() in _RETRY_METHODS else 1
+    async with httpx.AsyncClient(
+        base_url=base,
+        transport=get_async_transport(),
+        timeout=get_setting("TIMEOUT"),
+        follow_redirects=True,
+    ) as client:
+        for attempt in range(attempts):
+            try:
+                return await client.request(method, path, headers=headers, **kwargs)
+            except _RETRY_EXCEPTIONS:
+                if attempt + 1 >= attempts:
+                    raise
+                await asyncio.sleep(0.2 * (attempt + 1))
+        raise AssertionError("unreachable")  # pragma: no cover
+
+
+#: Max characters of an error body kept in the raised message.
+_ERROR_EXCERPT_MAX = 4000
+
+
+def _flatten_error(payload: Any) -> str:
+    """Readable text from a DRF error payload (str, list or field-keyed dict)."""
+    if isinstance(payload, str):
+        return payload
+    if isinstance(payload, list):
+        return "; ".join(
+            part for part in (_flatten_error(item) for item in payload) if part
+        )
+    if isinstance(payload, dict):
+        parts = []
+        for key, value in payload.items():
+            text = _flatten_error(value)
+            if key in ("detail", "non_field_errors"):
+                parts.append(text)
+            else:
+                parts.append(f"{key}: {text}")
+        return "; ".join(part for part in parts if part)
+    return str(payload)
+
+
+def _error_message(response: httpx.Response) -> str:
+    """Full DRF error detail when the body is JSON, else the raw excerpt."""
+    try:
+        payload = response.json()
+    except Exception:
+        return response.text[:_ERROR_EXCERPT_MAX]
+    return _flatten_error(payload)[:_ERROR_EXCERPT_MAX]
+
+
+def json(response: httpx.Response, esperado=(200, 201)) -> Any:
+    """Decode a JSON response, raising a readable error for unexpected statuses.
+
+    DRF errors (``{"detail": ...}``, a field map, or a list of messages) are
+    flattened so the whole message — including a model's valid ``sum_rows``
+    measures/dimensions — reaches the agent instead of a truncated raw body.
+    """
+    if response.status_code not in esperado:
+        detail = _error_message(response)
+        if response.status_code == 404 and "Página inválida" in detail:
+            detail += (
+                " (a página pedida não existe — reduza page= ou veja o total "
+                "de páginas com metadados=True ou resumo())"
+            )
+        raise ValueError(
+            f"{response.status_code} {response.reason_phrase}: {detail}"
+        )
+    return response.json()

drf_react_by_schema_mcp/metadata.py

@@ -0,0 +1,90 @@
+"""Protected Resource Metadata (RFC 9728) and the ``WWW-Authenticate`` glue.
+
+The MCP server is an OAuth 2.1 **resource server**: on an unauthenticated
+request it must answer ``401`` with a ``WWW-Authenticate: Bearer`` challenge
+pointing at its Protected Resource Metadata document, which in turn points at
+the authorization server (:mod:`drf_react_by_schema_oauth`). That is what lets
+``opencode mcp auth`` start the OAuth flow automatically.
+"""
+
+from urllib.parse import urlparse
+
+from django.http import JsonResponse
+from django.views import View
+from drf_react_by_schema_oauth.metadata import (
+    build_protected_resource_metadata,
+    get_issuer,
+)
+
+from .settings import get_setting
+
+WELL_KNOWN_PRM = "/.well-known/oauth-protected-resource"
+
+
+def _resource_path():
+    """Return the path component of the configured ``RESOURCE_URL``."""
+    resource = str(get_setting("RESOURCE_URL") or "/mcp")
+    if resource.startswith(("http://", "https://")):
+        return urlparse(resource).path or "/"
+    return resource if resource.startswith("/") else f"/{resource}"
+
+
+def resource_identifier(request):
+    """Absolute identifier of the protected resource (e.g. ``https://h/mcp``)."""
+    resource = str(get_setting("RESOURCE_URL") or "/mcp")
+    if resource.startswith(("http://", "https://")):
+        return resource
+    return request.build_absolute_uri(resource if resource.startswith("/") else f"/{resource}")
+
+
+def protected_resource_metadata_url(request):
+    """Absolute URL of this resource's RFC 9728 metadata document.
+
+    RFC 9728 inserts the resource's path *after* the well-known prefix, so the
+    resource ``/mcp`` is described at
+    ``/.well-known/oauth-protected-resource/mcp``.
+    """
+    path = _resource_path()
+    suffix = "" if path in ("", "/") else path
+    return request.build_absolute_uri(WELL_KNOWN_PRM + suffix)
+
+
+def build_prm(request):
+    """Build the RFC 9728 Protected Resource Metadata document."""
+    return build_protected_resource_metadata(
+        resource=resource_identifier(request),
+        authorization_servers=[get_issuer(request)],
+        scopes_supported=[
+            get_setting("READ_SCOPE"),
+            get_setting("WRITE_SCOPE"),
+        ],
+        bearer_methods_supported=["header"],
+    )
+
+
+def prm_url_for(scheme, host, resource_path=None):
+    """Absolute PRM URL built from raw scheme/host (usable outside Django)."""
+    path = resource_path if resource_path is not None else _resource_path()
+    suffix = "" if path in ("", "/") else path
+    return f"{scheme}://{host}{WELL_KNOWN_PRM}{suffix}"
+
+
+def www_authenticate_for(scheme, host, resource_path=None):
+    """``WWW-Authenticate`` value built from raw scheme/host."""
+    return f'Bearer resource_metadata="{prm_url_for(scheme, host, resource_path)}"'
+
+
+def www_authenticate_header(request):
+    """Return the ``WWW-Authenticate`` value for a ``401`` on this resource."""
+    return www_authenticate_for(request.scheme, request.get_host())
+
+
+class ProtectedResourceMetadataView(View):
+    """Serve the RFC 9728 Protected Resource Metadata document."""
+
+    http_method_names = ["get", "head"]
+
+    def get(self, request, *args, **kwargs):
+        response = JsonResponse(build_prm(request), json_dumps_params={"indent": 2})
+        response["Cache-Control"] = "no-store"
+        return response