plane-mcp-server-ce 0.3.0__py3-none-any.whl

plane_mcp/__init__.py

@@ -0,0 +1 @@
+"""Plane MCP Server - A Model Context Protocol server for Plane integration."""

plane_mcp/__main__.py

@@ -0,0 +1,208 @@
+"""Main entry point for the Plane MCP Server."""
+
+import json
+import logging
+import os
+import sys
+from contextlib import asynccontextmanager
+from datetime import datetime, timezone
+from enum import Enum
+
+import uvicorn
+from fastmcp.server.dependencies import get_access_token
+from starlette.applications import Starlette
+from starlette.middleware.cors import CORSMiddleware
+from starlette.routing import Mount
+
+from plane_mcp.server import get_header_mcp, get_oauth_mcp, get_stdio_mcp
+
+LOG_USER_INFO: bool = os.getenv("LOG_USER_INFO", "").lower() == "true"
+
+
+class UserContextFilter(logging.Filter):
+    """Attach authenticated user/workspace context to every log record.
+
+    Pulls the current request's access token via FastMCP's dependency, which
+    returns None (never raises) outside a request context — so startup logs fall
+    back to environment config and otherwise carry no user info.
+
+    Always logs the opaque user id (sub claim) and the workspace slug; neither is
+    PII. The display name IS PII and is only included when LOG_USER_INFO=true.
+    """
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        user_id = None
+        display_name = None
+        workspace_slug = None
+        try:
+            token = get_access_token()
+            if token:
+                user_id = token.claims.get("sub")
+                workspace_slug = token.claims.get("workspace_slug")
+                if LOG_USER_INFO:
+                    display_name = token.claims.get("display_name")
+        except Exception as exc:
+            # Never let logging enrichment break a request, but leave a signal.
+            record.user_context_enrichment_error = type(exc).__name__
+        record.user_id = user_id
+        record.display_name = display_name
+        # stdio mode has no token; fall back to the configured workspace.
+        record.workspace_slug = workspace_slug or os.getenv("PLANE_WORKSPACE_SLUG") or None
+        return True
+
+
+class JSONFormatter(logging.Formatter):
+    """JSON log formatter for structured logging (Datadog, ELK, etc.)."""
+
+    def format(self, record: logging.LogRecord) -> str:
+        log_entry = {
+            "timestamp": datetime.fromtimestamp(record.created, tz=timezone.utc).isoformat(),
+            "level": record.levelname,
+            "logger": record.name,
+        }
+        # The logging middleware emits a JSON object as its log message. Promote
+        # those keys to top-level fields (event, method, tool, duration_ms, ...)
+        raw_message = record.getMessage()
+        try:
+            parsed = json.loads(raw_message)
+        except (ValueError, TypeError):
+            parsed = None
+        if isinstance(parsed, dict):
+            log_entry.update(parsed)
+        else:
+            log_entry["message"] = raw_message
+        user_id = getattr(record, "user_id", None)
+        if user_id:
+            log_entry["user_id"] = user_id
+        workspace_slug = getattr(record, "workspace_slug", None)
+        if workspace_slug:
+            log_entry["workspace_slug"] = workspace_slug
+        display_name = getattr(record, "display_name", None)
+        if display_name:
+            log_entry["display_name"] = display_name
+        err = getattr(record, "user_context_enrichment_error", None)
+        if err:
+            log_entry["user_context_enrichment_error"] = err
+        if record.exc_info and record.exc_info[1]:
+            log_entry["error"] = str(record.exc_info[1])
+            log_entry["error_type"] = type(record.exc_info[1]).__name__
+        return json.dumps(log_entry)
+
+
+def configure_json_logging():
+    """Replace FastMCP's Rich handlers with a JSON formatter on the fastmcp logger."""
+    fastmcp_logger = logging.getLogger("fastmcp")
+
+    # Remove all existing handlers (Rich)
+    for handler in fastmcp_logger.handlers[:]:
+        fastmcp_logger.removeHandler(handler)
+
+    handler = logging.StreamHandler(sys.stderr)
+    handler.setFormatter(JSONFormatter())
+    handler.addFilter(UserContextFilter())
+    fastmcp_logger.addHandler(handler)
+    fastmcp_logger.setLevel(logging.INFO)
+    fastmcp_logger.propagate = False
+
+
+configure_json_logging()
+
+logger = logging.getLogger("fastmcp.plane_mcp")
+
+
+class ServerMode(Enum):
+    STDIO = "stdio"
+    SSE = "sse"
+    HTTP = "http"
+
+
+@asynccontextmanager
+async def combined_lifespan(oauth_app, header_app, sse_app):
+    """Combine lifespans from both OAuth and Header MCP apps."""
+    # Start both lifespans
+    async with oauth_app.lifespan(oauth_app):
+        async with header_app.lifespan(header_app):
+            async with sse_app.lifespan(sse_app):
+                yield
+
+
+def main() -> None:
+    """Run the MCP server."""
+    if len(sys.argv) > 1 and sys.argv[1] in {"-h", "--help"}:
+        print("Usage: plane-mcp-server-ce [stdio|http|sse]")
+        return
+
+    server_mode = ServerMode.STDIO
+    if len(sys.argv) > 1:
+        server_mode = ServerMode(sys.argv[1])
+
+    if server_mode == ServerMode.STDIO:
+        # Validate API_KEY and PLANE_WORKSPACE_SLUG are set
+        if not os.getenv("PLANE_API_KEY"):
+            raise ValueError("PLANE_API_KEY is not set")
+        if not os.getenv("PLANE_WORKSPACE_SLUG"):
+            raise ValueError("PLANE_WORKSPACE_SLUG is not set")
+
+        get_stdio_mcp().run()
+        return
+
+    if server_mode == ServerMode.HTTP:
+        prefix = os.getenv("MCP_PATH_PREFIX") or ""
+
+        oauth_mcp = get_oauth_mcp(prefix + "/http")
+        oauth_app = oauth_mcp.http_app(stateless_http=True)
+        header_app = get_header_mcp().http_app(stateless_http=True)
+
+        sse_mcp = get_oauth_mcp(prefix)
+        sse_app = sse_mcp.http_app(transport="sse")
+
+        # mcp_path is appended to the auth provider's base_url to form the
+        # advertised resource URL. base_url already carries the prefix, so these
+        # stay at /mcp and /sse to avoid double-prefixing.
+        oauth_well_known = oauth_mcp.auth.get_well_known_routes(mcp_path="/mcp")
+        sse_well_known = sse_mcp.auth.get_well_known_routes(mcp_path="/sse")
+
+        app = Starlette(
+            routes=[
+                # Well-known routes for OAuth and Header HTTP
+                *oauth_well_known,
+                *sse_well_known,
+                # Mount both MCP servers
+                Mount(prefix + "/http/api-key", app=header_app),
+                Mount(prefix + "/http", app=oauth_app),
+                Mount(prefix or "/", app=sse_app),
+            ],
+            lifespan=lambda app: combined_lifespan(oauth_app, header_app, sse_app),
+        )
+
+        app.add_middleware(
+            CORSMiddleware,
+            allow_origins=["*"],
+            allow_credentials=False,
+            allow_methods=["*"],
+            allow_headers=["*"],
+        )
+
+        # Configure uvicorn loggers to use JSON formatting too
+        for uv_logger_name in ("uvicorn", "uvicorn.error"):
+            uv_logger = logging.getLogger(uv_logger_name)
+            for h in uv_logger.handlers[:]:
+                uv_logger.removeHandler(h)
+            uv_handler = logging.StreamHandler(sys.stderr)
+            uv_handler.setFormatter(JSONFormatter())
+            uv_handler.addFilter(UserContextFilter())
+            uv_logger.addHandler(uv_handler)
+
+        logger.info("Starting HTTP server at URLs: /mcp and /header/mcp")
+        uvicorn.run(
+            app,
+            host="0.0.0.0",
+            port=8211,
+            log_level="info",
+            access_log=False,
+        )
+        return
+
+
+if __name__ == "__main__":
+    main()

plane_mcp/auth/__init__.py

@@ -0,0 +1,7 @@
+from plane_mcp.auth.plane_header_auth_provider import PlaneHeaderAuthProvider
+from plane_mcp.auth.plane_oauth_provider import PlaneOAuthProvider
+
+__all__ = [
+    "PlaneHeaderAuthProvider",
+    "PlaneOAuthProvider",
+]

plane_mcp/auth/plane_header_auth_provider.py

@@ -0,0 +1,73 @@
+import os
+import time
+
+import httpx
+from fastmcp.server.auth import TokenVerifier
+from fastmcp.server.auth.auth import AccessToken
+from fastmcp.utilities.logging import get_logger
+
+logger = get_logger(__name__)
+
+DEFAULT_PLANE_BASE_URL = "https://api.plane.so"
+
+
+class PlaneHeaderAuthProvider(TokenVerifier):
+    def __init__(self, required_scopes: list[str] | None = None, timeout_seconds: int = 10):
+        super().__init__(required_scopes=required_scopes)
+        self.timeout_seconds = timeout_seconds
+
+    async def _validate_api_key(self, token: str) -> bool:
+        """Validate the API key by calling the Plane API."""
+        base_url = (os.getenv("PLANE_INTERNAL_BASE_URL") or os.getenv("PLANE_BASE_URL", DEFAULT_PLANE_BASE_URL)).rstrip(
+            "/"
+        )
+        user_url = f"{base_url}/api/v1/users/me/"
+
+        try:
+            async with httpx.AsyncClient(timeout=self.timeout_seconds) as client:
+                response = await client.get(
+                    user_url,
+                    headers={
+                        "x-api-key": token,
+                        "Content-Type": "application/json",
+                    },
+                )
+                if response.status_code != 200:
+                    logger.warning("API key validation failed: %s", response.status_code)
+                    return False
+                return True
+        except httpx.RequestError as e:
+            logger.warning("API key validation request failed: %s", e)
+            return False
+
+    async def verify_token(self, token: str) -> AccessToken | None:
+        try:
+            from fastmcp.server.dependencies import get_http_headers
+
+            headers = get_http_headers()
+
+            if token:
+                workspace_slug = headers.get("x-workspace-slug")
+                if not workspace_slug:
+                    logger.warning("x-api-key header found but x-workspace-slug is missing")
+                    return None
+
+                if not await self._validate_api_key(token):
+                    logger.warning("API key validation against Plane API failed")
+                    return None
+
+                logger.info("API key validated successfully via Plane API")
+                expires_at = int(time.time() + 3600)
+                return AccessToken(
+                    token=token,
+                    client_id="api_key_header_user",
+                    scopes=["read", "write"],
+                    expires_at=expires_at,
+                    claims={
+                        "auth_method": "api_key_header",
+                        "workspace_slug": workspace_slug,
+                    },
+                )
+        except RuntimeError:
+            # No active HTTP request available (e.g., stdio transport)
+            logger.debug("No active HTTP request available for header check")

plane_mcp/auth/plane_oauth_provider.py

@@ -0,0 +1,374 @@
+"""Plane OAuth provider for FastMCP.
+
+This module provides a complete Plane OAuth integration that's ready to use
+with just a client ID and client secret. It handles all the complexity of
+Plane's OAuth flow, token validation, and user management.
+
+Example:
+    ```python
+    from fastmcp import FastMCP
+    from plane_mcp.plane_oauth_provider import PlaneOAuthProvider
+
+    # Simple Plane OAuth protection
+    auth = PlaneOAuthProvider(
+        client_id="your-plane-client-id",
+        client_secret="your-plane-client-secret",
+        base_url="https://api.plane.so"
+    )
+
+    mcp = FastMCP("My Protected Server", auth=auth)
+    ```
+"""
+
+from __future__ import annotations
+
+import os
+import time
+
+import httpx
+from fastmcp.server.auth import TokenVerifier
+from fastmcp.server.auth.auth import AccessToken
+from fastmcp.server.auth.oauth_proxy import OAuthProxy
+from fastmcp.settings import ENV_FILE
+from fastmcp.utilities.auth import parse_scopes
+from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.types import NotSet, NotSetT
+from key_value.aio.protocols import AsyncKeyValue
+from plane.models.users import UserLite
+from pydantic import AnyHttpUrl, BaseModel, SecretStr, field_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+logger = get_logger(__name__)
+
+# When true, user info (PII such as the display name) is included in logs.
+# Defaults to false so PII is never logged unless explicitly opted in.
+LOG_USER_INFO: bool = os.getenv("LOG_USER_INFO", "").lower() == "true"
+
+
+DEFAULT_PLANE_BASE_URL = "https://api.plane.so"
+
+
+class WorkspaceDetail(BaseModel):
+    """Workspace detail information."""
+
+    name: str
+    slug: str
+    id: str
+    logo_url: str | None = None
+
+
+class PlaneOAuthAppInstallation(BaseModel):
+    """Plane OAuth app installation information."""
+
+    id: str
+    workspace_detail: WorkspaceDetail
+    created_at: str
+    updated_at: str
+    deleted_at: str | None = None
+    status: str
+    created_by: str | None = None
+    updated_by: str | None = None
+    workspace: str
+    application: str
+    installed_by: str
+    app_bot: str
+    webhook: str | None = None
+
+
+class PlaneOAuthProviderSettings(BaseSettings):
+    """Settings for Plane OAuth provider."""
+
+    model_config = SettingsConfigDict(
+        env_prefix="PLANE_OAUTH_PROVIDER_",
+        env_file=ENV_FILE,
+        extra="ignore",
+    )
+
+    client_id: str | None = None
+    client_secret: SecretStr | None = None
+    base_url: AnyHttpUrl | str | None = None
+    issuer_url: AnyHttpUrl | str | None = None
+    redirect_path: str | None = None
+    required_scopes: list[str] | None = None
+    timeout_seconds: int | None = None
+    allowed_client_redirect_uris: list[str] | None = None
+    jwt_signing_key: str | None = None
+    plane_base_url: str | None = None
+    plane_internal_base_url: str | None = None  # Internal URL for server-to-server calls
+    enable_cimd: bool = False
+
+    @field_validator("required_scopes", mode="before")
+    @classmethod
+    def _parse_scopes(cls, v):
+        return parse_scopes(v)
+
+
+class PlaneOAuthTokenVerifier(TokenVerifier):
+    """Token verifier for Plane OAuth tokens.
+
+    Plane OAuth tokens are verified by calling Plane's API to check if they're
+    valid and get user info.
+    """
+
+    def __init__(
+        self,
+        *,
+        required_scopes: list[str] | None = None,
+        timeout_seconds: int = 10,
+        plane_base_url: str | None = None,
+    ):
+        """Initialize the Plane token verifier.
+
+        Args:
+            required_scopes: Required OAuth scopes (currently not enforced by Plane API)
+            timeout_seconds: HTTP request timeout
+            plane_base_url: Base URL for Plane API (defaults to https://api.plane.so)
+        """
+        super().__init__(required_scopes=required_scopes)
+        self.timeout_seconds = timeout_seconds
+        self.plane_base_url = plane_base_url or os.getenv("PLANE_BASE_URL", DEFAULT_PLANE_BASE_URL)
+
+    async def verify_token(self, token: str) -> AccessToken | None:
+        """Verify Plane OAuth token by calling Plane API."""
+        logger.info(f"verify_token called, token_present={bool(token)}, token_length={len(token) if token else 0}")
+        try:
+            # Build the user endpoint URL
+            base_url = self.plane_base_url.rstrip("/")
+            user_url = f"{base_url}/api/v1/users/me/"
+            logger.info(f"Verifying token against: {user_url}")
+
+            async with httpx.AsyncClient(timeout=self.timeout_seconds) as client:
+                # Get current user info to verify token
+                response = await client.get(
+                    user_url,
+                    headers={
+                        "Authorization": f"Bearer {token}",
+                        "Content-Type": "application/json",
+                    },
+                )
+
+                logger.info(f"Plane API response status: {response.status_code}")
+                if response.status_code != 200:
+                    logger.info(
+                        "Plane token verification failed: %s - %s",
+                        response.status_code,
+                        response.text[:200],
+                    )
+                    return None
+
+                # Parse user data
+                user_data = response.json()
+                user = UserLite.model_validate(user_data)
+
+                expires_at = int(time.time() + 3600)
+
+                # display_name is PII — only log it when explicitly opted in.
+                if LOG_USER_INFO:
+                    logger.info(f"User verified: ({user.id}) - {user.display_name}")
+                else:
+                    logger.info(f"User verified: ({user.id})")
+
+                installations_response = await client.get(
+                    f"{base_url}/auth/o/app-installation/",
+                    headers={
+                        "Authorization": f"Bearer {token}",
+                        "Content-Type": "application/json",
+                    },
+                )
+
+                installations: list[PlaneOAuthAppInstallation] = installations_response.json()
+
+                if not installations:
+                    raise ValueError("No app installations found")
+
+                installation = installations[0]
+
+                # Create AccessToken with Plane user info
+                return AccessToken(
+                    token=token,
+                    client_id=user.id or "unknown",
+                    scopes=["read", "write"],  # Plane doesn't expose scopes in user endpoint
+                    expires_at=expires_at,
+                    claims={
+                        "auth_method": "oauth",
+                        "sub": user.id or "unknown",
+                        "email": user.email,
+                        "first_name": user.first_name,
+                        "last_name": user.last_name,
+                        "display_name": user.display_name,
+                        "avatar": user.avatar,
+                        "avatar_url": user.avatar_url,
+                        "plane_user_data": user_data,
+                        "workspace_slug": installation.get("workspace_detail", {}).get("slug"),
+                        "workspace": installation.get("workspace_detail", {}),
+                    },
+                )
+
+        except httpx.RequestError as e:
+            logger.info(f"Failed to verify Plane token (request error): {e}")
+            return None
+        except Exception as e:
+            logger.info(f"Failed to verify Plane token: {e}", exc_info=True)
+            return None
+
+
+class PlaneOAuthProvider(OAuthProxy):
+    """Complete Plane OAuth provider for FastMCP.
+
+    This provider makes it trivial to add Plane OAuth protection to any
+    FastMCP server. Just provide your Plane OAuth app credentials and
+    a base URL, and you're ready to go.
+
+    Features:
+    - Transparent OAuth proxy to Plane
+    - Automatic token validation via Plane API
+    - User information extraction
+    - Minimal configuration required
+
+    Example:
+        ```python
+        from fastmcp import FastMCP
+        from plane_mcp.plane_oauth_provider import PlaneOAuthProvider
+
+        auth = PlaneOAuthProvider(
+            client_id="your-client-id",
+            client_secret="your-client-secret",
+            base_url="https://my-server.com",
+            plane_base_url="https://api.plane.so"
+        )
+
+        mcp = FastMCP("My App", auth=auth)
+        ```
+    """
+
+    def __init__(
+        self,
+        *,
+        client_id: str | NotSetT = NotSet,
+        client_secret: str | NotSetT = NotSet,
+        base_url: AnyHttpUrl | str | NotSetT = NotSet,
+        issuer_url: AnyHttpUrl | str | NotSetT = NotSet,
+        redirect_path: str | NotSetT = NotSet,
+        required_scopes: list[str] | NotSetT = NotSet,
+        timeout_seconds: int | NotSetT = NotSet,
+        allowed_client_redirect_uris: list[str] | NotSetT = NotSet,
+        client_storage: AsyncKeyValue | None = None,
+        jwt_signing_key: str | bytes | NotSetT = NotSet,
+        require_authorization_consent: bool = True,
+        plane_base_url: str | NotSetT = NotSet,
+        plane_internal_base_url: str | NotSetT = NotSet,
+        enable_cimd: bool | NotSetT = NotSet,
+    ):
+        """Initialize Plane OAuth provider.
+
+        Args:
+            client_id: Plane OAuth app client ID
+            client_secret: Plane OAuth app client secret
+            base_url: Public URL where OAuth endpoints will be accessible
+                (includes any mount path)
+            issuer_url: Issuer URL for OAuth metadata (defaults to base_url).
+                Use root-level URL to avoid 404s during discovery when mounting
+                under a path.
+            redirect_path: Redirect path configured in Plane OAuth app
+                (defaults to "/auth/callback")
+            required_scopes: Required Plane scopes
+                (currently not enforced by Plane API)
+            timeout_seconds: HTTP request timeout for Plane API calls
+            allowed_client_redirect_uris: List of allowed redirect URI patterns
+                for MCP clients. If None (default), all URIs are allowed.
+                If empty list, no URIs are allowed.
+            client_storage: Storage backend for OAuth state
+                (client registrations, encrypted tokens). If None, a DiskStore
+                will be created in the data directory (derived from
+                `platformdirs`). The disk store will be encrypted using a key
+                derived from the JWT Signing Key.
+            jwt_signing_key: Secret for signing FastMCP JWT tokens
+                (any string or bytes). If bytes are provided, they will be used
+                as is. If a string is provided, it will be derived into a
+                32-byte key. If not provided, the upstream client secret will be
+                used to derive a 32-byte key using PBKDF2.
+            require_authorization_consent: Whether to require user consent
+                before authorizing clients (default True). When True, users see
+                a consent screen before being redirected to Plane. When False,
+                authorization proceeds directly without user confirmation.
+                SECURITY WARNING: Only disable for local development or
+                testing environments.
+            plane_base_url: Base URL for Plane API
+                (defaults to https://api.plane.so or PLANE_BASE_URL env var)
+            enable_cimd: Whether to enable CIMD (Client ID Metadata Document) support.
+                Defaults to False. Can be set via the PLANE_OAUTH_PROVIDER_ENABLE_CIMD environment variable.
+        """
+
+        settings = PlaneOAuthProviderSettings.model_validate(
+            {
+                k: v
+                for k, v in {
+                    "client_id": client_id,
+                    "client_secret": client_secret,
+                    "base_url": base_url,
+                    "issuer_url": issuer_url,
+                    "redirect_path": redirect_path,
+                    "required_scopes": required_scopes,
+                    "timeout_seconds": timeout_seconds,
+                    "allowed_client_redirect_uris": allowed_client_redirect_uris,
+                    "jwt_signing_key": jwt_signing_key,
+                    "plane_base_url": plane_base_url,
+                    "plane_internal_base_url": plane_internal_base_url,
+                    "enable_cimd": enable_cimd,
+                }.items()
+                if v is not NotSet
+            }
+        )
+
+        # Validate required settings
+        if not settings.client_id:
+            raise ValueError("client_id is required - set via parameter or PLANE_OAUTH_PROVIDER_CLIENT_ID")
+        if not settings.client_secret:
+            raise ValueError("client_secret is required - set via parameter or PLANE_OAUTH_PROVIDER_CLIENT_SECRET")
+
+        # Apply defaults
+        timeout_seconds_final = settings.timeout_seconds or 10
+        required_scopes_final = settings.required_scopes or []
+        allowed_client_redirect_uris_final = settings.allowed_client_redirect_uris
+        plane_base_url_final = settings.plane_base_url or os.getenv("PLANE_BASE_URL", DEFAULT_PLANE_BASE_URL)
+        # Internal URL for server-to-server calls (token exchange, API verification)
+        # Falls back to external URL if not set
+        plane_internal_url = (
+            settings.plane_internal_base_url or os.getenv("PLANE_INTERNAL_BASE_URL") or plane_base_url_final
+        )
+
+        # Create Plane token verifier (uses internal URL for server-to-server calls)
+        token_verifier = PlaneOAuthTokenVerifier(
+            required_scopes=required_scopes_final,
+            timeout_seconds=timeout_seconds_final,
+            plane_base_url=plane_internal_url,
+        )
+
+        # Extract secret string from SecretStr
+        client_secret_str = settings.client_secret.get_secret_value() if settings.client_secret else ""
+
+        # Initialize OAuth proxy with Plane endpoints
+        # Authorization: external URL (user's browser)
+        # Token exchange: internal URL (server-to-server)
+        super().__init__(
+            upstream_authorization_endpoint=f"{plane_base_url_final}/auth/o/authorize-app/",
+            upstream_token_endpoint=f"{plane_internal_url}/auth/o/token/",
+            upstream_client_id=settings.client_id,
+            upstream_client_secret=client_secret_str,
+            token_verifier=token_verifier,
+            base_url=settings.base_url,
+            redirect_path=settings.redirect_path,
+            issuer_url=settings.issuer_url or settings.base_url,  # Default to base_url if not specified
+            allowed_client_redirect_uris=allowed_client_redirect_uris_final,
+            client_storage=client_storage,
+            jwt_signing_key=settings.jwt_signing_key,
+            require_authorization_consent=require_authorization_consent,
+            valid_scopes=["read", "write"],
+            enable_cimd=settings.enable_cimd,
+        )
+
+        logger.info(
+            "Initialized Plane OAuth provider for client %s with scopes: %s",
+            settings.client_id,
+            required_scopes_final,
+        )