# 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:

```text
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)

```bash
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.