Opentrons MCP Server

Instructions

Implementation Reference

• index.js:1387-1473 (handler)

  The main handler function for the 'get_api_overview' tool. It generates a comprehensive Markdown overview of the Opentrons HTTP API, including statistics on endpoints and methods, category breakdowns with descriptions, getting started guide, important notes, and common workflows for protocol execution, calibration, and hardware control.
  getApiOverview() { const categories = [...new Set(this.endpoints.flatMap(e => e.tags))]; const totalEndpoints = this.endpoints.length; const deprecatedCount = this.endpoints.filter(e => e.deprecated).length; const methodCounts = this.endpoints.reduce((acc, e) => { acc[e.method] = (acc[e.method] || 0) + 1; return acc; }, {}); let overview = `# Opentrons HTTP API Overview\n\n`; overview += `The Opentrons HTTP API provides comprehensive control over Opentrons Flex and OT-2 robots. This RESTful API runs on port 31950 and enables protocol execution, hardware control, calibration, and system management.\n\n`; overview += `## API Statistics\n\n`; overview += `- **Total Endpoints**: ${totalEndpoints}\n`; overview += `- **Deprecated Endpoints**: ${deprecatedCount}\n`; overview += `- **HTTP Methods**: ${Object.entries(methodCounts).map(([method, count]) => `${method} (${count})`).join(', ')}\n\n`; overview += `## API Categories\n\n`; const categoryDescriptions = { 'Health': 'Monitor robot status, get logs, check server health', 'Networking': 'Configure Wi-Fi, manage network settings, connectivity status', 'Control': 'Direct hardware control - movement, homing, lights, motors', 'Settings': 'Robot configuration, feature flags, calibration settings', 'Run Management': 'Execute protocols, control run state (play/pause/stop)', 'Protocol Management': 'Upload, analyze, and manage protocol files', 'Maintenance Run Management': 'Calibration workflows and diagnostics', 'Attached Modules': 'Control temperature modules, magnetic modules, etc.', 'Attached Instruments': 'Pipette information and configuration', 'Data files Management': 'CSV data files for runtime parameters', 'Simple Commands': 'Execute individual robot commands', 'Labware Offset Management': 'Calibration data for labware positioning', 'System Control': 'System time, restart, low-level system operations', 'Client Data': 'Store arbitrary key-value data on robot', 'Flex Deck Configuration': 'Flex-specific deck setup and configuration', 'Error Recovery Settings': 'Configure error handling policies' }; categories.forEach(category => { const count = this.endpoints.filter(e => e.tags.includes(category)).length; const description = categoryDescriptions[category] || 'Robot functionality'; overview += `- **${category}** (${count} endpoints): ${description}\n`; }); overview += `\n## Getting Started\n\n`; overview += `1. **Check Robot Health**: Start with \`GET /health\` to verify connectivity\n`; overview += `2. **Network Setup**: Use \`/networking/status\` and \`/wifi/*\` endpoints for network configuration\n`; overview += `3. **Upload Protocol**: Use \`POST /protocols\` to upload protocol files\n`; overview += `4. **Create Run**: Use \`POST /runs\` to create a protocol run\n`; overview += `5. **Execute**: Use \`POST /runs/{id}/actions\` to play/pause/stop runs\n`; overview += `6. **Monitor**: Use \`GET /runs/{id}\` and \`GET /runs/{id}/commands\` to monitor progress\n\n`; overview += `## Important Notes\n\n`; overview += `- **API Versioning**: All requests must include \`Opentrons-Version\` header (use "*" for latest)\n`; overview += `- **Port**: API runs on port 31950\n`; overview += `- **OpenAPI Spec**: Available at \`/openapi\` endpoint\n`; overview += `- **Documentation**: Interactive docs at \`/redoc\`\n`; overview += `- **Robot Differences**: Some endpoints are OT-2 or Flex specific\n`; overview += `- **Deprecated Endpoints**: ${deprecatedCount} endpoints are deprecated - use modern alternatives\n\n`; overview += `## Common Workflows\n\n`; overview += `### Protocol Execution\n`; overview += `1. Upload protocol: \`POST /protocols\`\n`; overview += `2. Create run: \`POST /runs\`\n`; overview += `3. Start execution: \`POST /runs/{id}/actions\` with "play"\n`; overview += `4. Monitor progress: \`GET /runs/{id}/commands\`\n\n`; overview += `### Robot Calibration\n`; overview += `1. Create maintenance run: \`POST /maintenance_runs\`\n`; overview += `2. Execute calibration commands: \`POST /maintenance_runs/{id}/commands\`\n`; overview += `3. Check calibration status: \`GET /calibration/status\`\n\n`; overview += `### Hardware Control\n`; overview += `1. Home robot: \`POST /robot/home\`\n`; overview += `2. Check attached instruments: \`GET /instruments\`\n`; overview += `3. Control lights: \`POST /robot/lights\`\n`; overview += `4. Execute simple commands: \`POST /commands\`\n\n`; return { content: [ { type: "text", text: overview } ] }; }
• index.js:102-110 (registration)

  Registration of the 'get_api_overview' tool in the ListToolsRequestSchema handler, including name, description, and empty input schema (no parameters required).
  { name: "get_api_overview", description: "Get high-level overview of the Opentrons HTTP API structure and capabilities", inputSchema: { type: "object", properties: {}, additionalProperties: false } },
• index.js:248-250 (registration)

  Dispatch registration in the CallToolRequestSchema switch statement that routes calls to the getApiOverview() handler method.
  case "get_api_overview": return this.getApiOverview(); case "upload_protocol":
• index.js:105-109 (schema)

  Input schema definition for the tool: an empty object (no input parameters required).
  inputSchema: { type: "object", properties: {}, additionalProperties: false }