mcp-vcf-orchestrator

# MCP Server for VCF Automation Orchestrator [](https://www.npmjs.com/package/@mgovedarov/mcp-vcf-orchestrator) [](https://www.apache.org/licenses/LICENSE-2.0) An [MCP](https://modelcontextprotocol.io/) server that exposes VCF Automation Orchestrator (vRO), Service Broker, and Cloud Assembly REST API operations as tools. It helps AI assistants list, inspect, run, create, export, preflight, diff, import, and delete VCFA/vRO automation assets through discovery-first workflows. Supports **VCF 9 Automation** and **Aria Automation 8.x**. ## Documentation Full documentation is available in the GitHub Pages site: - Published site: <https://mgovedarov.github.io/mcp-vcf-orchestrator/> - Local docs entry point: [docs/index.md](docs/index.md) - vRO artifact authoring notes: [docs/vro-artifact-authoring.md](docs/vro-artifact-authoring.md) - Security policy and vulnerability reporting: [SECURITY.md](SECURITY.md) The docs include installation, configuration, MCP client setup, tool references, resources/prompts, how-tos, artifact lifecycle guidance, safety notes, troubleshooting, and contributor guidance. Checked examples for common workflows are available in [examples/README.md](examples/README.md). These examples are validated against the registered tool and prompt names so stale snippets are caught during development. ## Quick Start Run directly from npm: The package is published on npm as [`@mgovedarov/mcp-vcf-orchestrator`](https://www.npmjs.com/package/@mgovedarov/mcp-vcf-orchestrator). ```bash npx @mgovedarov/mcp-vcf-orchestrator ``` Or install globally: ```bash npm install -g @mgovedarov/mcp-vcf-orchestrator mcp-vcf-orchestrator ``` Run from source: ```bash git clone https://github.com/mgovedarov/mcp-vcf-orchestrator.git cd mcp-vcf-orchestrator npm install npm run build ``` ## Claude Code Plugin A [Claude Code](https://claude.ai/code) plugin in this repository bundles two skills (`vcfa-authoring` and `vcfa-operations`) that auto-activate and route to the server's `vcfa-*` prompts and tools with discovery-first, confirm-before-write safety. Install it from a Claude Code session: ```text /plugin marketplace add mgovedarov/mcp-vcf-orchestrator /plugin install vcfa-orchestrator@mcp-vcf-orchestrator ``` The plugin contains skills only; configure the MCP server separately. See [docs/guide/claude-code-plugin.md](docs/guide/claude-code-plugin.md). ## License And Branding This project is licensed under the [Apache License 2.0](LICENSE). Attribution notices are provided in [NOTICE](NOTICE). Forks and derivatives should preserve the required license and attribution notices. Redistributed packages must not use the `@mgovedarov` npm scope or imply that they are the official `@mgovedarov/mcp-vcf-orchestrator` package or repository. ## Configuration Required environment variables: | Variable | Description | | --- | --- | | `VCFA_HOST` | VCF Automation hostname or `host:port`, for example `vcfa.example.com`. A value carrying a URL scheme is rejected at startup. | | `VCFA_USERNAME` | Username without organization, for example `admin`. | | `VCFA_ORGANIZATION` | Organization name (the tenant URL slug, not the display name), or `system` for provider/system administrator logins, which are routed to `/cloudapi/1.0.0/sessions/provider`. A provider session cannot read the tenant-scoped Automation services; use a tenant organization for the catalog, deployment, template, subscription, and project tools. In `vra8` mode this is the vIDM domain shown on the Workspace ONE login page, for example `System Domain` for local users. | | `VCFA_PASSWORD` | Password for the VCF Cloud API session, or the vIDM password used for the vRA 8 login when `VCFA_TARGET_PLATFORM=vra8`. | Useful optional variables: | Variable | Description | | --- | --- | | `VCFA_TARGET_PLATFORM` | Target platform mode. Defaults to `vcfa`, which uses the VCF Cloud API session flow and auto-negotiates the API version (`9.1.0` preferred, then `9.0.0`) via the unauthenticated `GET /api/versions` discovery document. Set to `vcfa9.1` or `vcfa9.0` to pin the VCF Cloud API version and skip the probe. Set to `vra8` for vRA/vRO 8.12+. That mode authenticates with the vRA 8 bearer-token flow: a vIDM login at `POST /csp/gateway/am/api/login?access_token` with `VCFA_ORGANIZATION` as the domain, a refresh-token exchange at `POST /iaas/api/login`, and `Authorization: Bearer` on every `/vco/api` request. That mode supports the full vRO `/vco/api` surface plus Automation-service reads (catalog, deployments, templates, projects, subscriptions, event topics) and the Automation-service writes: `create-template`, `delete-template`, the subscription create/update/delete tools, and — verified on vRA 8.18 under VCFO-088 — `create-deployment`, `delete-deployment` and `run-deployment-action`. `export-configuration-file` is unsupported there. That refusal is pre-emptive rather than platform-specific: no vRO tested, on either platform, serves a single configuration element as a `.vsoconf`, so a `406` from any other platform is reported with the same guidance. See [Configuration](docs/guide/configuration.md) for the per-service detail. | | `VCFA_VRO_HOST` | Optional `host[:port]` of an external vRO appliance. Only the vRO `/vco/api` requests go there; the login, the `GET /api/versions` probe, and the Automation services stay on `VCFA_HOST`, and the token issued there is reused as-is. Leave unset for the embedded vRO. Works with `vcfa`, `vcfa9.x`, and `vra8`. See [Configuration](docs/guide/configuration.md#external-vro-appliance). | | `VCFA_IGNORE_TLS` | Set to `true` to skip TLS certificate verification for this server's requests to the VCFA host and, when `VCFA_VRO_HOST` is set, the vRO host (lab environments only). | | `VCFA_ARTIFACT_DIR` | Root directory for local artifact files. Defaults to `artifacts/` in the MCP server process working directory, typically the open project. | | `VCFA_PACKAGE_DIR` | Override package artifact directory. | | `VCFA_RESOURCE_DIR` | Override resource artifact directory. | | `VCFA_WORKFLOW_DIR` | Override workflow artifact directory. | | `VCFA_EXECUTION_LOG_DIR` | Override workflow execution log export directory. | | `VCFA_ACTION_DIR` | Override action artifact directory. | | `VCFA_CONFIGURATION_DIR` | Override configuration artifact directory. | | `VCFA_CONTEXT_DIR` | Override persisted context snapshot directory. If unset, context snapshots prefer the MCP client's current workspace root at `artifacts/context/`, falling back to `VCFA_ARTIFACT_DIR/context`. | | `VCFA_PROJECT_PACKAGE_NAME` | Stable fully-qualified vRO package name reused by package-first project workflows, for example `com.example.project`. | | `VCFA_PROJECT_PACKAGE_DESCRIPTION` | Optional description used only when the exact project package is explicitly created. | ## Tool Coverage The server includes tools for: - Workflows, recursive workflow category/folder listing, workflow executions, inline/exported execution syslogs, workflow artifact scaffold/preflight/diff/import/export - Actions and action artifact import/export/preflight/diff - Configuration elements and resource elements - vRO packages and plugins, including package-first project package reuse - Categories - Cloud Assembly projects (read-only discovery of project IDs) - Service Broker catalog items and deployments - Deployment day-2 actions - Cloud Assembly blueprint templates - Event topics and extensibility subscriptions - Artifact promotion planning - Persisted Markdown/JSON context snapshots for future agents - MCP resources and prompts for discovery-first implementation work See the [tool reference](docs/reference/tools.md) for the full list. The source and reference docs are kept in sync by `npm run validate:docs`, which compares registered tools, prompts, and resources against the documentation and checks documented examples for stale tool names or top-level arguments. ## Prompt Examples Discover what is reusable before building: ```text Use prompt vcfa-discover-capabilities with: goal: "Map reusable VM provisioning workflows, actions, templates, catalog items, and subscriptions." ``` Persist environment context for future agents: ```text Use prompt vcfa-collect-context-snapshot with: goal: "Persist reusable VM provisioning context before implementation work." includeOptionalDomains: true ``` Persist VMware built-in workflow and action baseline context: ```text Use prompt vcfa-collect-context-snapshot with: goal: "Persist VMware built-in workflow and action baseline context." profile: vcfaBuiltIns ``` Author a real importable workflow artifact: ```text Use prompt vcfa-author-workflow with: goal: "Build a workflow that accepts a project name and returns matching VM names." categoryHint: "VCFA" ``` Wrap an existing vRO action as a workflow: ```text Use prompt vcfa-build-workflow-from-action with: actionHint: "getAllMachines" workflowGoal: "Expose machine inventory lookup as a workflow." categoryHint: "VCFA" ``` ## Common Tool Examples Collect a broader environment snapshot when the default item limit may skip relevant objects: ```text collect-context-snapshot(fileBaseName: "vcfa-context-full", includeOptionalDomains: true, maxItemsPerDomain: 600, overwrite: true) ``` Plan an implementation from verified discovery before authoring artifacts: ```text Use prompt vcfa-discovery-first-implementation-plan with: goal: "Create a workflow that lists VMs by project name." artifactKinds: "workflows and actions" ``` Prepare a safe workflow replacement with preflight, diff, and a live backup before importing: ```text prepare-artifact-promotion(kind: "workflow", fileName: "echo-message.workflow", target: { categoryId: "<workflow-category-id>", workflowId: "<live-workflow-id>" }, backup: { enabled: true, fileName: "echo-message-backup.workflow", overwrite: false }, overwrite: true) ``` Run a workflow with input validation, then export execution logs for troubleshooting: ```text get-workflow(id: "<workflow-id>") run-workflow-and-wait(id: "<workflow-id>", inputs: [{ name: "message", value: "hello" }], timeoutSeconds: 60, pollIntervalSeconds: 2, confirm: true) list-workflow-executions(workflowId: "<workflow-id>", maxResults: 5) get-workflow-execution-logs(workflowId: "<workflow-id>", executionId: "<execution-id>", fileName: "execution-logs.json", level: "info", format: "json", maxResult: 200, overwrite: true) ``` Publish reusable project content through the stable project package: ```text ensure-project-package(packageName: "com.example.project") add-workflow-to-project-package(packageName: "com.example.project", workflowId: "<workflow-id>", confirm: true) rebuild-project-package(packageName: "com.example.project", confirm: true) export-project-package(packageName: "com.example.project", fileName: "com.example.project.package", overwrite: true) get-project-package-import-details(packageName: "com.example.project", fileName: "com.example.project.package") ``` ## Development ```bash # Type-check and build npm run build # Run tests npm test # Run the full local validation gate npm run validate # Check docs/examples drift only npm run validate:docs # Run in dev mode VCFA_HOST=... VCFA_USERNAME=... VCFA_ORGANIZATION=... VCFA_PASSWORD=... npm start # Build documentation npm run docs:build # Preview documentation locally npm run docs:dev ``` `npm run validate` builds the project, runs unit tests, enforces conservative coverage thresholds, validates docs/examples drift, builds the VitePress docs, and dry-runs npm packaging with package-content checks. ## Safety Use read-only discovery tools before live writes. Create, update, import, delete, run, and deployment day-2 action operations require explicit confirmation (`confirm: true`). Local artifact export and snapshot tools write files under configured artifact directories, are not advertised as read-only, and reject unsafe paths. They do not require confirmation; `overwrite` defaults to `false`. Live VCFA validation should be run separately from local validation. Read-only list/get smoke checks are appropriate for sandbox environments; write, import, delete, and day-2 action tests should use disposable assets and explicit confirmation.