jawz/NixOS
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

mcp server done
Some checks failed
MCP Tests / mcp-tests (pull_request) Failing after 4s
Details

Browse Source
This commit is contained in:
Danilo Reyes
2026-02-01 10:36:54 -06:00
parent ecf058aacf
commit 8946ade5e8
15 changed files with 214 additions and 190 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/reference/index.md
View File

@@ -55,7 +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)
- MCP server reference: `docs/reference/mcp-server.md` (tool catalog, `nixos-mcp` wrapper, invocation, sync-docs)
## Quick Audit Checklist
- Module coverage: All categories (apps, dev, scripts, servers, services, shell, network, users, nix, patches) have corresponding entries and auto-import rules.

16
docs/reference/mcp-server.md
View File

@@ -2,8 +2,8 @@
## 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`.
- 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.
@@ -11,12 +11,14 @@
- `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: `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.
- 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.
@@ -24,5 +26,5 @@
## 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`.
- 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.