pal-e-docs

Review: Add hello-world MCP endpoint with get_schedule tool

review-992-2026-04-12 Review

review needs-refinement
Project

Verdict: NEEDS_REFINEMENT

Template Completeness

  • [x] Type -- Feature
  • [x] Lineage
  • [x] Repo
  • [x] User Story
  • [x] Context
  • [x] File Targets
  • [x] Acceptance Criteria
  • [x] Test Expectations
  • [x] Constraints
  • [x] Checklist
  • [x] Related

Traceability

  • [ ] story:ai-assistant label -- NO matching user story in project-westside-basketball user-stories section. No WS-S* code exists for AI assistant functionality. [SCOPE] Create user story entry on project-westside-basketball user-stories section (Admin stories) with a WS-S* code for AI assistant.
  • [ ] story note MISSING -- story-westside-basketball-ai-assistant referenced in Lineage does not exist as a pal-e-docs note. [SCOPE] Create story note story-westside-basketball-ai-assistant or add the story to the project page with a proper WS-S* code.
  • [ ] arch:dataflow label -- no arch-dataflow or arch-dataflow-westside-basketball note exists in pal-e-docs. [SCOPE] Create architecture note for the dataflow component.
  • [x] Forgejo issue -- #454, open, valid URL

File Targets

  • [x] src/basketball_api/mcp_server.py (create) -- does not exist yet, correct
  • [x] src/basketball_api/routes/mcp.py (create) -- does not exist yet, correct
  • [x] src/basketball_api/main.py (modify) -- exists, contains router registration pattern via app.include_router()
  • [x] pyproject.toml (modify) -- exists, mcp not yet in dependencies
  • [x] src/basketball_api/routes/schedule.py (do not touch) -- exists, correctly excluded

Repo Placement

OK. Issue filed on forgejo_admin/basketball-api, all file targets are in basketball-api. Single-repo scope.

Dependencies

No blocking dependencies found on board-westside-basketball. Item #729 (Add read-only SQL tool with Postgres access) is related but independent -- it targets a different MCP tool and is in backlog. The existing GET /public/schedule endpoint in routes/public.py confirms the data layer already works. The get_db dependency pattern is used across 10+ route files.

Acceptance Criteria

6 ACs, all verifiable by an agent:
  • [x] mcp package in pyproject.toml -- grep-verifiable
  • [x] MCP server mounts at /mcp -- route registration verifiable in main.py
  • [x] get_schedule tool returns schedule data -- testable via pytest
  • [x] Streamable HTTP transport -- testable via HTTP POST
  • [x] Existing endpoints unaffected -- run full test suite
  • [x] Health check passes -- testable via existing health endpoint

Blast Radius

Low. New endpoint on a new path (/mcp). No auth (hello-world scope), which the ticket explicitly acknowledges as deferred. No changes to existing routes or models. The mcp Python SDK is a new dependency -- agent should pin a version range. No other services in the platform consume MCP yet, so no downstream impact.

Decomposition Assessment

2 files to create, 2 files to modify, 1 repo, 6 ACs. Estimated agent time: ~3 minutes. No decomposition needed.

Recommendation

  • [SCOPE] Create user story entry in project-westside-basketball user-stories section (Admin stories) with a WS-S* code for "As an admin, I want to ask Claude questions about my business and get live data so that I can manage operations through conversation." Then update the board item label from story:ai-assistant to story:WS-S{N}.
  • [SCOPE] Create story note story-westside-basketball-ai-assistant referenced in issue Lineage, or align Lineage to use the WS-S* code.
  • [SCOPE] Create architecture note arch-dataflow (or more specific arch-dataflow-westside-basketball) documenting the MCP data flow component.