NixOS/docs/reference/mcp-server.md

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.

Sources of Truth

• Constitution: docs/constitution.md is authoritative for AI rules and workflows.
• Conflict handling: when human docs differ, update both and record the resolution in specs/001-ai-docs/research.md.
• Reference map: docs/reference/index.md is the navigation index for paths and responsibilities.
• Playbooks: docs/playbooks/*.md are the repeatable workflow guides; follow the template structure.
• Planning artifacts: specs/001-ai-docs/ captures decisions, plans, and change history.

Tool Catalog

show-constitution

• Purpose: Display docs/constitution.md to confirm authoritative rules.
• Docs anchor: docs/constitution.md → #ai-constitution-for-the-nixos-repository.

list-playbooks

• Purpose: List available playbooks under docs/playbooks/ for common tasks.
• Docs anchor: docs/playbooks/template.md → #playbook-template.

show-reference

• Purpose: Show docs/reference/index.md to navigate repo guidance.
• Docs anchor: docs/reference/index.md → #reference-map.

search-docs

• Purpose: Search the docs set for a query.
• Inputs: query (string).
• Docs anchor: docs/reference/mcp-server.md → #search-docs.

list-mcp-tasks

• Purpose: Show MCP feature task list from specs/002-mcp-server/tasks.md.
• Docs anchor: specs/002-mcp-server/tasks.md → #tasks-mcp-server-for-repo-maintenance.

sync-docs

• Purpose: Compare tool catalog against documented anchors for drift reporting.
• Docs anchor: docs/reference/mcp-server.md → #sync-docs.

Invocation

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

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 sync-docs.
• CI: .gitea/workflows/mcp-tests.yml runs lint/format/mypy/pytest with a 60s budget on scripts/** and docs/** changes.