31 lines
1.7 KiB
Markdown
31 lines
1.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.
|
|
|
|
## 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.
|