branch fixes

specs/002-mcp-server/tasks.md

@@ -0,0 +1,112 @@
+# Tasks: MCP Server for Repo Maintenance
+
+**Input**: Design documents from `/specs/002-mcp-server/`
+**Prerequisites**: plan.md, spec.md, research.md, data-model.md, contracts/
+
+## Phase 1: Setup (Shared Infrastructure)
+
+**Purpose**: Project initialization and base tooling
+
+- [X] T001 Create Python project skeleton under scripts/mcp-server with src/tests layout and __init__.py
+- [X] T002 Initialize scripts/mcp-server/pyproject.toml with runtime deps (MCP stdio/JSON-RPC, click) and dev deps (pytest, ruff, black)
+- [X] T003 [P] Configure lint/format/typing settings in scripts/mcp-server/pyproject.toml (ruff, black, mypy if used)
+- [X] 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
+
+- [X] T005 Implement stdio JSON-RPC server bootstrap with local-only guard in scripts/mcp-server/src/mcp_server/server.py
+- [X] T006 [P] Define tool catalog schema and registry stubs with type hints in scripts/mcp-server/src/mcp_server/tools.py
+- [X] T007 [P] Add documentation sync scaffolding and anchor loader in scripts/mcp-server/src/mcp_server/docs_sync.py
+- [X] 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, list tools via MCP, and successfully invoke a documented maintenance tool end-to-end without manual repo edits.
+
+### Tests for User Story 1
+
+- [X] T009 [P] [US1] Add contract tests for MCP tools/list, tools/call, and sync-docs responses in scripts/mcp-server/tests/test_server.py
+- [X] T010 [P] [US1] Add unit tests for tool registry schema and local-only guard behavior in scripts/mcp-server/tests/test_tools.py
+- [X] T011 [P] [US1] Add docs/catalog parity tests in scripts/mcp-server/tests/test_docs_sync.py
+- [X] T012 [P] [US1] Add performance regression tests for tools/list and tools/call latency (<2s) in scripts/mcp-server/tests/test_performance.py
+
+### Implementation for User Story 1
+
+- [X] T013 [US1] Populate tool registry with documented maintenance tasks and doc anchors in scripts/mcp-server/src/mcp_server/tools.py
+- [X] T014 [US1] Implement MCP tools/list and tool registration with input metadata in scripts/mcp-server/src/mcp_server/server.py
+- [X] T015 [US1] Implement MCP tools/call dispatch with guard clauses and standardized result payloads in scripts/mcp-server/src/mcp_server/server.py
+- [X] T016 [US1] Implement sync-docs comparison logic to flag drift between registry and docs in scripts/mcp-server/src/mcp_server/docs_sync.py
+- [X] 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
+- [X] 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
+
+- [X] 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)
+- [X] T020 [P] [US2] Add local helper script scripts/mcp-server/run-tests.sh mirroring CI commands for developer use
+- [X] 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
+
+- [X] T022 [US3] Add MCP overview and tool catalog mapping with anchors in docs/reference/mcp-server.md
+- [X] T023 [P] [US3] Link MCP reference into docs/reference/index.md and docs/constitution.md to satisfy two-click discoverability
+- [X] T024 [P] [US3] Document invocation examples and sync-docs 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
+
+- [X] T025 [P] Run ruff, black check, and pytest per quickstart to validate MCP package
+- [X] 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.