71 lines
3.5 KiB
Markdown
71 lines
3.5 KiB
Markdown
# MCP Config Drift Diagnostic & Sanctioned Repair Runbook (#672)
|
|
|
|
This document describes the diagnostic framework for detecting configuration drift between the active IDE MCP configuration (`~/.gemini/antigravity-ide/mcp_config.json`) and the offline/global canonical configuration (`~/.gemini/config/mcp_config.json`), and establishes the **sanctioned repair runbook**.
|
|
|
|
## Background & Problem Statement
|
|
|
|
Offline tools like `test_mcp_conn.py` test the global configuration (`~/.gemini/config/mcp_config.json`) via `subprocess.Popen`. However, the active IDE/client namespace uses `~/.gemini/antigravity-ide/mcp_config.json`. When required Gitea role servers (`gitea-author`, `gitea-reviewer`, `gitea-merger`, `gitea-reconciler`, `gitea-controller`, `gitea-tools`) are missing or carry mismatched profile environments in the active IDE config:
|
|
|
|
1. Offline tests pass (`test_mcp_conn.py` green).
|
|
2. The IDE client returns `EOF` / `transport closed` when attempting role-scoped mutations.
|
|
3. Operators misdiagnose missing server definitions as stale runtimes, leading to forbidden `pkill` attempts (#630) or `mtime` hacks (#655).
|
|
|
|
## Diagnostic Tool: `mcp_config_drift.py`
|
|
|
|
Run the diagnostic tool directly to compare configurations:
|
|
|
|
```bash
|
|
python3 mcp_config_drift.py --json
|
|
```
|
|
|
|
Or specify custom config locations:
|
|
|
|
```bash
|
|
python3 mcp_config_drift.py \
|
|
--active-config ~/.gemini/antigravity-ide/mcp_config.json \
|
|
--global-config ~/.gemini/config/mcp_config.json
|
|
```
|
|
|
|
### Key Diagnostic Outputs
|
|
|
|
- `in_sync`: Boolean indicating if all required Gitea role servers exist in the active IDE config with matching profile declarations.
|
|
- `missing_role_servers`: List of role servers present in global config but missing from active IDE config.
|
|
- `profile_mismatches`: List of profile environment mismatches per server.
|
|
- `reasons`: Explicit, human-readable list of drift causes.
|
|
|
|
All returned payloads automatically redact secret tokens, DSNs, Authorization headers, and private keys.
|
|
|
|
---
|
|
|
|
## Sanctioned Repair Path (Step-by-Step)
|
|
|
|
When `mcp_config_drift.py` reports drift (`in_sync: false`), execute the following **sanctioned repair steps**:
|
|
|
|
1. **Backup Active IDE Config:**
|
|
```bash
|
|
cp ~/.gemini/antigravity-ide/mcp_config.json ~/.gemini/antigravity-ide/mcp_config.json.bak
|
|
```
|
|
2. **Patch Active IDE Config:**
|
|
Copy the missing Gitea role server JSON blocks (`gitea-author`, `gitea-reviewer`, etc.) from `~/.gemini/config/mcp_config.json` into `~/.gemini/antigravity-ide/mcp_config.json`.
|
|
3. **Reconnect via IDE/Client:**
|
|
Use the IDE / client UI reconnection control (or restart the IDE client app).
|
|
4. **Verify Active Namespace Health:**
|
|
Invoke `gitea_whoami` (and optional `gitea_resolve_task_capability`) through the active IDE client on each required role namespace.
|
|
|
|
---
|
|
|
|
## FORBIDDEN Repair Actions (#630 / #655)
|
|
|
|
The following actions are **strictly forbidden** for config drift repair:
|
|
|
|
- ❌ **`pkill` or manual daemon process kill commands:** Process kills cause contamination and break active session leases.
|
|
- ❌ **`mtime` touch edits:** Artificial mtime modifications mask stale runtimes without updating configuration.
|
|
- ❌ **Source code edits:** Mutating python tool logic to bypass missing server entries.
|
|
- ❌ **Session-state edits:** Direct database or lock-file state mutation.
|
|
|
|
---
|
|
|
|
## Final Report Guidelines
|
|
|
|
A workflow final report **must not** rely on offline `test_mcp_conn.py` output alone. Final reports must include active-config evidence from live `gitea_whoami` calls on the active IDE namespaces.
|