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

{vmware_aria-2.2.0 → vmware_aria-2.3.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.3.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.3.0}/.mcp.json

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: vmware-aria
-Version: 2.2.0
+Version: 2.3.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,65 @@ 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.
+- 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.
+
+**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.3.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,63 @@ 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` 头。
+- 审计日志把每个调用者记为 `token:<名字>`。调用并行执行：每个调用独占一个到 target 的会话，每个 target 最多
+  `VMWARE_MCP_POOL_SIZE`（默认 2）个会话。每个会话都是在 target 上的一次登录；调用最多等待 300 秒拿到空闲会话。
+- **能连到这个端点的人，都以该 server 配置的账号操作。** token 只用来识别调用者，不在平台上授予任何权限。
+  每个权限级别单独起一个端点。
+
+**只提供读工具，加上你选定的写工具：**
+
+```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.3.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,65 @@ 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.
+- 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.
+
+**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.3.0}/RELEASE_NOTES.md

@@ -1,3 +1,26 @@
+## 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 +31,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.3.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.3.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.3.0",
         "vmware-aria-mcp"
       ]
     }

{vmware_aria-2.2.0 → vmware_aria-2.3.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.3.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.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "vmware-aria"
-version = "2.2.0"
+version = "2.3.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.3.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.3.0",
   "packages": [
     {
       "registryType": "pypi",
       "identifier": "vmware-aria",
-      "version": "2.2.0",
+      "version": "2.3.0",
       "runtimeHint": "uvx",
       "packageArguments": [
         {

{vmware_aria-2.2.0 → vmware_aria-2.3.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.3.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.3.0` (no network on launch), or set `UV_NATIVE_TLS=true` to use the system cert store.
 
 ## Audit & Safety
 

{vmware_aria-2.2.0 → vmware_aria-2.3.0}/skills/vmware-aria/references/capabilities.md

@@ -2,11 +2,11 @@
 
 ## Automation Level Reference
 
-Each operation is classified by autonomy level per the Enterprise Harness Engineering framework. **vmware-aria is heavily L1/L2 (34 read / 10 write)** — primarily a monitoring and analysis skill.
+Each operation is classified by autonomy level per the Enterprise Harness Engineering framework. **vmware-aria is heavily L1/L2 (36 read / 10 write)** — primarily a monitoring and analysis skill.
 
 | Level | Meaning | Agent autonomy | Examples in this skill |
 |:-:|---|---|---|
-| **L1** | Read-only, raw data | Always auto-run | `list_resources`, `get_resource`, `get_resource_metrics`, `list_metric_keys`, `get_resource_properties`, `get_resource_relationships`, `list_alerts`, `get_alert`, `list_alert_definitions`, `list_alert_notes`, `list_maintenance_schedules`, `get_aria_node_resources`, `list_adapters`, capacity / badge queries |
+| **L1** | Read-only, raw data | Always auto-run | `list_resources`, `get_resource`, `get_resource_metrics`, `list_metric_keys`, `get_resource_properties`, `get_resource_relationships`, `list_alerts`, `get_alert`, `list_alert_definitions`, `list_alert_notes`, `list_maintenance_schedules`, `get_aria_node_resources`, `list_adapters`, `search_api_operations`, `get_api_path`, capacity / badge queries |
 | **L2** | Read + analysis / recommendation | Always auto-run | `investigate_alert` (alert → confirmed affected resource), `get_alert_recommendations` (alert → definition state → prioritized recommendations), anomaly counts, top-N consumer ranking, capacity trend forecasting, rightsizing recommendations |
 | **L3** | Single write — user must approve | Only after explicit confirmation | `acknowledge_alert` (via takeownership action), `cancel_alert`, `create_alert_definition`, `set_alert_definition_state`, `delete_alert_definition`, `generate_report`, `delete_report`, `start_resource_maintenance`, `end_resource_maintenance`, `add_alert_note` *(the only writes; all auditable. On MCP, `acknowledge_alert`, `cancel_alert`, `delete_alert_definition`, `delete_report`, `start_resource_maintenance` and `end_resource_maintenance` take `confirm` (default false): without `confirm=true` they return a `blast_radius` — what the call would change — and change nothing; `confirm=true` is refused when a blocker is found or a field the radius depends on could not be read. `confirmed` is a deprecated alias. `add_alert_note` is low risk and has no gate — a note changes neither the alert nor monitoring; the CLI still asks once)* |
 | **L4** | Multi-step plan / apply workflow | *N/A currently* | — *(no multi-step orchestration; Aria is observe/analyze, not configure)* |
@@ -67,6 +67,13 @@ Each operation is classified by autonomy level per the Enterprise Harness Engine
 - **Aria node resources**: `get_aria_node_resources` reads Aria's own self-monitoring objects (`vC-Ops-Node`, `vC-Ops-Watchdog`): per node memory (`mem|total`, `mem|used`, `mem|free`, `mem|actualFree`, `mem|actualUsed`), swap, heap overall and per component, and watchdog restarts per service. Each value has `latest`, `unit` (from Aria's statkey definitions, never assumed) and `window` min / avg / max / points over `window_hours` (1–720, default 24) of 5-minute averages. `memory_pressure.level` is an indicator: HIGH when actual free memory is below 10% of total, ELEVATED below 20%, NORMAL at 20% or more, UNKNOWN when the readings do not settle it. A key with no value is in the node's `missing` list (`not_reported` / `no_data` / `undetermined`), never zeroed; `watchdog_restarts: null` is unknown, not zero. On Aria Operations 8.18.7 after a memory upgrade the node read `mem|total` 15.61 GB (was 7.75), actual free 41%, pressure NORMAL, and 9 watchdog services with 0 restarts
 - **Adapter collection state**: `list_adapters` — each adapter instance's kind, collector, monitoring interval, resources and metrics collected, last collected and last heartbeat with ages in seconds, its own message, and `stale`: true when the last collection is older than max(3 × monitoring interval, 15 minutes), false within that, null when the fields cannot support a verdict (`stale_basis` shows the arithmetic). Ages use the appliance clock from node status when it is available (`reference_clock`). An empty or unrecognised answer is an error, never "no adapters". A recent collection does not prove every object behind the adapter receives data. On Aria Operations 8.18.7 all 6 adapters were not stale
 
+### Raw API (read-only escape hatch)
+
+For a read no tool above covers (HLD §17 D-18). Prefer the dedicated tools: their results are shaped, paginated and explained.
+
+- **`search_api_operations(query, limit=20)`**: searches the suite-api operation index shipped in the package (`vmware_aria/api_spec/`: vROps 8.6, 315 operations; VCF Operations 9.1, 504 operations plus the verified fleet subset). Every word must appear in method, path or summary; path matches rank first, then GET. Each row: `method`, `path` template, `summary`, `indexes` (`8.6` / `9.1`) and `callable_with_get_api_path` (true only for GET). `limit` 1–100. Contacts no appliance. Typical response: ~1,500 tokens at the default limit
+- **`get_api_path(path, params=None, target=None)`**: one `GET` through the target's client (its token, retry and error translation). `path` must match a GET operation of the index with every `{name}` replaced by one segment (letters, digits, space, `- . _ ~ : @ + , =`). Refused before any request: other methods, unindexed paths, `..` / `.` / `//`, `?` or `#` in `path` (use `params`), URLs, percent-encoding, non-string `params`. A 9.x appliance (read from `/versions/current`) is held to the 9.1 index; on 8.x, or when the version cannot be read, a path in either index is accepted — the 8.6 index is the only 8.x specification held and 8.18 answers paths it lacks; a path the appliance does not have returns a 404 error. Every string in the answer is sanitized (control/format characters stripped, cut to 500 characters). Answers over 30,000 characters of JSON (about 8k tokens — one resource or one page of a list fits; an unpaged list, 1,000 rows by default, does not) return `truncated: true`, `original_size` and `body_text` (cut, not valid JSON): page with `params` such as `pageSize`. Audited like every call. The account's Aria roles still decide what it can read. Typical response: 500–8,000 tokens
+
 ---
 
 ## What vmware-aria Cannot Do
@@ -132,6 +139,7 @@ All requests carry `Authorization: vRealizeOpsToken <token>`.
 | `GET /suite-api/api/deployment/node/services/info` | get_aria_health, doctor (per-service health) |
 | `GET /suite-api/api/versions/current` | get_aria_health, doctor "Aria version" row, and the version shown when a 9.0+ tool (list_fleet_*, list_findings, promql_query) is called on an older appliance |
 | `GET /suite-api/api/collectorgroups` + `GET /suite-api/api/collectors` | list_collector_groups (groups carry member IDs; details enriched from /collectors) |
+| Any `GET` in the shipped index (`vmware_aria/api_spec/`) | get_api_path (GET only; path must match an indexed GET operation) |
 
 ---
 
@@ -194,4 +202,4 @@ Reading rules for an agent:
 | Anomaly detection | 7.5+ |
 | Suite API v2 paths used | 8.0+ |
 
-Endpoints are checked against the vROps 8.6 and VCF Operations 9.1 API indexes in `tests/eval/spec/`. Live-verified on Aria Operations 8.18.7 (2026-09): resources, metrics, alerts and symptoms, rightsizing, health, doctor, node resources, adapters, alert recommendations, and reads of maintenance schedules and alert notes (none existed).
+Endpoints are checked against the vROps 8.6 and VCF Operations 9.1 API indexes in `vmware_aria/api_spec/`. Live-verified on Aria Operations 8.18.7 (2026-09): resources, metrics, alerts and symptoms, rightsizing, health, doctor, node resources, adapters, alert recommendations, and reads of maintenance schedules and alert notes (none existed).