control_run

Instructions

Implementation Reference

• index.js:1766-1815 (handler)

  The main handler function for the 'control_run' tool. It sends a POST request to the Opentrons robot's /runs/{run_id}/actions endpoint with the specified action (play, pause, stop, resume-from-recovery), fetches the updated run status, and returns a formatted response with success or error message.

  async controlRun(args) {
    const { robot_ip, run_id, action } = args;
    
    try {
      const body = {
        data: {
          actionType: action
        }
      };
      
      const data = await this.makeApiRequest(
        'POST',
        `http://${robot_ip}:31950/runs/${run_id}/actions`,
        { 'Content-Type': 'application/json' },
        JSON.stringify(body)
      );
      
      const actionData = data.data;
      
      // Get updated run status
      const runData = await this.makeApiRequest(
        'GET',
        `http://${robot_ip}:31950/runs/${run_id}`
      );
      
      const run = runData.data;
      
      return {
        content: [
          {
            type: "text",
            text: `✅ Run action '${action}' executed successfully!\n\n` +
                  `**Action ID:** ${actionData.id}\n` +
                  `**Run Status:** ${run.status}\n` +
                  `**Current Action:** ${run.actions?.[run.actions.length - 1]?.actionType || 'None'}\n` +
                  `**Completed At:** ${run.completedAt ? new Date(run.completedAt).toLocaleString() : 'Not completed'}\n`
          }
        ]
      };
    } catch (error) {
      return {
        content: [
          {
            type: "text",
            text: `❌ Failed to control run: ${error.message}`
          }
        ]
      };
    }
  }

• index.js:152-163 (schema)

  Input schema definition for the 'control_run' tool, defining parameters: robot_ip (string), run_id (string), action (enum: play, pause, stop, resume-from-recovery). Included in the tools list returned by ListToolsRequestSchema.

    name: "control_run",
    description: "Control run execution (play, pause, stop, resume)",
    inputSchema: {
      type: "object",
      properties: {
        robot_ip: { type: "string", description: "Robot IP address" },
        run_id: { type: "string", description: "Run ID to control" },
        action: { type: "string", enum: ["play", "pause", "stop", "resume-from-recovery"], description: "Action to perform" }
      },
      required: ["robot_ip", "run_id", "action"]
    }
  },

• index.js:256-257 (registration)

  Registration of the 'control_run' tool handler in the CallToolRequestSchema switch statement, dispatching calls to this.controlRun(args).

  case "control_run":
    return this.controlRun(args);

• index.js:1476-1504 (helper)

  Helper method used by controlRun (and other tools) to make authenticated HTTP requests to the Opentrons robot API, handling Opentrons-Version header and common errors like connection refused.

  async makeApiRequest(method, url, headers = {}, body = null) {
    try {
      const options = {
        method,
        headers: {
          'Opentrons-Version': '*',
          ...headers
        }
      };
      
      if (body) {
        options.body = body;
      }
      
      const response = await fetch(url, options);
      const data = await response.json();
      
      if (!response.ok) {
        throw new Error(`API Error ${response.status}: ${data.message || JSON.stringify(data)}`);
      }
      
      return data;
    } catch (error) {
      if (error.code === 'ECONNREFUSED') {
        throw new Error(`Cannot connect to robot. Please check the IP address and ensure the robot is powered on.`);
      }
      throw error;
    }
  }