NixOS/docs/reference/mcp-server.md

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.