feat: diagnose live MCP namespace EOF health

2026-07-09 10:59:34 -04:00
parent cc4b95839d
commit 05fdceee5f
5 changed files with 540 additions and 24 deletions
@@ -0,0 +1,54 @@
+# MCP namespace EOF recovery
+
+Gitea MCP tools can be registered in the Python FastMCP server while the IDE's
+live MCP namespace is still unusable. The failure usually appears as
+`client is closing: EOF`, `transport closed`, or an empty response when calling
+a tool such as `gitea_whoami`.
+
+Do not treat static tool registration as proof that review or merge workflows
+can proceed. A reviewer or merger flow must have live namespace evidence that
+the required tool is callable through the configured namespace.
+
+## Required namespace probes
+
+Run the health check after changing MCP config, switching branches that affect
+server code, or seeing EOF from any Gitea namespace:
+
+```bash
+python3 test_mcp_conn.py --config ~/.gemini/config/mcp_config.json
+```
+
+By default the script checks these namespaces and required tools:
+
+| Namespace | Required tool |
+| --- | --- |
+| `gitea-author` | `gitea_whoami` |
+| `gitea-reviewer` | `gitea_whoami` |
+| `gitea-merger` | `gitea_whoami` |
+| `gitea-tools` | `gitea_list_profiles` |
+
+Use `--namespace gitea-reviewer` to test only one namespace. A passing probe
+requires:
+
+1. The namespace exists in the MCP config.
+2. JSON-RPC initialize succeeds.
+3. `tools/list` returns the required tool.
+4. `tools/call` successfully invokes the required tool.
+
+## Recovery steps
+
+When a namespace returns EOF:
+
+1. Note the reported namespace, required tool, PID, profile, environment
+   summary, and config path.
+2. Stop any stale MCP server process for that PID.
+3. Reload or touch the MCP config so the IDE reconnects the namespace.
+4. Verify the namespace command, args, profile env, and checkout path point at
+   the current repository.
+5. Re-run `python3 test_mcp_conn.py --namespace <name>`.
+6. Resume review or merge work only after the required tool call passes.
+
+The read-only `gitea_assess_mcp_namespace_health` tool can classify probe
+evidence supplied by a client. It intentionally distinguishes
+`required_tool_registered=true` from `required_tool_callable=false`; the latter
+must block reviewer and merger workflows until the live namespace is repaired.