panda-gateway: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

PanDA Gateway is a thin, stateless MCP routing layer between the PanDA Monitor (or any MCP client) and upstream MCP servers (Bamboo MCP, PanDA MCP, and future additions). It exposes a single MCP endpoint (Streamable HTTP) and routes each tools/call to the correct upstream based on a namespace prefix in the tool name. It carries no LLM logic, no planning, no synthesis.

Human-facing docs live in docs/: architecture.md (components, design decisions), catalog-and-search.md (tool catalog + RAG), security-and-resilience.md (trust model, hardening, failure recovery — read before any non-local deployment change). This file is the Claude-Code-specific companion to those, not a replacement.

Commands

# Install (runtime)
pip install -e .

# Install for development
pip install -e ".[dev]"

# Install with OpenTelemetry support
pip install -e ".[observability]"

# Run tests
python -m pytest tests/

# Run a single test file
python -m pytest tests/test_registry.py -v

# Lint
flake8 panda_gateway tests

# Type check
pyright

# Run the gateway (HTTP mode)
panda-gateway --config gateway.minimal.toml

# Run in stdio mode (development)
panda-gateway --config gateway.minimal.toml --stdio

# Health check
curl http://127.0.0.1:8090/healthz

Requires Python ≥ 3.11.

Architecture

PanDA Monitor (MCP client)
        │  MCP / Streamable HTTP  (Bearer token)
        ▼
┌─────────────────────────────────────────────┐
│              PanDA Gateway                  │
│  GatewayServer · UpstreamRegistry · Router  │
└─────────────────────────────────────────────┘
        │           │           │
   Bamboo MCP   PanDA MCP   (future)
   bamboo.*     panda.*

Module responsibilities

• config.py — Pydantic models loaded from TOML. Config path comes from --config CLI flag or PANDA_GATEWAY_CONFIG env var. Secrets (tokens) are never in the TOML; the file only names the env var or file path that holds them. All models set extra = "forbid": an unknown/misspelled TOML key raises at load time.
• auth.py — Inbound pure-ASGI BearerAuthMiddleware (constant-time compare; only /healthz is unauthenticated) and outbound TokenProviders: EnvTokenProvider and FileTokenProvider (re-reads the file on every reconnect for OIDC token renewal).
• registry.py — One UpstreamHandle per upstream, each running a supervisor task: open transport, initialise a ClientSession (bounded by init_timeout), run the paginated tools/list probe (bounded by probe_timeout, fully following pagination via nextCursor, bounded by _MAX_PROBE_PAGES, committed to the catalog only once all pages succeed) — state only becomes UP once this first probe succeeds, not right after initialize() — then the two-tier health loop (liveness ping every 45 s bounded by ping_timeout, tools/list probe every 12 min). On failure — including one reported by the router via report_failure() for a routed call that hit a broken session — reconnect with exponential backoff + jitter (consecutive-failure count resets after a reconnect completes init and its first probe, not only on clean shutdown). report_failure() is generation-guarded: a stale report about an already-replaced session is a no-op. UpstreamRegistry.start() runs each supervisor behind an outer crash boundary (_supervise) so an unexpected exception in one upstream's lifecycle can never cancel sibling upstreams or the app's own task group — they share one anyio task group (see server.py/cli.py). Outbound redirects are off by default per upstream (allow_redirects); httpx strips Authorization but not custom headers like X-Auth-Token on a cross-origin redirect.
• router.py — Splits <namespace><sep><tool> on the first separator, looks the namespace up in the registry, forwards the call verbatim. Returns JSON-RPC -32602 for unknown namespace, -32603 for a configured but DOWN upstream. A transport/protocol failure observed here (not a mere call-level timeout, and not a legitimate upstream tool error — those come back as ordinary isError results, never raised) is reported to the owning handle via report_failure(), forcing an immediate reconnect instead of waiting for the next scheduled health check.
• catalog.py — Per-namespace cache of probed tool lists with a SHA-256 fingerprint over the entire Tool model (not hand-picked fields, so a change to outputSchema/annotations/title/etc. is detected too), plus a ChromaDB RagIndex (cosine similarity over tool description embeddings) for gateway.search_tools. Reindexing embeds the replacement documents before mutating the collection, then upserts new entries and removes only stale ones — a failed embed never empties a namespace's index. RagIndex.query(..., namespaces=...) filters results to the caller's currently-UP namespaces so search never suggests an unavailable tool.
• server.py — Assembles everything into a FastAPI app; registers the gateway.search_tools tool and the /healthz endpoint. Uses a raw CallToolRequest handler (not the @server.call_tool() decorator) so McpError propagates as a genuine JSON-RPC error rather than an isError tool result.
• observability.py — Optional OTel tracing; no-op when the SDK/endpoint is absent.
• cli.py — Entry point (panda-gateway script), parses --config and --stdio flags.