mcp-core-auth 0.2.1__py3-none-any.whl

mcp_core/__init__.py

@@ -0,0 +1,324 @@
+"""
+mcp-core: Auth, billing, and logging infrastructure for MCP-first servers.
+
+Usage:
+    from mcp_core import MCPCore
+
+    core = MCPCore(
+        product_name="myapp",
+        logto_endpoint="https://your-tenant.logto.app",   # or self-hosted: https://auth.example.com
+        logto_api_resource="https://api.example.com",
+        mongodb_uri="mongodb+srv://...",
+        db_name="myapp",
+        stripe_secret_key="sk_test_...",
+        stripe_price_id="price_...",
+        stripe_meter_event="tool_calls",
+        free_credits=25,
+        tool_costs={"browse": 0, "generate": 2},
+        read_only_tools={"browse"},
+    )
+
+    # In your tool handler:
+    user = await core.auth_and_bill(request, "narrate_text")
+"""
+
+import logging
+import os
+from typing import Any, Dict, List, Optional, Set
+
+from fastapi import FastAPI, Request
+
+from .auth import LogtoAuth
+from .billing import StripeBilling
+from .dcr import LogtoDCR
+from .health import HealthCheck
+from .mcp_mount import mount_mcp
+from .routes import install_routes
+from .tool_logging import ToolLogger
+
+__all__ = [
+    "MCPCore", "LogtoAuth", "StripeBilling", "HealthCheck", "ToolLogger",
+    "LogtoDCR", "mount_mcp",
+]
+__version__ = "0.1.3"
+
+logger = logging.getLogger(__name__)
+
+
+class MCPCore:
+    """Facade that wires auth, billing, logging, and health together.
+
+    All parameters can also be provided via environment variables
+    with MCP_CORE_ prefix (e.g. MCP_CORE_PRODUCT_NAME).
+    Constructor args take precedence over env vars.
+    """
+
+    def __init__(
+        self,
+        product_name: str = "",
+        # Logto auth
+        logto_endpoint: str = "",
+        logto_api_resource: str = "",
+        free_credits: int = 0,
+        dev_auth_bypass: bool = False,
+        dev_user_id: str = "local-dev-user",
+        reject_m2m: bool = True,
+        # MongoDB
+        mongodb_uri: str = "",
+        db_name: str = "",
+        # Stripe billing
+        stripe_secret_key: str = "",
+        stripe_price_id: str = "",
+        stripe_meter_event: str = "mcp_tool_calls",
+        stripe_webhook_secret: str = "",
+        billing_success_url: str = "",
+        billing_cancel_url: str = "",
+        # Tools
+        tool_costs: Optional[Dict[str, int]] = None,
+        read_only_tools: Optional[Set[str]] = None,
+        # MCP OAuth
+        mcp_logto_app_id: str = "",
+        mcp_logto_app_secret: str = "",
+        oauth_scopes: Optional[List[str]] = None,
+        # Logto Management API (enables real RFC 7591 DCR when provided)
+        logto_mgmt_app_id: str = "",
+        logto_mgmt_app_secret: str = "",
+        logto_mgmt_api_resource: str = "",
+        # Set this when Management tokens are issued on a different origin than
+        # `logto_endpoint` (Logto OSS self-host with admin on a separate port).
+        # Cloud deployments leave this empty.
+        logto_mgmt_token_endpoint: str = "",
+        # When set, /oauth/authorize bounces unauthenticated users here for
+        # product-branded inline sign-in instead of showing Logto's hosted
+        # page. The product is responsible for implementing this URL as a
+        # page that (1) accepts ?return_to=<url>, (2) validates it is
+        # same-origin, (3) runs the product's sign-in UI, (4) redirects
+        # the browser back to return_to on success. Logto's session cookie
+        # must be emitted with `Domain=.<apex>` so the retry carries it
+        # to /oauth/authorize. Leave empty to keep using Logto's hosted UI.
+        branded_sign_in_url: str = "",
+    ):
+        def _env(key: str, default: str = "") -> str:
+            return os.getenv(f"MCP_CORE_{key}", default)
+
+        self.product_name = product_name or _env("PRODUCT_NAME", "mcp-server")
+        _read_only = read_only_tools or set()
+        _free = free_credits or int(_env("FREE_CREDITS", "30"))
+
+        # Auth
+        self.auth = LogtoAuth(
+            endpoint=logto_endpoint or _env("LOGTO_ENDPOINT"),
+            api_resource=logto_api_resource or _env("LOGTO_API_RESOURCE"),
+            free_credits=_free,
+            dev_bypass=dev_auth_bypass or _env("DEV_AUTH_BYPASS") == "1",
+            dev_user_id=dev_user_id,
+            read_only_tools=_read_only,
+            reject_m2m=reject_m2m,
+        )
+
+        # Billing
+        self.billing = StripeBilling(
+            stripe_secret_key=stripe_secret_key or _env("STRIPE_SECRET_KEY"),
+            price_id=stripe_price_id or _env("STRIPE_PRICE_ID"),
+            meter_event=stripe_meter_event or _env("STRIPE_METER_EVENT", "mcp_tool_calls"),
+            free_credits=_free,
+            tool_costs=tool_costs or {},
+            read_only_tools=_read_only,
+            success_url=billing_success_url or _env("BILLING_SUCCESS_URL"),
+            cancel_url=billing_cancel_url or _env("BILLING_CANCEL_URL"),
+        )
+
+        # MongoDB
+        self._mongodb_uri = mongodb_uri or _env("MONGODB_URI")
+        self._db_name = db_name or _env("DB_NAME", self.product_name)
+        self._db: Any = None  # set in connect() or injected directly
+
+        # Logging
+        self.tool_logger = ToolLogger(
+            db=None,  # set after connect()
+            product_name=self.product_name,
+        )
+
+        # Health
+        self.health = HealthCheck(product_name=self.product_name)
+
+        # MCP OAuth config
+        self._mcp_app_id = mcp_logto_app_id or _env("MCP_LOGTO_APP_ID")
+        self._mcp_app_secret = mcp_logto_app_secret or _env("MCP_LOGTO_APP_SECRET")
+        self._webhook_secret = stripe_webhook_secret or _env("STRIPE_WEBHOOK_SECRET")
+        self._oauth_scopes = oauth_scopes
+        self._branded_sign_in_url = (
+            branded_sign_in_url or _env("BRANDED_SIGN_IN_URL", "")
+        )
+
+        # Real DCR via Logto Management API (optional). If mgmt creds are
+        # provided, every /oauth/register call creates a fresh Logto app with
+        # the caller's redirect_uris baked in — fixing the dynamic-port
+        # loopback case that fake DCR can't handle.
+        _mgmt_id = logto_mgmt_app_id or _env("LOGTO_MGMT_APP_ID")
+        _mgmt_secret = logto_mgmt_app_secret or _env("LOGTO_MGMT_APP_SECRET")
+        self.dcr: Optional[LogtoDCR] = None
+        if _mgmt_id and _mgmt_secret and self.auth.endpoint:
+            self.dcr = LogtoDCR(
+                logto_endpoint=self.auth.endpoint,
+                mgmt_app_id=_mgmt_id,
+                mgmt_app_secret=_mgmt_secret,
+                mgmt_api_resource=(
+                    logto_mgmt_api_resource
+                    or _env("LOGTO_MGMT_API_RESOURCE", "")
+                ),
+                mgmt_token_endpoint=(
+                    logto_mgmt_token_endpoint
+                    or _env("LOGTO_MGMT_TOKEN_ENDPOINT", "")
+                ),
+                app_name_prefix=f"mcp-dcr-{self.product_name}",
+            )
+
+    # ── Database ──────────────────────────────────────────
+
+    @property
+    def db(self) -> Any:
+        return self._db
+
+    @db.setter
+    def db(self, value: Any) -> None:
+        self._db = value
+        self.tool_logger.db = value
+
+    async def connect_db(self) -> Any:
+        """Connect to MongoDB using configured URI. Returns the database."""
+        if not self._mongodb_uri:
+            logger.warning("[mcp-core] No MONGODB_URI — running without DB")
+            return None
+        import motor.motor_asyncio
+
+        client = motor.motor_asyncio.AsyncIOMotorClient(self._mongodb_uri)
+        self.db = client[self._db_name]
+        logger.info("[mcp-core] Connected to MongoDB: %s", self._db_name)
+        return self.db
+
+    # ── Main middleware ─────���──────────────────────────────
+
+    async def auth_and_bill(
+        self, request: Request, tool_name: str
+    ) -> Dict[str, Any]:
+        """Combined auth + billing check. The main entry point for tool handlers.
+
+        Returns user dict. Raises HTTPException on auth/billing failure.
+
+        On paid-tool calls the post-deduction billing result is attached to
+        the returned user as ``user["_billing"]`` = ``{"cost", "source",
+        "remaining_credits"}``. Tool handlers that want to surface a usage
+        block in their response can read it directly; callers that don't
+        care keep working unchanged (non-breaking addition).
+        """
+        user = await self.auth.require_auth(request, tool_name, self.db)
+        if user is None:
+            # Read-only tool, no auth provided
+            return {
+                "logto_user_id": "anonymous",
+                "free_credits": 0,
+                "credits_used": 0,
+            }
+        billing_info = await self.billing.check_and_deduct(
+            self.db, user, tool_name, request
+        )
+        if billing_info is not None:
+            user["_billing"] = billing_info
+        return user
+
+    # ── Logging shortcut ──────────────────────────────────
+
+    async def log_tool_call(
+        self,
+        request: Request,
+        tool: str,
+        user: Optional[Dict[str, Any]] = None,
+        duration_ms: int = 0,
+        status: str = "ok",
+        error: str = "",
+        meta: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """Log a tool call to the audit trail."""
+        user_id = (user or {}).get("logto_user_id", "")
+        cost = self.billing.get_tool_cost(tool)
+        await self.tool_logger.log(
+            request=request,
+            tool=tool,
+            user_id=user_id,
+            duration_ms=duration_ms,
+            status=status,
+            cost=cost,
+            error=error,
+            meta=meta,
+        )
+
+    # ── FastAPI integration ───────────────────────────────
+
+    def install_routes(self, app: FastAPI) -> None:
+        """Register standard routes: /health, /api/billing/credits, webhook, OAuth metadata."""
+        install_routes(app, self)
+
+    def mount_mcp(
+        self,
+        app: FastAPI,
+        *,
+        name: str,
+        description: str = "",
+        tags=("mcp",),
+        legacy_sse: bool = True,
+        mount_path_legacy: str = "/mcp",
+        mount_path_v2: str = "/mcp/v2",
+        instructions: str = "",
+        require_auth: bool = True,
+    ) -> Dict[str, Any]:
+        """Mount MCP transports (legacy SSE + stateless HTTP).
+
+        See `mcp_core.mcp_mount.mount_mcp` for full docs. This method
+        forwards `self` as `core` so callers don't repeat it.
+        """
+        return mount_mcp(
+            app,
+            core=self,
+            name=name,
+            description=description,
+            tags=tags,
+            legacy_sse=legacy_sse,
+            mount_path_legacy=mount_path_legacy,
+            mount_path_v2=mount_path_v2,
+            instructions=instructions,
+            require_auth=require_auth,
+        )
+
+    def mcp_auth_config(self) -> Any:
+        """Return an AuthConfig for fastapi-mcp.
+
+        Requires fastapi-mcp to be installed (it's a peer dependency).
+        """
+        if not self.auth.endpoint or not self._mcp_app_id:
+            return None
+        try:
+            from fastapi_mcp.types import AuthConfig
+        except ImportError:
+            from fastapi_mcp import AuthConfig
+        return AuthConfig(
+            issuer=f"{self.auth.endpoint}/oidc",
+            oauth_metadata_url=(
+                f"{self.auth.endpoint}/oidc/.well-known/openid-configuration"
+            ),
+            authorize_url=f"{self.auth.endpoint}/oidc/auth",
+            client_id=self._mcp_app_id,
+            client_secret=self._mcp_app_secret,
+            audience=self.auth.api_resource,
+            default_scope=" ".join(
+                self._oauth_scopes
+                or ["openid", "profile", "email"]
+            ),
+            setup_proxies=True,
+            # Keep fake DCR on so fastapi-mcp advertises `registration_endpoint`
+            # in the auth-server metadata (MCP SDK refuses servers without it).
+            # When real DCR is enabled, mcp-core's /oauth/register route is
+            # registered first via install_routes(), so FastAPI's first-match
+            # router dispatches there and fastapi-mcp's fake handler never runs.
+            setup_fake_dynamic_registration=True,
+        )

mcp_core/auth.py

@@ -0,0 +1,235 @@
+"""
+Logto JWT validation and user provisioning for MCP-first servers.
+
+Validates JWTs issued by Logto using JWKS endpoint.
+Creates user records in MongoDB on first auth (race-condition-safe upsert).
+"""
+
+import logging
+import time
+from datetime import datetime, timezone
+from typing import Any, Dict, Optional, Set
+
+import jwt
+from fastapi import HTTPException, Request
+from jwt import PyJWKClient
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["LogtoAuth"]
+
+
+class LogtoAuth:
+    """Logto JWT validation and user provisioning.
+
+    Args:
+        endpoint: Logto tenant URL (e.g. "https://your-tenant.logto.app" or self-hosted "https://auth.example.com").
+        api_resource: Logto API resource / audience (e.g. "https://api.example.com").
+        free_credits: Credits granted to new users on first auth.
+        dev_bypass: Accept "Bearer dev-bypass" as a valid token (local dev only).
+        dev_user_id: User ID returned for dev-bypass tokens.
+        read_only_tools: Tool names that don't require authentication.
+        reject_m2m: Reject machine-to-machine tokens (sub == client_id) for paid tools.
+    """
+
+    def __init__(
+        self,
+        endpoint: str = "",
+        api_resource: str = "",
+        free_credits: int = 30,
+        dev_bypass: bool = False,
+        dev_user_id: str = "local-dev-user",
+        read_only_tools: Optional[Set[str]] = None,
+        reject_m2m: bool = True,
+    ):
+        self.endpoint = endpoint.rstrip("/") if endpoint else ""
+        self.api_resource = api_resource
+        self.free_credits = free_credits
+        self.dev_bypass = dev_bypass
+        self.dev_user_id = dev_user_id
+        self.read_only_tools = read_only_tools or set()
+        self.reject_m2m = reject_m2m
+
+        self._jwks_client: Optional[PyJWKClient] = None
+        self._jwks_last_init: float = 0.0
+
+    # ── JWKS ──────────────────────────────────────────────
+
+    def _get_jwks_client(self) -> Optional[PyJWKClient]:
+        if not self.endpoint:
+            return None
+        # Refresh JWKS client every hour
+        if self._jwks_client and (time.time() - self._jwks_last_init) < 3600:
+            return self._jwks_client
+        jwks_url = f"{self.endpoint}/oidc/jwks"
+        try:
+            self._jwks_client = PyJWKClient(jwks_url, cache_keys=True)
+            self._jwks_last_init = time.time()
+            logger.info("[auth] JWKS client initialized: %s", jwks_url)
+            return self._jwks_client
+        except Exception as e:
+            logger.error("[auth] Failed to initialize JWKS client: %s", e)
+            return None
+
+    # ── Token extraction ──────────────────────────────────
+
+    @staticmethod
+    def _extract_bearer_token(request: Request) -> Optional[str]:
+        auth = request.headers.get("authorization", "")
+        if auth.startswith("Bearer "):
+            return auth[7:]
+        return None
+
+    # ── Token validation ──────────────────────────────────
+
+    async def verify_token(self, request: Request) -> Optional[Dict[str, Any]]:
+        """Validate JWT from request Authorization header.
+
+        Returns decoded payload if valid, None if no token provided.
+        Raises HTTPException(401) if token is invalid/expired.
+        """
+        token = self._extract_bearer_token(request)
+        if not token:
+            return None
+
+        # Dev bypass
+        if self.dev_bypass and token == "dev-bypass":
+            return {"sub": self.dev_user_id, "email": "dev@localhost"}
+
+        jwks_client = self._get_jwks_client()
+        if not jwks_client:
+            logger.warning("[auth] Auth not configured, allowing request through")
+            return {"sub": "anonymous", "dev_mode": True}
+
+        try:
+            signing_key = jwks_client.get_signing_key_from_jwt(token)
+            payload = jwt.decode(
+                token,
+                signing_key.key,
+                algorithms=["RS256", "ES256", "ES384", "ES512"],
+                audience=self.api_resource,
+                issuer=f"{self.endpoint}/oidc",
+                options={"verify_exp": True},
+                leeway=30,
+            )
+            return payload
+        except jwt.ExpiredSignatureError:
+            raise HTTPException(status_code=401, detail="Token expired")
+        except (jwt.InvalidTokenError, jwt.exceptions.PyJWKClientError) as e:
+            raise HTTPException(status_code=401, detail=f"Invalid token: {e}")
+
+    # ── User provisioning ─────────────────────────────────
+
+    async def get_or_create_user(
+        self, db: Any, token_payload: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        """Get or create user record in MongoDB from token payload.
+
+        Uses find_one_and_update with upsert to avoid race conditions.
+        Rejects M2M tokens if reject_m2m is True.
+        """
+        sub = token_payload.get("sub", "")
+        client_id = token_payload.get("client_id", "")
+
+        # Reject M2M tokens (sub == client_id means it's an app, not a user)
+        if self.reject_m2m and sub and client_id and sub == client_id:
+            raise HTTPException(
+                status_code=403,
+                detail="Machine-to-machine tokens cannot call paid tools. "
+                "Use a per-user OAuth token.",
+            )
+
+        if db is None:
+            return self._ephemeral_user(token_payload)
+
+        if not sub:
+            raise HTTPException(status_code=401, detail="Token missing 'sub' claim")
+
+        result = await db["users"].find_one_and_update(
+            {"logto_user_id": sub},
+            {
+                "$setOnInsert": {
+                    "logto_user_id": sub,
+                    "email": token_payload.get("email", ""),
+                    "free_credits": self.free_credits,
+                    "credits_used": 0,
+                    "stripe_customer_id": None,
+                    "stripe_subscription_id": None,
+                    "created_at": datetime.now(timezone.utc),
+                }
+            },
+            upsert=True,
+            return_document=True,  # motor uses True, not ReturnDocument enum
+        )
+        return result
+
+    def _ephemeral_user(self, token_payload: Dict[str, Any]) -> Dict[str, Any]:
+        """Return an in-memory user dict when no DB is available."""
+        return {
+            "logto_user_id": token_payload.get("sub", "anonymous"),
+            "email": token_payload.get("email", ""),
+            "free_credits": self.free_credits,
+            "credits_used": 0,
+            "stripe_customer_id": None,
+            "stripe_subscription_id": None,
+        }
+
+    # ── Require auth for tool ─────────────────────────────
+
+    async def require_auth(
+        self, request: Request, tool_name: str, db: Any = None
+    ) -> Optional[Dict[str, Any]]:
+        """Validate auth for a tool call.
+
+        Returns user dict for paid tools, None for read-only tools without a token.
+        Raises HTTPException(401) if a paid tool is called without valid auth.
+        """
+        if tool_name in self.read_only_tools:
+            payload = await self.verify_token(request)
+            # pymongo Database raises NotImplementedError on bool() (historical
+            # truthiness gotcha). The paid-tool branch below uses the correct
+            # `db is not None` — keep read-only consistent so authenticated
+            # read-only calls don't 500 on the first call.
+            if payload and db is not None:
+                return await self.get_or_create_user(db, payload)
+            return None
+
+        payload = await self.verify_token(request)
+        if payload is None:
+            raise HTTPException(
+                status_code=401,
+                detail=f"Authentication required for {tool_name}. "
+                "Provide a valid Bearer token.",
+            )
+        if db is not None:
+            return await self.get_or_create_user(db, payload)
+        return self._ephemeral_user(payload)
+
+    # ── OAuth metadata ────────────────────────────────────
+
+    def oauth_protected_resource_metadata(
+        self, scopes: Optional[list] = None, base_url: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """RFC 9728 /.well-known/oauth-protected-resource response.
+
+        Args:
+            scopes: Supported OAuth scopes.
+            base_url: When set (typically from the request), use the server's
+                own URL as the authorization server. This is required when
+                fastapi-mcp's ``setup_proxies=True`` proxies OAuth routes
+                through the server itself.
+        """
+        if base_url:
+            auth_servers = [base_url.rstrip("/")]
+        elif self.endpoint:
+            auth_servers = [f"{self.endpoint}/oidc"]
+        else:
+            auth_servers = []
+
+        return {
+            "resource": self.api_resource,
+            "authorization_servers": auth_servers,
+            "scopes_supported": scopes
+            or ["openid", "profile", "email"],
+            "bearer_methods_supported": ["header"],
+        }