Skip to content

armgit / Pulse

Public Imported from GitHub
0

Real-time monitoring dashboard for Proxmox VE, PBS, Docker, Kubernetes, TrueNAS and vSphere. Self-hosted, with alerts for failed backups, full disks, unhealthy containers and offline nodes.

Tell agent users what they can ask Pulse

rcourtman26c802d926ad
diff --git a/README.md b/README.md
index 58b202348c..712a013837 100644
--- a/README.md
+++ b/README.md
@@ -39,8 +39,11 @@ sample data and signs you in automatically.
Community, ninety in Pro.
- **Optional AI checks.** Connect your own AI provider or a local model and
Pulse Patrol runs scheduled checks for problems a dashboard only shows if
- someone is looking. An MCP adapter lets clients such as Claude Code and
- OpenCode query Pulse.
+ someone is looking.
+- **Answers your own AI agent.** Point Claude Code, Codex or OpenCode at Pulse
+ with [`pulse-mcp`](cmd/pulse-mcp/README.md#quick-start) and ask what changed
+ overnight, whether a host rebooted, or how a disk filled up. A read-only
+ token is enough.
- **Stays hands-off by default.** Proxmox is read through a read-only API
token, credentials are encrypted at rest, and agent commands stay off unless
you turn them on.
diff --git a/cmd/pulse-mcp/README.md b/cmd/pulse-mcp/README.md
index 0318b44100..dd4f936303 100644
--- a/cmd/pulse-mcp/README.md
+++ b/cmd/pulse-mcp/README.md
@@ -1,11 +1,16 @@
# pulse-mcp
`pulse-mcp` is the Model Context Protocol (MCP) adapter for Pulse
-Intelligence. It exposes the same governed operations substrate that
-Pulse Assistant uses inside the app, but as tools for Claude Desktop,
-Claude Code, OpenCode, and any other MCP-speaking client: list findings,
-read the fleet, drill into a resource, set operator intent, and run
-governed actions.
+Intelligence. It lets Claude Desktop, Claude Code, Codex, OpenCode and any
+other MCP-speaking client ask Pulse what it has seen while it monitors:
+what changed across the fleet and when (`list_recent_changes`), how a
+resource's metrics moved (`get_metric_history`), and where to look first
+(`get_fleet_context`, `get_resource_context`). A `monitoring:read` token
+covers those reads.
+
+With more scopes it exposes the same governed operations substrate that
+Pulse Assistant uses inside the app: list findings, set operator intent,
+and plan, approve and run governed actions.
## Pulse Intelligence surface contract
diff --git a/docs/release-control/v6/internal/subsystems/ai-runtime.md b/docs/release-control/v6/internal/subsystems/ai-runtime.md
index add91660f4..6ba41d5ac9 100644
--- a/docs/release-control/v6/internal/subsystems/ai-runtime.md
+++ b/docs/release-control/v6/internal/subsystems/ai-runtime.md
@@ -2097,6 +2097,11 @@ external-agent activity rather than a new telemetry activity. A range outside
`MetricHistoryRanges` or a non-positive `maxPoints` is a 400. `maxPoints` (capped
at 200) is the downsampling target, not an output bound: short windows and
fallback reads can return native samples, as the chart route does.
+The `cmd/pulse-mcp/README.md` introduction leads with the read-only questions
+external agents can ask (`list_recent_changes`, `get_metric_history`,
+`get_fleet_context`, `get_resource_context`) and says a `monitoring:read` token
+covers them; `TestContract_PulseMCPReadmeIntroNamesPublishedReadTools` fails if
+a tool it names stops being an MCP-published monitoring-read GET.
than in `cmd/pulse-mcp` or an MCP-only inventory registry. They must enter
through `ManifestSurfaceResourceCapabilities`,
`ListMCPManifestSurfaceResourcesHTTP`, and
diff --git a/docs/release-control/v6/internal/subsystems/api-contracts.md b/docs/release-control/v6/internal/subsystems/api-contracts.md
index 935546a20b..b0a20afa45 100644
--- a/docs/release-control/v6/internal/subsystems/api-contracts.md
+++ b/docs/release-control/v6/internal/subsystems/api-contracts.md
@@ -6826,6 +6826,10 @@ target kinds (`pod`, `k8s-cluster`, `k8s-node`, `k8s-deployment`) as the
`frontend-modern/public/docs/`, list those kinds beside `k8s`;
`scripts/tests/test_setup_access_docs.py` pins the documented set to the switch
and `docsLinks.test.ts` pins the published copies to their sources.
+The `cmd/pulse-mcp/README.md` introduction names these monitoring-read agent
+reads as the place a new MCP user starts; its named tools are pinned to the
+manifest's MCP surface and scope by
+`TestContract_PulseMCPReadmeIntroNamesPublishedReadTools`.
`/api/agent/resource-capabilities/{id}` is the agent-consumable
structured capability surface for a single resource: the governed
diff --git a/internal/api/contract_test.go b/internal/api/contract_test.go
index e68489355f..baad97a216 100644
--- a/internal/api/contract_test.go
+++ b/internal/api/contract_test.go
@@ -28685,6 +28685,41 @@ func TestContract_PulseMCPPublishesRecentChangesAsReadOnlyTool(t *testing.T) {
}
}
+// TestContract_PulseMCPReadmeIntroNamesPublishedReadTools pins the pulse-mcp
+// README introduction to the manifest. It promises that a monitoring:read
+// token covers the tools it names, so each must be an MCP-published GET with
+// that scope; a renamed tool or a widened scope fails here instead of leaving
+// the first thing a new user reads out of date.
+func TestContract_PulseMCPReadmeIntroNamesPublishedReadTools(t *testing.T) {
+ readme, err := os.ReadFile(filepath.Join("..", "..", "cmd", "pulse-mcp", "README.md"))
+ if err != nil {
+ t.Fatalf("read cmd/pulse-mcp/README.md: %v", err)
+ }
+ intro, _, found := strings.Cut(string(readme), "\n## ")
+ if !found || !strings.Contains(intro, "`monitoring:read` token") {
+ t.Fatalf("pulse-mcp README introduction no longer states which token covers its reads:\n%s", intro)
+ }
+ before, _, _ := strings.Cut(intro, "`monitoring:read` token")
+ named := regexp.MustCompile("`([a-z]+(?:_[a-z]+)+)`").FindAllStringSubmatch(before, -1)
+ if len(named) == 0 {
+ t.Fatal("pulse-mcp README introduction names no tools")
+ }
+ published := map[string]agentcapabilities.Capability{}
+ for _, capability := range agentcapabilities.ManifestSurfaceToolCapabilities(agentcapabilities.CanonicalManifest(), agentcapabilities.SurfaceIDPulseMCP) {
+ published[capability.Name] = capability
+ }
+ for _, match := range named {
+ capability, ok := published[match[1]]
+ if !ok {
+ t.Errorf("README introduction names %s, which Pulse MCP does not publish", match[1])
+ continue
+ }
+ if capability.Method != http.MethodGet || capability.Scope != config.ScopeMonitoringRead {
+ t.Errorf("README introduction says a monitoring:read token covers %s, but it is %s with scope %s", match[1], capability.Method, capability.Scope)
+ }
+ }
+}
+
// Change events reach only subscribers in the organization whose monitor
// recorded them; untagged events still reach everyone.
func TestContract_AgentChangeEventsStayInsideTheirOrganization(t *testing.T) {