Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelog.d/fixed-admin-mcp-docs-match-tools.md
Original file line number Diff line number Diff line change
@@ -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.
10 changes: 6 additions & 4 deletions src/docs/admin-mcp.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand Down Expand Up @@ -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`,
Expand All @@ -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

Expand Down
2 changes: 1 addition & 1 deletion src/pkg/adminmcp/adminmcp.go
Original file line number Diff line number Diff line change
Expand Up @@ -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."},
Expand Down
16 changes: 16 additions & 0 deletions src/pkg/adminmcp/tools_settings_test.go
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
package adminmcp

import (
"os"
"strings"
"testing"
)
Expand Down Expand Up @@ -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)
}
}
}
36 changes: 33 additions & 3 deletions src/pkg/dashboard/admin_mcp_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -196,23 +196,53 @@ 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":{}}}`))
adminmcp.NewHandler(dashboardAdminMCPProvider{server: s}).ServeHTTP(rec, req)
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
Expand Down
Loading