mcp-gateway: Instructions file for Codex

AGENTS.md

Project Overview

MCP Gateway — A standalone Python CLI that aggregates multiple MCP servers behind a single headless HTTP/SSE endpoint with Code Mode, plus an admin web dashboard at / (htpy + htmx + Tailwind CDN, v3.1.0 Unreleased — reintroduces management UI; CLI sigue canónico, catalog permanece retirado).

Nota interna: ver CHANGELOG.md (al día hasta v3.0.0, 2026-09-22). Releases internos no publicados — no anuncio externo.

Tech Stack

• Language: Python 3.12+
• Package Manager: uv (with mise for tool versions)
• CLI Framework: click
• HTTP Server: Starlette + uvicorn
• MCP SDK: mcp v2.0.0
• Sandbox: starlark-pyo3
• Testing: pytest + pytest-asyncio (621 tests)
• Linting: ruff
• Nota: htpy reintroducido en v3.1.0 (Unreleased, htpy==26.5.1) como renderer del dashboard admin — retirado en v2.0.0, ahora re-admitido; httpx v1 eliminado en favor de httpx2 (dependencia directa, alineada con mcp v2 y starlette 1.6).
• Dashboard: htpy (server rendering) + htmx 2.0.10 + Tailwind — ambos vía CDN (cdn.jsdelivr.net, cdn.tailwindcss.com); CSP relajado en la constante única CSP de gateway.py (script-src CDNs, style-src 'unsafe-inline', frame-ancestors 'none').

Project Structure

src/mcp_gway/
├── __init__.py          # Package version (3.1.0)
├── models.py            # Pydantic models (MCPServerConfig OpenCode-only local|remote, ToolInfo, OAuthConfig)
├── registry.py          # .pyi file CRUD (servers/ directory) — única fuente de verdad
├── sandbox.py           # Starlark sandbox (hermetic execution)
├── server_proxy.py      # MCP server wrapper for sandbox
├── server_factory.py    # Server structs + sync call wrappers for the sandbox
├── code_mode.py         # 4 meta-tools orchestrator
├── gateway.py           # HTTP/SSE server (JSON-RPC 2.0), local-first 127.0.0.1 + CSP — rutas /mcp por transporte (gateway.py:320-340, mcp_routes condicional; app.state.transport; sin fallback): http = POST /mcp (GET → 405 Allow: POST) + /health, /ready, /live, /metrics → 6 entradas; sse = GET /mcp (SSE) + POST /mcp → 405 Allow: GET + /mcp/messages (alias POST al handler _mcp_post, no endpoint independiente) + probes → 7 entradas
├── cli.py               # CLI commands (add/remove/update/list/inspect/refresh/serve --transport stdio|http|sse/mcp-hidden/local-unrestricted --host 127.0.0.1)
├── admin/               # Admin dashboard: theme, components, icons (SVG authored), layout, data, routes + pages/{status,overview,servers,tools,observability,policy} (htpy+htmx, CDN)
├── oauth.py             # OAuth2 support (dynamic registration, token storage); usa httpx2 (dependencia directa)
├── transport.py         # Shim deprecado → mcp_gway.core.transport (DeprecationWarning; eliminar en next major)
├── stdio.py             # SERVIDOR-side NDJSON: lee JSON-RPC 2.0 de stdin, responde por stdout (`mcp-gway serve --transport stdio`; `mcp` alias deprecado)
├── stdio_transport.py   # CLIENT-side: filtered_stdio_client conecta a niños MCP y filtra ruido no-JSON de su stdout
├── core/
│   ├── __init__.py      # Re-exports (create_client_transport, detect_transport, discover_tools, parse_envs/headers, refresh_server)
│   ├── transport.py     # Auto-detección de transporte remote (streamable-http → sse → http)
│   ├── policy.py        # Allow-list local + break-glass 72h (ADR-009), cwd/env gates, audit
│   ├── parsing.py       # parse_headers / parse_envs (KEY=VALUE)
│   ├── install.py       # Discovery + persist helpers (semáforo 3, oauth fallback)
│   └── client.py        # create_client_transport (local|remote), discover_tools, refresh_server
└── observability/
    ├── __init__.py      # Re-exports (JSONFormatter, MetricsRegistry, request_id_ctx, setup_logging)
    ├── logging.py       # JSONFormatter (stderr), request_id ContextVar, setup_logging
    ├── middleware.py    # Correlation (X-Request-ID), Metrics, Logging middlewares
    ├── metrics.py       # MetricsRegistry hand-rolled Prometheus exposition (counter/gauge/histogram)
    └── health.py        # /health, /ready, /live, /metrics (X-Warning: exposed gating)

> **Retirado en v2.0.0 (no servir):** dashboard legacy (`/dashboard`, `/api/servers`, `/static`) y catalog (`/api/catalog`, `/dashboard/catalog`, Bifrost fetch, `~/.config/mcp-gway/catalog.json`). El alias `/` fue reactivado en v3.1.0 como índice del admin (`/admin*`) — superficie nueva, no el dashboard legacy.

tests/
├── conftest.py                 # Fixtures compartidos
├── test_models.py              # Model validation tests (+ SSRF guard)
├── test_registry.py            # Registry CRUD tests (path traversal/symlink)
├── test_sandbox.py             # Sandbox execution tests
├── test_server_proxy.py        # Server proxy tests
├── test_server_factory.py      # Server factory structs + call wrappers
├── test_code_mode.py           # Code mode tests
├── test_gateway.py             # HTTP/SSE server tests
├── test_admin_dashboard.py     # Admin dashboard (pages, partials, CSRF, loopback gate, parity mutations)
├── test_cli.py                 # CLI command tests
├── test_integration.py         # End-to-end flow tests
├── test_transport.py           # Transport auto-detection tests
├── test_stdio.py               # Server-side NDJSON (mcp-gway mcp) tests
├── test_stdio_transport.py     # Client-side filtered stdio tests
├── test_policy_local_commands.py  # feat-006 allow-list policy tests
├── test_break_glass.py         # Break-glass marker TTL/permissions tests
├── test_feat006_harden.py      # feat-006 hardening tests (PATCH bypass, regates)
├── test_p0_fixes.py            # P0 regression fixes
├── test_wave2_api.py           # Wave-2 API asserts (CSP header etc.)
└── test_observability_*.py     # metrics / logging / probes / instrumentation

docs/
├── specs/SPEC-UI-001.md (+ SCENARIOS/ACCEPTANCE)  # SUPERSEDED 2026-09-10 (retirado; headless, CLI-only) — reversado parcial 2026-09-23: admin UI nueva en `/` + `/admin*` (v3.1.0 Unreleased, spec distinta)
├── adr/ADR-007-release-workflow-hybrid.md, ADR-008-catalog-mcp-001.md
├── architecture/adr-009-dynamic-local-commands.md, adr-010-unified-serve.md (referenciado, ausente en repo; enmienda ADR-010 AC-05 2026-09-22: http/sse comparten el entrypoint `_serve_http`, NO la app — rutas `/mcp` separadas por transporte, sin fallback)
├── sbtdd/specs/feat-006-dynamic-local-commands/   # spec + scenarios + acceptance + verify
├── superpowers/plans/                             # Planes fechados (históricos)
└── superpowers/specs/2026-08-2X-*                 # Specs de diseño (históricos)