branch fixes

specs/002-mcp-server/research.md

@@ -0,0 +1,16 @@
+# 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).