wxo-builder-mcp-server 1.0.8

package/CHANGELOG.md

@@ -0,0 +1,66 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [1.0.7] - 2026-02-21
+
+### Fixed
+- **Langflow DataFrame**: Flatten each row to only primitive values (string, number, boolean) so Langflow's "List items must be either all Data objects or all dictionaries" validation passes. Nested objects are JSON-stringified.
+
+## [1.0.6] - 2026-02-21
+
+### Fixed
+- **Langflow compatibility**: Removed `limit` and `offset` from tool input schemas (`list_skills`, `list_agents`, `list_flows`, etc.) to avoid validation errors when Langflow sends empty strings for optional numeric params.
+- **DataFrame compatibility**: Added `toDataFrameSafe()` so tool outputs are normalized to lists of plain objects for Langflow's MCP Tools component.
+
+## [1.0.5] - 2026-02-20
+
+### Added
+- **WO_AGENT_IDs**: Optional env var for a comma-separated list of default agent IDs. When the user omits `agent_id`/`agent_name` in tool calls, the first ID is used. Tools affected: `invoke_agent`, `execute_tool`, `list_agent_tools`, `get_agent`, `get_agent_chat_starter_settings`, `update_agent_chat_starter_settings`, `update_agent`, `update_agent_instructions_from_tools`, `assign_tool_to_agent`, `create_tool_and_assign_to_agent`.
+- **WO_AGENT_ID** (single) remains supported for backwards compatibility.
+
+## [1.0.4] - 2026-02-20
+
+### Added
+- Shebang (`#!/usr/bin/env node`) for correct bin execution via npx
+- Cursor deep link and one-click install in README (shows "WxO Builder MCP Server")
+- MCP Registry and cursor.directory links
+- CHANGELOG.md, CONTRIBUTING.md, and LICENSE links in README
+- Version, date, and author in README
+- Examples: Antigravity, Windsurf configs; `.vscode/mcp.json`, `.cursor/mcp.json`
+- Directory listing copy (cursor.directory) section
+
+### Changed
+- Server name: `io.github.markusvankempen/wxo-builder-mcp-server` (was wxo-builder)
+- server.json description shortened for MCP Registry (≤100 chars)
+- Extension mcpClient: config from `wxo-builder` (was watsonx-orchestrate)
+- README: npx-first config, removed ADK references, troubleshooting section
+
+## [1.0.3] - 2026-02-20
+
+### Added
+- npm package published; shebang fix for npx
+
+## [1.0.2] - 2026-02-20
+
+### Changed
+- Repository URLs point to standalone repo
+- package.json repository, homepage, bugs
+
+## [1.0.1] - 2026-02-19
+
+### Added
+- WxO Builder extension reference and links
+- Distribution options (npm, standalone repo, devkit)
+- .npmignore excludes tests/
+
+### Changed
+- Package name: @markusvankempen/wxo-builder-mcp-server
+
+## [1.0.0] - 2026-02-19
+
+### Added
+- Initial release: tools, agents, connections, flows
+- deploy_tool_from_url, create_tool_and_assign_to_agent
+- Chat starter settings (welcome_message, quick_prompts)
+- Integration tests

package/LICENSE

@@ -0,0 +1,194 @@
+   Watson Orchestrate (WXO) Builder MCP Server (@markusvankempen/wxo-builder-mcp-server)
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+      Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+      stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+      that You distribute, all copyright, patent, trademark, and
+      attribution notices from the Source form of the Work,
+      excluding those notices that do not pertain to any part of
+      the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+      distribution, then any Derivative Works that You distribute must
+      include a readable copy of the attribution notices contained
+      within such NOTICE file, excluding those notices that do not
+      pertain to any part of the Derivative Works, in at least one
+      of the following places: within a NOTICE text file distributed
+      as part of the Derivative Works; within the Source form or
+      documentation, if provided along with the Derivative Works; or,
+      within a display generated by the Derivative Works, if and
+      wherever such third-party notices normally appear. The contents
+      of the NOTICE file are for informational purposes only and
+      do not modify the License. You may add Your own attribution
+      notices within Derivative Works that You distribute, alongside
+      or as an addendum to the NOTICE text from the Work, provided
+      that such additional attribution notices cannot be construed
+      as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 Markus van Kempen <markus.van.kempen@gmail.com>
+
+   SPDX-License-Identifier: Apache-2.0
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,415 @@
+# WXO Builder MCP Server
+
+<p align="center">
+  <img src="resources/icon.svg" alt="WXO Builder MCP Server" width="96" height="96"/>
+</p>
+
+**Version** 1.0.4 · **Author** [Markus van Kempen](mailto:markus.van.kempen@gmail.com) · **Date** 2026-02-20
+
+MCP server for IBM Watson Orchestrate (WXO). Manage tools, agents, connections, flows, and execute tools from Cursor, VS Code Copilot, Claude Desktop, Antigravity, Windsurf, or the WxO Builder extension.
+
+[markusvankempen.github.io](https://markusvankempen.github.io) · [WxO Builder extension](https://marketplace.visualstudio.com/items?itemName=MarkusvanKempen.wxo-builder) · [CONTRIBUTING](CONTRIBUTING.md) · [CHANGELOG](CHANGELOG.md) · [LICENSE](LICENSE)
+
+## Architecture & Data Flow
+
+This package has a **dual role**:
+
+1. **MCP protocol:** It acts as an **MCP server** — your AI environment (Cursor, Claude Desktop, VS Code Copilot, Antigravity, Windsurf, etc.) is the MCP *client* that connects to it and calls tools.
+2. **Watson Orchestrate:** It acts as an **HTTP client** — it makes REST requests to your Watson Orchestrate instance. Watson Orchestrate never connects back to this process.
+
+```
+┌─────────────────────────────────┐     MCP protocol      ┌──────────────────────────┐     HTTP (REST API)     ┌─────────────────────────┐
+│  MCP Client                     │  ◄──────────────────► │  WXO Builder MCP Server │  ───────────────────►  │  Watson Orchestrate     │
+│  (Cursor, Claude Desktop,       │     tool calls        │  (this package)          │     /v1/orchestrate/*  │  instance                │
+│   Copilot, Antigravity, etc.)    │                       │                         │                        │  (your WO cloud/hosted)  │
+└─────────────────────────────────┘                       └──────────────────────────┘                        └─────────────────────────┘
+```
+
+The MCP server exposes tools that proxy operations to Watson Orchestrate. When you invoke a tool (e.g. `list_skills`, `invoke_agent`), the server forwards the request to the Watson Orchestrate API and returns the result.
+
+## Related: WxO Builder Extension + MCP Server – a perfect combo
+
+The **WxO Builder** extension and this **MCP Server** work together to create and administer Watson Orchestrate directly from your IDE. Use the extension for visual editing and the MCP server for AI-powered workflows (Cursor, Claude Desktop, etc.).
+
+| | Link |
+|---|------|
+| **WxO Builder extension** | [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=MarkusvanKempen.wxo-builder) |
+| **Open VSX** | [open-vsx.org/extension/markusvankempen/wxo-builder](https://open-vsx.org/extension/markusvankempen/wxo-builder) |
+| **Author** | [markusvankempen.github.io](https://markusvankempen.github.io) |
+| **MCP Registry** | [registry.modelcontextprotocol.io/?q=wxo-builder-mcp-server](https://registry.modelcontextprotocol.io/?q=wxo-builder-mcp-server) |
+| **Source Code** | [github.com/markusvankempen/wxo-builder-vscode-extension](https://github.com/markusvankempen/wxo-builder-vscode-extension) |
+
+The extension provides visual tool creation, drag-and-drop agent editing, and local/remote testing. The MCP server exposes the same Watson Orchestrate capabilities to AI assistants in Cursor, Claude Desktop, Antigravity, Windsurf, and VS Code Copilot.
+
+### Directory listing copy (cursor.directory, etc.)
+
+**Cursor Deep Link** (use this so the install dialog shows "WxO Builder MCP Server"):
+
+```
+cursor://anysphere.cursor-deeplink/mcp/install?name=WxO%20Builder%20MCP%20Server&config=eyJXeE8gQnVpbGRlciBNQ1AgU2VydmVyIjp7ImNvbW1hbmQiOiJucHgiLCJhcmdzIjpbIi15IiwiQG1hcmt1c3ZhbmtlbXBlbi93eG8tYnVpbGRlci1tY3Atc2VydmVyIl0sImVudiI6eyJXT19BUElfS0VZIjoieW91ci1hcGkta2V5IiwiV09fSU5TVEFOQ0VfVVJMIjoiaHR0cHM6Ly95b3VyLWluc3RhbmNlLm9yY2hlc3RyYXRlLmlibS5jb20ifX19
+```
+
+Config JSON for [Cursor deeplink generator](https://docs.cursor.com/deeplinks):
+
+```json
+{
+  "WxO Builder MCP Server": {
+    "command": "npx",
+    "args": ["-y", "@markusvankempen/wxo-builder-mcp-server"],
+    "env": {
+      "WO_API_KEY": "your-api-key",
+      "WO_INSTANCE_URL": "https://your-instance.orchestrate.ibm.com",
+      "WO_AGENT_IDs": "agent-id-1,agent-id-2"
+    }
+  }
+}
+```
+
+When `WO_AGENT_IDs` (comma-separated list) or `WO_AGENT_ID` is set, agent-based tools use the first ID as default when the user does not specify an agent.
+
+**Short description (≤100 chars):**
+
+> Manage Watson Orchestrate tools, agents, connections. Pair with [WxO Builder extension](https://marketplace.visualstudio.com/items?itemName=MarkusvanKempen.wxo-builder).
+
+**Longer description:**
+
+> Manage IBM Watson Orchestrate (WXO) tools, agents, connections, and flows from Cursor, Copilot, or Claude. Best used with the [WxO Builder VS Code extension](https://marketplace.visualstudio.com/items?itemName=MarkusvanKempen.wxo-builder) for a full IDE experience: visual tool creation, drag-and-drop agents, and local/remote testing.
+
+---
+
+**Distribution options:**
+
+- **npm** – Install `@markusvankempen/wxo-builder-mcp-server` (recommended)
+- **MCP Registry** – [registry.modelcontextprotocol.io/?q=wxo-builder-mcp-server](https://registry.modelcontextprotocol.io/?q=wxo-builder-mcp-server)
+- **Standalone repo** – [github.com/markusvankempen/wxo-builder-mcp-server](https://github.com/markusvankempen/wxo-builder-mcp-server) for cloning just the MCP server
+- **Devkit** – This package is also part of the [watsonx-orchestrate-devkit](https://github.com/markusvankempen/watsonx-orchestrate-devkit) at `packages/wxo-builder-mcp-server` (shared with the WxO Builder extension)
+
+## Install from npm
+
+```bash
+npm install @markusvankempen/wxo-builder-mcp-server
+```
+
+### One-click install in Cursor
+
+**[Add to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=WxO%20Builder%20MCP%20Server&config=eyJXeE8gQnVpbGRlciBNQ1AgU2VydmVyIjp7ImNvbW1hbmQiOiJucHgiLCJhcmdzIjpbIi15IiwiQG1hcmt1c3ZhbmtlbXBlbi93eG8tYnVpbGRlci1tY3Atc2VydmVyIl0sImVudiI6eyJXT19BUElfS0VZIjoieW91ci1hcGkta2V5IiwiV09fSU5TVEFOQ0VfVVJMIjoiaHR0cHM6Ly95b3VyLWluc3RhbmNlLm9yY2hlc3RyYXRlLmlibS5jb20ifX19)** — Click to install (shows "WxO Builder MCP Server"). Then set `WO_API_KEY` and `WO_INSTANCE_URL` in Cursor MCP settings.
+
+## Quick Start
+
+1. **Set environment variables** (or use `.env`):
+
+```env
+WO_API_KEY=<your_ibm_cloud_api_key>
+WO_INSTANCE_URL=https://<your-instance-id>.orchestrate.ibm.com
+
+# Optional: default agent(s) when user omits agent_id/agent_name (first is used)
+WO_AGENT_IDs=agent-id-1,agent-id-2
+# Or single agent (backwards compatible):
+# WO_AGENT_ID=<your-agent-id>
+```
+
+When `WO_AGENT_IDs` (comma-separated) or `WO_AGENT_ID` is set, tools use the first ID as default when the user does not specify an agent.
+
+2. **Configure your MCP client** – use `npx` so you never reference `.js` paths. Example for Cursor (`.cursor/mcp.json`):
+
+```json
+{
+    "mcpServers": {
+        "watsonx": {
+            "command": "npx",
+            "args": ["-y", "@markusvankempen/wxo-builder-mcp-server"],
+            "env": {
+                "WO_API_KEY": "your-api-key",
+                "WO_INSTANCE_URL": "https://xxx.orchestrate.ibm.com"
+            }
+        }
+    }
+}
+```
+
+VS Code Copilot uses `servers` instead of `mcpServers`; same `command` and `args`:
+
+```json
+{
+    "servers": {
+        "watsonx": {
+            "type": "stdio",
+            "command": "npx",
+            "args": ["-y", "@markusvankempen/wxo-builder-mcp-server"],
+            "env": {
+                "WO_API_KEY": "...",
+                "WO_INSTANCE_URL": "https://...orchestrate.ibm.com"
+            }
+        }
+    }
+}
+```
+
+### Example configs
+
+Copy-ready example files are in [`examples/`](examples/):
+
+| File | Use for |
+|------|---------|
+| `examples/.vscode/mcp.json` | VS Code / GitHub Copilot → copy to `.vscode/mcp.json` |
+| `examples/.cursor/mcp.json` | Cursor → copy to `.cursor/mcp.json` |
+| `examples/claude-desktop-config.json` | Claude Desktop → merge into `~/Library/Application Support/Claude/claude_desktop_config.json` |
+| `examples/antigravity-mcp-config.json` | Antigravity → add to `mcp_config.json` via Manage MCP Servers |
+| `examples/windsurf-mcp-config.json` | Windsurf → copy to `~/.codeium/windsurf/mcp_config.json` |
+| `examples/env.example` | Optional `.env` for env vars |
+
+See [`examples/README.md`](examples/README.md) for details.
+
+## Features (Parity with VS Code Extension)
+
+### OpenAPI Spec
+
+- **`watson-orchestrate-openapi.json`** – OpenAPI 3.0 spec describing the Watson Orchestrate REST API used by this MCP server (tools, agents, connections, flows, runs). Use `get_api_spec` to retrieve it.
+- **`get_api_spec`** – Returns the OpenAPI spec (full or summary). Use to discover what operations the Watson Orchestrate instance supports.
+
+### Tools (Skills)
+
+- **`list_skills`** – List all tools in the catalog (default limit 100)
+- **`list_tools_with_connections`** – List tools grouped by connection status (tools with connections vs standard tools). **Matches the extension Tools view.** Use for prompts like “list my Watson Orchestrate tools with active connections”.
+- **`list_standard_tools`** – List only standard tools (no connections). Returns accurate count and list.
+- **`get_skill`** – Get a tool by ID
+- **`delete_skill`** – Delete a tool
+- **`deploy_skill`** – Create a tool from OpenAPI spec. Set `openapi_spec["x-ibm-connection-id"]` to **bind a connection** to the tool
+- **`deploy_tool_from_url`** – Create a tool from a URL. Handles (1) APIs with API key → auto-creates connection, (2) public APIs (REST Countries, Open-Meteo) → no auth.
+- **`create_tool_and_assign_to_agent`** – Create a tool from URL and assign to agent in one step. `agent_id`/`agent_name` optional if `WO_AGENT_IDs` is set.
+- **`assign_tool_to_agent`** – Assign a tool to an agent. `agent_id`/`agent_name` optional if `WO_AGENT_IDs` is set.
+- **`update_skill`** – Update name, description, permission (binding/connection not editable after creation)
+- **`copy_skill`** – Copy a tool. Use `new_name` (e.g. "MVKWeatherV2") to name the copy. Keeps connection and parameters. Names: letters, digits, underscores only.
+- **`execute_tool`** – Execute a tool by name or ID. `agent_id` optional; uses first from `WO_AGENT_IDs` when omitted.
+
+### Agents
+
+- **`list_agents`** – List all agents
+- **`get_agent`** – Get agent by ID or name. `agent_id`/`agent_name` optional if `WO_AGENT_IDs` is set.
+- **`get_agent_chat_starter_settings`** – Get welcome message and quick prompts. `agent_id`/`agent_name` optional if `WO_AGENT_IDs` is set.
+- **`update_agent_chat_starter_settings`** – Update `welcome_message` and `quick_prompts`. `agent_id`/`agent_name` optional if `WO_AGENT_IDs` is set.
+- **`list_agent_tools`** – List tools assigned to an agent with display names. `agent_id`/`agent_name` optional if `WO_AGENT_IDs` is set.
+- **`create_agent`** – Create an agent. Pass `tools` array to **assign tools** to the agent
+- **`update_agent`** – Update an agent. `agent_id`/`agent_name` optional if `WO_AGENT_IDs` is set.
+- **`update_agent_instructions_from_tools`** – Auto-generate and set instructions from assigned tools. `agent_id`/`agent_name` optional if `WO_AGENT_IDs` is set.
+- **`invoke_agent`** – Chat with an agent. `agent_id`/`agent_name` optional if `WO_AGENT_IDs` is set.
+- **`delete_agent`** – Delete an agent
+
+### Connections
+
+- **`list_connectors`** – List available connector catalog
+- **`list_connections`** – List configured connections (scope: draft, live, all)
+- **`list_active_live_connections`** – List only active and live connections (not tools), deduplicated. Use for "list all connections which are active and live, just the connections".
+- **`get_connection`** – Get connection by app_id
+- **`create_connection`** – Create a connection entry
+- **`delete_connection`** – Delete a connection
+- **`configure_connection`** – Set credentials (api_key, basic, bearer) for a connection
+
+### Flows
+
+- **`list_flows`**, **`get_flow`**, **`create_flow`**, **`delete_flow`**
+
+## Client Compatibility
+
+The MCP server is tested and works with:
+
+| Client | Config | Notes |
+|--------|--------|------|
+| **Cursor** | `examples/.cursor/mcp.json` | stdio, npx or node |
+| **VS Code Copilot** | `examples/.vscode/mcp.json` | Use `servers` key, `type: "stdio"` |
+| **Antigravity** | `examples/antigravity-mcp-config.json` | Add via Manage MCP Servers |
+| **Langflow** | STDIO or JSON mode | Output flattened for DataFrame; list tools have no limit/offset params |
+
+**Langflow:** Tool output is normalized to a list of flat dicts (primitive values only) so the MCP Tools component's DataFrame validation passes. Nested objects (e.g. `binding`, `input_schema`) are JSON-stringified. Cursor, VS Code, and Antigravity receive the same format and work identically.
+
+**Verification:** Run `npm run test:integration` with `WO_API_KEY` and `WO_INSTANCE_URL` to validate core functionality. For Cursor/VS Code: add the server, ask "List my Watson Orchestrate tools" or "Which agents do I have?" For Langflow: add MCP server, connect MCP Tools to an Agent, run the flow.
+
+## Configuration
+
+Set these environment variables (or use a `.env` file):
+
+```env
+WO_API_KEY=<your_ibm_cloud_api_key>
+WO_INSTANCE_URL=https://<your-instance-id>.orchestrate.ibm.com
+
+# Optional: default agent(s) when user omits agent_id/agent_name (first is used)
+WO_AGENT_IDs=agent-id-1,agent-id-2
+```
+
+See [Quick Start](#quick-start) for full details on `WO_AGENT_IDs` and `WO_AGENT_ID`.
+
+## Troubleshooting
+
+**"Process exited with code 2" / "MCP server could not be started"**
+
+1. **Ensure credentials are set** – `WO_API_KEY` and `WO_INSTANCE_URL` must be in your MCP config `env` block or in a `.env` file.
+2. **Verify the server runs manually** – From a terminal:
+   ```bash
+   WO_API_KEY=your-key WO_INSTANCE_URL=https://xxx.orchestrate.ibm.com npx -y @markusvankempen/wxo-builder-mcp-server
+   ```
+   It should start and wait. Press Ctrl+C to exit.
+3. **Check Node version** – Requires Node.js 18+.
+4. **WxO Builder extension** – Ensure **API Key** and **Instance URL** are set in extension settings (search `wxo-builder` in VS Code settings).
+
+## Running Locally
+
+```bash
+npm install
+npm run build
+node dist/index.js
+```
+
+## Integration Tests
+
+The test suite validates MCP parity with the extension using **user-style test questions**. See [`tests/README.md`](tests/README.md) for full documentation. Test questions are defined in `tests/test-questions.ts` – add new ones to extend validation.
+
+```bash
+# With WO credentials (runs all 4 tests)
+WO_API_KEY=... WO_INSTANCE_URL=... npm run test:integration
+
+# Without WO credentials (runs local execution test only)
+npm run test:integration
+```
+
+**Test questions:** List live connections | Copy tool with new name | List standard tools | Create MVKWeather from URL | Execute locally (Toronto) | Execute remotely | Agent chat (Toronto weather) | Exchange rate (TimeWeatherAgent) | Create REST Countries and assign to TimeWeatherAgent | List agent tools
+
+## Assigning Tools to Agents
+
+Use `create_agent` or `update_agent` with a `tools` array of tool IDs:
+
+```json
+{
+    "name": "My Agent",
+    "description": "...",
+    "model_id": "groq/openai/gpt-oss-120b",
+    "instructions": "...",
+    "tools": ["tool-id-1", "tool-id-2"]
+}
+```
+
+## Assigning Connections to Tools
+
+When deploying a tool with `deploy_skill`, include `x-ibm-connection-id` in the OpenAPI spec (or the connection’s app_id) to bind a connection:
+
+```json
+{
+  "tool_spec": { "name": "my_tool", "description": "..." },
+  "openapi_spec": {
+    "openapi": "3.0.1",
+    "info": { "title": "My Tool", "version": "1.0.0" },
+    "x-ibm-connection-id": "YOUR_APP_ID",
+    "paths": { ... }
+  }
+}
+```
+
+## Editor configuration (VS Code, Cursor, Claude Desktop, Antigravity, Windsurf)
+
+**Important:** MCP config does **not** go in VS Code `settings.json`. Use the correct config file for your editor.
+
+### VS Code (with GitHub Copilot)
+
+Config file: **`.vscode/mcp.json`** (workspace) or run **MCP: Open User Configuration** for global. Use `npx` (no .js path needed):
+
+```json
+{
+    "servers": {
+        "watsonx": {
+            "type": "stdio",
+            "command": "npx",
+            "args": ["-y", "@markusvankempen/wxo-builder-mcp-server"],
+            "env": {
+                "WO_API_KEY": "...",
+                "WO_INSTANCE_URL": "https://...orchestrate.ibm.com"
+            }
+        }
+    }
+}
+```
+
+### Cursor
+
+Config file: **`.cursor/mcp.json`** (project) or `~/.cursor/mcp.json` (global). Uses `mcpServers` (not `servers`). Same `command` and `args` as above.
+
+### Antigravity (Google)
+
+Open **Manage MCP Servers → View raw config** and add the `watsonx` entry from `examples/antigravity-mcp-config.json` to your `mcp_config.json`. Same `mcpServers` format as Cursor.
+
+### Windsurf (Codeium)
+
+Config file: **`~/.codeium/windsurf/mcp_config.json`** (macOS/Linux) or **`%USERPROFILE%\.codeium\windsurf\mcp_config.json`** (Windows). Use `examples/windsurf-mcp-config.json`. Same `mcpServers` format as Cursor. Restart Windsurf after changes.
+
+### Alternative: WxO Builder extension bundled server
+
+If you installed the WxO Builder VSIX and want to use its bundled server (no npm install), use the extension path:
+
+```json
+"command": "node",
+"args": ["/Users/YOUR_USERNAME/.vscode/extensions/markusvankempen.wxo-builder-0.0.6/server/dist/index.js"]
+```
+
+### Local build (devkit or standalone repo)
+
+If you clone the devkit or the [standalone repo](https://github.com/markusvankempen/wxo-builder-mcp-server), build and run via `npx` using the package directory (no .js path):
+
+```bash
+cd packages/wxo-builder-mcp-server   # devkit
+# or
+cd wxo-builder-mcp-server            # standalone repo
+
+npm install && npm run build
+```
+
+```json
+{
+    "servers": {
+        "watsonx": {
+            "type": "stdio",
+            "command": "npx",
+            "args": ["-y", "/path/to/wxo-builder-mcp-server"],
+            "env": {
+                "WO_API_KEY": "...",
+                "WO_INSTANCE_URL": "https://...orchestrate.ibm.com"
+            }
+        }
+    }
+}
+```
+
+## Publishing (for maintainers)
+
+### Publish to npm
+
+From the devkit or standalone repo:
+
+```bash
+cd packages/wxo-builder-mcp-server   # devkit
+# or
+cd .                                 # standalone repo root
+
+npm run build
+npm publish --access public
+```
+
+### Publish to MCP Registry
+
+1. Install the MCP publisher CLI: `brew install mcp-publisher`
+2. Log in: `mcp-publisher login github`
+3. Update `server.json` version to match `package.json`
+4. Publish: `mcp-publisher publish`
+
+The server will appear at [registry.modelcontextprotocol.io](https://registry.modelcontextprotocol.io) as `io.github.markusvankempen/wxo-builder-mcp-server`.
+
+## Implementation: TypeScript vs Node.js
+
+This MCP server is written in **TypeScript** and compiled to JavaScript. It loads an OpenAPI spec (`watson-orchestrate-openapi.json`) for documentation and discovery.
+
+**Why TypeScript for Watson Orchestrate:**
+
+- Larger codebase (skills, agents, connections, flows, auth, models)
+- Type safety for Watson Orchestrate’s varied API responses
+- Easier to maintain and extend across multiple modules
+
+## License
+
+Apache-2.0 — See [LICENSE](LICENSE). [CONTRIBUTING](CONTRIBUTING.md) · [CHANGELOG](CHANGELOG.md)