interloper-mcp 0.42.0__tar.gz

interloper_mcp-0.42.0/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.3
+Name: interloper-mcp
+Version: 0.42.0
+Summary: Interloper MCP server — read-only platform access for AI agents
+Author: Guillaume Onfroy
+Author-email: Guillaume Onfroy <guillaume@digitlcloud.com>
+Requires-Dist: interloper-core
+Requires-Dist: interloper-db
+Requires-Dist: interloper-toolkit
+Requires-Dist: mcp>=1.28,<2
+Requires-Dist: uvicorn[standard]>=0.30.0
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# interloper-mcp
+
+A [Model Context Protocol](https://modelcontextprotocol.io) server exposing
+read-only interloper platform access to AI agents: catalog definitions,
+collection listings, lineage, run/backfill monitoring, and analytics.
+
+Authentication uses **personal access tokens** (PATs) minted via the
+interloper API (`POST /api/tokens`, session-authenticated). Tokens are
+org-scoped and carry the holder's live role; revocation and membership
+removal apply immediately.
+
+## Running
+
+Streamable HTTP (default; binds `INTERLOPER_MCP_HOST:INTERLOPER_MCP_PORT`,
+endpoint `/mcp`):
+
+```sh
+interloper-mcp
+```
+
+Clients authenticate every request with `Authorization: Bearer ilp_...`.
+
+stdio (single-user, authenticates once at startup):
+
+```sh
+INTERLOPER_MCP_TOKEN=ilp_... interloper-mcp --transport stdio
+```
+
+For local development without a token, `INTERLOPER_MCP_ORG_ID=<uuid>` scopes
+the stdio server to one organisation directly.
+
+## Connecting clients
+
+MCP Inspector:
+
+```sh
+npx @modelcontextprotocol/inspector
+# Transport: Streamable HTTP, URL: http://localhost:3001/mcp
+# Header: Authorization: Bearer ilp_...
+```
+
+Claude Code:
+
+```sh
+claude mcp add --transport http interloper http://localhost:3001/mcp \
+  --header "Authorization: Bearer ilp_..."
+```
+
+## Settings
+
+| Env var | Default | Purpose |
+| --- | --- | --- |
+| `INTERLOPER_MCP_HOST` | `0.0.0.0` | HTTP bind host |
+| `INTERLOPER_MCP_PORT` | `3001` | HTTP bind port |
+| `INTERLOPER_MCP_EXTERNAL_URL` | — | Public base URL (e.g. `https://mcp.interloper.app`), used in OAuth protected-resource metadata |
+| `INTERLOPER_MCP_TOKEN` | — | stdio only: PAT to authenticate as |
+| `INTERLOPER_MCP_ORG_ID` | — | stdio only: dev fallback, direct org scope |
+
+Database and catalog configuration is the standard interloper set
+(`INTERLOPER_POSTGRES_*`, `INTERLOPER_CATALOG`, ...).
+
+## Deployment (not yet wired)
+
+The container target would follow the existing dockerfile pattern:
+
+```dockerfile
+FROM base AS build-mcp
+COPY packages ./packages
+RUN docker/uv-sync.sh interloper-core interloper-assets interloper-db interloper-toolkit interloper-mcp
+
+FROM runtime AS mcp
+COPY --from=build-mcp /interloper/.venv /interloper/.venv
+USER app
+EXPOSE 3001
+CMD ["interloper-mcp"]
+```
+
+plus a `mcp` role in the Makefile/publish workflow, a Helm/Flux workload
+(`apps/interloper/mcp/` with an HTTPRoute for `mcp.interloper.app` — wildcard
+DNS + TLS already cover it), and its own GSA/IAM DB user in terraform if it
+should not share the app's identity.

interloper_mcp-0.42.0/README.md

@@ -0,0 +1,81 @@
+# interloper-mcp
+
+A [Model Context Protocol](https://modelcontextprotocol.io) server exposing
+read-only interloper platform access to AI agents: catalog definitions,
+collection listings, lineage, run/backfill monitoring, and analytics.
+
+Authentication uses **personal access tokens** (PATs) minted via the
+interloper API (`POST /api/tokens`, session-authenticated). Tokens are
+org-scoped and carry the holder's live role; revocation and membership
+removal apply immediately.
+
+## Running
+
+Streamable HTTP (default; binds `INTERLOPER_MCP_HOST:INTERLOPER_MCP_PORT`,
+endpoint `/mcp`):
+
+```sh
+interloper-mcp
+```
+
+Clients authenticate every request with `Authorization: Bearer ilp_...`.
+
+stdio (single-user, authenticates once at startup):
+
+```sh
+INTERLOPER_MCP_TOKEN=ilp_... interloper-mcp --transport stdio
+```
+
+For local development without a token, `INTERLOPER_MCP_ORG_ID=<uuid>` scopes
+the stdio server to one organisation directly.
+
+## Connecting clients
+
+MCP Inspector:
+
+```sh
+npx @modelcontextprotocol/inspector
+# Transport: Streamable HTTP, URL: http://localhost:3001/mcp
+# Header: Authorization: Bearer ilp_...
+```
+
+Claude Code:
+
+```sh
+claude mcp add --transport http interloper http://localhost:3001/mcp \
+  --header "Authorization: Bearer ilp_..."
+```
+
+## Settings
+
+| Env var | Default | Purpose |
+| --- | --- | --- |
+| `INTERLOPER_MCP_HOST` | `0.0.0.0` | HTTP bind host |
+| `INTERLOPER_MCP_PORT` | `3001` | HTTP bind port |
+| `INTERLOPER_MCP_EXTERNAL_URL` | — | Public base URL (e.g. `https://mcp.interloper.app`), used in OAuth protected-resource metadata |
+| `INTERLOPER_MCP_TOKEN` | — | stdio only: PAT to authenticate as |
+| `INTERLOPER_MCP_ORG_ID` | — | stdio only: dev fallback, direct org scope |
+
+Database and catalog configuration is the standard interloper set
+(`INTERLOPER_POSTGRES_*`, `INTERLOPER_CATALOG`, ...).
+
+## Deployment (not yet wired)
+
+The container target would follow the existing dockerfile pattern:
+
+```dockerfile
+FROM base AS build-mcp
+COPY packages ./packages
+RUN docker/uv-sync.sh interloper-core interloper-assets interloper-db interloper-toolkit interloper-mcp
+
+FROM runtime AS mcp
+COPY --from=build-mcp /interloper/.venv /interloper/.venv
+USER app
+EXPOSE 3001
+CMD ["interloper-mcp"]
+```
+
+plus a `mcp` role in the Makefile/publish workflow, a Helm/Flux workload
+(`apps/interloper/mcp/` with an HTTPRoute for `mcp.interloper.app` — wildcard
+DNS + TLS already cover it), and its own GSA/IAM DB user in terraform if it
+should not share the app's identity.

interloper_mcp-0.42.0/pyproject.toml

@@ -0,0 +1,42 @@
+# ###############
+# PROJECT / UV
+# ###############
+[project]
+name = "interloper-mcp"
+version = "0.42.0"
+description = "Interloper MCP server — read-only platform access for AI agents"
+readme = "README.md"
+authors = [{ name = "Guillaume Onfroy", email = "guillaume@digitlcloud.com" }]
+requires-python = ">=3.10"
+dependencies = [
+    "interloper-core",
+    "interloper-db",
+    "interloper-toolkit",
+    "mcp>=1.28,<2",
+    "uvicorn[standard]>=0.30.0",
+]
+
+[project.scripts]
+interloper-mcp = "interloper_mcp.main:main"
+
+[build-system]
+requires = ["uv_build>=0.11.5,<0.12"]
+build-backend = "uv_build"
+
+[tool.uv.sources]
+interloper-core = { workspace = true }
+interloper-db = { workspace = true }
+interloper-toolkit = { workspace = true }
+
+# ###############
+# RUFF
+# ###############
+[tool.ruff]
+line-length = 120
+
+[tool.ruff.lint]
+extend-select = ["E", "I", "UP", "ANN001", "ANN201", "ANN202"]
+
+[tool.ruff.lint.per-file-ignores]
+"__init__.py" = ["F401", "F403"]
+"tests/**" = ["ANN", "F811"]

interloper_mcp-0.42.0/src/interloper_mcp/__init__.py

@@ -0,0 +1 @@
+"""Interloper MCP server — read-only platform access for AI agents."""

interloper_mcp-0.42.0/src/interloper_mcp/auth.py

@@ -0,0 +1,55 @@
+"""Bearer-token verification: personal access tokens as MCP access tokens.
+
+The SDK treats the server as an OAuth resource server; a
+:class:`~mcp.server.auth.provider.TokenVerifier` is its seam for validating
+whatever bearer token arrives. Interloper PATs slot straight in — and an
+OAuth authorization server can later mint short-lived tokens verified through
+this same seam without touching the tools.
+"""
+
+from __future__ import annotations
+
+import anyio.to_thread
+from interloper_db import Store
+from mcp.server.auth.provider import AccessToken, TokenVerifier
+
+
+class PatAccessToken(AccessToken):
+    """An access token backed by a verified personal access token."""
+
+    org_id: str
+    role: str
+    profile_id: str
+
+
+class PatVerifier(TokenVerifier):
+    """Verify raw bearer tokens against the PAT store.
+
+    Resolution enforces revocation, expiry, and live org membership; the
+    resulting token carries the tenant scope every tool call runs under.
+    """
+
+    def __init__(self, store: Store) -> None:
+        self._store = store
+
+    async def verify_token(self, token: str) -> AccessToken | None:
+        """Resolve a raw bearer token; ``None`` rejects the request with a 401.
+
+        Args:
+            token: The bearer token exactly as presented by the client.
+        """
+        # The store is synchronous — keep the event loop free.
+        result = await anyio.to_thread.run_sync(self._store.resolve_token, token)
+        if result is None:
+            return None
+
+        profile, pat, role = result
+        return PatAccessToken(
+            token=token,
+            client_id=str(profile.id),
+            scopes=[f"role:{role}"],
+            expires_at=int(pat.expires_at.timestamp()) if pat.expires_at else None,
+            org_id=str(pat.organisation_id),
+            role=role,
+            profile_id=str(profile.id),
+        )

interloper_mcp-0.42.0/src/interloper_mcp/context.py

@@ -0,0 +1,82 @@
+"""Process globals and per-request toolkit context resolution.
+
+Two authentication paths converge on :func:`get_ctx`:
+
+- **Streamable HTTP**: every request carries a bearer PAT; the SDK's auth
+  middleware stores the verified token in a contextvar, read back here via
+  ``get_access_token()``.
+- **stdio**: single-user by nature; the context is resolved once at startup
+  (from a PAT or a direct org scope) and seeded via :func:`set_static_ctx`.
+"""
+
+from __future__ import annotations
+
+from contextvars import ContextVar
+from typing import Any
+from uuid import UUID
+
+from interloper.catalog.base import Catalog
+from interloper_db import Store
+from interloper_toolkit import ToolkitContext
+from mcp.server.auth.middleware.auth_context import get_access_token
+
+from interloper_mcp.auth import PatAccessToken
+
+_store: Store | None = None
+_catalog_dump: dict[str, Any] | None = None
+
+_static_ctx: ContextVar[ToolkitContext | None] = ContextVar("interloper_mcp_static_ctx", default=None)
+
+
+def init_context(store: Store, catalog: Catalog) -> None:
+    """Set the process-wide store and catalog (once, at startup).
+
+    Args:
+        store: The Store every request queries.
+        catalog: The catalog; dumped once — definitions don't change at runtime.
+    """
+    global _store, _catalog_dump  # noqa: PLW0603
+    _store = store
+    _catalog_dump = catalog.dump()
+
+
+def set_static_ctx(org_id: UUID) -> None:
+    """Seed the static (stdio) context with an organisation scope.
+
+    Args:
+        org_id: The organisation all tool calls are scoped to.
+    """
+    _static_ctx.set(ToolkitContext(store=_require_store(), catalog=_require_catalog(), org_id=org_id))
+
+
+def get_ctx() -> ToolkitContext:
+    """Build the toolkit context for the current tool call.
+
+    Returns:
+        The org-scoped context — from the request's verified bearer token
+        (HTTP) or the startup-seeded scope (stdio).
+
+    Raises:
+        RuntimeError: When no authenticated context exists (a programming
+            error: the transport must enforce auth before tools run).
+    """
+    token = get_access_token()
+    if isinstance(token, PatAccessToken):
+        return ToolkitContext(store=_require_store(), catalog=_require_catalog(), org_id=UUID(token.org_id))
+
+    ctx = _static_ctx.get()
+    if ctx is None:
+        raise RuntimeError("No authenticated context for this tool call")
+    return ctx
+
+
+def _require_store() -> Store:
+    if _store is None:
+        raise RuntimeError("MCP context not initialized. Call init_context() first.")
+    return _store
+
+
+def _require_catalog() -> dict[str, Any]:
+    if _catalog_dump is None:
+        raise RuntimeError("MCP context not initialized. Call init_context() first.")
+    return _catalog_dump

interloper_mcp-0.42.0/src/interloper_mcp/main.py

@@ -0,0 +1,84 @@
+"""Console entry point for the interloper MCP server."""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import sys
+from uuid import UUID
+
+from interloper.catalog.base import Catalog
+from interloper.settings import AppSettings
+from interloper_db import Store
+
+from interloper_mcp.context import init_context, set_static_ctx
+from interloper_mcp.server import create_mcp_server
+
+logger = logging.getLogger(__name__)
+
+
+def main() -> None:
+    """Run the MCP server on the selected transport."""
+    parser = argparse.ArgumentParser(prog="interloper-mcp", description="Interloper MCP server (read-only)")
+    parser.add_argument(
+        "--transport",
+        choices=["streamable-http", "stdio"],
+        default="streamable-http",
+        help="streamable-http serves bearer-authenticated HTTP (default); stdio authenticates once at startup",
+    )
+    parser.add_argument("--host", default=None, help="Bind host (overrides INTERLOPER_MCP_HOST)")
+    parser.add_argument("--port", type=int, default=None, help="Bind port (overrides INTERLOPER_MCP_PORT)")
+    args = parser.parse_args()
+
+    logging.basicConfig(level=logging.INFO, stream=sys.stderr)
+
+    settings = AppSettings.get().mcp
+    if args.host is not None:
+        settings.host = args.host
+    if args.port is not None:
+        settings.port = args.port
+
+    catalog = Catalog.from_settings()
+    store = Store.from_settings(catalog=catalog)
+    init_context(store, catalog)
+
+    if args.transport == "stdio":
+        set_static_ctx(_resolve_stdio_org(store, settings.token, settings.org_id))
+        mcp = create_mcp_server(settings, store=None)
+        mcp.run(transport="stdio")
+    else:
+        mcp = create_mcp_server(settings, store=store)
+        logger.info("Serving streamable HTTP on %s:%s/mcp", settings.host, settings.port)
+        mcp.run(transport="streamable-http")
+
+
+def _resolve_stdio_org(store: Store, token: str, org_id: str) -> UUID:
+    """Resolve the organisation scope for the stdio transport.
+
+    A PAT (``INTERLOPER_MCP_TOKEN``) is the normal path; a bare
+    ``INTERLOPER_MCP_ORG_ID`` is a local-development fallback that skips
+    authentication entirely.
+
+    Args:
+        store: The Store to resolve the token against.
+        token: Raw personal access token, or empty.
+        org_id: Organisation UUID string, or empty.
+
+    Returns:
+        The organisation UUID to scope all tool calls to.
+    """
+    if token:
+        resolved = store.resolve_token(token)
+        if resolved is None:
+            raise SystemExit("INTERLOPER_MCP_TOKEN is invalid, expired, or revoked")
+        profile, pat, role = resolved
+        logger.info("Authenticated as %s (role %s)", profile.email, role)
+        return pat.organisation_id
+    if org_id:
+        logger.warning("Running without authentication, scoped to org %s (INTERLOPER_MCP_ORG_ID)", org_id)
+        return UUID(org_id)
+    raise SystemExit("stdio transport needs INTERLOPER_MCP_TOKEN (or INTERLOPER_MCP_ORG_ID for local development)")
+
+
+if __name__ == "__main__":
+    main()

interloper_mcp-0.42.0/src/interloper_mcp/server.py

@@ -0,0 +1,61 @@
+"""MCP server factory: FastMCP wired with PAT auth and the read-only tools."""
+
+from __future__ import annotations
+
+from interloper.settings import McpSettings
+from interloper_db import Store
+from mcp.server.auth.settings import AuthSettings as McpAuthSettings
+from mcp.server.fastmcp import FastMCP
+from pydantic import AnyHttpUrl
+
+from interloper_mcp.auth import PatVerifier
+from interloper_mcp.tools import register_tools
+
+SERVER_NAME = "interloper"
+
+INSTRUCTIONS = (
+    "Read-only access to an interloper deployment: the catalog of available "
+    "component definitions, the organisation's collection (sources, "
+    "connections, destinations, jobs), asset lineage, run and backfill "
+    "monitoring, and analytics (freshness, coverage, history). All results "
+    "are scoped to the organisation of the authenticated token."
+)
+
+
+def create_mcp_server(settings: McpSettings, store: Store | None = None) -> FastMCP:
+    """Build the FastMCP server.
+
+    Args:
+        settings: The MCP settings (host, port, external URL).
+        store: When provided, requests authenticate as bearer PATs against
+            this store (the streamable HTTP mode). ``None`` builds an
+            unauthenticated server for the stdio transport, whose context is
+            seeded once at startup instead.
+
+    Returns:
+        The configured server with all read-only tools registered.
+    """
+    auth_kwargs: dict = {}
+    if store is not None:
+        # external_url doubles as issuer and resource URL in the RFC 9728
+        # protected-resource metadata; default to the local bind address so
+        # dev servers work without configuration.
+        base_url = settings.external_url or f"http://localhost:{settings.port}"
+        auth_kwargs = {
+            "token_verifier": PatVerifier(store),
+            "auth": McpAuthSettings(
+                issuer_url=AnyHttpUrl(base_url),
+                resource_server_url=AnyHttpUrl(base_url),
+            ),
+        }
+
+    mcp = FastMCP(
+        SERVER_NAME,
+        instructions=INSTRUCTIONS,
+        host=settings.host,
+        port=settings.port,
+        stateless_http=True,
+        **auth_kwargs,
+    )
+    register_tools(mcp)
+    return mcp

interloper_mcp-0.42.0/src/interloper_mcp/tools.py

@@ -0,0 +1,125 @@
+"""MCP tool registration — thin wrappers over the shared read-only toolkit.
+
+Every wrapper is one delegation line; the implementations live in
+``interloper_toolkit`` (shared with the ADK agent), and their LLM-facing
+docstrings are adopted as the tool descriptions. FastMCP derives each tool's
+input schema from the wrapper's signature and its output schema from the
+typed ``<SuccessModel> | ToolError`` return annotation.
+
+Deliberately read-only: no mutation (trigger/toggle/create) tools are
+registered here.
+"""
+
+from __future__ import annotations
+
+from interloper_toolkit import analytics, catalog, collection, lineage, scheduling
+from interloper_toolkit import models as m
+from mcp.server.fastmcp import FastMCP
+
+from interloper_mcp.context import get_ctx
+
+
+def register_tools(mcp: FastMCP) -> None:
+    """Register the read-only interloper tools on the server.
+
+    Args:
+        mcp: The FastMCP server instance.
+    """
+    # -- Catalog ----------------------------------------------------------
+
+    @mcp.tool(description=catalog.list_definitions.__doc__)
+    def list_definitions(kind: str | None = None) -> m.DefinitionCounts | m.DefinitionList | m.ToolError:
+        return catalog.list_definitions(get_ctx(), kind)
+
+    @mcp.tool(description=catalog.get_definition.__doc__)
+    def get_definition(key: str) -> m.DefinitionDetail | m.ToolError:
+        return catalog.get_definition(get_ctx(), key)
+
+    @mcp.tool(description=catalog.get_asset_schema.__doc__)
+    def get_asset_schema(source_key: str, asset_key: str) -> m.AssetSchemaResult | m.ToolError:
+        return catalog.get_asset_schema(get_ctx(), source_key, asset_key)
+
+    @mcp.tool(description=catalog.search_fields.__doc__)
+    def search_fields(query: str) -> m.FieldSearchResult | m.ToolError:
+        return catalog.search_fields(get_ctx(), query)
+
+    @mcp.tool(description=catalog.compare_schemas.__doc__)
+    def compare_schemas(
+        source_key_a: str,
+        asset_key_a: str,
+        source_key_b: str,
+        asset_key_b: str,
+    ) -> m.SchemaComparison | m.ToolError:
+        return catalog.compare_schemas(get_ctx(), source_key_a, asset_key_a, source_key_b, asset_key_b)
+
+    # -- Collection -------------------------------------------------------
+
+    @mcp.tool(description=collection.list_components.__doc__)
+    def list_components(kind: str | None = None) -> m.ComponentCounts | m.ComponentList | m.ToolError:
+        return collection.list_components(get_ctx(), kind)
+
+    # -- Lineage ----------------------------------------------------------
+
+    @mcp.tool(description=lineage.get_upstream.__doc__)
+    def get_upstream(asset_id: str) -> m.UpstreamResult | m.ToolError:
+        return lineage.get_upstream(get_ctx(), asset_id)
+
+    @mcp.tool(description=lineage.get_downstream.__doc__)
+    def get_downstream(asset_id: str) -> m.DownstreamResult | m.ToolError:
+        return lineage.get_downstream(get_ctx(), asset_id)
+
+    @mcp.tool(description=lineage.get_full_lineage.__doc__)
+    def get_full_lineage(asset_id: str, direction: str = "upstream") -> m.LineageResult | m.ToolError:
+        return lineage.get_full_lineage(get_ctx(), asset_id, direction)
+
+    @mcp.tool(description=lineage.impact_analysis.__doc__)
+    def impact_analysis(asset_id: str) -> m.ImpactAnalysis | m.ToolError:
+        return lineage.impact_analysis(get_ctx(), asset_id)
+
+    @mcp.tool(description=lineage.cross_source_dependencies.__doc__)
+    def cross_source_dependencies() -> m.CrossSourceDependencies | m.ToolError:
+        return lineage.cross_source_dependencies(get_ctx())
+
+    # -- Scheduling (read-only) --------------------------------------------
+
+    @mcp.tool(description=scheduling.list_jobs.__doc__)
+    def list_jobs() -> m.JobList | m.ToolError:
+        return scheduling.list_jobs(get_ctx())
+
+    @mcp.tool(description=scheduling.get_job_health.__doc__)
+    def get_job_health(component_id: str) -> m.JobHealth | m.ToolError:
+        return scheduling.get_job_health(get_ctx(), component_id)
+
+    @mcp.tool(description=scheduling.list_recent_runs.__doc__)
+    def list_recent_runs(
+        component_id: str | None = None,
+        status: str | None = None,
+        limit: int = 20,
+    ) -> m.RunList | m.ToolError:
+        return scheduling.list_recent_runs(get_ctx(), component_id, status, limit)
+
+    @mcp.tool(description=scheduling.get_run_detail.__doc__)
+    def get_run_detail(run_id: str) -> m.RunDetail | m.ToolError:
+        return scheduling.get_run_detail(get_ctx(), run_id)
+
+    @mcp.tool(description=scheduling.list_failures.__doc__)
+    def list_failures(limit: int = 20) -> m.FailureList | m.ToolError:
+        return scheduling.list_failures(get_ctx(), limit)
+
+    @mcp.tool(description=scheduling.list_backfills.__doc__)
+    def list_backfills(active_only: bool = True) -> m.BackfillList | m.ToolError:
+        return scheduling.list_backfills(get_ctx(), active_only)
+
+    # -- Analytics ---------------------------------------------------------
+
+    @mcp.tool(description=analytics.run_history_summary.__doc__)
+    def run_history_summary(component_id: str | None = None, days: int = 7) -> m.RunHistorySummary | m.ToolError:
+        return analytics.run_history_summary(get_ctx(), component_id, days)
+
+    @mcp.tool(description=analytics.partition_coverage.__doc__)
+    def partition_coverage(component_id: str, start_date: str, end_date: str) -> m.PartitionCoverage | m.ToolError:
+        return analytics.partition_coverage(get_ctx(), component_id, start_date, end_date)
+
+    @mcp.tool(description=analytics.freshness_check.__doc__)
+    def freshness_check() -> m.FreshnessReport | m.ToolError:
+        return analytics.freshness_check(get_ctx())