NixOS/specs/002-mcp-server/contracts/mcp-tools.md

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.