51 lines
2.7 KiB
Markdown
51 lines
2.7 KiB
Markdown
# 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.
|