Review: Paldocs MCP server -- new Ruby/Node MCP for Rails API endpoints (re-review)

Verdict: APPROVED

Previous Issues -- Resolution

• [x] arch:infra label changed to arch:mcp -- confirmed on board item #1564 (labels now type:feature,story:consolidation,arch:mcp). Architecture note arch-mcp created in pal-e-docs with overview, tool surface (36 tools, 7 groups), and transition strategy.
• [x] AC5 deferred pending #52 -- issue body now reads "deferred verification -- not blocking this ticket" in AC5 and Constraints section says "Semantic search verification deferred until paldocs#52 lands."

Template Completeness

• [x] Type -- Feature
• [x] Lineage -- Depends on paldocs#57, #58, #59 (API endpoints). Updated from #51 to split issues.
• [x] Repo -- ldraney/paldocs (or new ldraney/paldocs-mcp)
• [x] User Story -- present, well-formed
• [x] Context -- present, good rationale
• [x] File Targets -- present (new MCP code, ~/.mcp.json, with do-not-touch list)
• [x] Feature Flag -- none (additive, correct)
• [x] Acceptance Criteria -- 5 criteria (AC5 deferred)
• [x] Test Expectations -- present
• [x] Constraints -- present, includes deferred semantic search note
• [x] Checklist -- present
• [x] Related -- present

Traceability

• [x] story:consolidation label -- present on board item
• [x] story note verified -- story-paldocs-consolidation exists (user-story type, project paldocs), listed in project-paldocs user-stories section
• [x] arch:mcp label -- present on board item (changed from arch:infra per round 1 recommendation)
• [x] arch note verified -- arch-mcp exists in pal-e-docs (doc type, project paldocs, tags: architecture, paldocs, mcp)
• [x] Forgejo issue -- ldraney/paldocs#54, open

File Targets

• [x] ~/.mcp.json -- verified: exists, lists 8 servers including "pal-e-docs". Adding "paldocs" alongside is correct.
• [x] ~/pal-e-mcp/ -- correctly listed as do-NOT-touch. Verified: exists with src/, tests/, pyproject.toml.
• [x] ~/claude-custom/settings.json -- correctly listed as do-NOT-touch (migrated in #55).
• [x] New MCP server code -- TBD repo placement acceptable as design decision.

Repo Placement

Dependencies

• paldocs#57 (Notes API, 12 endpoints) -- OPEN, backlog, board item #1567. Hard dependency.
• paldocs#58 (Boards + Board Items API, 12 endpoints) -- OPEN, backlog, board item #1568. Hard dependency.
• paldocs#59 (Projects/Repos/Tags/Search API, 9 endpoints) -- OPEN, backlog, board item #1569. Hard dependency.
• paldocs#52 (Embedding pipeline) -- OPEN, backlog, board item #1562. Required for AC5 (deferred). Not blocking.
• paldocs#49 (Schema ownership) -- in_progress, board item #1559. Indirect dependency (must complete before API endpoints).
• paldocs#55 (Migrate tool references) -- OPEN, backlog, board item #1565. Downstream (depends on this ticket).

Acceptance Criteria

• [x] AC1 (MCP server initializes) -- verifiable
• [x] AC2 (36 tools match old server) -- verifiable
• [x] AC3 (no tool name conflicts) -- verifiable, mcp__paldocs__* vs mcp__pal-e-docs__*
• [x] AC4 (CRUD operations) -- verifiable via smoke test
• [x] AC5 (semantic search) -- correctly deferred pending #52. Not blocking.

Blast Radius

Decomposition Assessment

Recommendation