get_protocols

Instructions

Implementation Reference

• index.js:1661-1716 (handler)

  The handler function that implements the get_protocols tool. It makes a GET request to the Opentrons robot's /protocols endpoint, optionally filters by protocol_kind, formats the list of protocols with details like ID, name, type, creation date, analysis status, and author, and returns a formatted text response.

  async getProtocols(args) {
    const { robot_ip, protocol_kind } = args;
    
    try {
      const data = await this.makeApiRequest(
        'GET',
        `http://${robot_ip}:31950/protocols`
      );
      
      let protocols = data.data || [];
      
      // Filter by kind if specified
      if (protocol_kind) {
        protocols = protocols.filter(p => p.protocolKind === protocol_kind);
      }
      
      if (protocols.length === 0) {
        return {
          content: [
            {
              type: "text",
              text: `No protocols found on robot${protocol_kind ? ` of type '${protocol_kind}'` : ''}.`
            }
          ]
        };
      }
      
      const protocolList = protocols.map(p => {
        const analysis = p.analysisSummaries?.[0];
        return `**${p.metadata?.protocolName || p.files[0]?.name || 'Unnamed Protocol'}**\n` +
               `  ID: ${p.id}\n` +
               `  Type: ${p.protocolKind || 'standard'}\n` +
               `  Created: ${new Date(p.createdAt).toLocaleString()}\n` +
               `  Analysis: ${analysis?.status || 'No analysis'}\n` +
               `  Author: ${p.metadata?.author || 'Unknown'}\n`;
      }).join('\n');
      
      return {
        content: [
          {
            type: "text",
            text: `Found ${protocols.length} protocol${protocols.length !== 1 ? 's' : ''} on robot:\n\n${protocolList}`
          }
        ]
      };
    } catch (error) {
      return {
        content: [
          {
            type: "text",
            text: `❌ Failed to get protocols: ${error.message}`
          }
        ]
      };
    }
  }

• index.js:126-137 (schema)

  The schema definition for the get_protocols tool, including input parameters: robot_ip (required string) and optional protocol_kind (enum: standard, quick-transfer). This is returned by the ListToolsRequestSchema handler.

  {
    name: "get_protocols", 
    description: "List all protocols stored on the robot",
    inputSchema: {
      type: "object",
      properties: {
        robot_ip: { type: "string", description: "Robot IP address" },
        protocol_kind: { type: "string", enum: ["standard", "quick-transfer"], description: "Filter by protocol type (optional)" }
      },
      required: ["robot_ip"]
    }
  },

• index.js:252-253 (registration)

  The registration of the get_protocols handler in the CallToolRequestSchema switch statement, which dispatches to the getProtocols method.

  case "get_protocols":
    return this.getProtocols(args);

• index.js:1476-1504 (helper)

  Helper method used by get_protocols (and other tools) to make authenticated HTTP requests to the Opentrons robot API, handling Opentrons-Version header, JSON parsing, and common error cases 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;
    }
  }