mcp

docs/reference/mcp-server.md

@@ -0,0 +1,28 @@
+# MCP Server Reference
+
+## Overview
+- Purpose: local-only MCP server that exposes repository maintenance helpers to Codex CLI.
+- Transport: JSON-RPC over stdio; no network listeners; enforced local-only guard.
+- Source: `scripts/mcp-server/`; connect via `python -m mcp_server.server`.
+
+## Tool Catalog
+- `show-constitution`: Display `docs/constitution.md` to confirm authoritative rules.
+- `list-playbooks`: List available playbooks under `docs/playbooks/` for common tasks.
+- `show-reference`: Show `docs/reference/index.md` to navigate repo guidance.
+- `search-docs`: Search the docs set for a query (param: `query`).
+- `list-mcp-tasks`: Show MCP feature task list from `specs/001-mcp-server/tasks.md`.
+
+## Invocation
+- Start server: `python -m mcp_server.server` (from repo root, stdio mode).
+- Codex CLI: configure MCP endpoint as local stdio, then call `listTools` to verify catalog.
+- Invoke: `invokeTool` with `name` and `args` as defined above.
+- Drift check: call `syncDocs` to report mismatches between tool catalog and documented anchors.
+
+## Local-Only Expectations
+- Remote access is blocked by guard clauses; unset `SSH_CONNECTION` applies local-only behavior.
+- If `MCP_ALLOW_REMOTE` is set to `true/1/yes`, guard is relaxed (not recommended).
+
+## Maintenance
+- Update tool definitions in `scripts/mcp-server/src/mcp_server/tools.py` with doc anchors.
+- Keep docs aligned by updating this reference and running `syncDocs`.
+- CI: `.gitea/workflows/mcp-tests.yml` runs lint/format/mypy/pytest with a 60s budget on `scripts/**` and `docs/**` changes.