pal-e-docs

Review: Paldocs MCP server -- new Ruby/Node MCP for Rails API endpoints

review-1564-2026-06-22 Review

review needs-refinement
Project

Verdict: NEEDS_REFINEMENT

Template Completeness

  • [x] Type -- Feature
  • [x] Lineage -- Depends on paldocs#51, replaces paldocs#53 (closed)
  • [x] Repo -- ldraney/paldocs (or new ldraney/paldocs-mcp)
  • [x] User Story -- present, well-formed
  • [x] Context -- present, good rationale for new MCP vs repointing
  • [x] File Targets -- present (new MCP server code, ~/.mcp.json)
  • [x] Feature Flag -- present (none, additive)
  • [x] Acceptance Criteria -- 5 criteria
  • [x] Test Expectations -- present
  • [x] Constraints -- present
  • [x] Checklist -- present
  • [x] Related -- present
All template sections present.

Traceability

  • [x] story:consolidation label -- present on board item
  • [x] story note verified -- story-paldocs-consolidation exists in pal-e-docs, listed in project-paldocs user-stories section
  • [ ] arch:infra label -- TOO GENERIC. No arch-infra note exists. Multiple previous reviews (review-1552, review-1432, review-1563) have flagged arch:infra as a non-existent catch-all. The story note references arch-rails-api as the relevant architecture component for MCP-facing work. [LABEL] Change arch:infra to arch:mcp or create arch-mcp note for the MCP server layer.
  • [x] Forgejo issue -- ldraney/paldocs#54, open

File Targets

  • [x] ~/.mcp.json -- verified: exists, currently lists "pal-e-docs" server. Adding "paldocs" entry is correct.
  • [x] ~/pal-e-mcp/ -- correctly listed as "do NOT touch". Verified: exists at ~/pal-e-mcp/ with 36 tools across 7 modules.
  • [x] ~/claude-custom/settings.json -- correctly listed as "do NOT touch" (tool references migrated in #55).
  • [x] New MCP server code -- TBD repo placement is acceptable (design decision). Repo ldraney/paldocs-mcp does not yet exist on Forgejo.
Note: The issue says "36 MCP tools" -- verified accurate: boards (12), notes (9), blocks (6), projects (3), repos (3), links (2), tags (1) = 36 tools.

Repo Placement

Issue is filed on ldraney/paldocs but acknowledges the server may live in a new ldraney/paldocs-mcp repo. This is acceptable -- the decision depends on whether the MCP server is a subdirectory of the Rails app or a standalone project. Either way, the Forgejo issue is correctly placed on paldocs since it is the parent project.

Dependencies

  • paldocs#51 (API endpoints) -- OPEN, in backlog on board-paldocs. This is the hard dependency: the MCP server cannot proxy to Rails API endpoints that don't exist yet. Board item #1561. Dependency is correctly documented in the issue.
  • paldocs#52 (Embedding pipeline) -- OPEN, in backlog. Required for AC #5 (semantic search via vector results). Dependency is documented in Related but not in Lineage.
  • paldocs#49 (Schema ownership) -- In progress (board item #1559). Must complete before #51 and #52. Indirect dependency.
  • paldocs#55 (Migrate tool references) -- Downstream. Correctly documented as sibling, not dependency.
  • wave:3 label -- Consistent with dependency chain: wave:0 (schema) -> wave:2 (API + embeddings) -> wave:3 (this MCP server) -> wave:4 (migrate references).
Wave ordering is correct and well-structured.

Acceptance Criteria

  • [x] AC1 (MCP server initializes) -- verifiable via Claude Code session
  • [x] AC2 (36 tools match old server) -- verifiable but broad. "Results match" is testable by running each tool against both servers.
  • [x] AC3 (no tool name conflicts) -- verifiable. Issue correctly specifies mcp__paldocs__* prefix vs mcp__pal-e-docs__*.
  • [x] AC4 (CRUD operations) -- verifiable via smoke test
  • [ ] AC5 (semantic search) -- DEPENDS on paldocs#52 (embedding pipeline). If #52 is not complete, this AC cannot pass. [BODY] Either add a note that AC5 is deferred until #52 lands, or remove it and create a follow-up AC on #55.

Blast Radius

Low blast radius. The new MCP server is purely additive -- it registers as "paldocs" alongside the existing "pal-e-docs" server. No existing tool names are affected. The only risk is tool name collisions, which AC3 explicitly addresses via the mcp__paldocs__* prefix convention.
No sibling services use a similar MCP pattern that would need the same fix.

Decomposition Assessment

  • File targets: 1-2 locations (new server code + ~/.mcp.json). Single repo.
  • Acceptance criteria: 5 (at limit but acceptable since AC5 may be deferred)
  • Estimated agent work: The MCP server is described as "~200-300 lines, thin REST proxy". This is a single focused task within the 5-minute rule if using a mature MCP SDK.
  • Verdict: No decomposition needed.

Recommendation

  • [LABEL] Change arch:infra to arch:mcp (or arch:rails-api). The arch:infra label has no backing note and has been flagged in 4+ previous reviews as too generic. Create arch-mcp note if this is a new architecture component, or use arch:rails-api to match the story note's Related Architecture.
  • [BODY] Clarify AC5 (semantic search): either note it is deferred pending paldocs#52, or move it to paldocs#55 as a post-migration verification criterion.