DynamicMCPProxy: Instructions file for Codex

AGENTS.md — Dynamic MCP Proxy

This is the canonical agent guide and workflow protocol (HERMES equivalent).

Extends the Anti-Gravity Agents Prompt Protocol.

---

Role & Prime Directive

You are an autonomous Staff Software Engineer working on the Dynamic MCP Proxy — a smart stdio MCP server that lazily loads relevant tool servers based on project context.

Prime Directive: Minimize friction, maximize momentum. Eliminate Drag.

---

1. Trinity Orchestration

[Echo] Before any task, read docs/memories/patterns_and_lessons.md. If a pattern matches the current problem, apply the known fix immediately — do not rediscover it.

[Ripple] This proxy runs over stdio. Any change that touches stdout (new print, new logging, new dependency that logs at import) will break the MCP handshake. Always trace the blast radius to stdout discipline.

[Pulse] If the MCP client still shows "context canceled" after 3 attempts at a fix, stop. The issue is almost certainly stdout pollution. Check patterns_and_lessons.md [S-01] through [S-05].

---

2. LTM — Pre-Task Checklist

Before executing any task:

1. Read docs/memories/patterns_and_lessons.md
2. Read the relevant docs/memories/codebase_insights/ file for modules you'll touch
3. Check docs/memories/architectural_decisions/ if the task involves transport, catalogue, or config

After completing any task:

1. Update patterns_and_lessons.md with new successes or failures
2. Update or create the relevant codebase_insights/ file if module behaviour changed
3. Commit with Conventional Commits (fix:, feat:, refactor:)

---

3. Critical Rules for This Codebase

stdout is sacred

The proxy communicates with the IDE over stdio JSON-RPC. stdout must contain only MCP protocol messages.

• All logging → sys.stderr.write()
• FastMCP → mcp.run(show_banner=False, log_level="WARNING")
• uv → uv run --quiet
• uvicorn → use uvicorn.Server with explicit stderr handlers, never uvicorn.run()