mcp server done

specs/001-mcp-server/contracts/mcp-tools.md

@@ -1,35 +1,29 @@
-# MCP Tooling Contracts (JSON-RPC over stdio)
+# MCP Tooling Contracts (MCP over stdio via `nixos-mcp`)
 
-## listTools
-- **Method**: `listTools`
+## tools/list
+- **Method**: `tools/list`
 - **Params**: none
 - **Result**:
   - `tools`: array of Tool objects  
     - `name`: string (unique)  
     - `description`: string  
-    - `inputs`: array of InputParam  
-      - `name`: string  
-      - `type`: string (constrained to allowed primitives)  
-      - `required`: boolean  
-      - `description`: string  
-    - `docsAnchor`: object  
-      - `path`: string (under `docs/`)  
-      - `anchor`: string (heading id)  
-      - `summary`: string  
+    - `inputSchema`: object (JSON schema derived from tool signature)  
 
-## invokeTool
-- **Method**: `invokeTool`
+## tools/call
+- **Method**: `tools/call`
 - **Params**:
   - `name`: string (must match Tool.name)
-  - `args`: object (key/value per Tool.inputs)
+  - `arguments`: object (key/value per Tool inputs)
 - **Result**:
   - `status`: enum (`ok`, `invalid_input`, `failed`, `unsupported`)
-  - `output`: string (human-readable result or guidance)
+  - `output`: string or object (human-readable result or structured payload)
   - `actions`: array of suggested follow-ups (optional)
-  - `docsAnchor`: object (same shape as listTools.docsAnchor) for quick navigation
+  - `docsAnchor`: object for quick navigation  
+    - `path`: string (under `docs/` or `specs/`)  
+    - `anchor`: string (heading id)  
+    - `summary`: string  
 
-## syncDocs
-- **Method**: `syncDocs`
+## sync-docs (tool)
 - **Purpose**: Validate that documented tools match the live catalog.
 - **Params**: none
 - **Result**:
@@ -42,6 +36,6 @@
     - `actual`: string  
 
 ## Error Handling
-- **Transport errors**: standard JSON-RPC error object with code/message.
+- **Transport errors**: standard MCP error object with code/message.
 - **Validation errors**: return `invalid_input` with details in `output`.
-- **Unknown methods**: return `unsupported` status with guidance to run `listTools`.
+- **Unknown tools**: return `unsupported` status with guidance to run `tools/list`.

specs/001-mcp-server/quickstart.md

@@ -1,9 +1,9 @@
 # Quickstart: MCP Server for Repo Maintenance
 
-1) **Prereqs**: Python 3.12, `uv` or `pip`, and Codex CLI installed locally.  
-2) **Install**: From repo root, `cd scripts/mcp-server` and run `uv pip install -e .` (or `pip install -e .` if uv unavailable).  
-3) **Run tests**: `pytest --maxfail=1 --disable-warnings -q` (adds lint/format checks via ruff/black in CI).  
-4) **Launch MCP server**: `python -m mcp_server.server` (stdio mode).  
-5) **Connect Codex CLI**: Configure Codex to use the local MCP endpoint (stdin transport) and run `listTools` to verify catalog.  
-6) **Docs alignment**: If adding/updating tools, run `syncDocs` to confirm docs match; update `docs/` MCP section accordingly.  
+1) **Prereqs**: Nix with flakes enabled and Codex CLI installed locally.  
+2) **Install**: `nix profile install .#nixos-mcp` (or `nix develop .#mcp` for a dev shell).  
+3) **Run tests**: `./scripts/mcp-server/run-tests.sh`.  
+4) **Launch MCP server**: `nixos-mcp` (stdio mode).  
+5) **Connect Codex CLI**: Ensure `.codex/config.toml` points to `nixos-mcp` and `.codex/requirements.toml` allowlists it, then list tools via the MCP client to verify catalog.  
+6) **Docs alignment**: If adding/updating tools, run `sync-docs` to confirm docs match; update `docs/` MCP section accordingly.  
 7) **CI behavior**: Gitea runs lint/format/tests when `scripts/**` or `docs/**` change; fix failures before merging.

specs/001-mcp-server/tasks.md

@@ -31,21 +31,21 @@
 
 **Goal**: Codex CLI lists and runs documented maintenance tools via MCP server
 
-**Independent Test**: Connect Codex CLI to the local MCP server, call listTools, and successfully invoke a documented maintenance tool end-to-end without manual repo edits.
+**Independent Test**: Connect Codex CLI to the local MCP server, list tools via MCP, and successfully invoke a documented maintenance tool end-to-end without manual repo edits.
 
 ### Tests for User Story 1
 
-- [X] T009 [P] [US1] Add contract tests for listTools/invokeTool/syncDocs responses in scripts/mcp-server/tests/test_server.py
+- [X] T009 [P] [US1] Add contract tests for MCP tools/list, tools/call, and sync-docs responses in scripts/mcp-server/tests/test_server.py
 - [X] T010 [P] [US1] Add unit tests for tool registry schema and local-only guard behavior in scripts/mcp-server/tests/test_tools.py
 - [X] T011 [P] [US1] Add docs/catalog parity tests in scripts/mcp-server/tests/test_docs_sync.py
-- [X] T012 [P] [US1] Add performance regression tests for listTools/invokeTool latency (<2s) in scripts/mcp-server/tests/test_performance.py
+- [X] T012 [P] [US1] Add performance regression tests for tools/list and tools/call latency (<2s) in scripts/mcp-server/tests/test_performance.py
 
 ### Implementation for User Story 1
 
 - [X] T013 [US1] Populate tool registry with documented maintenance tasks and doc anchors in scripts/mcp-server/src/mcp_server/tools.py
-- [X] T014 [US1] Implement listTools handler with input metadata in scripts/mcp-server/src/mcp_server/server.py
-- [X] T015 [US1] Implement invokeTool dispatch with guard clauses and standardized result payloads in scripts/mcp-server/src/mcp_server/server.py
-- [X] T016 [US1] Implement syncDocs comparison logic to flag drift between registry and docs in scripts/mcp-server/src/mcp_server/docs_sync.py
+- [X] T014 [US1] Implement MCP tools/list and tool registration with input metadata in scripts/mcp-server/src/mcp_server/server.py
+- [X] T015 [US1] Implement MCP tools/call dispatch with guard clauses and standardized result payloads in scripts/mcp-server/src/mcp_server/server.py
+- [X] T016 [US1] Implement sync-docs comparison logic to flag drift between registry and docs in scripts/mcp-server/src/mcp_server/docs_sync.py
 - [X] T017 [US1] Add CLI/stdio entrypoint for MCP server (`python -m mcp_server.server`) enforcing local-only access in scripts/mcp-server/src/mcp_server/server.py
 - [X] T018 [US1] Implement unavailable-service handling with actionable guidance in scripts/mcp-server/src/mcp_server/server.py and cover in tests
 
@@ -79,7 +79,7 @@
 
 - [X] T022 [US3] Add MCP overview and tool catalog mapping with anchors in docs/reference/mcp-server.md
 - [X] T023 [P] [US3] Link MCP reference into docs/reference/index.md and docs/constitution.md to satisfy two-click discoverability
-- [X] T024 [P] [US3] Document invocation examples and syncDocs usage aligned to tool anchors in docs/reference/mcp-server.md
+- [X] T024 [P] [US3] Document invocation examples and sync-docs usage aligned to tool anchors in docs/reference/mcp-server.md
 
 **Checkpoint**: User Story 3 functional and independently testable