wxo-builder-mcp-server 1.0.8

package/package.json

@@ -0,0 +1,99 @@
+{
+    "name": "wxo-builder-mcp-server",
+    "version": "1.0.8",
+    "description": "MCP server for IBM Watson Orchestrate (WXO): manage tools, agents, connections, flows, and execute tools from Cursor, VS Code Copilot, or Claude.",
+    "mcpName": "io.github.markusvankempen/wxo-builder-mcp-server",
+    "type": "module",
+    "main": "dist/index.js",
+    "bin": {
+        "wxo-builder-mcp-server": "dist/index.js",
+        "wxo-builder-mcp": "dist/index.js"
+    },
+    "files": [
+        "dist",
+        "README.md",
+        "CHANGELOG.md",
+        "LICENSE",
+        "watson-orchestrate-openapi.json",
+        "resources"
+    ],
+    "scripts": {
+        "build": "tsc",
+        "start": "node dist/index.js",
+        "dev": "ts-node src/index.ts",
+        "test:integration": "npm run build && node -r ts-node/register/transpile-only tests/integration-mcp-parity.ts",
+        "prepublishOnly": "npm run build",
+        "lint": "eslint src --ext .ts",
+        "lint:fix": "eslint src --ext .ts --fix",
+        "format": "prettier --write \"src/**/*.ts\" \"*.json\" \"*.md\"",
+        "format:check": "prettier --check \"src/**/*.ts\" \"*.json\" \"*.md\"",
+        "check": "npm run lint && npm run format:check && npm run build",
+        "fix": "npm run lint:fix && npm run format",
+        "prepare": "husky"
+    },
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/markusvankempen/wxo-builder-mcp-server.git"
+    },
+    "homepage": "https://github.com/markusvankempen/wxo-builder-mcp-server#readme",
+    "bugs": "https://github.com/markusvankempen/wxo-builder-mcp-server/issues",
+    "keywords": [
+        "mcp",
+        "model-context-protocol",
+        "watsonx",
+        "watson-orchestrate",
+        "watsonx-orchestrate",
+        "wxo",
+        "ibm",
+        "ai",
+        "agents",
+        "tools",
+        "cursor",
+        "claude",
+        "vscode",
+        "copilot",
+        "antigravity",
+        "windsurf",
+        "openai"
+    ],
+    "author": "Markus van Kempen <markus.van.kempen@gmail.com>",
+    "license": "Apache-2.0",
+    "publishConfig": {
+        "access": "public"
+    },
+    "engines": {
+        "node": ">=18"
+    },
+    "dependencies": {
+        "@modelcontextprotocol/sdk": "^1.26.0",
+        "archiver": "^7.0.1",
+        "dotenv": "^17.3.1",
+        "node-fetch": "^3.3.2",
+        "zod": "^4.3.6"
+    },
+    "lint-staged": {
+        "src/**/*.ts": [
+            "eslint --fix",
+            "prettier --write"
+        ],
+        "*.{json,md}": [
+            "prettier --write"
+        ]
+    },
+    "devDependencies": {
+        "@commitlint/cli": "^20.4.1",
+        "@commitlint/config-conventional": "^20.4.1",
+        "@types/archiver": "^7.0.0",
+        "@types/node": "^20.19.33",
+        "@typescript-eslint/eslint-plugin": "^6.21.0",
+        "@typescript-eslint/parser": "^6.21.0",
+        "eslint": "^8.57.1",
+        "eslint-config-prettier": "^10.1.8",
+        "eslint-plugin-prettier": "^5.5.5",
+        "husky": "^9.1.7",
+        "lint-staged": "^16.2.7",
+        "prettier": "^3.8.1",
+        "ts-node": "^10.9.2",
+        "typescript": "^5.9.3"
+    }
+}

package/resources/icon.svg

@@ -0,0 +1,18 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 128 128" fill="none">
+  <defs>
+    <linearGradient id="bg" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" style="stop-color:#4a4a6a" />
+      <stop offset="100%" style="stop-color:#2d2d44" />
+    </linearGradient>
+  </defs>
+  <rect x="0" y="0" width="128" height="128" rx="28" fill="url(#bg)"/>
+  <!-- Connected nodes: orchestration / flow -->
+  <line x1="32" y1="64" x2="64" y2="48" stroke="white" stroke-width="4" stroke-linecap="round" opacity="0.7"/>
+  <line x1="64" y1="48" x2="96" y2="64" stroke="white" stroke-width="4" stroke-linecap="round" opacity="0.7"/>
+  <line x1="96" y1="64" x2="64" y2="88" stroke="white" stroke-width="4" stroke-linecap="round" opacity="0.7"/>
+  <line x1="64" y1="88" x2="32" y2="64" stroke="white" stroke-width="4" stroke-linecap="round" opacity="0.7"/>
+  <circle cx="32" cy="64" r="10" fill="white" opacity="0.95"/>
+  <circle cx="64" cy="48" r="10" fill="white" opacity="0.95"/>
+  <circle cx="96" cy="64" r="10" fill="white" opacity="0.95"/>
+  <circle cx="64" cy="88" r="10" fill="white" opacity="0.95"/>
+</svg>

package/watson-orchestrate-openapi.json

@@ -0,0 +1,359 @@
+{
+  "openapi": "3.0.3",
+  "info": {
+    "title": "Watson Orchestrate API",
+    "description": "IBM Watson Orchestrate REST API used by the Watson Orchestrate MCP server. This spec documents the endpoints the MCP server calls to manage tools, agents, connections, and flows. Agentic flow definitions are tools with binding.flow — use POST/PUT /v1/orchestrate/tools for flow creation and updates.",
+    "version": "1.1.0",
+    "contact": {
+      "name": "Markus van Kempen",
+      "email": "markus.van.kempen@gmail.com"
+    },
+    "license": {
+      "name": "Apache-2.0",
+      "url": "http://www.apache.org/licenses/LICENSE-2.0"
+    }
+  },
+  "servers": [
+    {
+      "url": "{baseUrl}",
+      "variables": {
+        "baseUrl": {
+          "default": "https://api.us-south.watson-orchestrate.cloud.ibm.com/instances/YOUR_INSTANCE_ID",
+          "description": "WO_INSTANCE_URL from .env"
+        }
+      }
+    }
+  ],
+  "security": [
+    { "bearerAuth": [] }
+  ],
+  "components": {
+    "securitySchemes": {
+      "bearerAuth": {
+        "type": "http",
+        "scheme": "bearer",
+        "bearerFormat": "JWT",
+        "description": "IAM Bearer token obtained from IBM Cloud API key"
+      }
+    },
+    "schemas": {
+      "Tool": {
+        "type": "object",
+        "properties": {
+          "id": { "type": "string" },
+          "name": { "type": "string" },
+          "display_name": { "type": "string" },
+          "description": { "type": "string" },
+          "permission": { "type": "string", "enum": ["read_only", "read_write"] },
+          "input_schema": { "type": "object" },
+          "output_schema": { "type": "object" },
+          "binding": {
+            "type": "object",
+            "description": "For flows: { flow: { flow_id, model, dependencies } }. For OpenAPI tools: { openapi: {...} }."
+          }
+        }
+      },
+      "FlowToolCreate": {
+        "type": "object",
+        "description": "Create an agentic workflow (flow) as a tool. Flows support Timer, Branch, Decisions, Foreach, Prompt, Tool, Agent nodes.",
+        "required": ["name", "binding"],
+        "properties": {
+          "name": { "type": "string" },
+          "display_name": { "type": "string" },
+          "description": { "type": "string" },
+          "permission": { "type": "string", "enum": ["read_only", "read_write"], "default": "read_only" },
+          "binding": {
+            "type": "object",
+            "required": ["flow"],
+            "properties": {
+              "flow": {
+                "type": "object",
+                "required": ["flow_id", "model"],
+                "properties": {
+                  "flow_id": { "type": "string" },
+                  "model": {
+                    "type": "object",
+                    "description": "Flow DSL: spec (kind: flow), nodes, edges, schemas"
+                  },
+                  "dependencies": {
+                    "type": "object",
+                    "properties": {
+                      "tools": { "type": "array", "items": { "type": "string" }, "description": "Tool IDs for tool nodes" },
+                      "agents": { "type": "array", "items": { "type": "string" }, "description": "Agent IDs for agent nodes" }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      },
+      "Agent": {
+        "type": "object",
+        "properties": {
+          "id": { "type": "string" },
+          "name": { "type": "string" },
+          "description": { "type": "string" },
+          "llm": { "type": "string" },
+          "tools": { "type": "array", "items": { "type": "string" } }
+        }
+      },
+      "Connection": {
+        "type": "object",
+        "properties": {
+          "app_id": { "type": "string" },
+          "display_name": { "type": "string" }
+        }
+      },
+      "Flow": {
+        "type": "object",
+        "properties": {
+          "id": { "type": "string" },
+          "name": { "type": "string" }
+        }
+      }
+    }
+  },
+  "paths": {
+    "/v1/orchestrate/tools": {
+      "get": {
+        "summary": "List tools",
+        "description": "List all tools/skills in the Watson Orchestrate catalog",
+        "operationId": "listTools",
+        "parameters": [
+          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 100 } },
+          { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } }
+        ],
+        "responses": { "200": { "description": "List of tools" } }
+      },
+      "post": {
+        "summary": "Create tool",
+        "description": "Create a new tool. For OpenAPI tools: provide binding.openapi. For agentic flows: provide binding.flow with flow_id and model (Flow DSL with nodes, edges, schemas). Flows support Timer, Branch, Decisions, Foreach, Prompt, Tool, Agent nodes. See internal/docs/agent_flow_research.md.",
+        "operationId": "createTool",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "description": "Flow: use binding.flow. OpenAPI: use binding.openapi. See FlowToolCreate schema."
+              }
+            }
+          }
+        },
+        "responses": { "200": { "description": "Created tool (returns id)" } }
+      }
+    },
+    "/v1/orchestrate/tools/{toolId}": {
+      "get": {
+        "summary": "Get tool",
+        "operationId": "getTool",
+        "parameters": [{ "name": "toolId", "in": "path", "required": true, "schema": { "type": "string" } }],
+        "responses": { "200": { "description": "Tool details" } }
+      },
+      "delete": {
+        "summary": "Delete tool",
+        "operationId": "deleteTool",
+        "parameters": [{ "name": "toolId", "in": "path", "required": true, "schema": { "type": "string" } }],
+        "responses": { "200": { "description": "Deleted" } }
+      },
+      "patch": {
+        "summary": "Patch tool",
+        "operationId": "patchTool",
+        "parameters": [{ "name": "toolId", "in": "path", "required": true, "schema": { "type": "string" } }],
+        "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } },
+        "responses": { "200": { "description": "Updated tool" } }
+      },
+      "put": {
+        "summary": "Update tool (full replacement)",
+        "description": "Full replace of tool. Use for flow model updates (e.g. fix model: null). Avoid $ref to #/input or #/nodes/<id>/output — causes 500.",
+        "operationId": "updateTool",
+        "parameters": [{ "name": "toolId", "in": "path", "required": true, "schema": { "type": "string" } }],
+        "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } },
+        "responses": { "200": { "description": "Updated tool" } }
+      }
+    },
+    "/v1/orchestrate/tools/{toolId}/upload": {
+      "post": {
+        "summary": "Upload tool OpenAPI bundle",
+        "description": "Upload OpenAPI zip for tool deployment",
+        "operationId": "uploadTool",
+        "parameters": [{ "name": "toolId", "in": "path", "required": true, "schema": { "type": "string" } }],
+        "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object" } } } },
+        "responses": { "200": { "description": "Uploaded" } }
+      }
+    },
+    "/v1/orchestrate/agents": {
+      "get": {
+        "summary": "List agents",
+        "operationId": "listAgents",
+        "parameters": [
+          { "name": "limit", "in": "query", "schema": { "type": "integer" } },
+          { "name": "offset", "in": "query", "schema": { "type": "integer" } }
+        ],
+        "responses": { "200": { "description": "List of agents" } }
+      },
+      "post": {
+        "summary": "Create agent",
+        "operationId": "createAgent",
+        "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agent" } } } },
+        "responses": { "200": { "description": "Created agent" } }
+      }
+    },
+    "/v1/orchestrate/agents/{agentId}": {
+      "get": {
+        "summary": "Get agent",
+        "operationId": "getAgent",
+        "parameters": [{ "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } }],
+        "responses": { "200": { "description": "Agent details" } }
+      },
+      "patch": {
+        "summary": "Update agent",
+        "operationId": "updateAgent",
+        "parameters": [{ "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } }],
+        "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } },
+        "responses": { "200": { "description": "Updated agent" } }
+      },
+      "delete": {
+        "summary": "Delete agent",
+        "operationId": "deleteAgent",
+        "parameters": [{ "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } }],
+        "responses": { "200": { "description": "Deleted" } }
+      }
+    },
+    "/v1/orchestrate/agents/{agentId}/chat-starter-settings": {
+      "get": {
+        "summary": "Get chat starter settings",
+        "description": "Retrieve welcome message and quick prompts for an agent",
+        "operationId": "getChatStarterSettings",
+        "parameters": [{ "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } }],
+        "responses": { "200": { "description": "Chat starter settings" } }
+      },
+      "put": {
+        "summary": "Update chat starter settings",
+        "description": "Set welcome message and quick prompts for an agent",
+        "operationId": "updateChatStarterSettings",
+        "parameters": [{ "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } }],
+        "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } },
+        "responses": { "200": { "description": "Updated" } }
+      }
+    },
+    "/v1/orchestrate/runs": {
+      "post": {
+        "summary": "Start run",
+        "description": "Start an agentic run (invoke agent or tool). Used for invoke_agent and execute_tool.",
+        "operationId": "createRun",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": ["message"],
+                "properties": {
+                  "agent_id": { "type": "string", "description": "Required for agentic runs. Use tool_id + agent_id to run a specific tool." },
+                  "tool_id": { "type": "string", "description": "Tool/flow to execute. Agent routes to it." },
+                  "parameters": { "type": "object", "description": "Flow/tool input parameters" },
+                  "message": {
+                    "type": "object",
+                    "required": ["role", "content"],
+                    "properties": {
+                      "role": { "type": "string", "enum": ["user"] },
+                      "content": { "type": "string", "description": "Directive e.g. 'Run the flow with these parameters.'" }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": { "200": { "description": "Run started. Returns thread_id. Poll GET /v1/orchestrate/threads/{threadId}/messages for result." } }
+      }
+    },
+    "/v1/orchestrate/threads/{threadId}/messages": {
+      "get": {
+        "summary": "Get thread messages",
+        "description": "Poll for run completion (assistant response)",
+        "operationId": "getThreadMessages",
+        "parameters": [{ "name": "threadId", "in": "path", "required": true, "schema": { "type": "string" } }],
+        "responses": { "200": { "description": "Messages array" } }
+      }
+    },
+    "/v1/orchestrate/catalog/applications": {
+      "get": {
+        "summary": "List connectors",
+        "description": "List available connector applications from catalog",
+        "operationId": "listConnectors",
+        "parameters": [{ "name": "limit", "in": "query", "schema": { "type": "integer" } }],
+        "responses": { "200": { "description": "Connector catalog" } }
+      }
+    },
+    "/v1/orchestrate/connections/applications": {
+      "get": {
+        "summary": "List connections",
+        "parameters": [
+          { "name": "scope", "in": "query", "schema": { "enum": ["draft", "live"] } },
+          { "name": "include_details", "in": "query", "schema": { "type": "boolean" } }
+        ],
+        "responses": { "200": { "description": "Configured connections" } }
+      },
+      "post": {
+        "summary": "Create connection",
+        "operationId": "createConnection",
+        "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } },
+        "responses": { "200": { "description": "Created connection" } }
+      }
+    },
+    "/v1/orchestrate/connections/applications/{appId}": {
+      "get": {
+        "summary": "Get connection",
+        "parameters": [{ "name": "appId", "in": "path", "required": true, "schema": { "type": "string" } }],
+        "responses": { "200": { "description": "Connection details" } }
+      },
+      "delete": {
+        "summary": "Delete connection",
+        "parameters": [{ "name": "appId", "in": "path", "required": true, "schema": { "type": "string" } }],
+        "responses": { "200": { "description": "Deleted" } }
+      }
+    },
+    "/v1/flows/": {
+      "get": {
+        "summary": "List flows",
+        "description": "List flows. Note: Flow definitions are tools with binding.flow. Prefer GET /v1/orchestrate/tools and filter by binding.flow for flow definitions.",
+        "operationId": "listFlows",
+        "parameters": [
+          { "name": "limit", "in": "query", "schema": { "type": "integer" } },
+          { "name": "offset", "in": "query", "schema": { "type": "integer" } }
+        ],
+        "responses": { "200": { "description": "List of flows" } }
+      },
+      "post": {
+        "summary": "Create flow",
+        "description": "Create flow. Prefer POST /v1/orchestrate/tools with binding.flow for agentic workflows.",
+        "operationId": "createFlow",
+        "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } },
+        "responses": { "200": { "description": "Created flow" } }
+      }
+    },
+    "/v1/flows/{flowId}": {
+      "get": {
+        "summary": "Get flow",
+        "description": "Get flow by ID. Flow definitions: use GET /v1/orchestrate/tools/{toolId} — flows are tools with binding.flow.",
+        "parameters": [{ "name": "flowId", "in": "path", "required": true, "schema": { "type": "string" } }],
+        "responses": { "200": { "description": "Flow details" } }
+      },
+      "delete": {
+        "summary": "Delete flow",
+        "description": "Delete flow. Flow definitions: use DELETE /v1/orchestrate/tools/{toolId}.",
+        "parameters": [{ "name": "flowId", "in": "path", "required": true, "schema": { "type": "string" } }],
+        "responses": { "200": { "description": "Deleted" } }
+      }
+    },
+    "/v1/models/list": {
+      "get": {
+        "summary": "List models",
+        "description": "List LLM models available for agents",
+        "operationId": "listModels",
+        "responses": { "200": { "description": "Model list" } }
+      }
+    }
+  }
+}