1.8 KiB
1.8 KiB
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/**ordocs/**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).