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

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.