113 lines
5.9 KiB
Markdown
113 lines
5.9 KiB
Markdown
# 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.
|