Spec 044 Diagnostics — End-to-End Verification

Summary

Phase 1 — CLI

Ran the freshly-built dev mcpproxy on an isolated port (127.0.0.1:18080) and data dir (/tmp/mcpproxy-test-spec044) with a purpose-built test config containing a broken-stdio server whose command points at /nonexistent/binary. The production daemon on :8080 was never touched; its config was backed up (byte-identical after test) and the dev binary was run from the worktree.

$ ./mcpproxy doctor list-codes
29 diagnostic codes registered:

  MCPX_CONFIG_DEPRECATED_FIELD          warn   The configuration uses a deprecated field that will be removed in a future release.
    docs: docs/errors/MCPX_CONFIG_DEPRECATED_FIELD.md
    fix (button):  Preview migration (dry-run)  key=config_migrate_deprecated [destructive -> dry-run default]
    fix (link):    Migration notes  docs/errors/MCPX_CONFIG_DEPRECATED_FIELD.md

  MCPX_CONFIG_MISSING_SECRET            error  The configuration references a secret that is not defined.
    docs: docs/errors/MCPX_CONFIG_MISSING_SECRET.md
    fix (command): List secrets  mcpproxy secret list
    fix (link):    Secret references  docs/errors/MCPX_CONFIG_MISSING_SECRET.md
  ... (27 more) ...

$ ./mcpproxy doctor list-codes -o json | jq 'length'
29

$ ./mcpproxy doctor list-codes -o json | jq '[.[] | select(.code | startswith("MCPX_STDIO_"))] | map(.code)'
[
  "MCPX_STDIO_EXIT_NONZERO",
  "MCPX_STDIO_HANDSHAKE_INVALID",
  "MCPX_STDIO_HANDSHAKE_TIMEOUT",
  "MCPX_STDIO_SPAWN_EACCES",
  "MCPX_STDIO_SPAWN_ENOENT"
]

$ ./mcpproxy doctor --server broken-stdio
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔍 MCPProxy Health Check
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Version: v0.24.9 (latest)

⚠ Found 1 issue that need attention

❌ Upstream Server Connection Errors
  Server: broken-stdio

⚠️  Deprecated Configuration
  • features
    features is deprecated and has no effect
    Suggestion: Remove from config (all feature flags are unused)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

$ ./mcpproxy doctor --server broken-stdio   # enable_socket: false
Error: doctor requires running daemon. Start with: mcpproxy serve
# ...usage text elided...
Error: doctor requires running daemon. Start with: mcpproxy serve

$ ./mcpproxy doctor fix MCPX_STDIO_SPAWN_ENOENT --server broken-stdio
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🛠  Doctor Fix: MCPX_STDIO_SPAWN_ENOENT
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Server:      broken-stdio
Fix step:    Show last server log lines
Fixer key:   stdio_show_last_logs
Destructive: no
Mode:        dry_run

Outcome:     ✅ success

Preview:
  Server 'broken-stdio' log tail unavailable in this build — enable server-side
  log access to view the last 50 lines here.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

$ ./mcpproxy doctor fix MCPX_STDIO_SPAWN_ENOENT --server broken-stdio --execute
Error: fix invocation failed: API returned status 429: {
  "success":false,
  "error":"Too many fix attempts; try again shortly",
  "request_id":"eeb5791b-06ab-4055-aa2f-1acabf83bf42"
}

Phase 2 — Web UI

Opened http://127.0.0.1:18080/ui/servers/broken-stdio?apikey=*** in claude-in-chrome. The Vue ErrorPanel component (4d92c82) rendered the full diagnostic payload with all expected elements. Clicking the Preview (dry-run) button fires the fix endpoint successfully.

Screenshots

Phase 3 — macOS Tray

What still needs a human check

• Red-dot badge on the tray menu-bar icon when total_issues > 0
• New "Fix issues" menu group opens and lists affected servers
• Clicking a menu row opens /ui/servers/<name> in the default browser

Relevant code lives in the commit 6aa8305 — feat(spec-044): macOS tray badge + Fix issues menu group. To verify post-merge, run:

$ # after-hours, when it's safe to cycle production
$ cd ~/repos/mcpproxy-go
$ make build
$ pkill -x MCPProxy
$ open /tmp/MCPProxy.app

Findings (non-blocking)

Confirmed-working (no action needed)

• 29 diagnostic codes registered, matching list-codes -o json | jq length
• Stdio spawn failure via /nonexistent/binary correctly classifies to MCPX_STDIO_SPAWN_ENOENT even when wrapped through /bin/zsh -l -c
• Diagnostic payload shape matches spec: code, severity, user_message, cause, fix_steps[], docs_url, detected_at
• server.health block populated with level: unhealthy, action: restart — matches Spec 044's action-suggestion design
• Server list endpoint carries per-server error_code field at top level
• doctor fix rate-limiter returns structured 429 with a request_id for correlation

Environment & Reproducibility

Build context

Reproducing the test setup

# 1. back up production config, but don't touch it
$ cp ~/.mcpproxy/mcp_config.json /tmp/mcp_config.json.backup-$(date +%s)

# 2. build dev binary on the feature branch
$ cd ~/repos/mcpproxy-go-diagnostics-taxonomy
$ make build

# 3. isolated data dir + config
$ mkdir -p /tmp/mcpproxy-test-spec044
$ cat > /tmp/mcpproxy-test-spec044/config.json <<'JSON'
{
  "listen": "127.0.0.1:18080",
  "api_key": "***",
  "enable_socket": true,
  "enable_web_ui": true,
  "mcpServers": [
    {"name":"broken-stdio", "command":"/nonexistent/binary",
     "protocol":"stdio", "enabled":true},
    {"name":"healthy-control", "command":"echo",
     "protocol":"stdio", "enabled":false}
  ]
}
JSON

# 4. launch in tmux on the isolated port + data dir
$ tmux new-session -d -s spec044 \
    "./mcpproxy serve -c /tmp/mcpproxy-test-spec044/config.json \
     -d /tmp/mcpproxy-test-spec044 --log-level=debug"

# 5. exercise CLI + REST + Web UI
$ ./mcpproxy doctor list-codes -o json | jq length
$ ./mcpproxy doctor --server broken-stdio
$ ./mcpproxy doctor fix MCPX_STDIO_SPAWN_ENOENT --server broken-stdio
$ curl -s -H "X-API-Key: ***" \
    http://127.0.0.1:18080/api/v1/servers/broken-stdio/diagnostics | jq .

# 6. cleanup
$ tmux kill-session -t spec044
$ rm -rf /tmp/mcpproxy-test-spec044
$ diff -q ~/.mcpproxy/mcp_config.json /tmp/mcp_config.json.backup-*

Raw artifacts consulted by this report

• /Users/user/repos/mcpproxy-go/tmp-agent-report-spec044-verify.md (structured verification report, 9,038 bytes)
• /tmp/spec044-verify-cli.log (CLI command outputs, 10,091 bytes)
• /tmp/mcpproxy-test-spec044/server.log (server log — not found, test data dir was cleaned up)
• /tmp/spec044-verify-webui-*.png (Web UI screenshots — not found, captured via claude-in-chrome but not persisted to disk)
• /tmp/spec044-verify-tray-*.png (tray screenshots — not found, Phase 3 skipped)