init

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

@@ -0,0 +1,47 @@
+# MCP Tooling Contracts (JSON-RPC over stdio)
+
+## listTools
+- **Method**: `listTools`
+- **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  
+
+## invokeTool
+- **Method**: `invokeTool`
+- **Params**:
+  - `name`: string (must match Tool.name)
+  - `args`: object (key/value per Tool.inputs)
+- **Result**:
+  - `status`: enum (`ok`, `invalid_input`, `failed`, `unsupported`)
+  - `output`: string (human-readable result or guidance)
+  - `actions`: array of suggested follow-ups (optional)
+  - `docsAnchor`: object (same shape as listTools.docsAnchor) for quick navigation
+
+## syncDocs
+- **Method**: `syncDocs`
+- **Purpose**: Validate that documented tools match the live catalog.
+- **Params**: none
+- **Result**:
+  - `status`: enum (`ok`, `drift_detected`)
+  - `missingInDocs`: array of tool names
+  - `missingInCatalog`: array of doc anchors without tools
+  - `mismatches`: array of objects  
+    - `name`: string  
+    - `expected`: string (description/input summary)  
+    - `actual`: string  
+
+## Error Handling
+- **Transport errors**: standard JSON-RPC error object with code/message.
+- **Validation errors**: return `invalid_input` with details in `output`.
+- **Unknown methods**: return `unsupported` status with guidance to run `listTools`.