pal-e-docs
Project not found.

Review: MCP tools bug

review-342-2026-03-27 Review

review needs-refinement
Project

Verdict: NEEDS_REFINEMENT

Template Completeness

  • [x] Type — Bug
  • [x] Lineage — Standalone, discovered during operations 2026-03-13
  • [x] Repo — forgejo_admin/claude-custom
  • [x] What Broke — Clear description of silent MCP server load failure
  • [x] Repro Steps — Present, notes non-deterministic reproduction
  • [x] Expected Behavior — Present, describes desired SessionStart hook
  • [x] Environment — Present (local dev on archbox)
  • [x] Acceptance Criteria — Present (3 items)
  • [x] Related — Present (pal-e-agency, sop-mcp-server-recovery, issue #76)

Traceability

  • [x] story:pm-scope label — PM scope management
  • [x] arch:mcp-tools label — MCP tools architecture component
  • [x] Forgejo issue — forgejo_admin/claude-custom#155, open

File Targets

The issue does not list specific file targets. However, the acceptance criteria describe work that has already been implemented:
  • [x] ~/.claude/hooks/check-mcp-servers.sh — EXISTS (185 lines). SessionStart hook that reads ~/.mcp.json, builds process fingerprints for each configured MCP server, checks ps output for matching processes, and warns if any are missing.
  • [x] ~/.claude/settings.json line 40 — hook is WIRED into SessionStart hooks array.
  • [x] sop-mcp-server-recovery — EXISTS in pal-e-docs. Documents failure modes, decision tree, and prevention. References the hook in the Prevention section (though it says "planned but not yet implemented" — this is stale).

Repo Placement

OK — issue is filed on forgejo_admin/claude-custom, and the hook lives in claude-custom (hardlinked to ~/.claude/hooks/).

Dependencies

  • Related issue #76 ("Add SessionStart hook to detect missing MCP servers") is CLOSED. This was the original implementation ticket. Commits: e7d2193, 118f16a (fix), merged as PR #88.
  • No blocking dependencies on the board.

Acceptance Criteria Assessment

All three acceptance criteria appear to already be met:
  • AC1: "SessionStart hook checks that expected MCP servers are present in tool registry" — DONE. check-mcp-servers.sh exists and is wired.
  • AC2: "Warning or auto-recovery when a server fails to load" — PARTIALLY DONE. The hook warns but does not auto-recover. Auto-recovery is not possible via hooks (Claude Code provides no mid-session MCP reload mechanism).
  • AC3: "Hook documented in agent-workflow SOP" — STALE. The sop-mcp-server-recovery note says the hook is "planned but not yet implemented" — needs updating.

Blast Radius

Low. The hook is fail-open (any error exits 0 silently). No downstream consumers affected.

Recommendation

This ticket is a duplicate of the already-closed issue #76. Two residual items:
  • Close as duplicate of #76, or repurpose narrowly to cover the SOP doc update below.
  • Update sop-mcp-server-recovery — Prevention section says hook is "planned but not yet implemented." Stale text, 1-line fix.
  • Clarify AC2 — Auto-recovery is infeasible in Claude Code's architecture. Should be filed upstream if desired.