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

MCP namespace health diagnostics (#543)

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 client-namespace evidence that the required tool is callable through the configured IDE MCP namespace.

Probe sources (do not confuse them)

Source	How obtained	Proves IDE namespace?
client_namespace	Tool call through the IDE-managed MCP client	Yes
offline_spawn	test_mcp_conn.py subprocess JSON-RPC handshake	No (offline only)

gitea_assess_mcp_namespace_health accepts probe_source and only sets ide_namespace_proven=true for client_namespace success. Offline spawn success never clears review/merge mutation gates.

Client-namespace health check (canonical)

1. Through the IDE client, call a cheap tool on the target namespace (gitea_whoami or gitea_list_profiles).
2. Feed the live result into:

gitea_assess_mcp_namespace_health(
    namespace="gitea-merger",          # or reviewer / author / tools
    registered_tools=[...],            # optional static list
    probe_result={"success": true, "result": {...}},
    probe_source="client_namespace",
)

3. A healthy client-namespace assessment is recorded in the MCP session and consulted by live gitea_submit_pr_review / gitea_merge_pr gates.
4. If the probe fails with EOF, recover via client reconnect only — see docs/mcp-namespace-eof-recovery.md. Do not kill PIDs or touch MCP config mtimes as a recovery procedure.

Offline spawn probe (non-authoritative)

python3 test_mcp_conn.py --config ~/.gemini/config/mcp_config.json

This script spawns a separate server process from config, performs JSON-RPC initialize → tools/list → tools/call, and classifies the result with probe_source=offline_spawn. Use it for offline debugging of launch command / registration. It does not prove the IDE-managed namespace is healthy.

By default the script checks:

Namespace	Required tool
gitea-author	gitea_whoami
gitea-reviewer	gitea_whoami
gitea-merger	gitea_whoami
gitea-tools	gitea_list_profiles

Recovery (canonical)

When a namespace returns EOF, follow docs/mcp-namespace-eof-recovery.md in order:

1. Confirm blast radius (Gitea namespace vs all MCP servers).
2. Reconnect the namespace through the client (IDE reconnect / relaunch).
3. Do not repair via shell imports, raw JSON-RPC, PID kills, or config mtime touches — those do not restore the client's closed transport.
4. Re-verify the specific required tool through the target namespace.
5. Resume review/merge only after a successful client_namespace assessment.

Enforcement

1. State machine (read-only): feed blocks_merge_workflow from a client_namespace assessment into gitea_assess_review_merge_state_machine(live_namespace_broken=...).
2. Live mutations: gitea_submit_pr_review and gitea_merge_pr call _live_namespace_health_gate and fail closed when the session has a recorded unhealthy or non-client probe for the required namespace (gitea-reviewer for review, gitea-merger for merge).

When blocked, repair the IDE namespace and re-record a healthy client_namespace assessment before retrying the mutation.

Connected vs Attached Tool Surface (#708)

MCP servers can report Connected at the CLI / host inventory layer while the active LLM session exposes none of their tool namespaces.

Core principle

• Connected status at host layer ≠ attached tools in active session.
• Required preflight proof is live tool visibility + gitea_whoami call through the target namespace, not host Connected status alone.
• When servers report Connected but namespaces are absent from attached tools, classify as mcp_connected_namespaces_missing.

Forbidden unsafe fallbacks

When mcp_connected_namespaces_missing is detected, workflows must fail closed and must never encourage or perform:

• direct imports of MCP server Python modules
• CLI or raw Gitea API mutations as a substitute for native tools
• profile hopping to another MCP profile/namespace to bypass the empty session
• session-state overrides or hand-edited session/ledger files
• process kills (pkill), config mtime touches, or .env edits

Only sanctioned recovery: client reconnect path, followed by full preflight (whoami → capability resolve → task).