# 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/001-mcp-server/tasks.md`.
- Docs anchor: `specs/001-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.