codeforge-mcp: Instructions file for Claude Code

CodeForge MCP — Agent Notes

Container Names

All three services use explicit container_name entries in docker-compose.yaml: codeforge-mcp-server, codeforge-proxy, codeforge-sandbox. The sandbox name is hardcoded in mcp-server/src/sandbox.ts and in the Docker socket proxy whitelist (mcp-server/docker-proxy.cjs) — both constants and the compose entry must stay in sync.

APIs Are Image-Baked

apis/ is COPYed into both the mcp-server and proxy images at build time — there is no runtime bind mount. Changes to apis/ on the host require docker compose up -d --build mcp-server proxy to take effect.

MCP Transport

The server uses Streamable HTTP with stateful sessions (not SSE, not stdio). Each client connection gets a fresh McpServer + StreamableHTTPServerTransport pair, tracked by session ID. The SDK (v1.29+) forbids reusing a stateless transport across requests — do not revert to a single shared transport. Claude Desktop connects via npx mcp-remote http://localhost:8080/mcp.

Proxy Host Resolution

In transparent mode, mitmproxy's flow.request.host returns the destination IP, not the hostname — so the substitution addon must use flow.request.pretty_host (which prefers SNI / Host header) to look up per-host credential maps. Reverting to flow.request.host silently breaks all credential substitution because the configured host strings (e.g. api.tavily.com) never match the IP keys.

Proxy Privilege Drop

The proxy entrypoint runs as root only long enough to: generate the mitmproxy CA cert, configure iptables NAT rules, and chown -R mitmproxy:mitmproxy /certs. Then it exec su -s /bin/bash mitmproxy -c "mitmdump ..." to run mitmproxy as the unprivileged mitmproxy user (created in proxy/Dockerfile). The chown is required because mitmproxy creates mitmproxy-ca.pem (CA private key) at 0600 via its umask_secret() context — the running mitmproxy needs read access to the key for on-the-fly leaf cert generation.