branch fixes

specs/002-mcp-server/plan.md

@@ -0,0 +1,68 @@
+# Implementation Plan: MCP Server for Repo Maintenance
+
+**Branch**: `002-mcp-server` | **Date**: 2026-01-30 | **Spec**: specs/002-mcp-server/spec.md  
+**Input**: Feature specification from `/specs/002-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/002-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/002-mcp-server/`.
+
+## Complexity Tracking
+
+| Violation | Why Needed | Simpler Alternative Rejected Because |
+|-----------|------------|-------------------------------------|
+| None | - | - |