drupal-mcp-server 0.1.0__py3-none-any.whl

drupal_mcp_server/__init__.py

@@ -0,0 +1,3 @@
+"""Drupal MCP Server - Model Context Protocol server for Drupal."""
+
+__version__ = "0.1.0"

drupal_mcp_server/auth/__init__.py

@@ -0,0 +1,94 @@
+"""Authentication managers for Drupal MCP Server."""
+
+from typing import Any, cast
+
+from .basic import BasicAuth
+from .mcp_oauth import DrupalOAuthProvider
+from .session import SessionAuth
+from .token import TokenAuth
+
+
+class AuthManager:
+    """Selects and wraps auth strategy from settings."""
+
+    def __init__(self, settings: Any):
+        self._auth: Any | None = None
+        self._session: Any | None = None
+        self._basic: BasicAuth | None = None
+
+        if settings.DRUPAL_OAUTH_TOKEN_URL:
+            self._auth = TokenAuth(self._fetch_oauth_token(settings))
+        elif settings.DRUPAL_USERNAME and settings.DRUPAL_PASSWORD:
+            # Session auth covers both reads and writes; basic auth alone is
+            # rejected with 403 on Drupal's mutating endpoints. Basic remains
+            # as a fallback for sites without /user/login so reads still work.
+            self._basic = BasicAuth(settings.DRUPAL_USERNAME, settings.DRUPAL_PASSWORD)
+            self._session = SessionAuth(
+                base_url=settings.DRUPAL_BASE_URL,
+                username=settings.DRUPAL_USERNAME,
+                password=settings.DRUPAL_PASSWORD,
+                verify_ssl=bool(getattr(settings, "DRUPAL_VERIFY_SSL", True)),
+            )
+            self._auth = self._session
+        elif getattr(settings, "DRUPAL_API_TOKEN", None):
+            # Documented as an auth method since v0.1 but never wired up, so
+            # setting it silently produced unauthenticated requests.
+            self._auth = TokenAuth(settings.DRUPAL_API_TOKEN)
+
+    async def ensure_session(self) -> None:
+        """Log in and cache a CSRF token. Safe to call more than once."""
+        if self._session is not None and not self._session.is_logged_in():
+            await self._session.login()
+
+    def get_session_cookies(self) -> dict[str, str]:
+        """Session cookies for mutating requests, or {} if not using session auth."""
+        if self._session is None:
+            return {}
+        return cast("dict[str, str]", self._session.get_cookies())
+
+    def _fetch_oauth_token(self, settings: Any) -> str:
+        """Fetch OAuth token from the configured token URL."""
+        import httpx
+        try:
+            resp = httpx.post(
+                settings.DRUPAL_OAUTH_TOKEN_URL,
+                data={
+                    "grant_type": "client_credentials",
+                    "client_id": settings.DRUPAL_OAUTH_CLIENT_ID or "",
+                    "client_secret": settings.DRUPAL_OAUTH_CLIENT_SECRET or "",
+                },
+                timeout=30.0,
+            )
+            resp.raise_for_status()
+            return cast("str", resp.json().get("access_token", ""))
+        except Exception:
+            return ""
+
+    def get_headers(self) -> dict[str, str]:
+        """Return request headers for the active auth strategy.
+
+        Synchronous to match the underlying strategies and the sync call site in
+        ``clients/base.py::_headers``.
+
+        When session auth is configured but not (yet) logged in, fall back to
+        basic auth rather than sending an unauthenticated request.
+        """
+        if self._session is not None and not self._session.is_logged_in():
+            if self._basic is not None:
+                return self._basic.get_headers()
+            return {}
+        if self._auth:
+            return cast("dict[str, str]", self._auth.get_headers())
+        return {}
+
+    def get_mcp_oauth_provider(self, settings: Any) -> DrupalOAuthProvider | None:
+        """Get OAuth provider for MCP HTTP transport."""
+        if settings.MCP_TRANSPORT in ("http", "sse", "streamable-http"):
+            base_url = f"http://{settings.MCP_HOST}:{settings.MCP_PORT}"
+            return DrupalOAuthProvider(
+                base_url=base_url,
+                client_id=settings.DRUPAL_OAUTH_CLIENT_ID,
+                client_secret=settings.DRUPAL_OAUTH_CLIENT_SECRET,
+                token_url=settings.DRUPAL_OAUTH_TOKEN_URL,
+            )
+        return None

drupal_mcp_server/auth/basic.py

@@ -0,0 +1,10 @@
+"""Basic authentication for Drupal."""
+import base64
+
+
+class BasicAuth:
+    def __init__(self, username: str, password: str):
+        self._token = base64.b64encode(f"{username}:{password}".encode()).decode()
+
+    def get_headers(self) -> dict[str, str]:
+        return {"Authorization": f"Basic {self._token}"}

drupal_mcp_server/auth/mcp_oauth.py

@@ -0,0 +1,256 @@
+"""OAuth 2.1 authentication provider for FastMCP HTTP transport with per-session scopes."""
+
+from typing import Any
+
+from fastmcp.server.auth import AccessToken as FastMCPAccessToken
+from fastmcp.server.auth import OAuthProvider
+from mcp.server.auth.provider import (
+    AccessToken,
+    AuthorizationCodeT,
+    AuthorizationParams,
+    RefreshTokenT,
+)
+from mcp.shared.auth import OAuthClientInformationFull, OAuthToken
+
+
+class DrupalOAuthProvider(OAuthProvider):
+    """OAuth 2.1 provider with Drupal integration and per-session scopes."""
+    
+    # Define available scopes
+    SCOPES = {
+        "drupal:read": "Read Drupal content and configuration",
+        "drupal:write": "Create and update Drupal content",
+        "drupal:admin": "Administrative access (config, modules, users)",
+        "drupal:migrate": "Run migrations and analysis tools",
+        "drupal:devops": "Execute Drush commands and manage infrastructure",
+        "drupal:ai": "Use AI-powered tools",
+        "drupal:security": "Run security audits and scans",
+    }
+    
+    # Default scopes for different roles
+    ROLE_SCOPES = {
+        "anonymous": ["drupal:read"],
+        "authenticated": ["drupal:read", "drupal:write"],
+        "editor": ["drupal:read", "drupal:write"],
+        "administrator": ["drupal:read", "drupal:write", "drupal:admin"],
+        "migrator": ["drupal:read", "drupal:write", "drupal:migrate"],
+        "devops": ["drupal:read", "drupal:write", "drupal:devops"],
+        "security": ["drupal:read", "drupal:admin", "drupal:security"],
+    }
+    
+    def __init__(
+        self,
+        base_url: str,
+        client_id: str | None = None,
+        client_secret: str | None = None,
+        token_url: str | None = None,
+        required_scopes: list[str] | None = None,
+    ):
+        super().__init__(
+            base_url=base_url,
+            required_scopes=required_scopes or ["drupal:read", "drupal:write"],
+        )
+        self._drupal_client_id = client_id
+        self._drupal_client_secret = client_secret
+        self._drupal_token_url = token_url
+        self._access_tokens: dict[str, dict[str, Any]] = {}
+        self._auth_codes: dict[str, dict[str, Any]] = {}
+        self._refresh_tokens: dict[str, dict[str, Any]] = {}
+        self._clients: dict[str, OAuthClientInformationFull] = {}
+        # Per-session scopes: session_id -> list of scopes
+        self._session_scopes: dict[str, list[str]] = {}
+        # Session -> client mapping
+        self._session_clients: dict[str, str] = {}
+    
+    def get_available_scopes(self) -> dict[str, str]:
+        """Get all available scopes with descriptions."""
+        return self.SCOPES.copy()
+    
+    def get_role_scopes(self, role: str) -> list[str]:
+        """Get scopes for a role."""
+        return self.ROLE_SCOPES.get(role, self.ROLE_SCOPES["authenticated"])
+    
+    def set_session_scopes(self, session_id: str, scopes: list[str]) -> None:
+        """Set scopes for a session."""
+        # Validate scopes
+        valid_scopes = [s for s in scopes if s in self.SCOPES]
+        self._session_scopes[session_id] = valid_scopes
+    
+    def get_session_scopes(self, session_id: str) -> list[str]:
+        """Get scopes for a session."""
+        return self._session_scopes.get(session_id, self.required_scopes)
+    
+    def set_session_client(self, session_id: str, client_id: str) -> None:
+        """Associate a client with a session."""
+        self._session_clients[session_id] = client_id
+    
+    def get_session_client(self, session_id: str) -> str | None:
+        """Get client ID for a session."""
+        return self._session_clients.get(session_id)
+    
+    def clear_session(self, session_id: str) -> None:
+        """Clear session data."""
+        self._session_scopes.pop(session_id, None)
+        self._session_clients.pop(session_id, None)
+    
+    def get_challenge_scopes(self, required_scopes: list[str] | None = None) -> list[str]:
+        """Get scopes for WWW-Authenticate challenge.
+        
+        This can be overridden to provide session-specific scopes.
+        """
+        # If we have session-specific scopes, use those
+        # For now, use the default behavior
+        return super().get_challenge_scopes(required_scopes)
+    
+    async def load_access_token(self, token: str) -> FastMCPAccessToken | None:
+        """Load and validate an access token.
+
+        The token has to be returned as an `AccessToken`, not as the dict it
+        was stored in. FastMCP reads `.scopes` and `.client_id` off the result
+        to decide whether a request is allowed, and a dict answers every one of
+        those with `AttributeError` -- so a perfectly good token was rejected as
+        harshly as a forged one, and the only OAuth behaviour ever observed was
+        the fail-closed side. That also makes this the constructor of last
+        resort for the stored fields, which is why `expires_at` is stored as an
+        int: `AccessToken.expires_at` is one, and a float fails its validation.
+        """
+        token_data = self._access_tokens.get(token)
+        if token_data is None:
+            return None
+        import time
+
+        if token_data.get("expires_at", 0) <= time.time():
+            return None
+        return FastMCPAccessToken(
+            token=str(token_data.get("token", token)),
+            client_id=str(token_data.get("client_id") or ""),
+            scopes=list(token_data.get("scopes") or []),
+            expires_at=int(token_data.get("expires_at", 0)),
+        )
+    
+    async def load_authorization_code(
+        self,
+        client: OAuthClientInformationFull,
+        authorization_code: str,
+    ) -> AuthorizationCodeT | None:
+        """Load an authorization code."""
+        auth_code_str = str(authorization_code)
+        return self._auth_codes.get(auth_code_str)  # type: ignore[return-value]
+    
+    async def load_refresh_token(
+        self,
+        client: OAuthClientInformationFull,
+        refresh_token: str,
+    ) -> RefreshTokenT | None:
+        """Load a refresh token."""
+        refresh_token_str = str(refresh_token)
+        return self._refresh_tokens.get(refresh_token_str)  # type: ignore[return-value]
+    
+    async def get_client(self, client_id: str) -> OAuthClientInformationFull | None:
+        """Get client information."""
+        return self._clients.get(client_id)
+    
+    async def register_client(self, client_info: OAuthClientInformationFull) -> None:
+        """Register a new OAuth client."""
+        self._clients[client_info.client_id] = client_info
+    
+    async def authorize(self, client: OAuthClientInformationFull, params: AuthorizationParams) -> str:
+        """Handle authorization request - redirect to Drupal OAuth."""
+        # Generate auth code
+        import secrets
+        auth_code = secrets.token_urlsafe(32)
+        self._auth_codes[auth_code] = {
+            "client_id": client.client_id,
+            "redirect_uri": params.redirect_uri,
+            "scopes": params.scopes,
+            "code_challenge": params.code_challenge,
+        }
+        
+        # Redirect back to client with auth code
+        return f"{params.redirect_uri}?code={auth_code}"
+    
+    async def exchange_authorization_code(
+        self,
+        client: OAuthClientInformationFull,
+        authorization_code: AuthorizationCodeT,
+    ) -> OAuthToken:
+        """Exchange authorization code for access token."""
+        auth_code_str = str(authorization_code)
+        if auth_code_str not in self._auth_codes:
+            raise ValueError("Invalid authorization code")
+        
+        code_data = self._auth_codes.pop(auth_code_str)
+        
+        # Generate tokens
+        import secrets
+        import time
+        access_token = secrets.token_urlsafe(32)
+        refresh_token = secrets.token_urlsafe(32)
+        expires_at = int(time.time()) + 3600  # 1 hour
+        
+        token_data = {
+            "token": access_token,
+            "client_id": client.client_id,
+            "scopes": code_data["scopes"],
+            "expires_at": expires_at,
+        }
+        self._access_tokens[access_token] = token_data
+        self._refresh_tokens[refresh_token] = {
+            "client_id": client.client_id,
+            "scopes": code_data["scopes"],
+        }
+        
+        return OAuthToken(
+            access_token=access_token,
+            refresh_token=refresh_token,
+            token_type="Bearer",
+            expires_in=3600,
+            scope=" ".join(code_data["scopes"]),
+        )
+    
+    async def exchange_refresh_token(
+        self,
+        client: OAuthClientInformationFull,
+        refresh_token: RefreshTokenT,
+        scopes: list[str],
+    ) -> OAuthToken:
+        """Exchange refresh token for new access token."""
+        refresh_token_str = str(refresh_token)
+        if refresh_token_str not in self._refresh_tokens:
+            raise ValueError("Invalid refresh token")
+        
+        # Indexed for its KeyError side effect: it rejects unknown tokens.
+        _token_data = self._refresh_tokens[refresh_token_str]
+        
+        import secrets
+        import time
+        new_access_token = secrets.token_urlsafe(32)
+        new_refresh_token = secrets.token_urlsafe(32)
+        expires_at = int(time.time()) + 3600
+        
+        new_token_data = {
+            "token": new_access_token,
+            "client_id": client.client_id,
+            "scopes": scopes,
+            "expires_at": expires_at,
+        }
+        self._access_tokens[new_access_token] = new_token_data
+        self._refresh_tokens[new_refresh_token] = {
+            "client_id": client.client_id,
+            "scopes": scopes,
+        }
+        del self._refresh_tokens[refresh_token_str]
+        
+        return OAuthToken(
+            access_token=new_access_token,
+            refresh_token=new_refresh_token,
+            token_type="Bearer",
+            expires_in=3600,
+            scope=" ".join(scopes),
+        )
+    
+    async def revoke_token(self, token: AccessToken | RefreshTokenT) -> None:
+        """Revoke an access or refresh token."""
+        token_str = str(token)
+        self._access_tokens.pop(token_str, None)
+        self._refresh_tokens.pop(token_str, None)

drupal_mcp_server/auth/session.py

@@ -0,0 +1,108 @@
+"""Session (cookie + CSRF) authentication for Drupal.
+
+Drupal protects every mutating endpoint behind a per-session CSRF token.
+Basic auth alone is sufficient for reads but is rejected with 403 on writes,
+so tools that create/update/delete content must hold a real session.
+
+Flow:
+    1. POST /user/login with the credentials to obtain a session cookie.
+    2. GET /session/token on that session to obtain the CSRF token.
+    3. Send both the cookie and X-CSRF-Token on every mutating request.
+"""
+
+import httpx
+
+
+class SessionAuth:
+    """Cookie + CSRF token auth for Drupal write operations."""
+
+    def __init__(self, base_url: str, username: str, password: str,
+                 verify_ssl: bool = True, timeout: float = 30.0):
+        self._base_url = base_url.rstrip("/")
+        self._username = username
+        self._password = password
+        self._verify_ssl = verify_ssl
+        self._timeout = timeout
+        self._cookies: dict[str, str] = {}
+        self._csrf: str | None = None
+        self._logged_in = False
+
+    async def login(self) -> None:
+        """Establish a session and fetch a CSRF token.
+
+        The login POST is deliberately not followed past its redirect. Drupal
+        answers a good login with 303 to the account page, built from the
+        scheme and host it saw the request arrive on -- its own idea of its
+        base URL, not the client's. Following that turns a successful login
+        into a failure whenever the two disagree: reached on a port-mapped
+        HTTPS endpoint the site reported itself as plain `http`, so the
+        redirect was fetched as HTTP against a TLS port, nginx answered 400,
+        and the session cookie the same response had just issued was thrown
+        away. Every write then silently fell back to basic auth, which
+        Drupal's mutating endpoints reject.
+
+        Only the redirect's status and the cookie it sets are wanted here;
+        the page it points at is the site's business.
+
+        Raises:
+            RuntimeError: If login fails or no token is issued.
+        """
+        async with httpx.AsyncClient(
+            verify=self._verify_ssl,
+            timeout=self._timeout,
+            follow_redirects=False,
+        ) as client:
+            resp = await client.post(
+                f"{self._base_url}/user/login",
+                data={
+                    "name": self._username,
+                    "pass": self._password,
+                    "form_id": "user_login_form",
+                    "op": "Log in",
+                },
+            )
+            if resp.status_code >= 400:
+                raise RuntimeError(
+                    f"Drupal login failed (HTTP {resp.status_code}); "
+                    "check DRUPAL_USERNAME and DRUPAL_PASSWORD"
+                )
+
+            # A 3xx here is the success path, and a refused login is a 200
+            # re-rendering the form without setting a cookie -- so this check,
+            # not the status above, is what actually rejects bad credentials.
+            self._cookies = {k: v for k, v in client.cookies.items()}
+            if not self._cookies:
+                raise RuntimeError(
+                    "Drupal login returned no session cookie; "
+                    "the site may not expose /user/login, or the credentials "
+                    "were refused."
+                )
+
+            token_resp = await client.get(
+                f"{self._base_url}/session/token",
+                cookies=self._cookies,
+            )
+            if token_resp.status_code >= 400:
+                raise RuntimeError("Failed to fetch Drupal CSRF token")
+            self._csrf = token_resp.text.strip() or None
+            if not self._csrf:
+                raise RuntimeError("Drupal issued an empty CSRF token")
+
+            self._logged_in = True
+
+    def get_headers(self) -> dict[str, str]:
+        """Headers for a mutating request, including the CSRF token."""
+        if not self._logged_in:
+            return {}
+        headers = {}
+        if self._csrf:
+            headers["X-CSRF-Token"] = self._csrf
+        return headers
+
+    def get_cookies(self) -> dict[str, str]:
+        """Session cookies to attach to a request."""
+        return dict(self._cookies) if self._logged_in else {}
+
+    def is_logged_in(self) -> bool:
+        """Whether a session has been established."""
+        return self._logged_in

drupal_mcp_server/auth/token.py

@@ -0,0 +1,9 @@
+"""Bearer token authentication for Drupal."""
+
+
+class TokenAuth:
+    def __init__(self, token: str):
+        self._token = token
+
+    def get_headers(self) -> dict[str, str]:
+        return {"Authorization": f"Bearer {self._token}"}

drupal_mcp_server/clients/__init__.py

@@ -0,0 +1,7 @@
+"""HTTP clients for Drupal MCP Server."""
+from .base import DrupalBaseClient
+from .drush import DrushClient
+from .graphql import GraphQLClient
+from .jsonapi import JSONAPIClient
+
+__all__ = ["DrupalBaseClient", "JSONAPIClient", "GraphQLClient", "DrushClient"]

drupal_mcp_server/clients/base.py

@@ -0,0 +1,163 @@
+"""Base HTTP client for Drupal REST endpoints."""
+
+from typing import Any, cast
+
+import httpx
+
+
+class DrupalBaseClient:
+    """Base client for Drupal REST endpoints (JSON:API, GraphQL)."""
+
+    # Media type for requests. JSON:API rejects application/json with 415.
+    _media_type = "application/json"
+
+    def __init__(self, settings: Any, auth_manager: Any = None):
+        self.settings = settings
+        self.auth_manager = auth_manager
+        self._base_url = settings.DRUPAL_BASE_URL.rstrip("/")
+        self._timeout = 60
+        self._verify_ssl = bool(getattr(settings, "DRUPAL_VERIFY_SSL", True))
+
+    def _cookies(self) -> dict[str, str]:
+        """Session cookies from SessionAuth, if one is configured."""
+        mgr = self.auth_manager
+        if mgr is None:
+            return {}
+        getter = getattr(mgr, "get_session_cookies", None)
+        if getter is None:
+            return {}
+        return cast("dict[str, str]", getter())
+
+    def _client(self) -> httpx.AsyncClient:
+        """Build an AsyncClient honouring the DRUPAL_VERIFY_SSL setting.
+
+        Local dev environments (DDEV, Lando) serve self-signed certs, so this
+        must be configurable or every request fails with CERTIFICATE_VERIFY_FAILED.
+
+        Session cookies are attached here so reads see the same authenticated
+        session as writes.
+        """
+        return httpx.AsyncClient(
+            timeout=self._timeout,
+            verify=self._verify_ssl,
+            cookies=self._cookies(),
+        )
+
+    def _build_url(self, endpoint: str) -> str:
+        return f"{self._base_url}/{endpoint.lstrip('/')}"
+
+    def _headers(self) -> dict[str, str]:
+        headers = {
+            "Accept": self._media_type,
+            "Content-Type": self._media_type,
+        }
+        if self.auth_manager:
+            headers.update(self.auth_manager.get_headers())
+        return headers
+
+    @staticmethod
+    def _decode(response: httpx.Response, method: str) -> Any:
+        """Parse a JSON body, and say what happened when there isn't one.
+
+        An empty body used to surface as ``Expecting value: line 1 column 1
+        (char 0)``, which reads like a client bug and gives no clue that
+        Drupal's own PHP died mid-request.
+        """
+        body = response.content
+        if not body.strip():
+            if response.status_code == 204 or method == "DELETE":
+                return {}
+            raise RuntimeError(
+                f"{method} {response.request.url} returned HTTP "
+                f"{response.status_code} with an empty body, so there is "
+                "nothing to parse. Drupal does this when PHP fails "
+                "mid-request - a vendor directory being rewritten by a "
+                "concurrent `composer install`, or a fatal error with output "
+                "buffering enabled. Check the site's watchdog or web server "
+                "log and retry."
+            )
+        try:
+            return response.json()
+        except ValueError as exc:
+            raise RuntimeError(
+                f"{method} {response.request.url} returned HTTP "
+                f"{response.status_code} with a body that is not JSON "
+                f"({exc}): {body[:160]!r}"
+            ) from None
+
+    @staticmethod
+    def _raise(response: httpx.Response) -> None:
+        """Raise for status, preserving Drupal's JSON:API error body.
+
+        ``raise_for_status()`` alone reports only the status code, which hides
+        the actionable ``errors[].detail`` Drupal returns on validation failures.
+        """
+        try:
+            response.raise_for_status()
+        except httpx.HTTPStatusError as exc:
+            detail = response.text.strip()
+            if detail:
+                # Drupal returns HTML for some 40x pages; keep it short.
+                detail = detail[:400]
+                raise httpx.HTTPStatusError(
+                    f"{exc} — {detail}", request=exc.request, response=exc.response
+                ) from None
+            raise
+
+    async def request(
+        self,
+        method: str,
+        endpoint: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json_body: Any = None,
+        data: dict[str, Any] | None = None,
+    ) -> httpx.Response:
+        """Perform an HTTP request and return the raw response."""
+        url = self._build_url(endpoint)
+        async with self._client() as client:
+            return await client.request(
+                method,
+                url,
+                headers=self._headers(),
+                params=params,
+                json=json_body,
+                data=data,
+            )
+
+    async def get(
+        self,
+        endpoint: str,
+        params: dict[str, Any] | None = None,
+    ) -> dict[str, Any] | list[Any]:
+        """Perform a GET request to the Drupal endpoint."""
+        response = await self.request("GET", endpoint, params=params)
+        self._raise(response)
+        return self._decode(response, "GET")  # type: ignore[no-any-return]
+
+    async def post(
+        self,
+        endpoint: str,
+        data: dict[str, Any] | None = None,
+        json_body: dict[str, Any] | None = None,
+    ) -> dict[str, Any] | list[Any]:
+        """Perform a POST request to the Drupal endpoint."""
+        response = await self.request("POST", endpoint, json_body=json_body or data)
+        self._raise(response)
+        return self._decode(response, "POST")  # type: ignore[no-any-return]
+
+    async def patch(self, endpoint: str, json_body: dict[str, Any]) -> dict[str, Any] | list[Any]:
+        """Perform a PATCH request to the Drupal endpoint."""
+        response = await self.request("PATCH", endpoint, json_body=json_body)
+        self._raise(response)
+        return self._decode(response, "PATCH")  # type: ignore[no-any-return]
+
+    async def delete(self, endpoint: str) -> dict[str, Any] | list[Any]:
+        """Perform a DELETE request to the Drupal endpoint.
+
+        Drupal answers DELETE with 204 No Content, so an empty body is normal
+        and must not be parsed as JSON.
+        """
+        response = await self.request("DELETE", endpoint)
+        self._raise(response)
+        return {"deleted": True, "status_code": response.status_code}