diff --git a/changelog.d/fixed-admin-mcp-docs-match-tools.md b/changelog.d/fixed-admin-mcp-docs-match-tools.md new file mode 100644 index 0000000000..e8ba8f6c48 --- /dev/null +++ b/changelog.d/fixed-admin-mcp-docs-match-tools.md @@ -0,0 +1 @@ +- Admin MCP: the `version_read` tool description and the operator guide name the fields the hive really returns for the running commit, `hash` and `short`. They named `currentCommit`, which `GET /api/version` does not return, so a model asked for the running commit looked for a field that was never there. The guide (`src/docs/admin-mcp.md`) also lists the `triggers` settings section, which `settings_read` has always offered, and no longer says the write tools appear only when writes are on: `write_preview` and `write_confirm` are always listed, marked disabled with the reason. diff --git a/src/docs/admin-mcp.md b/src/docs/admin-mcp.md index f823ac7bb4..87931bc856 100644 --- a/src/docs/admin-mcp.md +++ b/src/docs/admin-mcp.md @@ -205,7 +205,7 @@ capped at 256 KiB. |------|---------| | `hive_status` | Hive status summary | | `fleet_status` | Fleet state; `systemResources` also carries the container's memory limit (`memLimit`, `unlimited` when none is set, with `memLimitBytes`) and out-of-memory kill count (`oomKillCount`), see [Start records, crash traces and out-of-memory evidence](#start-records-crash-traces-and-out-of-memory-evidence) | -| `version_read` | Running build from `/api/version`: `currentCommit`, `branch`, `channel`, `commitsBehind`, `behind`; over stdio also `stdio_build` (`version`, `sha`, `short`, `branch`) and `skew` (true when the stdio and hub short SHAs are both known and differ); over HTTP also `last_seen_stdio_build` and `last_seen_stdio_at` alongside `hub_build` | +| `version_read` | Running build from `/api/version`: `hash` and `short` (the running commit), `branch`, `channel`, `commitsBehind`, `behind`; over stdio also `stdio_build` (`version`, `sha`, `short`, `branch`) and `skew` (true when the stdio and hub short SHAs are both known and differ); over HTTP also `last_seen_stdio_build` and `last_seen_stdio_at` alongside `hub_build` | | `agents_list` | Agents | | `runs_list` | Runs | | `leases_list` | Leases | @@ -240,7 +240,7 @@ is scrubbed like every other read. budget, notifications, health, sensing, logging, security, features, hub, LiteLLM, watchdog, trajectory, classifier, release sentinel), `project`, `github_apps`, `authorized_users`, `dashboard`, `channels`, `escalation`, - `auto_merge`, `review`, `convergence`, `sla`, `advisor`, `advisory`, `replan`, + `auto_merge`, `review`, `convergence`, `sla`, `triggers`, `advisor`, `advisory`, `replan`, `question_autoclose`, `question_autoclose_schedule`, `fleet_report`, `work_source`, `project_observability`, `general_advanced`, `cadence_scope`, `threshold_scaling`, `backup`, `bob`, `inference_auth`, `gateways`, @@ -264,8 +264,10 @@ Meta tools: - `exclusion_catalogue` lists what the admin MCP will never do, and why. - `refuse_operation` explains the refusal for a named operation. -Write tools (`write_preview`, `write_confirm`) appear only when writes are on. -On stdio, `select_hive` is also available. +Write tools (`write_preview`, `write_confirm`) are always listed. When writes +are off, or not available to the caller, their `metadata.preview.enabled` is +`false` with a note saying why, and a call is refused. On stdio, `select_hive` +is also available. ### Diagnostic reads diff --git a/src/pkg/adminmcp/adminmcp.go b/src/pkg/adminmcp/adminmcp.go index 38cb05a6a1..4ebd7b7ebb 100644 --- a/src/pkg/adminmcp/adminmcp.go +++ b/src/pkg/adminmcp/adminmcp.go @@ -339,7 +339,7 @@ func toolDefs(writesEnabled bool, unavailableReason string) []map[string]any { defs := []struct{ name, desc string }{ {ToolHiveStatus, "Read this hive's dashboard status summary."}, {ToolFleetStatus, "Read this hive's fleet status, including repo and agent health rollups. systemResources also carries the container's memory limit (memLimit, \"unlimited\" when none is set) and its out-of-memory kill count (oomKillCount); a restart resets that count, and the starts log source keeps the reading taken before the previous run ended."}, - {ToolVersionRead, "Read the build this hive is running (currentCommit, branch, channel, commitsBehind, behind) through the existing /api/version endpoint."}, + {ToolVersionRead, "Read the build this hive is running (hash and short for the running commit, branch, channel, commitsBehind, behind) through the existing /api/version endpoint."}, {ToolAgentsList, "Read the capped list of agents known to this hive."}, {ToolRunsList, "Read the capped list of runs known to this hive."}, {ToolLeasesList, "Read active run leases through the existing runs surface."}, diff --git a/src/pkg/adminmcp/tools_settings_test.go b/src/pkg/adminmcp/tools_settings_test.go index e49f2ff376..aa804f59dc 100644 --- a/src/pkg/adminmcp/tools_settings_test.go +++ b/src/pkg/adminmcp/tools_settings_test.go @@ -1,6 +1,7 @@ package adminmcp import ( + "os" "strings" "testing" ) @@ -58,3 +59,18 @@ func TestSettingsReadSchemaListsSections(t *testing.T) { t.Fatal("description does not list the sections") } } + +// The operator guide lists the settings_read sections by name. A section +// added to the tool and not to the guide (triggers was one) is one an +// operator reading the guide never learns to ask for. +func TestOperatorGuideListsEverySettingsSection(t *testing.T) { + doc, err := os.ReadFile("../../docs/admin-mcp.md") + if err != nil { + t.Fatal(err) + } + for _, section := range SettingsSections() { + if !strings.Contains(string(doc), "`"+section.Name+"`") { + t.Errorf("docs/admin-mcp.md does not list the settings_read section %q", section.Name) + } + } +} diff --git a/src/pkg/dashboard/admin_mcp_test.go b/src/pkg/dashboard/admin_mcp_test.go index 470272badc..2dcac85f08 100644 --- a/src/pkg/dashboard/admin_mcp_test.go +++ b/src/pkg/dashboard/admin_mcp_test.go @@ -196,11 +196,11 @@ func TestAdminMCPAdvisorRecordsMatchesREST(t *testing.T) { } // TestDashboardAdminMCPVersionReadReturnsAPIVersion: version_read answers with -// the same currentCommit the authenticated /api/version reports (#11220). +// the same running commit the authenticated /api/version reports (#11220). func TestDashboardAdminMCPVersionReadReturnsAPIVersion(t *testing.T) { s := &Server{mux: http.NewServeMux()} s.mux.HandleFunc("GET /api/version", func(w http.ResponseWriter, r *http.Request) { - _ = json.NewEncoder(w).Encode(map[string]any{"currentCommit": "1ffbbae", "branch": "v6"}) + _ = json.NewEncoder(w).Encode(map[string]any{"short": "1ffbbae", "branch": "v6"}) }) rec := httptest.NewRecorder() req := httptest.NewRequest(http.MethodPost, adminmcp.EndpointPath, strings.NewReader(`{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"version_read","arguments":{}}}`)) @@ -208,11 +208,41 @@ func TestDashboardAdminMCPVersionReadReturnsAPIVersion(t *testing.T) { if rec.Code != http.StatusOK { t.Fatalf("status = %d body=%s", rec.Code, rec.Body.String()) } - if !strings.Contains(rec.Body.String(), "1ffbbae") || !strings.Contains(rec.Body.String(), "currentCommit") { + if !strings.Contains(rec.Body.String(), "1ffbbae") || !strings.Contains(rec.Body.String(), "short") { t.Fatalf("version_read body = %s", rec.Body.String()) } } +// The version_read description told the model to read "currentCommit", a +// field GET /api/version does not return: the running commit is in hash and +// short. The description must name fields the real endpoint answers with. +func TestVersionReadDescriptionNamesTheCommitFieldsTheHiveReturns(t *testing.T) { + s := &Server{mux: http.NewServeMux()} + s.mux.HandleFunc("GET /api/version", s.handleVersion) + data, err := dashboardAdminMCPProvider{server: s}.Read(context.Background(), adminmcp.ToolVersionRead, map[string]any{}) + if err != nil { + t.Fatal(err) + } + answer, _ := data.(map[string]any) + desc := "" + for _, tool := range adminmcp.Tools() { + if tool["name"] == adminmcp.ToolVersionRead { + desc, _ = tool["description"].(string) + } + } + for _, field := range []string{"hash", "short", "branch"} { + if _, ok := answer[field]; !ok { + t.Errorf("GET /api/version no longer returns %q; update the version_read description and docs/admin-mcp.md", field) + } + if !strings.Contains(desc, field) { + t.Errorf("version_read description does not name %q: %s", field, desc) + } + } + if _, ok := answer["currentCommit"]; !ok && strings.Contains(desc, "currentCommit") { + t.Errorf("version_read description names currentCommit, which the hive does not return: %s", desc) + } +} + func TestParseStdioBuildFromUserAgent(t *testing.T) { for _, tc := range []struct { ua string