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)

specs/001-mcp-server/
├── plan.md
├── research.md
├── data-model.md
├── quickstart.md
├── contracts/
└── tasks.md            # created by /speckit.tasks

Source Code (repository root)

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	-	-

3.0 KiB Raw Blame History