Opentrons MCP Server

Instructions

Implementation Reference

• index.js:1507-1659 (handler)

  The main handler function that executes the upload_protocol tool. It validates the input file, constructs a curl command to POST multipart form data to the Opentrons robot's /protocols endpoint, handles errors, and returns formatted success/error responses.

  async uploadProtocol(args) {
    const { robot_ip, file_path, support_files = [], protocol_kind = "standard" } = args;
    
    try {
      // Import required modules
      const fs = await import('fs');
      const path = await import('path');
      
      // Check if main protocol file exists and is readable
      if (!fs.existsSync(file_path)) {
        return {
          content: [{
            type: "text",
            text: `❌ **File not found**: ${file_path}\n\nPlease check:\n- File path is correct\n- File exists\n- You have read permissions`
          }]
        };
      }
  
      // Check file permissions
      try {
        fs.accessSync(file_path, fs.constants.R_OK);
      } catch (err) {
        return {
          content: [{
            type: "text", 
            text: `❌ **Permission denied**: Cannot read ${file_path}\n\nTry:\n- \`chmod 644 "${file_path}"\`\n- Moving file to a readable location\n- Running with proper permissions`
          }]
        };
      }
  
      // Validate file extension
      const ext = path.extname(file_path).toLowerCase();
      if (!['.py', '.json'].includes(ext)) {
        return {
          content: [{
            type: "text",
            text: `❌ **Invalid file type**: ${ext}\n\nOpentrons protocols must be:\n- Python files (.py)\n- JSON protocol files (.json)`
          }]
        };
      }
  
      // For now, let's use curl instead of trying to fight FormData
      const { exec } = await import('child_process');
      const { promisify } = await import('util');
      const execAsync = promisify(exec);
  
      // Build curl command
      let curlCmd = `curl -X POST "http://${robot_ip}:31950/protocols"`;
      curlCmd += ` -H "Opentrons-Version: *"`;
      curlCmd += ` -H "accept: application/json"`;
      curlCmd += ` -F "files=@${file_path}"`;
      
      // Add support files
      for (const supportPath of support_files) {
        if (fs.existsSync(supportPath)) {
          curlCmd += ` -F "supportFiles=@${supportPath}"`;
        }
      }
      
      // Add protocol kind if not standard
      if (protocol_kind !== "standard") {
        curlCmd += ` -F "protocolKind=${protocol_kind}"`;
      }
  
      console.error(`Executing: ${curlCmd}`);
      
      const { stdout, stderr } = await execAsync(curlCmd);
      
      if (stderr && !stderr.includes('% Total')) {
        throw new Error(`Curl error: ${stderr}`);
      }
  
      let responseData;
      try {
        responseData = JSON.parse(stdout);
      } catch (parseErr) {
        return {
          content: [{
            type: "text",
            text: `❌ **Upload failed** - Invalid response from robot\n\n**Response**: ${stdout.slice(0, 500)}${stdout.length > 500 ? '...' : ''}\n\n**Possible issues**:\n- Robot not reachable at ${robot_ip}:31950\n- Robot server not running\n- Network connectivity problems`
          }]
        };
      }
  
      // Check for errors in response
      if (responseData.errors || (responseData.data && responseData.data.errors)) {
        const errors = responseData.errors || responseData.data.errors || [];
        let errorDetails = `❌ **Upload failed**\n\n`;
        
        if (errors.length > 0) {
          errorDetails += `**Protocol Errors**:\n${errors.map(err => `- ${err.detail || err.message || err}`).join('\n')}\n`;
        } else {
          errorDetails += `**Error**: ${responseData.message || 'Unknown error'}\n`;
        }
        
        errorDetails += `\n**Troubleshooting**:\n`;
        errorDetails += `- Check robot is connected: \`curl http://${robot_ip}:31950/health\`\n`;
        errorDetails += `- Verify protocol file syntax\n`;
        errorDetails += `- Try uploading via Opentrons App first\n`;
        
        return {
          content: [{
            type: "text",
            text: errorDetails
          }]
        };
      }
  
      // Success response
      const protocolId = responseData?.data?.id;
      const protocolName = responseData?.data?.metadata?.protocolName || path.basename(file_path);
      const apiVersion = responseData?.data?.metadata?.apiLevel || 'Unknown';
      
      let successMsg = `✅ **Protocol uploaded successfully!**\n\n`;
      successMsg += `**Protocol ID**: \`${protocolId}\`\n`;
      successMsg += `**Name**: ${protocolName}\n`;
      successMsg += `**API Version**: ${apiVersion}\n`;
      successMsg += `**File**: ${path.basename(file_path)}\n`;
      
      if (support_files.length > 0) {
        successMsg += `**Support Files**: ${support_files.length} files\n`;
      }
      
      successMsg += `\n**Next Steps**:\n`;
      successMsg += `1. Create a run: \`POST /runs\` with \`{"data": {"protocolId": "${protocolId}"}}\`\n`;
      successMsg += `2. Start run: \`POST /runs/{run_id}/actions\` with \`{"data": {"actionType": "play"}}\`\n`;
      
      // Check for analysis warnings
      if (responseData?.data?.analyses?.length > 0) {
        const analysis = responseData.data.analyses[0];
        if (analysis.status === 'completed' && analysis.result === 'ok') {
          successMsg += `\n✅ **Protocol analysis passed** - Ready to run\n`;
        } else if (analysis.status === 'completed' && analysis.result === 'error') {
          successMsg += `\n⚠️ **Protocol analysis found issues** - Check protocol before running\n`;
        }
      }
      
      return {
        content: [{
          type: "text",
          text: successMsg
        }]
      };
  
    } catch (error) {
      return {
        content: [{
          type: "text",
          text: `❌ **Upload error**: ${error.message}\n\n**Possible causes**:\n- Robot not reachable at ${robot_ip}:31950\n- Network connectivity issues\n- File permissions\n- curl not installed\n\n**Debug info**: ${error.stack?.split('\n')[0] || 'No stack trace'}`
        }]
      };
    }
  }

• index.js:112-125 (schema)

  The JSON schema defining the input parameters and structure for the upload_protocol tool, including required fields robot_ip and file_path.

    name: "upload_protocol",
    description: "Upload a protocol file to an Opentrons robot",
    inputSchema: {
      type: "object",
      properties: {
        robot_ip: { type: "string", description: "Robot IP address (e.g., '192.168.1.100')" },
        file_path: { type: "string", description: "Path to protocol file (.py or .json)" },
        protocol_kind: { type: "string", enum: ["standard", "quick-transfer"], default: "standard" },
        key: { type: "string", description: "Optional client tracking key (~100 chars)" },
        run_time_parameters: { type: "object", description: "Optional runtime parameter values" }
      },
      required: ["robot_ip", "file_path"]
    }
  },

• index.js:250-252 (registration)

  The dispatch case in the CallToolRequestSchema handler that routes calls to the uploadProtocol method.

  case "upload_protocol":
    return this.uploadProtocol(args);
  case "get_protocols":