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