sysadmin
ebd06b73c9
- Distinguish client_namespace vs offline_spawn probe sources; only IDE client probes prove namespace health and feed mutation gates. - Record assessments in session; gate gitea_submit_pr_review and gitea_merge_pr when client-namespace health is unhealthy/non-proven. - Mark test_mcp_conn.py offline-only; align recovery docs to client reconnect (no PID-kill/config-touch as canonical recovery). - Rebase onto current master so #590 ledger isolation keeps TestMergePR.test_unknown_profile_blocks green.
89 lines
3.6 KiB
Markdown
89 lines
3.6 KiB
Markdown
# 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.
|