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

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

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