vcf-automation-mcp 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+All notable changes to `vcf-automation-mcp`. Newest first.
+
+## 0.3.0 — 2026-11-14
+
+### Added
+- `eventbroker_list_subscriptions` (`GET /event-broker/api/subscriptions`) and `eventbroker_create_or_update_subscription` (`POST /event-broker/api/subscriptions`). The Event Broker spec published for VCF Automation 9 only has get-by-ID and delete for subscriptions, so these two come from a hand-written supplement spec, `specs/Event Broker - Subscriptions (extra).json`, using the same endpoints as Aria Automation 8.x that the VCF Automation UI calls. Their tool descriptions say they're outside the published spec.
+- This changelog.
+
+### Changed
+- 698 operation tools (was 696); `eventbroker` has 9 (was 7).
+
+## 0.2.1 — 2026-11-02
+
+### Fixed
+- Object-typed query parameters are now exploded per the OpenAPI form/explode default (`page=0&size=5&sort=...`). Before this they were sent as JSON text, so paging and sorting on `/vro/workflows` were ignored. Found in the first live lab test.
+
+### Docs
+- Quick start rewritten from the first real `setup` run: global install step, tested admin roles, the HTTP 500 "Unable to find the following role(s)" error, Windows notes.
+
+## 0.2.0 — 2026-10-31
+
+### Changed
+- Login now works the same way as vcf-orchestrator-mcp:
+  - The `vcf-automation-mcp setup` command creates a service account (session login, register, device authorization, grant, device-code token).
+  - It also checks API access per automation service.
+  - Auth modes are `api-token`, `token`, `vcfa-cloudapi`, `vcfa` and `auto`.
+- Rotated refresh tokens are saved to `~/.vcf-automation-mcp/tokens.json` (0600, written atomically), and `client_id` is sent with each refresh, so restarts no longer fail with `invalid_grant`.
+- Session login tries `/cloudapi`, then `/tm/cloudapi`, with several Accept versions, and stops at the first 401 so a wrong password counts once towards the account lockout.
+- All HTTP calls use undici `request()` instead of `fetch()`, because VCF Automation's session login rejects fetch's browser headers.
+
+## 0.1.0 — 2026-10-31
+
+### Added
+- First release:
+  - One MCP tool per REST operation, generated from the VCF Automation 9 VM Apps org OpenAPI specs: 696 tools across 16 services.
+  - Helper tools `vcfa_connection_status` and `vcfa_describe_operation`.
+  - Read-only switch, plus service and tool filters.

package/README.md

@@ -2,7 +2,7 @@
 
 ![vcf-automation-mcp](.github/social-preview.png)
 
-MCP server for **VCF Automation 9** (VM Apps organization). Every REST operation in the VCF Automation API set becomes one MCP tool: **696 operation tools** across 16 services, generated straight from the OpenAPI specs that VCF Automation serves at `https://<vcfa>/tenant/<org>/api-docs`.
+MCP server for **VCF Automation 9** (VM Apps organization). Every REST operation in the VCF Automation API set becomes one MCP tool: **698 operation tools** across 16 services: 696 generated straight from the OpenAPI specs that VCF Automation serves at `https://<vcfa>/tenant/<org>/api-docs`, plus 2 Event Broker subscription calls those specs leave out (see [Event Broker subscriptions](#event-broker-subscriptions)).
 
 Sister project of [vcf-orchestrator-mcp](https://github.com/imtrinity94/vcf-orchestrator-mcp).
 
@@ -19,7 +19,7 @@ Sister project of [vcf-orchestrator-mcp](https://github.com/imtrinity94/vcf-orch
 | `policy` | 9 | Policies and policy types |
 | `form` | 42 | Custom Forms |
 | `content` | 11 | Content Gateway (content sources, source control) |
-| `eventbroker` | 7 | Event Broker: events, topics, audit, subscriptions |
+| `eventbroker` | 9 | Event Broker: events, topics, audit, subscriptions (list, create/update, get, delete) |
 | `iaas` | 265 | Provisioning Service (IaaS): cloud accounts, zones, mappings, networks, storage, machines |
 | `identity` | 53 | Identity Service (`/csp/gateway/am/api`) |
 | `onboarding` | 27 | Onboarding (relocation) plans, resources, deployments |
@@ -40,13 +40,30 @@ There are also two helper tools:
 
 Login works the same way as [vcf-orchestrator-mcp](https://github.com/imtrinity94/vcf-orchestrator-mcp). A one-time `setup` creates a VCF Automation **service account** and stores its refresh token on your machine. After that the server keeps its own login alive, so no token or password goes into your MCP config.
 
-### 1. Run setup once
+### 1. Install globally
 
 ```bash
 npm i -g vcf-automation-mcp
-vcf-automation-mcp setup --url "https://auto.vmw.lab" --org "vmapps-org" --user "<local-admin>" --name "Lab-VCFA-MCP" --role "Organization Owner" --insecure
 ```
 
+The MCP config below runs the `vcf-automation-mcp` command, so the global install is required. If you only run setup with `npx`, there's no command for the client to start and Claude Desktop shows **"vcf-automation couldn't start. Its command wasn't found."**
+
+### 2. Run setup once
+
+```bash
+vcf-automation-mcp setup --url "https://auto.vmw.lab" --org "vmapps-org" --user "admin" --name "Lab-VCFA-MCP" --role "Service Broker Administrator,Orchestrator Administrator,Assembler Administrator" --insecure
+```
+
+This exact command was tested end to end against a VCF Automation 9 VM Apps org (Windows 11, Claude Desktop).
+
+**Role names must exist in your org exactly as typed.** Each name becomes a `urn:vcloud:role:<name>` scope. A name the org doesn't have fails registration with HTTP 500, for example:
+
+```
+Registering service account failed: HTTP 500 ... Unable to find the following role(s) in org <id>: [Organization Administrator].
+```
+
+The error names only the roles it couldn't find, so drop or rename those and run setup again (the failed run creates nothing, so you can reuse the same `--name`). Role names vary per org: check **Access Control > Roles** in the tenant UI, or the role list in setup's first line (`1/5 Logged in as admin@vmapps-org (..., role ...)`). Leave `--role` out to copy the role of the user you log in with.
+
 Setup asks for the password with a masked prompt. It uses it once to log in and never stores it. Then it:
 
 1. Logs in as `user@org` at `/cloudapi/1.0.0/sessions`.
@@ -70,7 +87,7 @@ It saves the refresh token to `~/.vcf-automation-mcp/tokens.json` (on Windows, `
 
 > If the access check shows **403** for an API, the service account's role doesn't cover it. Give it a broader role (e.g. Organization Owner), then restart your MCP client.
 
-### 2. Add it to your MCP client
+### 3. Add it to your MCP client
 
 ```json
 {
@@ -89,7 +106,19 @@ It saves the refresh token to `~/.vcf-automation-mcp/tokens.json` (on Windows, `
 }
 ```
 
-The config file is at `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS and `%APPDATA%\Claude\claude_desktop_config.json` on Windows.
+The config file is at `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS and `%APPDATA%\Claude\claude_desktop_config.json` on Windows. After editing it, quit Claude Desktop completely (on Windows, from the system tray) and reopen it.
+
+**Windows: if the command still isn't found** after the global install, Claude Desktop isn't seeing the npm folder on its PATH. Run `where vcf-automation-mcp` and put the full path in `command`, with doubled backslashes:
+
+```json
+"command": "C:\\Users\\<you>\\AppData\\Roaming\\npm\\vcf-automation-mcp.cmd"
+```
+
+Without a global install, `"command": "cmd"` with `"args": ["/c", "npx", "-y", "vcf-automation-mcp"]` also works, but it's slower to start.
+
+### 4. Check the connection
+
+Ask your client to run `vcfa_connection_status` with `test: true`. A working setup shows `"modeInUse": "api-token"`, the token file under your home folder, and `GET /iaas/api/about -> HTTP 200 OK`. On VCF Automation 9 the token endpoint resolves to `/tm/oauth/tenant/<org>/token`. With the `VCFA_SERVICES` list above, 184 of the 698 tools load.
 
 ## Configuration
 
@@ -136,6 +165,19 @@ Access tokens are renewed a minute before they expire, and once more after a `40
 - OData parameters drop the `$` because MCP clients reject `$` in argument names: `$top` becomes `top`, and likewise `skip`, `filter`, `select`, `orderby`, `count`.
 - Many automation endpoints take an optional `apiVersion` query parameter.
 
+## Event Broker subscriptions
+
+The Event Broker spec published for VCF Automation 9 VM Apps orgs has only two subscription operations: get one by ID, and delete. It has no way to list or create subscriptions, although the VCF Automation UI does both. The UI uses the same endpoints as Aria Automation 8.x, so this server adds them from a small hand-written supplement (`specs/Event Broker - Subscriptions (extra).json`):
+
+| Tool | Request |
+|---|---|
+| `eventbroker_list_subscriptions` | `GET /event-broker/api/subscriptions` with `page`, `size`, `filter` (e.g. `type eq 'RUNNABLE'`) |
+| `eventbroker_create_or_update_subscription` | `POST /event-broker/api/subscriptions`. Omit `id` to create; send an existing `id` to update |
+
+A workflow subscription needs `name`, `eventTopicId` (from `eventbroker_get_all_event_topics`), `type: "RUNNABLE"`, `runnableType: "extensibility.vro"` and `runnableId` (the workflow ID). For an ABX action, use `runnableType: "extensibility.abx"` with the action ID. Optional fields are `blocking`, `timeout`, `priority`, `criteria`, `constraints.projectId` and `disabled`.
+
+Because these two calls aren't in Broadcom's published API, their tool descriptions say so, and a future VCF Automation release could change them.
+
 ## Development
 
 ```bash