Harden the protocol

A compliant MCP server must format standard JSON-RPC errors and handle notifications (messages omitting the id key) without emitting any stdout response.

Mental Model: JSON-RPC Errors & Notifications

1. Parse Error (-32700 / id: null): Unparsable incoming lines.
2. Method Not Found (-32601 / id: <id>): Unregistered method invocations.
3. Tool Execution Errors: Returns isError: true in result when tool arguments are missing or invalid.
4. Notifications: Requests lacking an id property (e.g. "notifications/initialized") generate no output.

Your Goal in this Stage

Handle JSON parse failures, unrecognized methods, tool argument errors, and silent notifications.

Input Format (Parse error)

not-json

Output Format

{
  "jsonrpc": "2.0",
  "id": null,
  "error": { "code": -32700, "message": "Parse error" }
}

Input Format (Unknown method)

{ "jsonrpc": "2.0", "id": 8, "method": "unknown" }

Output Format

{
  "jsonrpc": "2.0",
  "id": 8,
  "error": { "code": -32601, "message": "Method not found" }
}

Step-by-Step Implementation Guide

1. Catch JSON syntax errors: Return -32700 with id: null.
2. Ignore notifications: If id is missing, execute side effects silently without writing to stdout.
3. Catch missing methods: Return -32601 with caller id.
4. Validate tool parameters: Return isError: true when arguments are incomplete.

Acceptance Criteria

• ✅ Emits code -32700 on unparsable input.
• ✅ Emits code -32601 on unrecognized methods.
• ✅ Flags invalid tool arguments with isError: true.
• ✅ Produces zero output for notifications.

A notification omits id; id: null is not a notification and is invalid in MCP. Respond with id: null, code -32600, and message Invalid Request. Unknown resources use -32002 / Resource not found; unknown tools use -32602 / Unknown tool. For echo, require a string text and no additional properties; invalid arguments return result.content: [{"type":"text","text":"Invalid arguments for echo"}] and isError: true. For add, require exactly a and b, both finite numbers. Do not coerce values to hide type errors. Protocol errors go to stdout and processing continues until EOF with exit 0.

MCP 2025-06-18.

Multiline examples are formatted for readability. Emit compact JSON without optional spaces, with properties in the order shown by the output examples, and a final newline. Keep logs off stdout. Tests compare exact text.