Conductor MCP Server

# conductor-mcp MCP server for Netflix Conductor Workflow Engine - enables AI assistants to interact with Conductor workflows for troubleshooting, creation, and management. ## Overview This Model Context Protocol (MCP) server provides a comprehensive interface to Netflix Conductor, allowing AI assistants like Claude to help developers: - **Troubleshoot workflows**: Get detailed status, view execution history, analyze failed tasks - **Manage workflow executions**: Start, pause, resume, terminate, restart, and retry workflows - **Work with workflow definitions**: Create, update, and query workflow definitions - **Manage task definitions**: Create, update, and query task definitions - **Search and query**: Advanced search capabilities across workflow executions ## Installation ```bash npm install -g conductor-mcp ``` Or install locally: ```bash npm install conductor-mcp ``` ## Configuration The MCP server connects to your Conductor instance using environment variables: - `CONDUCTOR_SERVER_URL`: Base URL of your Conductor server (default: `http://localhost:8080`) - `CONDUCTOR_API_PATH`: API path prefix (default: `/api`) ### Claude Desktop Configuration Add this to your Claude Desktop configuration file: **MacOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` **Windows**: `%APPDATA%/Claude/claude_desktop_config.json` ```json { "mcpServers": { "conductor": { "command": "conductor-mcp", "env": { "CONDUCTOR_SERVER_URL": "http://localhost:8080", "CONDUCTOR_API_PATH": "/api" } } } } ``` For a remote Conductor server: ```json { "mcpServers": { "conductor": { "command": "conductor-mcp", "env": { "CONDUCTOR_SERVER_URL": "https://conductor.yourcompany.com", "CONDUCTOR_API_PATH": "/api" } } } } ``` ## Available Tools ### Workflow Execution Management #### `list_workflows` List workflow executions with optional filters. **Parameters:** - `workflowName` (optional): Filter by workflow name/type - `status` (optional): Filter by status (RUNNING, COMPLETED, FAILED, TIMED_OUT, TERMINATED, PAUSED) - `startTime` (optional): Filter workflows started after this time (epoch milliseconds) - `endTime` (optional): Filter workflows started before this time (epoch milliseconds) - `freeText` (optional): Free text search **Example:** ``` List all failed workflows in the last 24 hours ``` #### `get_workflow_status` Get detailed status of a specific workflow execution. **Parameters:** - `workflowId` (required): The workflow execution ID - `includeTaskDetails` (optional): Include detailed task information (default: true) **Example:** ``` Get status of workflow abc-123-def ``` #### `start_workflow` Start a new workflow execution. **Parameters:** - `workflowName` (required): Name of the workflow to start - `version` (optional): Version of the workflow (defaults to latest) - `input` (optional): Input parameters as JSON object - `correlationId` (optional): Correlation ID for tracking - `priority` (optional): Priority 0-99 (default: 0) **Example:** ``` Start a new order_processing workflow with input {"orderId": "12345", "customerId": "C789"} ``` #### `pause_workflow` Pause a running workflow. **Parameters:** - `workflowId` (required): The workflow execution ID #### `resume_workflow` Resume a paused workflow. **Parameters:** - `workflowId` (required): The workflow execution ID #### `terminate_workflow` Terminate a workflow execution. **Parameters:** - `workflowId` (required): The workflow execution ID - `reason` (optional): Reason for termination #### `restart_workflow` Restart a workflow from the beginning. **Parameters:** - `workflowId` (required): The workflow execution ID - `useLatestDefinition` (optional): Use latest workflow definition (default: false) #### `retry_workflow` Retry a failed workflow from the last failed task. **Parameters:** - `workflowId` (required): The workflow execution ID - `resumeSubworkflowTasks` (optional): Resume subworkflow tasks (default: false) #### `search_workflows` Advanced search for workflow executions. **Parameters:** - `query` (required): Query string (e.g., 'workflowType=MyWorkflow AND status=FAILED') - `start` (optional): Start index for pagination (default: 0) - `size` (optional): Number of results (default: 100) - `sort` (optional): Sort field and order (e.g., 'startTime:DESC') **Example:** ``` Search for all failed payment workflows in the last week ``` ### Workflow Definition Management #### `get_workflow_definition` Get a workflow definition by name and version. **Parameters:** - `workflowName` (required): Name of the workflow - `version` (optional): Version (defaults to latest) #### `list_workflow_definitions` List all registered workflow definitions. **Parameters:** - `access` (optional): Filter by access type (READ or CREATE) - `tagKey` (optional): Filter by tag key - `tagValue` (optional): Filter by tag value #### `create_workflow_definition` Create or update a workflow definition. **Parameters:** - `definition` (required): Complete workflow definition as JSON object - `overwrite` (optional): Overwrite existing definition (default: true) ### Task Management #### `get_task_details` Get details of a specific task execution. **Parameters:** - `taskId` (required): The task execution ID #### `get_task_logs` Get execution logs for a specific task. **Parameters:** - `taskId` (required): The task execution ID #### `update_task_status` Update the status of a task execution. **Parameters:** - `taskId` (required): The task execution ID - `workflowInstanceId` (required): The workflow instance ID - `status` (required): New status (IN_PROGRESS, FAILED, FAILED_WITH_TERMINAL_ERROR, COMPLETED) - `output` (optional): Task output data - `logs` (optional): Task execution logs ### Task Definition Management #### `get_task_definition` Get a task definition by name. **Parameters:** - `taskName` (required): Name of the task #### `list_task_definitions` List all registered task definitions. **Parameters:** - `access` (optional): Filter by access type (READ or CREATE) #### `create_task_definition` Create or update a task definition. **Parameters:** - `definition` (required): Complete task definition as JSON object ### Event Handlers #### `get_event_handlers` Get event handlers. **Parameters:** - `event` (optional): Filter by event name - `activeOnly` (optional): Return only active handlers (default: true) ## Usage Examples Here are some common scenarios you can ask Claude to help with: ### Troubleshooting ``` "Show me all failed workflows in the last hour" "Why did workflow abc-123 fail?" "What tasks are currently running in workflow xyz-789?" "Show me the execution history of the payment_processing workflow" ``` ### Workflow Management ``` "Start a new order_processing workflow with orderId 12345" "Pause workflow abc-123" "Retry the failed workflow xyz-789" "Terminate all stuck workflows" ``` ### Workflow Development ``` "Show me the definition of the payment_processing workflow" "Create a new workflow definition for customer onboarding" "List all available task definitions" "What workflows are registered in the system?" ``` ## Development ### Building from Source ```bash git clone https://github.com/opensensor/conductor-mcp.git cd conductor-mcp npm install npm run build ``` ### Running Locally ```bash npm run build CONDUCTOR_SERVER_URL=http://localhost:8080 node build/index.js ``` ### Watch Mode ```bash npm run watch ``` ## Architecture This MCP server uses: - **@modelcontextprotocol/sdk**: MCP protocol implementation - **axios**: HTTP client for Conductor API calls - **TypeScript**: Type-safe development The server runs on stdio transport, making it compatible with Claude Desktop and other MCP clients. ## API Compatibility This server is compatible with Netflix Conductor v3.x API. It has been tested with: - Conductor v3.15.0 - Conductor v3.13.0 ## Contributing Contributions are welcome! Please feel free to submit a Pull Request. ## License Apache-2.0 ## Resources - [Netflix Conductor Documentation](https://conductor.netflix.com/) - [Model Context Protocol](https://modelcontextprotocol.io/) - [MCP Servers](https://github.com/modelcontextprotocol/servers) ## Support For issues and questions: - GitHub Issues: https://github.com/opensensor/conductor-mcp/issues - Conductor Documentation: https://conductor.netflix.com/ ## Acknowledgments Built with the Model Context Protocol SDK and inspired by the Netflix Conductor workflow orchestration platform.