mcp

docs/constitution.md

@@ -59,5 +59,6 @@ config.services = {
 ## Quick Reference and Navigation
 - Constitution: `docs/constitution.md` (this file)
 - Reference map: `docs/reference/index.md` (paths, hosts, secrets, proxies, stylix)
+- MCP server reference: `docs/reference/mcp-server.md` (tools, invocation, sync checks)
 - Playbooks: `docs/playbooks/*.md` (add module/server/script/host toggle/secret, plus template)
 - Planning artifacts: `specs/001-ai-docs/` (plan, research, data-model, quickstart, contracts)

docs/reference/index.md

@@ -55,6 +55,7 @@
 - Playbook template: `docs/playbooks/template.md`
 - Workflows: `docs/playbooks/add-module.md`, `add-server.md`, `add-script.md`, `add-host-toggle.md`, `add-secret.md`
 - Constitution link-back: `docs/constitution.md` sections on terminology, proxies, secrets, and maintenance.
+- MCP server reference: `docs/reference/mcp-server.md` (tool catalog, invocation, syncDocs)
 
 ## Quick Audit Checklist
 - Module coverage: All categories (apps, dev, scripts, servers, services, shell, network, users, nix, patches) have corresponding entries and auto-import rules.

docs/reference/mcp-server.md

@@ -0,0 +1,28 @@
+# MCP Server Reference
+
+## Overview
+- Purpose: local-only MCP server that exposes repository maintenance helpers to Codex CLI.
+- Transport: JSON-RPC over stdio; no network listeners; enforced local-only guard.
+- Source: `scripts/mcp-server/`; connect via `python -m mcp_server.server`.
+
+## 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`.
+
+## Invocation
+- Start server: `python -m mcp_server.server` (from repo root, stdio mode).
+- Codex CLI: configure MCP endpoint as local stdio, then call `listTools` to verify catalog.
+- Invoke: `invokeTool` with `name` and `args` as defined above.
+- Drift check: call `syncDocs` 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 `syncDocs`.
+- CI: `.gitea/workflows/mcp-tests.yml` runs lint/format/mypy/pytest with a 60s budget on `scripts/**` and `docs/**` changes.