init

2026-01-30 22:48:02 -06:00
parent 2a418c4394
commit 527fad8da0
9 changed files with 410 additions and 0 deletions
--- a/specs/001-mcp-server/checklists/requirements.md
+++ b/specs/001-mcp-server/checklists/requirements.md
@@ -0,0 +1,34 @@
+# Specification Quality Checklist: MCP Server for Repo Maintenance
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning  
+**Created**: 2026-01-30  
+**Feature**: specs/001-mcp-server/spec.md
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+- Checklist completed; no outstanding issues identified.
--- a/specs/001-mcp-server/contracts/mcp-tools.md
+++ b/specs/001-mcp-server/contracts/mcp-tools.md
@@ -0,0 +1,47 @@
+# MCP Tooling Contracts (JSON-RPC over stdio)
+
+## listTools
+- **Method**: `listTools`
+- **Params**: none
+- **Result**:
+  - `tools`: array of Tool objects  
+    - `name`: string (unique)  
+    - `description`: string  
+    - `inputs`: array of InputParam  
+      - `name`: string  
+      - `type`: string (constrained to allowed primitives)  
+      - `required`: boolean  
+      - `description`: string  
+    - `docsAnchor`: object  
+      - `path`: string (under `docs/`)  
+      - `anchor`: string (heading id)  
+      - `summary`: string  
+
+## invokeTool
+- **Method**: `invokeTool`
+- **Params**:
+  - `name`: string (must match Tool.name)
+  - `args`: object (key/value per Tool.inputs)
+- **Result**:
+  - `status`: enum (`ok`, `invalid_input`, `failed`, `unsupported`)
+  - `output`: string (human-readable result or guidance)
+  - `actions`: array of suggested follow-ups (optional)
+  - `docsAnchor`: object (same shape as listTools.docsAnchor) for quick navigation
+
+## syncDocs
+- **Method**: `syncDocs`
+- **Purpose**: Validate that documented tools match the live catalog.
+- **Params**: none
+- **Result**:
+  - `status`: enum (`ok`, `drift_detected`)
+  - `missingInDocs`: array of tool names
+  - `missingInCatalog`: array of doc anchors without tools
+  - `mismatches`: array of objects  
+    - `name`: string  
+    - `expected`: string (description/input summary)  
+    - `actual`: string  
+
+## Error Handling
+- **Transport errors**: standard JSON-RPC error object with code/message.
+- **Validation errors**: return `invalid_input` with details in `output`.
+- **Unknown methods**: return `unsupported` status with guidance to run `listTools`.
--- a/specs/001-mcp-server/data-model.md
+++ b/specs/001-mcp-server/data-model.md
@@ -0,0 +1,24 @@
+# Data Model: MCP Server for Repo Maintenance
+
+## Entities
+
+### MCP Server
+- **Purpose**: Hosts MCP tools for Codex CLI and orchestrates tool discovery and invocation.
+- **Attributes**: transport (`stdio`), tool registry (list of Tool Catalog Entries), doc mapping (anchors/paths), version metadata.
+- **Relationships**: Contains many Tool Catalog Entries; references Documentation Anchors for guidance.
+
+### Tool Catalog Entry
+- **Purpose**: Represents a callable maintenance task exposed via MCP.
+- **Attributes**: name (unique), description, input schema (parameters, types, required flags), execution scope (paths affected), documentation anchor (path + heading), safeguards (preconditions/guards), tags (category).
+- **Relationships**: Linked to one Documentation Anchor; owned by MCP Server.
+- **Uniqueness**: Name must be unique across the catalog.
+
+### Documentation Anchor
+- **Purpose**: Points to the AI documentation section explaining when and how to use a tool.
+- **Attributes**: doc path (under `docs/`), heading id/anchor, summary, last-synced version marker.
+- **Relationships**: Referenced by Tool Catalog Entries; aligns with AI documentation updates.
+
+### CI Job
+- **Purpose**: Executes lint, format, and test suites for MCP server on scoped path changes.
+- **Attributes**: path filters (`scripts/**`, `docs/**`), steps (setup, install deps, lint, format check, tests, coverage), status output.
+- **Relationships**: Observes repository changes; reports status to Gitea pipeline.
--- a/specs/001-mcp-server/plan.md
+++ b/specs/001-mcp-server/plan.md
@@ -0,0 +1,68 @@
+# Implementation Plan: MCP Server for Repo Maintenance
+
+**Branch**: `001-mcp-server` | **Date**: 2026-01-30 | **Spec**: specs/001-mcp-server/spec.md  
+**Input**: Feature specification from `/specs/001-mcp-server/spec.md`
+
+## Summary
+
+Build a local-only MCP server under `scripts/` that Codex CLI can use to run documented repository maintenance tasks. Provide a tool catalog aligned to AI docs, add automated tests, gate changes in Gitea when `scripts/` or `docs/` change, and expand AI documentation with MCP usage guidance.
+
+## Technical Context
+
+**Language/Version**: Python 3.12  
+**Primary Dependencies**: MCP server library (Python, JSON-RPC/stdin transport), click for CLI entrypoint, pytest + coverage for tests, ruff/black for lint/format  
+**Storage**: None (in-memory tool definitions; filesystem access for repo interactions)  
+**Testing**: pytest with coverage thresholds and path-filtered CI runs  
+**Target Platform**: Local Nix/Linux environment (Codex CLI host)  
+**Project Type**: CLI-style local service (MCP over stdio/JSON-RPC)  
+**Performance Goals**: Tool discovery and invocation responses within 2s on local machine; test suite under 60s in CI  
+**Constraints**: Local-only binding; no network listeners; avoid non-flake dependencies; follow minimal indentation/guard-clause coding style with docstrings/type hints and functional patterns  
+**Scale/Scope**: Supports current AI-documented maintenance tasks (≥5 tools) with room for incremental additions
+
+## Constitution Check
+
+*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
+
+- AI docs must stay business-level and technology-agnostic; update `docs/` to reflect MCP tools and mappings. **Pass**
+- Coding conventions: minimize comments, keep markdown examples tight (no blank lines between code blocks), maintain clear naming. **Pass**
+- Nix conventions: flatten single-leaf attribute sets and merge siblings when touching Nix files (e.g., CI path filters). **Pass**
+- Discoverability: ensure MCP documentation reachable within two clicks from AI docs. **Pass**
+- Secret handling: no new secret categories introduced; MCP remains local-only. **Pass**
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/001-mcp-server/
+├── plan.md
+├── research.md
+├── data-model.md
+├── quickstart.md
+├── contracts/
+└── tasks.md            # created by /speckit.tasks
+```
+
+### Source Code (repository root)
+
+```text
+scripts/mcp-server/
+├── pyproject.toml
+├── src/mcp_server/
+│   ├── __init__.py
+│   ├── server.py
+│   ├── tools.py
+│   └── docs_sync.py
+└── tests/
+    ├── test_tools.py
+    ├── test_server.py
+    └── test_docs_sync.py
+```
+
+**Structure Decision**: Single Python project under `scripts/mcp-server` with src/tests layout; documentation lives in `docs/` and spec artifacts in `specs/001-mcp-server/`.
+
+## Complexity Tracking
+
+| Violation | Why Needed | Simpler Alternative Rejected Because |
+|-----------|------------|-------------------------------------|
+| None | - | - |
--- a/specs/001-mcp-server/quickstart.md
+++ b/specs/001-mcp-server/quickstart.md
@@ -0,0 +1,9 @@
+# Quickstart: MCP Server for Repo Maintenance
+
+1) **Prereqs**: Python 3.12, `uv` or `pip`, and Codex CLI installed locally.  
+2) **Install**: From repo root, `cd scripts/mcp-server` and run `uv pip install -e .` (or `pip install -e .` if uv unavailable).  
+3) **Run tests**: `pytest --maxfail=1 --disable-warnings -q` (adds lint/format checks via ruff/black in CI).  
+4) **Launch MCP server**: `python -m mcp_server.server` (stdio mode).  
+5) **Connect Codex CLI**: Configure Codex to use the local MCP endpoint (stdin transport) and run `listTools` to verify catalog.  
+6) **Docs alignment**: If adding/updating tools, run `syncDocs` to confirm docs match; update `docs/` MCP section accordingly.  
+7) **CI behavior**: Gitea runs lint/format/tests when `scripts/**` or `docs/**` change; fix failures before merging.
--- a/specs/001-mcp-server/research.md
+++ b/specs/001-mcp-server/research.md
@@ -0,0 +1,16 @@
+# Research: MCP Server for Repo Maintenance
+
+## Runtime and transport
+- **Decision**: Implement the MCP server in Python 3.12 using JSON-RPC over stdio for Codex CLI compatibility and local-only execution.
+- **Rationale**: Python is already acceptable for repo scripts; stdio transport keeps the server local without exposing network ports and matches Codex CLI expectations for MCP endpoints.
+- **Alternatives considered**: HTTP listener on localhost (would require network binding and firewall considerations); Node/TypeScript implementation (adds a new toolchain and package manager to the repo).
+
+## Tool catalog and documentation alignment
+- **Decision**: Define the tool catalog in code with a single source of truth that includes tool name, description, inputs, and linked documentation anchors; generate doc snippets from this catalog to avoid drift.
+- **Rationale**: Centralizing metadata reduces duplication, keeps docs and server capabilities synchronized, and allows tests to validate parity.
+- **Alternatives considered**: Free-form documentation authored manually (high drift risk); external manifest file (adds parsing overhead without clear benefit over a code-local registry).
+
+## CI triggers and test approach
+- **Decision**: Add a Gitea workflow job that runs MCP tests when paths under `scripts/**` or `docs/**` change; use pytest with coverage and lint/format checks (ruff/black) to enforce coding preferences.
+- **Rationale**: Path filters prevent unnecessary runs, while enforcing lint/format plus tests protects against regressions and code-style drift across both code and documentation updates.
+- **Alternatives considered**: Always-on job (wastes CI minutes on unrelated changes); relying solely on manual runs (risks regressions and documentation/tool mismatches).
--- a/specs/001-mcp-server/spec.md
+++ b/specs/001-mcp-server/spec.md
@@ -0,0 +1,97 @@
+# Feature Specification: MCP Server for Repo Maintenance
+
+**Feature Branch**: `001-mcp-server`  
+**Created**: 2026-01-30  
+**Status**: Draft  
+**Input**: User description: "build a mcp server under the directory /scripts the intention for this mcp server is to be consumed by codex-cli to help on modifying the repository by doing but not limited to, the tasks declared on the ai-oriented documentation found in /docs. as an extra, I want this mcp to have tests, which run on the gitea pipeline when any changes done to the mcp or docs directories are commited. expand the ai-documentation on /docs with info about the built mcp so that it is compliant with what of the available tools of the mcp can be called for what specific tasks, ensuring that the mcp provides the easiest up to date assistance to giving this repository maintenance. When it comes to the coding preferences for the server, I want: 1) indentation kept to the bare minimum 2) guard clauses & early returns 3) easy to read coding style, with no comments, but professional easy to maintain code structure 4) functions with docstrings, typehints, etc. 5) give preference to iteration tools such as lambdas, map, filters, as opposed to for loops and multiple ifs. 6) functional code, with reduced duplicated code 7) lint & format the code"
+
+## Clarifications
+
+### Session 2026-01-30
+
+- Q: How should MCP server access be scoped for Codex CLI users? → A: Restrict MCP server to local-only use with local filesystem permissions.
+
+## User Scenarios & Testing *(mandatory)*
+
+### User Story 1 - Codex CLI invokes MCP tools (Priority: P1)
+
+Codex CLI users connect to the MCP server to list and invoke repository maintenance tasks that mirror the AI documentation, receiving clear guidance to execute changes safely.
+
+**Why this priority**: Enables AI-assisted maintenance with minimal friction and ensures the new MCP server delivers immediate value.
+
+**Independent Test**: Connect Codex CLI to the MCP server and run a documented maintenance task end-to-end without manual repository edits.
+
+**Acceptance Scenarios**:
+
+1. **Given** the MCP server is available to Codex CLI, **When** a user requests available tools, **Then** the server returns a list covering the documented maintenance tasks with descriptions and expected inputs.
+2. **Given** a user selects a documented task, **When** they invoke the corresponding tool, **Then** the tool executes the task guidance without requiring extra configuration steps outside the documented flow.
+
+---
+
+### User Story 2 - Automated checks guard MCP changes (Priority: P2)
+
+Repository maintainers rely on automated tests to validate the MCP server whenever scripts or documentation change, preventing regressions before merging.
+
+**Why this priority**: Protects repo quality and ensures MCP reliability as docs and tools evolve.
+
+**Independent Test**: Modify a file in `scripts/` or `docs/`, trigger the pipeline, and confirm MCP tests run and gate the change.
+
+**Acceptance Scenarios**:
+
+1. **Given** a commit touching `scripts/` or `docs/`, **When** the Gitea pipeline runs, **Then** MCP tests execute and block merging on failure.
+
+---
+
+### User Story 3 - AI docs explain MCP usage (Priority: P3)
+
+Documentation readers can quickly understand what MCP tools exist, when to use them, and how they align to repository maintenance tasks.
+
+**Why this priority**: Keeps AI-facing guidance discoverable and reduces guesswork for tool selection.
+
+**Independent Test**: From the AI documentation, navigate to the MCP section and identify the correct tool and invocation steps for a chosen maintenance task without external help.
+
+**Acceptance Scenarios**:
+
+1. **Given** the AI documentation, **When** a reader searches for how to run a specific maintenance task, **Then** they find the mapped MCP tool, inputs, and scope within two clicks.
+2. **Given** new MCP tools are added, **When** the docs are updated, **Then** the listed tools and capabilities match what the MCP server exposes.
+
+---
+
+### Edge Cases
+
+- Requests for tasks not mapped in the AI documentation should return guidance to supported options rather than executing ambiguous actions.
+- Pipeline runs on documentation-only changes must still execute the MCP test suite and report status.
+- MCP tool list and documentation drift are detected and corrected during testing or documentation updates.
+- Codex CLI connections encountering unavailable MCP services return actionable guidance to retry or fallback without repository impact.
+
+## Requirements *(mandatory)*
+
+### Functional Requirements
+
+- **FR-001**: Provide an MCP server under `scripts/` that Codex CLI can connect to for repository maintenance tasks aligned to the AI documentation.
+- **FR-002**: Expose a discoverable catalog of MCP tools with names, purposes, inputs, and scope that mirrors the maintenance tasks defined in `docs/`.
+- **FR-003**: Ensure MCP tool execution follows documented guardrails, returning clear outcomes and guidance without requiring undocumented configuration.
+- **FR-004**: Deliver automated tests that verify tool availability, parameter handling, and parity between documented tasks and MCP capabilities.
+- **FR-005**: Configure the Gitea pipeline to run the MCP test suite whenever changes touch `scripts/` or `docs/`, marking the pipeline failed on test failures.
+- **FR-006**: Update AI-facing documentation to include MCP server overview, tool mappings to tasks, invocation examples, and maintenance expectations.
+- **FR-007**: Keep coding standards observable in the MCP codebase (minimal indentation, guard clauses, docstrings, type hints, functional style, linted/ formatted outputs) to maintain readability and consistency.
+- **FR-008**: Restrict MCP server availability to local-only access, relying on local filesystem permissions and avoiding remote exposure.
+- **FR-009**: Meet runtime goals for local operation: list and invoke responses under 2 seconds on typical developer hardware and full MCP test suite completion under 60 seconds in CI, with safeguards to detect regressions.
+
+### Key Entities
+
+- **MCP Server**: The service Codex CLI connects to for repository maintenance tasks; defines available tools and their behavior.
+- **Codex CLI User**: Consumers invoking MCP tools to perform maintenance guided by AI documentation.
+- **Tool Catalog Entry**: A documented pairing of a maintenance task, its MCP tool name, expected inputs, and constraints.
+- **Gitea Pipeline**: The automation that runs MCP tests and reports pass/fail status on relevant commits.
+- **AI Documentation Set**: Guidance under `docs/` that describes maintenance tasks, tool mappings, and usage flows.
+
+## Success Criteria *(mandatory)*
+
+### Measurable Outcomes
+
+- **SC-001**: Codex CLI users can discover and invoke at least five documented maintenance tasks through the MCP server without extra configuration steps.
+- **SC-002**: MCP documentation and tool catalog stay in sync with zero mismatches detected during automated tests across three consecutive pipeline runs.
+- **SC-003**: Any commit modifying `scripts/` or `docs/` triggers MCP tests, and merges are blocked unless all MCP tests pass.
+- **SC-004**: Readers reach the correct MCP tool guidance for a chosen maintenance task within two clicks from the AI documentation landing page.
+- **SC-005**: Tool discovery/invocation completes within 2 seconds locally and MCP test suite completes within 60 seconds in CI across three consecutive runs.
--- a/specs/001-mcp-server/tasks.md
+++ b/specs/001-mcp-server/tasks.md
@@ -0,0 +1,112 @@
+# 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.