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