5.9 KiB
Tasks: MCP Server for Repo Maintenance
Input: Design documents from /specs/001-mcp-server/
Prerequisites: plan.md, spec.md, research.md, data-model.md, contracts/
Phase 1: Setup (Shared Infrastructure)
Purpose: Project initialization and base tooling
- T001 Create Python project skeleton under scripts/mcp-server with src/tests layout and init.py
- T002 Initialize scripts/mcp-server/pyproject.toml with runtime deps (MCP stdio/JSON-RPC, click) and dev deps (pytest, ruff, black)
- T003 [P] Configure lint/format/typing settings in scripts/mcp-server/pyproject.toml (ruff, black, mypy if used)
- T004 [P] Add pytest config and coverage thresholds in scripts/mcp-server/pyproject.toml
Phase 2: Foundational (Blocking Prerequisites)
Purpose: Core scaffolding required before user stories
- T005 Implement stdio JSON-RPC server bootstrap with local-only guard in scripts/mcp-server/src/mcp_server/server.py
- T006 [P] Define tool catalog schema and registry stubs with type hints in scripts/mcp-server/src/mcp_server/tools.py
- T007 [P] Add documentation sync scaffolding and anchor loader in scripts/mcp-server/src/mcp_server/docs_sync.py
- T008 [P] Add ruff/mypy configurations enforcing docstrings, guard clauses, and functional style rules in scripts/mcp-server/pyproject.toml
Checkpoint: Foundation ready for user story work
Phase 3: User Story 1 - Codex CLI invokes MCP tools (Priority: P1) 🎯 MVP
Goal: Codex CLI lists and runs documented maintenance tools via MCP server
Independent Test: Connect Codex CLI to the local MCP server, call listTools, and successfully invoke a documented maintenance tool end-to-end without manual repo edits.
Tests for User Story 1
- T009 [P] [US1] Add contract tests for listTools/invokeTool/syncDocs responses in scripts/mcp-server/tests/test_server.py
- T010 [P] [US1] Add unit tests for tool registry schema and local-only guard behavior in scripts/mcp-server/tests/test_tools.py
- T011 [P] [US1] Add docs/catalog parity tests in scripts/mcp-server/tests/test_docs_sync.py
- T012 [P] [US1] Add performance regression tests for listTools/invokeTool latency (<2s) in scripts/mcp-server/tests/test_performance.py
Implementation for User Story 1
- T013 [US1] Populate tool registry with documented maintenance tasks and doc anchors in scripts/mcp-server/src/mcp_server/tools.py
- T014 [US1] Implement listTools handler with input metadata in scripts/mcp-server/src/mcp_server/server.py
- T015 [US1] Implement invokeTool dispatch with guard clauses and standardized result payloads in scripts/mcp-server/src/mcp_server/server.py
- T016 [US1] Implement syncDocs comparison logic to flag drift between registry and docs in scripts/mcp-server/src/mcp_server/docs_sync.py
- T017 [US1] Add CLI/stdio entrypoint for MCP server (
python -m mcp_server.server) enforcing local-only access in scripts/mcp-server/src/mcp_server/server.py - T018 [US1] Implement unavailable-service handling with actionable guidance in scripts/mcp-server/src/mcp_server/server.py and cover in tests
Checkpoint: User Story 1 fully functional and independently testable
Phase 4: User Story 2 - Automated checks guard MCP changes (Priority: P2)
Goal: CI runs MCP lint/format/tests when scripts/ or docs/ change and blocks on failure
Independent Test: Touch a file under scripts/ or docs/, trigger the Gitea workflow, and observe MCP job running lint/format/tests and failing on errors.
Implementation for User Story 2
- T019 [US2] Add Gitea workflow .gitea/workflows/mcp-tests.yml with path filters for scripts/** and docs/** running ruff, black check, and pytest (including performance tests)
- T020 [P] [US2] Add local helper script scripts/mcp-server/run-tests.sh mirroring CI commands for developer use
- T021 [US2] Add CI time-budget check in .gitea/workflows/mcp-tests.yml to fail when MCP test suite exceeds 60s
Checkpoint: User Story 2 functional and independently testable
Phase 5: User Story 3 - AI docs explain MCP usage (Priority: P3)
Goal: AI docs map maintenance tasks to MCP tools with invocation guidance discoverable within two clicks
Independent Test: From AI docs landing, reach MCP section within two clicks and find the correct tool mapping and invocation steps for a chosen maintenance task.
Implementation for User Story 3
- T022 [US3] Add MCP overview and tool catalog mapping with anchors in docs/reference/mcp-server.md
- T023 [P] [US3] Link MCP reference into docs/reference/index.md and docs/constitution.md to satisfy two-click discoverability
- T024 [P] [US3] Document invocation examples and syncDocs usage aligned to tool anchors in docs/reference/mcp-server.md
Checkpoint: User Story 3 functional and independently testable
Phase 6: Polish & Cross-Cutting
Purpose: Final quality, consistency, and validation
- T025 [P] Run ruff, black check, and pytest per quickstart to validate MCP package
- T026 [P] Verify tool catalog and documentation anchors remain in sync after changes in scripts/ and docs/
Dependencies & Execution Order
- Setup → Foundational → User Stories (US1 P1, US2 P2, US3 P3) → Polish
- User stories can proceed in priority order; US2 and US3 can run in parallel after foundational if US1 interfaces are stable.
Parallel Execution Examples
- Run T003/T004 in parallel while T001/T002 complete.
- After foundational, execute US1 tests T009–T012 in parallel, then parallelize T014–T016 while T013 seeds the registry; finalize with T017–T018.
- US2 tasks (T019–T021) can run alongside US3 doc tasks (T022–T024) once foundational is done.
Implementation Strategy (MVP first)
- Deliver US1 as the MVP: registry, handlers, sync checks, and tests.
- Add CI gating (US2) to protect future changes.
- Finish with AI documentation integration (US3) and polish runs.