@robotyxx/robotyx-mcp 0.1.0

package/README.md

@@ -0,0 +1,76 @@
+# robotyx-mcp
+
+Stdio MCP server that wraps Robotyx's REST API. Lets Claude Code / Claude
+Desktop browse recorded workflows, refine their TestSteps into grouped
+functional steps ("clicks 1-7 → Log in as admin"), and push the result back
+— without leaving the chat.
+
+No new business logic lives here. Every tool is a thin wrapper around an
+existing endpoint the Robotyx web UI also uses.
+
+## Tools
+
+| Tool | Wraps | Notes |
+|------|-------|-------|
+| `list_workflows` | `GET /api/workflows` | Summary rows. |
+| `get_workflow` | `GET /api/workflows/:id` | Screenshots stripped by default. Pass `include_screenshots: "all"` or `"indices"` + `screenshot_step_indices: [1,3,5]` when you need visual context. |
+| `list_testsuites` | `GET /api/testsuites` | |
+| `get_testsuite` | `GET /api/testsuites/:id` | Includes cases + their steps. |
+| `create_testsuite` | `POST /api/testsuites` | |
+| `add_test_case` | `POST /api/testsuites/:id/cases` | Optionally links a Workflow id. |
+| `set_test_steps` | `POST /api/testsuites/:id/cases/:caseId/import-mapping` | The refine path. Body shape mirrors the UI's Excel import — pass `workflow_step_ids` (full ordered list from `get_workflow`) + `mappings: [{description, expected_result, workflow_step_indices: [1,2,3]}]`. |
+| `merge_step` | `POST .../steps/:stepId/merge` | |
+| `split_step` | `POST .../steps/:stepId/split` | |
+| `create_defect` | `POST /api/defects` | |
+
+## Wire-up — Claude Code
+
+Drop a `.mcp.json` in your workspace root (already done for
+`ai-automation-platform/` and `footprint-platform/`):
+
+```json
+{
+  "mcpServers": {
+    "robotyx": {
+      "command": "npx",
+      "args": ["-y", "tsx", "C:\\Users\\…\\ai-automation-platform\\robotyx-mcp\\src\\index.ts"],
+      "env": {
+        "ROBOTYX_URL": "http://localhost:3001",
+        "ROBOTYX_API_KEY": "${ROBOTYX_API_KEY}"
+      }
+    }
+  }
+}
+```
+
+Then in PowerShell (once per machine):
+
+```powershell
+[Environment]::SetEnvironmentVariable("ROBOTYX_API_KEY", "rx_…", "User")
+```
+
+Restart Claude Code so it picks up the new MCP. Verify with `/mcp` — you
+should see `robotyx: ✓ connected (10 tools)`.
+
+## Wire-up — Claude Desktop
+
+Add the same `mcpServers` block to
+`%APPDATA%\Claude\claude_desktop_config.json` and restart the app.
+
+## Typical refine loop
+
+1. `list_workflows` → pick a workflow id.
+2. `get_workflow` (no screenshots) → AI proposes a grouping based on
+   step descriptions + action types.
+3. `get_workflow` with `include_screenshots: "indices"` and the ambiguous
+   step indices → AI disambiguates visually.
+4. Either `add_test_case` (linking the workflow) or pick an existing one
+   from `get_testsuite`.
+5. `set_test_steps` with the proposed mapping → done.
+
+## Token budget
+
+A 30-step browser recording with full-page PNGs is ~200-400k tokens with
+`include_screenshots: "all"`. Always start with `"none"`, then use
+`"indices"` to fetch only the screenshots you need. The server strips
+`footprint_*` bookkeeping keys (raw a11y dumps, console logs) unconditionally.

package/dist/gateway-bridge.js

@@ -0,0 +1,92 @@
+/**
+ * Gateway tool bridge — exposes ALL of the gateway's aggregated MCP tools
+ * (autopilot / selenium / electron / playwright / java / api-agent …) to an
+ * external MCP client (Claude Code) through a single server, and forwards every
+ * call to the gateway's POST /api/tools/call.
+ *
+ * Why a bridge instead of wiring each MCP into the client directly: tool calls
+ * must flow through the gateway so the gateway's RecordingManager captures them
+ * into the active workflow (see /api/tools/call). Calling the underlying MCP
+ * servers directly would bypass recording — and we'd have to solve recording
+ * per-client. One bridge → all tools, all recorded, all replayable by the
+ * PlaybackEngine.
+ *
+ * Env:
+ *   ROBOTYX_URL      — gateway base URL (default http://localhost:3001)
+ *   ROBOTYX_API_KEY  — long-lived `rx_…` Bearer token (required)
+ *
+ * .mcp.json:
+ *   "gateway-tools": {
+ *     "command": "npx",
+ *     "args": ["-y", "tsx", "…/robotyx-mcp/src/gateway-bridge.ts"],
+ *     "env": { "ROBOTYX_URL": "http://localhost:3001", "ROBOTYX_API_KEY": "rx_…" }
+ *   }
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+const ROBOTYX_URL = (process.env.ROBOTYX_URL || "http://localhost:3001").replace(/\/+$/, "");
+const ROBOTYX_API_KEY = process.env.ROBOTYX_API_KEY || "";
+if (!ROBOTYX_API_KEY) {
+    process.stderr.write("[gateway-bridge] ROBOTYX_API_KEY is not set. Mint a key in the Robotyx UI " +
+        "(Settings → API keys) and set it in the MCP env. Exiting.\n");
+    process.exit(1);
+}
+async function fetchTools() {
+    const res = await fetch(`${ROBOTYX_URL}/api/tools`, {
+        headers: { Authorization: `Bearer ${ROBOTYX_API_KEY}` },
+    });
+    if (!res.ok) {
+        throw new Error(`GET /api/tools → ${res.status} ${await res.text().catch(() => "")}`);
+    }
+    const data = (await res.json());
+    return data.tools ?? [];
+}
+/** Forward a tool call to the gateway; it routes + records + returns the MCP result. */
+async function callTool(name, args) {
+    const res = await fetch(`${ROBOTYX_URL}/api/tools/call`, {
+        method: "POST",
+        headers: {
+            Authorization: `Bearer ${ROBOTYX_API_KEY}`,
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify({ name, args }),
+    });
+    const text = await res.text();
+    if (!res.ok) {
+        return { isError: true, content: [{ type: "text", text: `${res.status}: ${text}` }] };
+    }
+    // The gateway returns the underlying MCP result ({ content, isError }) verbatim.
+    try {
+        const parsed = JSON.parse(text);
+        if (parsed && Array.isArray(parsed.content))
+            return parsed;
+        return { content: [{ type: "text", text }] };
+    }
+    catch {
+        return { content: [{ type: "text", text }] };
+    }
+}
+const server = new Server({ name: "gateway-tools", version: "0.1.0" }, { capabilities: { tools: {} } });
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    const tools = await fetchTools();
+    return {
+        tools: tools.map((t) => ({
+            name: t.name,
+            description: `[${t.server}] ${t.description || ""}`.trim(),
+            inputSchema: t.inputSchema || { type: "object" },
+        })),
+    };
+});
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    const { name, arguments: args } = req.params;
+    try {
+        return await callTool(name, (args ?? {}));
+    }
+    catch (err) {
+        return { isError: true, content: [{ type: "text", text: err?.message ?? String(err) }] };
+    }
+});
+const transport = new StdioServerTransport();
+await server.connect(transport);
+process.stderr.write(`[gateway-bridge] connected, target ${ROBOTYX_URL}\n`);