Gitea-Tools/docs/mcp-namespace-health.md

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:

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.