42 lines
1.5 KiB
Markdown
42 lines
1.5 KiB
Markdown
# MCP Tooling Contracts (MCP over stdio via `nixos-mcp`)
|
|
|
|
## tools/list
|
|
- **Method**: `tools/list`
|
|
- **Params**: none
|
|
- **Result**:
|
|
- `tools`: array of Tool objects
|
|
- `name`: string (unique)
|
|
- `description`: string
|
|
- `inputSchema`: object (JSON schema derived from tool signature)
|
|
|
|
## tools/call
|
|
- **Method**: `tools/call`
|
|
- **Params**:
|
|
- `name`: string (must match Tool.name)
|
|
- `arguments`: object (key/value per Tool inputs)
|
|
- **Result**:
|
|
- `status`: enum (`ok`, `invalid_input`, `failed`, `unsupported`)
|
|
- `output`: string or object (human-readable result or structured payload)
|
|
- `actions`: array of suggested follow-ups (optional)
|
|
- `docsAnchor`: object for quick navigation
|
|
- `path`: string (under `docs/` or `specs/`)
|
|
- `anchor`: string (heading id)
|
|
- `summary`: string
|
|
|
|
## sync-docs (tool)
|
|
- **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 MCP error object with code/message.
|
|
- **Validation errors**: return `invalid_input` with details in `output`.
|
|
- **Unknown tools**: return `unsupported` status with guidance to run `tools/list`.
|