diff --git a/changelog.d/fixed-admin-mcp-http-ping.md b/changelog.d/fixed-admin-mcp-http-ping.md new file mode 100644 index 0000000000..d1a64d5819 --- /dev/null +++ b/changelog.d/fixed-admin-mcp-http-ping.md @@ -0,0 +1 @@ +- Admin MCP HTTP endpoint (`POST /api/admin/mcp`): `ping` is answered with an empty result, as MCP requires, instead of "method not found", so a client that pings to check the server is alive no longer reads the hive as gone. Notifications other than `notifications/initialized` (for example `notifications/cancelled`, which a client sends after it gives up on a tool call) are acknowledged the same way `notifications/initialized` always was, instead of being answered with a "method not found" error. Unknown request methods are still refused with `-32601`. The stdio binary was not affected. diff --git a/src/docs/admin-mcp.md b/src/docs/admin-mcp.md index f823ac7bb4..72ca9eab70 100644 --- a/src/docs/admin-mcp.md +++ b/src/docs/admin-mcp.md @@ -113,6 +113,9 @@ claude mcp add hive-admin \ `POST /api/admin/mcp` is always registered on v6; there is no enable flag. - Stateless JSON-RPC 2.0: one request per POST, no SSE, no session id. +- `ping` is answered with an empty result. A notification (any + `notifications/...` method) is acknowledged with `200` and + `{"jsonrpc":"2.0","result":{}}`, never with an error. - `GET` returns 405. - Request bodies are capped at 64 KiB. - Authenticate with `Authorization: Bearer `. A `?token=` query diff --git a/src/pkg/adminmcp/adminmcp.go b/src/pkg/adminmcp/adminmcp.go index cb4532efa8..dafa43c177 100644 --- a/src/pkg/adminmcp/adminmcp.go +++ b/src/pkg/adminmcp/adminmcp.go @@ -262,13 +262,22 @@ func (h *Handler) dispatch(r *http.Request, req rpcRequest) (any, *rpcError) { switch req.Method { case "initialize": return map[string]any{"protocolVersion": ProtocolVersion, "serverInfo": map[string]string{"name": ServerName, "version": ServerVersion}, "capabilities": map[string]any{"tools": map[string]any{}}}, nil - case "notifications/initialized": + case "ping": + // MCP's liveness check: the receiver answers with an empty result. return map[string]any{}, nil case "tools/list": return map[string]any{"tools": toolDefs(h.writesUsable(), h.WritesUnavailableReason)}, nil case "tools/call": return h.callTool(r.Context(), req.Params) default: + // A notification expects no answer, and "method not found" is the + // wrong one: a client that sends notifications/cancelled after a + // tool call it gave up on would be told its message was an error. + // Every notification is acknowledged the way notifications/initialized + // always was. + if strings.HasPrefix(req.Method, "notifications/") { + return map[string]any{}, nil + } return nil, &rpcError{Code: -32601, Message: "method not found"} } } diff --git a/src/pkg/adminmcp/protocol_test.go b/src/pkg/adminmcp/protocol_test.go new file mode 100644 index 0000000000..7ca0748d56 --- /dev/null +++ b/src/pkg/adminmcp/protocol_test.go @@ -0,0 +1,64 @@ +package adminmcp + +import ( + "encoding/json" + "net/http" + "net/http/httptest" + "strings" + "testing" +) + +func rpcCall(t *testing.T, body string) map[string]any { + t.Helper() + rec := httptest.NewRecorder() + NewHandler(nil).ServeHTTP(rec, httptest.NewRequest(http.MethodPost, EndpointPath, strings.NewReader(body))) + if rec.Code != http.StatusOK { + t.Fatalf("status = %d body = %s", rec.Code, rec.Body.String()) + } + var resp map[string]any + if err := json.Unmarshal(rec.Body.Bytes(), &resp); err != nil { + t.Fatalf("response is not JSON: %s", rec.Body.String()) + } + return resp +} + +// MCP's ping is a liveness check the receiver must answer with an empty +// result. The HTTP endpoint answered "method not found", so a client that +// pings to see whether the server is still there was told it is not. +func TestHTTPEndpointAnswersPing(t *testing.T) { + resp := rpcCall(t, `{"jsonrpc":"2.0","id":7,"method":"ping"}`) + if resp["error"] != nil { + t.Fatalf("ping answered with an error: %v", resp["error"]) + } + if result, ok := resp["result"].(map[string]any); !ok || len(result) != 0 { + t.Fatalf("ping result = %#v, want an empty object", resp["result"]) + } + if resp["id"] != float64(7) { + t.Fatalf("ping answer id = %v, want 7", resp["id"]) + } +} + +// A notification expects no answer. The endpoint always writes one, so every +// notification gets the empty acknowledgement notifications/initialized has +// always had, not "method not found". +func TestHTTPEndpointAcknowledgesEveryNotification(t *testing.T) { + for _, method := range []string{"notifications/initialized", "notifications/cancelled", "notifications/progress", "notifications/roots/list_changed"} { + resp := rpcCall(t, `{"jsonrpc":"2.0","method":"`+method+`","params":{"requestId":3,"reason":"timeout"}}`) + if resp["error"] != nil { + t.Errorf("%s answered with an error: %v", method, resp["error"]) + } + if result, ok := resp["result"].(map[string]any); !ok || len(result) != 0 { + t.Errorf("%s result = %#v, want an empty object", method, resp["result"]) + } + } +} + +func TestHTTPEndpointStillRefusesUnknownMethods(t *testing.T) { + for _, method := range []string{"resources/list", "prompts/list", "notifications", "tools/unknown", ""} { + resp := rpcCall(t, `{"jsonrpc":"2.0","id":1,"method":"`+method+`"}`) + rpcErr, _ := resp["error"].(map[string]any) + if rpcErr["code"] != float64(-32601) { + t.Errorf("%q answered %v, want error -32601", method, resp) + } + } +}