@smartbear/mcp 0.14.1 → 0.16.0

package/dist/reflect/client.js

@@ -1,18 +1,39 @@
 import { z } from "zod";
 import { MCP_SERVER_NAME, MCP_SERVER_VERSION } from "../common/info.js";
 import { ToolError } from "../common/tools.js";
+import { API_KEY_HEADER } from "./config/constants.js";
+import { SapTest } from "./prompt/sap-test.js";
+import { AddPromptStep } from "./tool/recording/add-prompt-step.js";
+import { AddSegment } from "./tool/recording/add-segment.js";
+import { ConnectToSession } from "./tool/recording/connect-to-session.js";
+import { DeletePreviousStep } from "./tool/recording/delete-previous-step.js";
+import { GetScreenshot } from "./tool/recording/get-screenshot.js";
+import { CancelSuiteExecution } from "./tool/suites/cancel-suite-execution.js";
+import { ExecuteSuite } from "./tool/suites/execute-suite.js";
+import { GetSuiteExecutionStatus } from "./tool/suites/get-suite-execution-status.js";
+import { ListSuiteExecutions } from "./tool/suites/list-suite-executions.js";
+import { ListSuites } from "./tool/suites/list-suites.js";
+import { GetTestStatus } from "./tool/tests/get-test-status.js";
+import { ListSegments } from "./tool/tests/list-segments.js";
+import { ListTests } from "./tool/tests/list-tests.js";
+import { RunTest } from "./tool/tests/run-test.js";
 const ConfigurationSchema = z.object({
   api_token: z.string().describe("Reflect API authentication token")
 });
 class ReflectClient {
   headers = {};
+  apiToken = "";
+  activeConnections = /* @__PURE__ */ new Map();
+  sessionStates = /* @__PURE__ */ new Map();
+  mcpSessionConnections = /* @__PURE__ */ new Map();
   name = "Reflect";
   toolPrefix = "reflect";
   configPrefix = "Reflect";
   config = ConfigurationSchema;
   async configure(_server, config, _cache) {
+    this.apiToken = config.api_token;
     this.headers = {
-      "X-API-KEY": `${config.api_token}`,
+      [API_KEY_HEADER]: `${config.api_token}`,
       "Content-Type": "application/json",
       "User-Agent": `${MCP_SERVER_NAME}/${MCP_SERVER_VERSION}`
     };
@@ -20,269 +41,75 @@ class ReflectClient {
   isConfigured() {
     return Object.keys(this.headers).length !== 0;
   }
-  async listReflectSuites() {
-    const response = await fetch("https://api.reflect.run/v1/suites", {
-      method: "GET",
-      headers: this.headers
-    });
-    return response.json();
+  getApiToken() {
+    return this.apiToken;
   }
-  async listSuiteExecutions(suiteId) {
-    const response = await fetch(
-      `https://api.reflect.run/v1/suites/${suiteId}/executions`,
-      {
-        method: "GET",
-        headers: this.headers
-      }
-    );
-    return response.json();
-  }
-  async getSuiteExecutionStatus(suiteId, executionId) {
-    const response = await fetch(
-      `https://api.reflect.run/v1/suites/${suiteId}/executions/${executionId}`,
-      {
-        method: "GET",
-        headers: this.headers
-      }
-    );
-    return response.json();
+  getHeaders() {
+    return this.headers;
   }
-  async executeSuite(suiteId) {
-    const response = await fetch(
-      `https://api.reflect.run/v1/suites/${suiteId}/executions`,
-      {
-        method: "POST",
-        headers: this.headers
-      }
-    );
-    return response.json();
+  getSessionState(sessionId) {
+    return this.sessionStates.get(sessionId);
   }
-  async cancelSuiteExecution(suiteId, executionId) {
-    const response = await fetch(
-      `https://api.reflect.run/v1/suites/${suiteId}/executions/${executionId}/cancel`,
-      {
-        method: "PATCH",
-        headers: this.headers
-      }
-    );
-    return response.json();
+  isSessionConnected(sessionId) {
+    const wsManager = this.activeConnections.get(sessionId);
+    return wsManager?.isConnected() ?? false;
   }
-  async listReflectTests() {
-    const response = await fetch("https://api.reflect.run/v1/tests", {
-      method: "GET",
-      headers: this.headers
-    });
-    return response.json();
+  getConnectedSession(sessionId) {
+    if (!this.isSessionConnected(sessionId)) {
+      throw new ToolError(
+        `Session ${sessionId} is not connected. Call connect_to_session first.`
+      );
+    }
+    return this.activeConnections.get(sessionId);
   }
-  async runReflectTest(testId) {
-    const response = await fetch(
-      `https://api.reflect.run/v1/tests/${testId}/executions`,
-      {
-        method: "POST",
-        headers: this.headers
-      }
-    );
-    return response.json();
+  registerConnection(sessionId, ws, state, mcpSessionId) {
+    this.activeConnections.set(sessionId, ws);
+    this.sessionStates.set(sessionId, state);
+    if (mcpSessionId) {
+      const existing = this.mcpSessionConnections.get(mcpSessionId) ?? /* @__PURE__ */ new Set();
+      existing.add(sessionId);
+      this.mcpSessionConnections.set(mcpSessionId, existing);
+    }
   }
-  async getReflectTestStatus(_testId, executionId) {
-    const response = await fetch(
-      `https://api.reflect.run/v1/executions/${executionId}`,
-      {
-        method: "GET",
-        headers: this.headers
+  async cleanupSession(mcpSessionId) {
+    const reflectSessionIds = this.mcpSessionConnections.get(mcpSessionId);
+    if (!reflectSessionIds) return;
+    for (const reflectSessionId of reflectSessionIds) {
+      const ws = this.activeConnections.get(reflectSessionId);
+      if (ws) {
+        await ws.disconnect();
+        this.activeConnections.delete(reflectSessionId);
+        this.sessionStates.delete(reflectSessionId);
       }
-    );
-    return response.json();
+    }
+    this.mcpSessionConnections.delete(mcpSessionId);
   }
   async registerTools(register, _getInput) {
-    register(
-      {
-        title: "List Suites",
-        summary: "Retrieve a list of all reflect suites available",
-        parameters: []
-      },
-      async (_args, _extra) => {
-        const response = await this.listReflectSuites();
-        return {
-          content: [{ type: "text", text: JSON.stringify(response) }]
-        };
-      }
-    );
-    register(
-      {
-        title: "List Suite Executions",
-        summary: "List all executions for a given suite",
-        parameters: [
-          {
-            name: "suiteId",
-            type: z.string(),
-            description: "ID of the reflect suite to list executions for",
-            required: true
-          }
-        ]
-      },
-      async (args, _extra) => {
-        if (!args.suiteId) throw new ToolError("suiteId argument is required");
-        const response = await this.listSuiteExecutions(args.suiteId);
-        return {
-          content: [{ type: "text", text: JSON.stringify(response) }]
-        };
-      }
-    );
-    register(
-      {
-        title: "Get Suite Execution Status",
-        summary: "Get the status of a reflect suite execution",
-        parameters: [
-          {
-            name: "suiteId",
-            type: z.string(),
-            description: "ID of the reflect suite to get execution status for",
-            required: true
-          },
-          {
-            name: "executionId",
-            type: z.string(),
-            description: "ID of the reflect suite execution to get status for",
-            required: true
-          }
-        ]
-      },
-      async (args, _extra) => {
-        if (!args.suiteId || !args.executionId)
-          throw new ToolError(
-            "Both suiteId and executionId arguments are required"
-          );
-        const response = await this.getSuiteExecutionStatus(
-          args.suiteId,
-          args.executionId
-        );
-        return {
-          content: [{ type: "text", text: JSON.stringify(response) }]
-        };
-      }
-    );
-    register(
-      {
-        title: "Execute Suite",
-        summary: "Execute a reflect suite",
-        parameters: [
-          {
-            name: "suiteId",
-            type: z.string(),
-            description: "ID of the reflect suite to list executions for",
-            required: true
-          }
-        ]
-      },
-      async (args, _extra) => {
-        if (!args.suiteId) throw new ToolError("suiteId argument is required");
-        const response = await this.executeSuite(args.suiteId);
-        return {
-          content: [{ type: "text", text: JSON.stringify(response) }]
-        };
-      }
-    );
-    register(
-      {
-        title: "Cancel Suite Execution",
-        summary: "Cancel a reflect suite execution",
-        parameters: [
-          {
-            name: "suiteId",
-            type: z.string(),
-            description: "ID of the reflect suite to cancel execution for",
-            required: true
-          },
-          {
-            name: "executionId",
-            type: z.string(),
-            description: "ID of the reflect suite execution to cancel",
-            required: true
-          }
-        ]
-      },
-      async (args, _extra) => {
-        if (!args.suiteId || !args.executionId)
-          throw new ToolError(
-            "Both suiteId and executionId arguments are required"
-          );
-        const response = await this.cancelSuiteExecution(
-          args.suiteId,
-          args.executionId
-        );
-        return {
-          content: [{ type: "text", text: JSON.stringify(response) }]
-        };
-      }
-    );
-    register(
-      {
-        title: "List Tests",
-        summary: "List all reflect tests",
-        parameters: []
-      },
-      async (_args, _extra) => {
-        const response = await this.listReflectTests();
-        return {
-          content: [{ type: "text", text: JSON.stringify(response) }]
-        };
-      }
-    );
-    register(
-      {
-        title: "Run Test",
-        summary: "Run a reflect test",
-        parameters: [
-          {
-            name: "testId",
-            type: z.string(),
-            description: "ID of the reflect test to run",
-            required: true
-          }
-        ]
-      },
-      async (args, _extra) => {
-        if (!args.testId) throw new ToolError("testId argument is required");
-        const response = await this.runReflectTest(args.testId);
-        return {
-          content: [{ type: "text", text: JSON.stringify(response) }]
-        };
-      }
-    );
-    register(
-      {
-        title: "Get Test Status",
-        summary: "Get the status of a reflect test execution",
-        parameters: [
-          {
-            name: "testId",
-            type: z.string(),
-            description: "ID of the reflect test to run",
-            required: true
-          },
-          {
-            name: "executionId",
-            type: z.string(),
-            description: "ID of the reflect test execution to get status for",
-            required: true
-          }
-        ]
-      },
-      async (args, _extra) => {
-        if (!args.testId || !args.executionId)
-          throw new ToolError(
-            "Both testId and executionId arguments are required"
-          );
-        const response = await this.getReflectTestStatus(
-          args.testId,
-          args.executionId
-        );
-        return {
-          content: [{ type: "text", text: JSON.stringify(response) }]
-        };
-      }
-    );
+    const tools = [
+      new ListSuites(this),
+      new ListSuiteExecutions(this),
+      new GetSuiteExecutionStatus(this),
+      new ExecuteSuite(this),
+      new CancelSuiteExecution(this),
+      new ListTests(this),
+      new RunTest(this),
+      new GetTestStatus(this),
+      new ListSegments(this),
+      new ConnectToSession(this),
+      new AddPromptStep(this),
+      new GetScreenshot(this),
+      new DeletePreviousStep(this),
+      new AddSegment(this)
+    ];
+    for (const tool of tools) {
+      register(tool.specification, tool.handle);
+    }
+  }
+  registerPrompts(register) {
+    const prompts = [new SapTest(this)];
+    for (const prompt of prompts) {
+      register(prompt.name, prompt.params, prompt.callback);
+    }
   }
 }
 export {

package/dist/reflect/config/constants.js

@@ -0,0 +1,8 @@
+const API_KEY_HEADER = "X-API-KEY";
+const API_HOSTNAME = "api.reflect.run";
+const WEBSOCKET_HOSTNAME = "recording.us-east-1.reflect.run";
+export {
+  API_HOSTNAME,
+  API_KEY_HEADER,
+  WEBSOCKET_HOSTNAME
+};

package/dist/reflect/prompt/sap-test.js

@@ -0,0 +1,29 @@
+import { Prompt } from "../../common/prompts.js";
+class SapTest extends Prompt {
+  name = "reflect-sap-test";
+  params = {
+    title: "Reflect SAP Test",
+    description: "Guidelines for creating a Reflect test against an SAP S4/HANA or SAP BTP application.",
+    argsSchema: {}
+  };
+  callback = () => ({
+    messages: [
+      {
+        role: "user",
+        content: {
+          type: "text",
+          text: `When creating an SAP test:
+        1. Always precede an input step with a click step.
+        2. Always capture a screenshot after each step, even form field actions.
+        3. If text is ellipsized with a hyphen, do not include the hyphen in your prompt step.
+        4. If you navigate to the wrong page, use browser navigation (e.g. "Click the back button") or on-screen navigation to get to the prior screen. Make sure to delete the original step and any steps you added to navigate back to the previous screen so that the test is repeatable and contains no unnecessary steps.
+        5. When applicable, use the prompt "Press the tab key" to tab through fields and the prompt "Press the enter key" to submit a form.
+        6. When building tests from BPD docs, if the input value for the next step is based on an example value in the doc, prompt the user to ask for their desired value. Provide the example value in your prompt so the user has additional context.`
+        }
+      }
+    ]
+  });
+}
+export {
+  SapTest
+};

package/dist/reflect/tool/recording/add-prompt-step.js

@@ -0,0 +1,60 @@
+import { randomUUID } from "node:crypto";
+import { z } from "zod";
+import { Tool, ToolError } from "../../../common/tools.js";
+class AddPromptStep extends Tool {
+  specification = {
+    title: "Add Prompt Step",
+    summary: "Add a natural language prompt step to an active Reflect recording session",
+    readOnly: false,
+    idempotent: false,
+    parameters: [
+      {
+        name: "sessionId",
+        type: z.string(),
+        description: "The ID of the Reflect recording session",
+        required: true
+      },
+      {
+        name: "prompt",
+        type: z.string(),
+        description: 'The natural language prompt describing the test step. The prompt should describe a single action, assertion, or query. The prompt can only contain literal text; it cannot contain template variables, secrets, or other dynamic syntax. If we are in a Web recording, the prompt can perform browser navigation (e.g. "Click on the back button", "Navigate to https://www.example.com") and use the tab and enter keys to navigate (e.g. "Press the tab key", "Press the enter key").',
+        required: true
+      }
+    ]
+  };
+  handle = async (args) => {
+    const { sessionId, prompt } = args;
+    if (!sessionId) throw new ToolError("sessionId argument is required");
+    if (!prompt) throw new ToolError("prompt argument is required");
+    const wsManager = this.client.getConnectedSession(sessionId);
+    const id = randomUUID();
+    const responsePromise = wsManager.waitForResponse(id);
+    await wsManager.sendMcpMessage({
+      type: "mcp:add-prompt-step",
+      id,
+      prompt
+    });
+    const response = await responsePromise;
+    const result = response.result;
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            success: true,
+            sessionId,
+            message: `Successfully added prompt step: "${prompt}"`,
+            intent: {
+              prompt,
+              type: result?.type,
+              response: result?.response
+            }
+          })
+        }
+      ]
+    };
+  };
+}
+export {
+  AddPromptStep
+};

package/dist/reflect/tool/recording/add-segment.js

@@ -0,0 +1,56 @@
+import { randomUUID } from "node:crypto";
+import { z } from "zod";
+import { Tool, ToolError } from "../../../common/tools.js";
+class AddSegment extends Tool {
+  specification = {
+    title: "Add Segment",
+    summary: "Insert a reusable test segment into an active Reflect recording session",
+    readOnly: false,
+    idempotent: false,
+    parameters: [
+      {
+        name: "sessionId",
+        type: z.string(),
+        description: "The ID of the Reflect recording session",
+        required: true
+      },
+      {
+        name: "segmentId",
+        type: z.number(),
+        description: "The ID of the segment to add",
+        required: true
+      }
+    ]
+  };
+  handle = async (args) => {
+    const { sessionId, segmentId } = args;
+    if (!sessionId) throw new ToolError("sessionId argument is required");
+    if (segmentId === void 0 || segmentId === null)
+      throw new ToolError("segmentId argument is required");
+    const wsManager = this.client.getConnectedSession(sessionId);
+    const id = randomUUID();
+    const responsePromise = wsManager.waitForResponse(id);
+    await wsManager.sendMcpMessage({
+      type: "mcp:add-segment",
+      id,
+      segmentId
+    });
+    await responsePromise;
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            success: true,
+            sessionId,
+            message: `Successfully added and executed segment ${segmentId}`,
+            segmentId
+          })
+        }
+      ]
+    };
+  };
+}
+export {
+  AddSegment
+};

package/dist/reflect/tool/recording/connect-to-session.js

@@ -0,0 +1,89 @@
+import { randomUUID } from "node:crypto";
+import { z } from "zod";
+import { Tool, ToolError } from "../../../common/tools.js";
+import { WebSocketManager } from "../../websocket-manager.js";
+class ConnectToSession extends Tool {
+  specification = {
+    title: "Connect To Session",
+    summary: `Connect to an active Reflect recording session via WebSocket to enable interactive control. When creating or editing a Reflect test using a connected recording session, follow these guidelines:
+
+1. After connecting to a session, get the list of segments for the session's platform type so you know what actions could be added via segments vs needing to create new steps. Do not list tests, only list segments.
+2. Before performing an action, take a screenshot to understand the current state of the application.
+3. Each add_prompt_step request should perform a single action or assertion. Do not combine multiple actions or assertions into a single step.
+4. Only perform one action at a time unless you're sure the action won't move the application to a different screen. For example, you can send multiple add_prompt_step requests to fill out individual form fields if those fields are visible on the current screen.
+5. Check the list of existing Segments to see if a Segment exists that achieves a similar goal to what you're trying to do next. If so, add the segment instead of creating new steps.
+6. If a step fails, use delete_previous_step to remove it and try a different approach.
+7. After completing a task, if the task required multiple prompt steps, add a final prompt step that validates the current state of the page based on what you see on the screen. In your validation, do not reference information that can change from run to run.`,
+    readOnly: false,
+    idempotent: true,
+    parameters: [
+      {
+        name: "sessionId",
+        type: z.string(),
+        description: "The ID of the Reflect recording session to connect to",
+        required: true
+      }
+    ]
+  };
+  handle = async (args, extra) => {
+    const { sessionId } = args;
+    if (!sessionId) throw new ToolError("sessionId argument is required");
+    if (this.client.isSessionConnected(sessionId)) {
+      const state = this.client.getSessionState(sessionId);
+      const { platform: platform2, test: test2 } = state;
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({ success: true, sessionId, platform: platform2, test: test2 })
+          }
+        ]
+      };
+    }
+    const wsManager = new WebSocketManager(
+      sessionId,
+      this.client.getApiToken()
+    );
+    try {
+      await wsManager.connect();
+    } catch (error) {
+      throw new ToolError(
+        `Failed to connect to session: ${error.message}`
+      );
+    }
+    const connectId = randomUUID();
+    let connectResponse;
+    try {
+      const connectResponsePromise = wsManager.waitForResponse(connectId);
+      await wsManager.sendMcpMessage({
+        type: "mcp:connect-to-session",
+        id: connectId
+      });
+      connectResponse = await connectResponsePromise;
+    } catch (connectError) {
+      await wsManager.disconnect();
+      throw new ToolError(
+        `MCP connect-to-session failed: ${connectError instanceof Error ? connectError.message : String(connectError)}`
+      );
+    }
+    const mcpSessionId = extra?.sessionId;
+    const { platform, test } = connectResponse;
+    this.client.registerConnection(
+      sessionId,
+      wsManager,
+      { platform, test },
+      mcpSessionId
+    );
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({ success: true, sessionId, platform, test })
+        }
+      ]
+    };
+  };
+}
+export {
+  ConnectToSession
+};

package/dist/reflect/tool/recording/delete-previous-step.js

@@ -0,0 +1,47 @@
+import { randomUUID } from "node:crypto";
+import { z } from "zod";
+import { Tool, ToolError } from "../../../common/tools.js";
+class DeletePreviousStep extends Tool {
+  specification = {
+    title: "Delete Previous Step",
+    summary: "Delete the last step added to an active Reflect recording session",
+    readOnly: false,
+    idempotent: false,
+    destructive: true,
+    parameters: [
+      {
+        name: "sessionId",
+        type: z.string(),
+        description: "The ID of the Reflect recording session",
+        required: true
+      }
+    ]
+  };
+  handle = async (args) => {
+    const { sessionId } = args;
+    if (!sessionId) throw new ToolError("sessionId argument is required");
+    const wsManager = this.client.getConnectedSession(sessionId);
+    const id = randomUUID();
+    const responsePromise = wsManager.waitForResponse(id);
+    await wsManager.sendMcpMessage({
+      type: "mcp:delete-step",
+      id
+    });
+    await responsePromise;
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            success: true,
+            sessionId,
+            message: "Successfully deleted previous step"
+          })
+        }
+      ]
+    };
+  };
+}
+export {
+  DeletePreviousStep
+};