vmware-aria 2.2.0__tar.gz → 2.4.0__tar.gz

{vmware_aria-2.2.0 → vmware_aria-2.4.0}/.claude-plugin/plugin.json

@@ -2,8 +2,8 @@
   "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
   "name": "vmware-aria",
   "displayName": "VMware Aria",
-  "version": "2.2.0",
-  "description": "VMware Aria Operations: metrics, alerts, capacity, anomaly detection — 44 MCP tools.",
+  "version": "2.4.0",
+  "description": "VMware Aria Operations: metrics, alerts, capacity, anomaly detection — 46 MCP tools.",
   "author": {
     "name": "Wei Zhou",
     "email": "zhouwei008@gmail.com",

{vmware_aria-2.2.0 → vmware_aria-2.4.0}/.mcp.json

@@ -5,7 +5,7 @@
       "command": "uvx",
       "args": [
         "--from",
-        "vmware-aria==2.2.0",
+        "vmware-aria==2.4.0",
         "vmware-aria-mcp"
       ]
     }

{vmware_aria-2.2.0 → vmware_aria-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: vmware-aria
-Version: 2.2.0
+Version: 2.4.0
 Summary: VMware Aria Operations (vRealize Operations) monitoring, alerting, and capacity planning
 Project-URL: Homepage, https://github.com/vmware-skills/VMware-Aria
 Project-URL: Repository, https://github.com/vmware-skills/VMware-Aria
@@ -20,7 +20,7 @@ Requires-Dist: python-dotenv<2.0,>=1.0
 Requires-Dist: pyyaml<7.0,>=6.0
 Requires-Dist: rich<15.0,>=13.0
 Requires-Dist: typer<1.0,>=0.12
-Requires-Dist: vmware-policy<2.0,>=1.21.0
+Requires-Dist: vmware-policy<2.0,>=1.22.0
 Description-Content-Type: text/markdown
 
 <!-- mcp-name: io.github.vmware-skills/vmware-aria -->
@@ -39,7 +39,7 @@ AI-assisted monitoring and capacity planning for VMware Aria Operations (vRealiz
 
 ## Upgrading to 2.0
 
-2.0 renames 4 of its 44 MCP tools so every name starts with a verb (e.g. `findings_list` → `list_findings`, `fleet_certificate_list` → `list_fleet_certificates`, `fleet_domain_list` → `list_fleet_domains`). The full old → new table is in
+2.0 renames 4 of its MCP tools so every name starts with a verb (e.g. `findings_list` → `list_findings`, `fleet_certificate_list` → `list_fleet_certificates`, `fleet_domain_list` → `list_fleet_domains`). The full old → new table is in
 [RELEASE_NOTES.md](RELEASE_NOTES.md#v200--mcp-tools-renamed-verb-first). Nothing else changes: same tools, parameters,
 safety gates and CLI commands. If an agent prompt, script or `~/.vmware/rules.yaml` names a tool, update it — though deny
 rules written with the old names keep working with vmware-policy ≥ 1.18 (`vmware-audit policy` lists any rule the
@@ -49,7 +49,7 @@ against both the old and the new name, so one file serves both.
 
 ## Overview
 
-`vmware-aria` exposes 44 MCP tools for interacting with Aria Operations through natural language AI agents (Claude Code, Cursor, Goose, etc.):
+`vmware-aria` exposes 46 MCP tools for interacting with Aria Operations through natural language AI agents (Claude Code, Cursor, Goose, etc.):
 
 | Category | Tools | Type |
 |----------|-------|------|
@@ -62,8 +62,9 @@ against both the old and the new name, so one file serves both.
 | **Health** | platform health, collector groups, Aria node memory/swap/heap, adapter collection state | Read-only (4) |
 | **Maintenance** | start / end resource maintenance, maintenance schedules | Read + 2 Write (3) |
 | **Fleet / PromQL** (VCF Ops 9.1) | fleet certificates, password accounts, VCF domains, diagnostic findings, real-time PromQL query | Read-only (5) |
+| **Raw API** | search the API operation index, GET one indexed path — for reads no tool above covers | Read-only (2) |
 
-**Total**: 44 tools — 34 read-only, 10 write
+**Total**: 46 tools — 36 read-only, 10 write
 
 ## Quick Start
 
@@ -248,6 +249,72 @@ VMs / Hosts / Clusters / Alerts / Capacity
 - **SDKs**: <https://developer.broadcom.com/sdks> — VCF Python SDK
 - **CLI Tools**: <https://developer.broadcom.com/tools> — PowerCLI 9.1 includes "VCF Operations (formerly vRealize Operations Manager)" cmdlets
 
+<!-- usage: remote-and-exposure -->
+## Remote access (HTTPS) and limiting tools
+
+By default `vmware-aria mcp` speaks stdio to one local client and offers every tool. Two options change that
+(vmware-policy ≥ 1.21.0).
+
+**Serve over HTTPS** so clients on other machines can connect. Every caller needs a bearer token:
+
+```bash
+vmware-audit token create alice          # prints the token once; give it to alice
+vmware-audit token list                  # names only
+vmware-audit token revoke alice          # refused from its next request, no restart
+vmware-aria mcp --transport https --host 0.0.0.0 --port 8443 \
+    --cert /etc/vmware-mcp/server.pem --key /etc/vmware-mcp/server-key.pem \
+    --public-name mcp.example.com
+```
+
+Connect a client (Claude Code shown; any MCP client that supports streamable HTTP and custom headers works):
+
+```bash
+claude mcp add --transport http vmware-aria https://mcp.example.com:8443/mcp \
+    --header "Authorization: Bearer $VMWARE_MCP_TOKEN"
+```
+
+```json
+{
+  "mcpServers": {
+    "vmware-aria": {
+      "type": "http",
+      "url": "https://mcp.example.com:8443/mcp",
+      "headers": { "Authorization": "Bearer ${VMWARE_MCP_TOKEN}" }
+    }
+  }
+}
+```
+
+- The server will not start without a token, refuses Host/Origin values outside `--public-name`, and checks
+  before it binds that unauthenticated requests get 401. Use a certificate your clients trust for those names.
+- Behind a TLS-terminating reverse proxy on the same machine use `--transport http --host 127.0.0.1
+  --public-name mcp.example.com` and pass the `Authorization` header through.
+- Behind a load balancer or gateway on another machine, keep `--transport https` (a self-signed certificate is
+  fine), list in `--public-name` the host name the balancer sends as `Host`, and have it forward `Authorization`.
+  Its health probe can use `GET /healthz`, which needs no token and returns only `{"status": "ok"}`
+  (vmware-policy ≥ 1.23.0).
+- Send `traceparent` or `X-Request-ID` with each request to have it stored on the audit row;
+  `vmware-audit log --correlation-id ID` then finds the calls behind one platform request.
+- The audit log records each caller as `token:<name>`. Calls run side by side: each holds its own session to a
+  target, up to `VMWARE_MCP_POOL_SIZE` (default 2) sessions per target. Each session is a login on the target; a
+  call waits at most 300 s for a free one.
+- **Everyone who can reach the endpoint acts with this server's account.** Tokens identify callers; they grant
+  nothing on the platform. Run one endpoint per privilege level.
+- **Several people or roles on one endpoint:** run `vmware-audit roles enable` once, then give each token a role (`vmware-audit token create NAME --role reader`, or a role in `roles.yaml` naming tools and targets; vmware-policy ≥ 1.24.0). A role limits what the token may call on this endpoint; it cannot grant more than the account has. See vmware-policy's README, "Roles for network callers".
+
+**Offer only read tools, plus the writes you choose:**
+
+```bash
+vmware-aria mcp --expose read --allow-write acknowledge_alert
+# or: VMWARE_ARIA_MCP_EXPOSE=read VMWARE_ARIA_MCP_ALLOW_WRITE=acknowledge_alert vmware-aria mcp
+```
+
+Tools not offered do not appear in the client's tool list. A bad value or an unknown write tool stops the server
+(exit 2). This limits what clients are offered; it is not authorization, so the account itself should be
+least-privilege.
+
+Details: `skills/vmware-aria/references/setup-guide.md` ("Serving MCP over HTTPS", "Limiting which tools are offered").
+
 ## License
 
 MIT — see [LICENSE](LICENSE)

{vmware_aria-2.2.0 → vmware_aria-2.4.0}/README-CN.md

@@ -9,7 +9,7 @@
 
 ## 升级到 2.0
 
-2.0 把 44 个 MCP 工具中的 4 个改成动词在前（例如 `findings_list` → `list_findings`, `fleet_certificate_list` → `list_fleet_certificates`, `fleet_domain_list` → `list_fleet_domains`），完整的新旧名对照表见
+2.0 把 MCP 工具名改成动词在前（共改名 4 处）（例如 `findings_list` → `list_findings`, `fleet_certificate_list` → `list_fleet_certificates`, `fleet_domain_list` → `list_fleet_domains`），完整的新旧名对照表见
 [RELEASE_NOTES.md](RELEASE_NOTES.md#v200--mcp-tools-renamed-verb-first)。其他都不变：工具、参数、安全确认门和 CLI 命令都一样。
 如果 agent 提示词、脚本或 `~/.vmware/rules.yaml` 里写了工具名，请改成新名——不过用旧名写的 deny 规则在
 vmware-policy ≥ 1.18 下仍然生效（`vmware-audit policy` 会列出因改名而多匹配的规则），vmware-pilot ≥ 1.13 也会自动转换已保存工作流里的旧名。
@@ -17,7 +17,7 @@ vmware-policy ≥ 1.18 下仍然生效（`vmware-audit policy` 会列出因改
 
 ## 概述
 
-`vmware-aria` 提供 44 个 MCP 工具，支持通过自然语言 AI Agent（Claude Code、Cursor、Goose 等）与 Aria Operations 交互：
+`vmware-aria` 提供 46 个 MCP 工具，支持通过自然语言 AI Agent（Claude Code、Cursor、Goose 等）与 Aria Operations 交互：
 
 | 类别 | 工具 | 类型 |
 |------|------|------|
@@ -30,8 +30,9 @@ vmware-policy ≥ 1.18 下仍然生效（`vmware-audit policy` 会列出因改
 | **健康** | 平台健康、采集器状态、Aria 节点内存/交换/堆、适配器采集状态 | 只读 (4) |
 | **维护** | 开始 / 结束资源维护模式、维护计划 | 读+2写 (3) |
 | **Fleet / PromQL**（VCF Ops 9.1） | Fleet 证书、密码账户、VCF 域、诊断发现、实时 PromQL 查询 | 只读 (5) |
+| **原始 API** | 搜索 API 操作索引、GET 一个索引内的路径 —— 用于上面工具都覆盖不到的读取 | 只读 (2) |
 
-**共 44 个工具** — 34 只读、10 写操作
+**共 46 个工具** — 36 只读、10 写操作
 
 ## 快速开始
 
@@ -202,6 +203,69 @@ Token 为 6 小时滑动有效期（每次调用自动延长，官方规范行
 - MCP 的破坏性写操作（告警确认/取消、删除告警定义和报表、开始/结束维护）带 `confirm` 参数（默认 `false`）：不传 `confirm=true` 时只返回将改变什么的 `blast_radius`，不做任何修改；遇到阻断项（如资源已在维护中）或有字段读不到时，`confirm=true` 会被拒绝。`confirmed` 为已弃用的别名
 - 默认开启 TLS 校验；私有 CA 请把 `SSL_CERT_FILE` 指向包含你 CA 的证书包（见 setup guide）。`verify_ssl: false` 仅用于隔离的自签名实验环境
 
+<!-- usage: remote-and-exposure -->
+## 远程访问（HTTPS）与限制工具
+
+默认情况下 `vmware-aria mcp` 通过 stdio 服务一个本地客户端，并提供全部工具。以下两个选项可以改变这一点
+（需 vmware-policy ≥ 1.21.0）。
+
+**通过 HTTPS 提供服务**，让其他机器上的客户端连接。每个调用者都需要一个 bearer token：
+
+```bash
+vmware-audit token create alice          # 只显示一次，交给 alice
+vmware-audit token list                  # 只列名字
+vmware-audit token revoke alice          # 下一个请求起即拒绝，无需重启
+vmware-aria mcp --transport https --host 0.0.0.0 --port 8443 \
+    --cert /etc/vmware-mcp/server.pem --key /etc/vmware-mcp/server-key.pem \
+    --public-name mcp.example.com
+```
+
+连接客户端（以 Claude Code 为例；任何支持 streamable HTTP 和自定义请求头的 MCP 客户端都可以）：
+
+```bash
+claude mcp add --transport http vmware-aria https://mcp.example.com:8443/mcp \
+    --header "Authorization: Bearer $VMWARE_MCP_TOKEN"
+```
+
+```json
+{
+  "mcpServers": {
+    "vmware-aria": {
+      "type": "http",
+      "url": "https://mcp.example.com:8443/mcp",
+      "headers": { "Authorization": "Bearer ${VMWARE_MCP_TOKEN}" }
+    }
+  }
+}
+```
+
+- 没有 token 时服务不会启动；`--public-name` 之外的 Host/Origin 一律拒绝；绑定端口前会自检，确认未认证请求得到 401。
+  证书要用客户端信任、且覆盖这些名字的证书。
+- 在同一台机器上由反向代理终结 TLS 时，用 `--transport http --host 127.0.0.1 --public-name mcp.example.com`，
+  并让代理透传 `Authorization` 头。
+- 负载均衡或网关在另一台机器上时，保持 `--transport https`（自签证书也可以），在 `--public-name` 里写上负载均衡
+  转发时带的 `Host` 名，并让它透传 `Authorization`。健康检查可以用 `GET /healthz`：不需要 token，只返回
+  `{"status": "ok"}`（需 vmware-policy ≥ 1.23.0）。
+- 每个请求带上 `traceparent` 或 `X-Request-ID`，它会记进审计记录；用 `vmware-audit log --correlation-id ID`
+  就能查到平台上某一次请求对应的调用。
+- 审计日志把每个调用者记为 `token:<名字>`。调用并行执行：每个调用独占一个到 target 的会话，每个 target 最多
+  `VMWARE_MCP_POOL_SIZE`（默认 2）个会话。每个会话都是在 target 上的一次登录；调用最多等待 300 秒拿到空闲会话。
+- **能连到这个端点的人，都以该 server 配置的账号操作。** token 只用来识别调用者，不在平台上授予任何权限。
+  每个权限级别单独起一个端点。
+- **一个端点给多人或多种角色用：** 先运行一次 `vmware-audit roles enable`，再给每个 token 指定角色（`vmware-audit token create 名字 --role reader`，或在 `roles.yaml` 里定义可用的工具和 target；需 vmware-policy ≥ 1.24.0）。角色只能限定这个 token 在本端点上能调用什么，不能超出账号本身的权限。详见 vmware-policy README 的「网络调用者的角色」一节。
+
+**只提供读工具，加上你选定的写工具：**
+
+```bash
+vmware-aria mcp --expose read --allow-write acknowledge_alert
+# 或：VMWARE_ARIA_MCP_EXPOSE=read VMWARE_ARIA_MCP_ALLOW_WRITE=acknowledge_alert vmware-aria mcp
+```
+
+未提供的工具不会出现在客户端的工具列表里。取值错误或写工具名不存在时服务直接退出（exit 2）。
+这只限制提供给客户端的工具，不是授权；账号本身仍应遵循最小权限。
+
+详见 `skills/vmware-aria/references/setup-guide.md`（"Serving MCP over HTTPS"、"Limiting which tools are offered"）。
+
 ## 许可证
 
 MIT

{vmware_aria-2.2.0 → vmware_aria-2.4.0}/README.md

@@ -14,7 +14,7 @@ AI-assisted monitoring and capacity planning for VMware Aria Operations (vRealiz
 
 ## Upgrading to 2.0
 
-2.0 renames 4 of its 44 MCP tools so every name starts with a verb (e.g. `findings_list` → `list_findings`, `fleet_certificate_list` → `list_fleet_certificates`, `fleet_domain_list` → `list_fleet_domains`). The full old → new table is in
+2.0 renames 4 of its MCP tools so every name starts with a verb (e.g. `findings_list` → `list_findings`, `fleet_certificate_list` → `list_fleet_certificates`, `fleet_domain_list` → `list_fleet_domains`). The full old → new table is in
 [RELEASE_NOTES.md](RELEASE_NOTES.md#v200--mcp-tools-renamed-verb-first). Nothing else changes: same tools, parameters,
 safety gates and CLI commands. If an agent prompt, script or `~/.vmware/rules.yaml` names a tool, update it — though deny
 rules written with the old names keep working with vmware-policy ≥ 1.18 (`vmware-audit policy` lists any rule the
@@ -24,7 +24,7 @@ against both the old and the new name, so one file serves both.
 
 ## Overview
 
-`vmware-aria` exposes 44 MCP tools for interacting with Aria Operations through natural language AI agents (Claude Code, Cursor, Goose, etc.):
+`vmware-aria` exposes 46 MCP tools for interacting with Aria Operations through natural language AI agents (Claude Code, Cursor, Goose, etc.):
 
 | Category | Tools | Type |
 |----------|-------|------|
@@ -37,8 +37,9 @@ against both the old and the new name, so one file serves both.
 | **Health** | platform health, collector groups, Aria node memory/swap/heap, adapter collection state | Read-only (4) |
 | **Maintenance** | start / end resource maintenance, maintenance schedules | Read + 2 Write (3) |
 | **Fleet / PromQL** (VCF Ops 9.1) | fleet certificates, password accounts, VCF domains, diagnostic findings, real-time PromQL query | Read-only (5) |
+| **Raw API** | search the API operation index, GET one indexed path — for reads no tool above covers | Read-only (2) |
 
-**Total**: 44 tools — 34 read-only, 10 write
+**Total**: 46 tools — 36 read-only, 10 write
 
 ## Quick Start
 
@@ -223,6 +224,72 @@ VMs / Hosts / Clusters / Alerts / Capacity
 - **SDKs**: <https://developer.broadcom.com/sdks> — VCF Python SDK
 - **CLI Tools**: <https://developer.broadcom.com/tools> — PowerCLI 9.1 includes "VCF Operations (formerly vRealize Operations Manager)" cmdlets
 
+<!-- usage: remote-and-exposure -->
+## Remote access (HTTPS) and limiting tools
+
+By default `vmware-aria mcp` speaks stdio to one local client and offers every tool. Two options change that
+(vmware-policy ≥ 1.21.0).
+
+**Serve over HTTPS** so clients on other machines can connect. Every caller needs a bearer token:
+
+```bash
+vmware-audit token create alice          # prints the token once; give it to alice
+vmware-audit token list                  # names only
+vmware-audit token revoke alice          # refused from its next request, no restart
+vmware-aria mcp --transport https --host 0.0.0.0 --port 8443 \
+    --cert /etc/vmware-mcp/server.pem --key /etc/vmware-mcp/server-key.pem \
+    --public-name mcp.example.com
+```
+
+Connect a client (Claude Code shown; any MCP client that supports streamable HTTP and custom headers works):
+
+```bash
+claude mcp add --transport http vmware-aria https://mcp.example.com:8443/mcp \
+    --header "Authorization: Bearer $VMWARE_MCP_TOKEN"
+```
+
+```json
+{
+  "mcpServers": {
+    "vmware-aria": {
+      "type": "http",
+      "url": "https://mcp.example.com:8443/mcp",
+      "headers": { "Authorization": "Bearer ${VMWARE_MCP_TOKEN}" }
+    }
+  }
+}
+```
+
+- The server will not start without a token, refuses Host/Origin values outside `--public-name`, and checks
+  before it binds that unauthenticated requests get 401. Use a certificate your clients trust for those names.
+- Behind a TLS-terminating reverse proxy on the same machine use `--transport http --host 127.0.0.1
+  --public-name mcp.example.com` and pass the `Authorization` header through.
+- Behind a load balancer or gateway on another machine, keep `--transport https` (a self-signed certificate is
+  fine), list in `--public-name` the host name the balancer sends as `Host`, and have it forward `Authorization`.
+  Its health probe can use `GET /healthz`, which needs no token and returns only `{"status": "ok"}`
+  (vmware-policy ≥ 1.23.0).
+- Send `traceparent` or `X-Request-ID` with each request to have it stored on the audit row;
+  `vmware-audit log --correlation-id ID` then finds the calls behind one platform request.
+- The audit log records each caller as `token:<name>`. Calls run side by side: each holds its own session to a
+  target, up to `VMWARE_MCP_POOL_SIZE` (default 2) sessions per target. Each session is a login on the target; a
+  call waits at most 300 s for a free one.
+- **Everyone who can reach the endpoint acts with this server's account.** Tokens identify callers; they grant
+  nothing on the platform. Run one endpoint per privilege level.
+- **Several people or roles on one endpoint:** run `vmware-audit roles enable` once, then give each token a role (`vmware-audit token create NAME --role reader`, or a role in `roles.yaml` naming tools and targets; vmware-policy ≥ 1.24.0). A role limits what the token may call on this endpoint; it cannot grant more than the account has. See vmware-policy's README, "Roles for network callers".
+
+**Offer only read tools, plus the writes you choose:**
+
+```bash
+vmware-aria mcp --expose read --allow-write acknowledge_alert
+# or: VMWARE_ARIA_MCP_EXPOSE=read VMWARE_ARIA_MCP_ALLOW_WRITE=acknowledge_alert vmware-aria mcp
+```
+
+Tools not offered do not appear in the client's tool list. A bad value or an unknown write tool stops the server
+(exit 2). This limits what clients are offered; it is not authorization, so the account itself should be
+least-privilege.
+
+Details: `skills/vmware-aria/references/setup-guide.md` ("Serving MCP over HTTPS", "Limiting which tools are offered").
+
 ## License
 
 MIT — see [LICENSE](LICENSE)

{vmware_aria-2.2.0 → vmware_aria-2.4.0}/RELEASE_NOTES.md

@@ -1,3 +1,35 @@
+## v2.4.0 — roles for network callers (HLD §18)
+
+* Declares the role metadata vmware-policy ≥ 1.24.0 needs to apply **roles** to this server over HTTPS
+  (HLD §18): how a missing target resolves, and that `get_api_path` escapes a role (it reads any indexed API path, account and credential listings included). With an older vmware-policy nothing changes. Once an operator runs
+  `vmware-audit roles enable`, a token's role decides which tools and targets it may use here; a refused call is
+  audited as `denied`. See vmware-policy's README, "Roles for network callers".
+* A target-limited role is checked against the same config the connection uses: the copy the server's connection manager loaded on its first connection. Edit `config.yaml` and restart for both to see the change.
+* README and setup guide: one endpoint for several people or roles.
+
+## v2.3.0 — calls run side by side; read-only raw API escape hatch
+
+**Calls no longer wait for each other** (HLD §16 D-13(2), via vmware-policy 1.22.0). When one server serves several
+callers (`--transport https` / `http`), each call now holds its own connection to a target for as long as it runs,
+up to `VMWARE_MCP_POOL_SIZE` (default 2) connections per target. Each connection is a login on Aria Operations with
+its own token, so two calls never share or refresh one token. A call that finds every connection busy waits at most
+300 s, then fails naming the target. The CLI and stdio keep one connection per target, as before.
+
+**Two new read tools for questions no tool answers** (HLD §17 D-18; 44 → 46 tools, 36 read / 10 write):
+
+* `search_api_operations(query, limit=20)` searches the suite-api operation index now shipped in the package
+  (`vmware_aria/api_spec/`: vROps 8.6 and VCF Operations 9.1). It marks which operations are GET and which index
+  documents each. It contacts no appliance.
+* `get_api_path(path, params, target)` issues one `GET` through the target's existing client (token, retry, error
+  messages). The path must match a GET operation in the index; other methods, unindexed paths, `..`, `//`, `?` or `#`
+  in the path, URLs, percent-encoding and non-string params are refused before any request. A 9.x appliance is held to
+  the 9.1 index; on 8.x, or when the version cannot be read, either index is accepted. Strings are sanitized; answers
+  over 30,000 characters of JSON come back `truncated: true` with `original_size` — page with `pageSize`.
+* CLI: `vmware-aria api search <words>` and `vmware-aria api get <path> [--param NAME=VALUE]`, audited under the same
+  tool names.
+
+The account's Aria roles still decide what can be read. Requires `vmware-policy>=1.22.0`.
+
 ## v2.2.0 — serve MCP over HTTPS
 
 `vmware-aria mcp` can now serve the network as well as stdio (HLD §16, via vmware-policy 1.21.0):
@@ -8,6 +40,15 @@ vmware-aria mcp --transport https --host 0.0.0.0 --port 8443 \
     --cert server.pem --key server-key.pem --public-name mcp.example.com
 ```
 
+Connect a client and manage callers (Claude Code shown; any MCP client with streamable HTTP and custom headers works):
+
+```bash
+claude mcp add --transport http vmware-aria https://mcp.example.com:8443/mcp \
+    --header "Authorization: Bearer $VMWARE_MCP_TOKEN"
+vmware-audit token list                  # names only
+vmware-audit token revoke alice          # refused from its next request, no restart
+```
+
 * Every request needs `Authorization: Bearer <token>`; the server will not start without a token, refuses Host or
   Origin values outside `--public-name`, and checks itself (unauthenticated requests must get 401) before it
   binds. `--transport http` binds loopback only, for a TLS-terminating reverse proxy.

{vmware_aria-2.2.0 → vmware_aria-2.4.0}/SECURITY.md

@@ -26,12 +26,14 @@ Do **not** open a public GitHub issue for security vulnerabilities.
 
 ### Read-Heavy Design
 
-34 of 44 MCP tools are read-only. The 10 write operations are limited to:
+36 of 46 MCP tools are read-only. The 10 write operations are limited to:
 - Alert acknowledge, cancel and notes
 - Alert definition create, enable/disable and delete
 - Report generation and deletion
 - Resource maintenance mode start and end
 
+`get_api_path` (raw API escape hatch) issues `GET` only, and only for a path that matches a GET operation in the operation index shipped with the package; other methods, unindexed paths, `..`, `//`, query strings in the path and absolute URLs are refused before any request. Its answer is sanitized and capped at 30,000 characters.
+
 No VM lifecycle, no networking, no storage operations.
 
 ### MCP Confirmation Gate

{vmware_aria-2.2.0 → vmware_aria-2.4.0}/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "vmware-aria",
   "name": "VMware Aria",
-  "description": "VMware Aria Operations: metrics, alerts, capacity, anomaly detection — 44 MCP tools.",
+  "description": "VMware Aria Operations: metrics, alerts, capacity, anomaly detection — 46 MCP tools.",
   "skills": [
     "./skills"
   ],
@@ -11,7 +11,7 @@
       "command": "uvx",
       "args": [
         "--from",
-        "vmware-aria==2.2.0",
+        "vmware-aria==2.4.0",
         "vmware-aria-mcp"
       ]
     }

{vmware_aria-2.2.0 → vmware_aria-2.4.0}/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zw008/vmware-aria",
-  "version": "2.2.0",
-  "description": "VMware Aria Operations: metrics, alerts, capacity, anomaly detection — 44 MCP tools.",
+  "version": "2.4.0",
+  "description": "VMware Aria Operations: metrics, alerts, capacity, anomaly detection — 46 MCP tools.",
   "private": true,
   "license": "MIT",
   "homepage": "https://github.com/vmware-skills/VMware-Aria",

{vmware_aria-2.2.0 → vmware_aria-2.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "vmware-aria"
-version = "2.2.0"
+version = "2.4.0"
 description = "VMware Aria Operations (vRealize Operations) monitoring, alerting, and capacity planning"
 readme = "README.md"
 license = "MIT"
@@ -24,7 +24,7 @@ dependencies = [
     "pyyaml>=6.0,<7.0",
     "python-dotenv>=1.0,<2.0",
     "mcp[cli]>=1.28,<2.0",
-    "vmware-policy>=1.21.0,<2.0",
+    "vmware-policy>=1.22.0,<2.0",
 ]
 
 [project.scripts]

{vmware_aria-2.2.0 → vmware_aria-2.4.0}/server.json

@@ -2,17 +2,17 @@
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.vmware-skills/vmware-aria",
   "title": "VMware Aria Operations",
-  "description": "VMware Aria Operations: metrics, alerts, capacity, anomaly detection — 44 MCP tools.",
+  "description": "VMware Aria Operations: metrics, alerts, capacity, anomaly detection — 46 MCP tools.",
   "repository": {
     "url": "https://github.com/vmware-skills/VMware-Aria",
     "source": "github"
   },
-  "version": "2.2.0",
+  "version": "2.4.0",
   "packages": [
     {
       "registryType": "pypi",
       "identifier": "vmware-aria",
-      "version": "2.2.0",
+      "version": "2.4.0",
       "runtimeHint": "uvx",
       "packageArguments": [
         {

{vmware_aria-2.2.0 → vmware_aria-2.4.0}/skills/vmware-aria/SKILL.md

@@ -15,7 +15,7 @@ metadata: {"openclaw":{"requires":{"anyBins":["vmware-aria","uvx"]},"optional":{
 compatibility: >
   vmware-policy auto-installed as Python dependency (provides @vmware_tool decorator and audit logging). All write operations audited to ~/.vmware/audit.db.
   Credentials: Each Aria Operations target requires a per-target password env var in ~/.vmware-aria/.env following the pattern VMWARE_ARIA_<TARGET_NAME_UPPER>_PASSWORD. Passwords are never logged or echoed.
-  Read-heavy: 34 of 44 tools are read-only. Write operations limited to alert acknowledge/cancel, alert notes, alert definition management, report management, and resource maintenance start/end.
+  Read-heavy: 36 of 46 tools are read-only. Write operations limited to alert acknowledge/cancel, alert notes, alert definition management, report management, and resource maintenance start/end.
   No webhooks, no outbound network calls, no guest operations. Local only: stdio MCP + Aria Operations REST API (HTTPS 443).
   Transitive dependencies: Only vmware-policy (audit/policy). No post-install scripts or background services.
 ---
@@ -24,7 +24,7 @@ compatibility: >
 
 > **Disclaimer**: This is a community-maintained open-source project and is **not affiliated with, endorsed by, or sponsored by VMware, Inc. or Broadcom Inc.** "VMware" and "Aria" are trademarks of Broadcom. Source code is publicly auditable at [github.com/vmware-skills/VMware-Aria](https://github.com/vmware-skills/VMware-Aria) under the MIT license.
 
-VMware Aria Operations (vRealize Operations 8.x, VCF Operations 9.x) AI-assisted monitoring — 44 MCP tools for resources (metric keys, properties, relationships), alerts (notes, recommendations), alert definitions, capacity planning, anomaly detection, report automation, resource maintenance mode, platform health (Aria node memory, adapter collection), and VCF 9.1 fleet certificates/passwords/domains, diagnostic findings, and real-time PromQL metrics.
+VMware Aria Operations (vRealize Operations 8.x, VCF Operations 9.x) AI-assisted monitoring — 46 MCP tools, by category below.
 
 > **Know the version first**: `vmware-aria health status` (MCP `get_aria_health`) names the product line. Fleet, findings and PromQL exist only on VCF Operations 9.0+ (PromQL uses the 9.1 VODAP service); on 8.x they return a "requires 9.0 or newer" error, not data.
 > **Companion skills**: vmware-monitor (real-time vSphere), vmware-aiops (VM lifecycle), vmware-nsx (networking), vmware-avi (AVI/ALB/AKO), vmware-harden (compliance), vmware-pilot (approval workflows), vmware-policy (audit/policy).
@@ -42,13 +42,14 @@ VMware Aria Operations (vRealize Operations 8.x, VCF Operations 9.x) AI-assisted
 | **Health** | Aria platform health, collector group status, Aria node memory/swap/heap, adapter collection state | 4 |
 | **Maintenance** | start / end resource maintenance, list maintenance schedules | 3 |
 | **Fleet / PromQL** (VCF Ops 9.1) | fleet certificates, password accounts, VCF domains, diagnostic findings, real-time PromQL query | 5 |
+| **Raw API** | search the API operation index; GET one indexed path (read-only escape hatch) | 2 |
 
-**Total**: 44 tools (34 read-only + 10 write)
+**Total**: 46 tools (36 read-only + 10 write)
 
 ## Quick Install
 
 ```bash
-uv tool install vmware-aria==2.2.0
+uv tool install vmware-aria==2.4.0
 vmware-aria init      # guided setup: writes config + .env (chmod 600, password grep-safe), then verifies
 vmware-aria doctor
 ```
@@ -61,6 +62,7 @@ vmware-aria doctor
 - **Capacity**: cluster headroom, time until full, VM rightsizing
 - **Reports**: generate, poll, download and delete reports
 - **Maintenance**: put a resource in maintenance before planned work (timed or until ended), end it, list maintenance schedules
+- **Anything else the API reads**: when no tool answers, `search_api_operations` then one `get_api_path` (GET of an indexed path only)
 - **Platform**: is Aria Operations itself healthy (DEGRADED vs DOWN, which service), which version and product line, collector groups, whether the Aria node is short of memory, which adapter stopped collecting
 
 For VM changes, NSX, vSphere alarms, storage or load balancing, route with the table below.
@@ -83,7 +85,7 @@ For VM changes, NSX, vSphere alarms, storage or load balancing, route with the t
 
 > **Troubleshooting paths**: step-by-step playbooks for a DEGRADED platform, alert triage, VM contention, empty metrics, pre-resize checks and planned maintenance — [`references/ops-playbooks.md`](references/ops-playbooks.md).
 >
-> **Diagnostic investigations**: Before running any "why is X slow / failing / down" workflow, follow [`references/investigation-protocol.md`](references/investigation-protocol.md). It enforces the four root-cause completeness criteria (falsifiability / sufficiency / necessity / mechanism) and the up-to-three-rounds deepening loop. Stopping at a partial conclusion is an anti-pattern — always self-check against the criteria before outputting a report.
+> **Diagnostic investigations**: before any "why is X slow / failing / down" report, follow [`references/investigation-protocol.md`](references/investigation-protocol.md) — four root-cause criteria and up to three deepening rounds; never stop at a partial conclusion.
 
 ### Daily VM Health Check (Proactive Ops)
 
@@ -110,7 +112,7 @@ For VM changes, NSX, vSphere alarms, storage or load balancing, route with the t
 
 ### Post-Incident: Create Detection Alert (RCA Follow-up)
 
-After resolving an incident, create an early-warning alert to prevent recurrence. Alert definition management is **MCP-only** (no CLI subcommands):
+After an incident, create an early-warning alert. Alert definition management is **MCP-only**:
 
 1. Find matching symptom definitions → MCP `list_symptom_definitions` (filter by `name_filter` / `resource_kind`)
 2. Create alert definition referencing symptoms → MCP `create_alert_definition` with name, resource_kind, symptom_definition_ids, criticality (any one symptom firing triggers the alert)
@@ -137,7 +139,7 @@ Running vmware-aria with a local or small model? See [`references/agent-guardrai
 
 Every command accepts `--target <name>` (every MCP tool `target`) to pick the Aria Operations instance.
 
-## MCP Tools (44 — 34 read, 10 write)
+## MCP Tools (46 — 36 read, 10 write)
 
 All MCP tools accept an optional `target`. The six destructive writes take `confirm`: without `confirm=true` they return a `blast_radius` and change nothing — show it to the user first.
 
@@ -187,8 +189,10 @@ All MCP tools accept an optional `target`. The six destructive writes take `conf
 | | `list_fleet_domains` | Read | SDDC/workload domains behind one registered VCF integration |
 | | `list_findings` | Read | Operations diagnostic findings (not compliance — see vmware-harden) |
 | | `promql_query` | Read | Real-time PromQL instant query via the VODAP service (base path INFERRED, unverified on real hardware) |
+| Raw API | `search_api_operations` | Read | Search the shipped 8.6 / 9.1 operation index; marks GET operations |
+| | `get_api_path` | Read | GET one indexed path (`{id}` filled in, query in `params`); sanitized, capped at 30,000 chars (`truncated`) |
 
-**Read/write split**: 34 read-only, 10 write. All write operations are audit-logged to `~/.vmware/audit.db` (via vmware-policy).
+**Read/write split**: 36 read-only, 10 write. All write operations are audit-logged to `~/.vmware/audit.db` (via vmware-policy).
 
 ### List results are envelopes — read `truncated` before you summarise
 
@@ -218,9 +222,7 @@ vmware-aria alert notes <alert-id>
 vmware-aria alert note-add <alert-id> "Taking this: rebooting esx-03"
 vmware-aria alert recommendations <alert-id>
 
-# Alert Definitions: creation/enable/disable/delete and symptom-definition
-# lookup are MCP-only tools (list_symptom_definitions, create_alert_definition,
-# set_alert_definition_state, delete_alert_definition) — no CLI subcommands.
+# Alert definitions and symptom lookup are MCP-only (no CLI subcommands).
 
 # Capacity
 vmware-aria capacity overview <cluster-id>
@@ -250,6 +252,10 @@ vmware-aria maintenance start <resource-id> --duration 60   # neither --duration
 vmware-aria maintenance end <resource-id>
 vmware-aria maintenance schedules [--resource-id <id>]
 
+# Raw API (read-only: GET of an indexed path only)
+vmware-aria api search "resource properties" [--limit 20]
+vmware-aria api get /api/resources/<id>/properties [--param pageSize=20]
+
 # Diagnostics
 vmware-aria doctor [--skip-auth]
 ```
@@ -277,14 +283,14 @@ VirtualMachine keys and units as defined on Aria Operations 8.18.7; other resour
 
 ### "Token not found" error after setup
 
-The token acquisition request failed. Verify:
+Token acquisition failed. Verify:
 1. Aria Ops is reachable: `vmware-aria doctor`
 2. The `auth_source` in config matches your environment (LOCAL, LDAP, AD)
 3. The password env var follows the naming convention: `VMWARE_ARIA_<TARGET>_PASSWORD`
 
 ### Resources appear missing from list_resources
 
-The collector agent may be offline. Check `list_collector_groups` for any collectors in a DOWN state. Restart the affected collector from the Aria Ops UI under Administration > Collector Groups.
+A collector may be offline: `list_collector_groups` shows DOWN ones. Restart it in the Aria Ops UI (Administration > Collector Groups).
 
 ### Metrics return empty data
 
@@ -296,11 +302,11 @@ The node flag is OFFLINE whenever any one service is not running. Read `assessme
 
 ### "Password not found" error
 
-Variable names follow the pattern `VMWARE_ARIA_<TARGET_NAME_UPPER>_PASSWORD` where hyphens become underscores. Example: target `prod` needs `VMWARE_ARIA_PROD_PASSWORD`. Check your `~/.vmware-aria/.env` file.
+Set `VMWARE_ARIA_<TARGET_NAME_UPPER>_PASSWORD` (hyphens become underscores; target `prod` → `VMWARE_ARIA_PROD_PASSWORD`) in `~/.vmware-aria/.env`.
 
 ### `invalid peer certificate: UnknownIssuer` when running uvx (corporate TLS proxy)
 
-`uvx` re-resolves dependencies from PyPI on every launch. Behind a corporate TLS-intercepting proxy whose CA is not in uv's bundled cert store, the handshake fails. Use the v1.5.15+ recommended single-command form `vmware-aria mcp` (after `uv tool install vmware-aria==2.2.0` — no network on launch), or set `UV_NATIVE_TLS=true` to make uv use the system cert store.
+`uvx` re-resolves from PyPI on every launch, and a TLS-intercepting proxy breaks that. Run `vmware-aria mcp` after `uv tool install vmware-aria==2.4.0` (no network on launch), or set `UV_NATIVE_TLS=true` to use the system cert store.
 
 ## Audit & Safety