supergateway/AGENTS.md

AGENTS.md

This repo is not an application. It is a local MCP server stack: a docker-compose file that runs AI-coding-tool helpers in Docker so opencode, crush, and VS Code plugins (Cline/Roo/Kilo) can all share the same local services over Streamable HTTP. There is no app source, no test suite, no linter — verification is manual (health endpoints, MCP handshakes, opencode mcp list).

Commands

cp .env.example .env        # once; add BRAVE_API_KEY
./add-project.sh <repo>     # register a project for code indexing (idempotent; starts stack)
./add-project.sh --remove <repo-or-slug>
docker compose up -d --build
docker compose ps / logs -f mcp / logs -f mcp-codebase-index
opencode reload && sleep 3 && opencode mcp list   # acceptance check

Architecture

Two services, one image (Dockerfile, node:24-slim: supergateway@4 + open-codebase-index + context7/brave/mcp-server-fetch preinstalled, glibc because the index ships NAPI binaries — do not switch the base to alpine):

• mcp-gateway (:8000) — supergateway --config supergateway.config.jsonc; one endpoint per shared tool: /fetch/mcp, /context7/mcp, /brave-search/mcp (edit the jsonc to add servers, then docker compose restart mcp).
• mcp-codebase-index (:8001) — supergateway --config supergateway.projects.jsonc (GENERATED by add-project.sh from projects.env; do not hand-edit, re-run the script). One endpoint per registered project: /<slug>/mcp. Mounts PROJECTS_ROOT (default ~/src, kept in .env) at the identical container path so index results return valid host paths. Runs as user: node (uid 1000) so index data is host-user owned. Index data lives in each project at .opencode/index/ (structural mode: BM25 + call graph, no embedding provider; ollama upgrade documented in README).

Per-project client configs (written into each project by add-project.sh): opencode.json, .crush.json, .roo/mcp.json, each pointing at http://localhost:8001/<slug>/mcp. Global client configs only carry the shared tools (fetch/context7/brave-search).

Gotchas

• Host docker networking is partly broken: the default docker0 bridge has NO egress (DNS/TCP fail); custom compose networks work fine. That is why builds use network: host in the compose file — keep it.
• opencode mcp list can print "No MCP servers configured" for a few seconds after opencode reload (daemon reconnects asynchronously). Retry before assuming breakage.
• After changing client configs, crush/opencode sessions must be restarted/reloaded; VS Code plugins need the workspace reopened.
• supergateway.projects.jsonc, projects.env, .env are gitignored and machine-specific. docker-compose.override.yml (if present) is the documented way to mount extra project roots.
• supergateway runs stateful Streamable HTTP; each client session spawns its own stdio server process (nothing idles; index data persists on disk between sessions).
• Add brief imperative commit messages; keep disabled blocks commented rather than deleted.