69 lines
3.0 KiB
Markdown
69 lines
3.0 KiB
Markdown
# 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 | - | - |
|