MCP Server Reference

Overview

Purpose: local-only MCP server that exposes repository maintenance helpers to Codex CLI.
Transport: MCP protocol over stdio via the official Python SDK; no network listeners; enforced local-only guard.
Source: scripts/mcp-server/; connect via the nixos-mcp wrapper package.

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.
sync-docs: Compare tool catalog against documented anchors for drift reporting.

Start server: nixos-mcp (stdio mode).
Dev shell: nix develop .#mcp provides nixos-mcp and Codex CLI.
Codex CLI: configure MCP endpoint as local stdio and allowlist nixos-mcp in .codex/requirements.toml.
Invoke: call the MCP tool by name with arguments as defined above.
Drift check: invoke sync-docs to report mismatches between tool catalog and documented anchors.

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

Update tool definitions in scripts/mcp-server/src/mcp_server/tools.py with doc anchors.
Keep docs aligned by updating this reference and running sync-docs.
CI: .gitea/workflows/mcp-tests.yml runs lint/format/mypy/pytest with a 60s budget on scripts/** and docs/** changes.