Conductor MCP Server

# Conductor MCP Improvements Summary ## ✅ Completed Improvements ### 1. MCP Resources Support Added 4 resources that provide quick access to frequently used data: - **`conductor://workflows/definitions`** - All registered workflow definitions - **`conductor://tasks/definitions`** - All registered task definitions - **`conductor://workflows/running`** - Currently running workflows - **`conductor://workflows/failed`** - Recently failed workflows **Benefits:** - Quick access to common data without calling tools - Resources are like bookmarks in the MCP client - Better UX for browsing Conductor state **Usage Example:** ``` # In Claude Desktop, resources appear in the UI # Click on "Running Workflows" to see all running workflows ``` ### 2. MCP Prompts Support Added 4 pre-built prompts for common scenarios: #### `troubleshoot_workflow` Guides through troubleshooting a failed/stuck workflow: - Gets workflow status - Identifies failed tasks - Checks task logs - Suggests solutions - Recommends next steps **Arguments:** `workflowId` (required) #### `analyze_failures` Analyzes recent workflow failures to identify patterns: - Lists failed workflows in time range - Identifies common error patterns - Finds frequently failing tasks - Suggests root causes - Recommends preventive measures **Arguments:** `workflowName` (optional), `hours` (optional, default: 24) #### `create_workflow` Guides through creating a new workflow: - Shows existing workflows as examples - Helps create workflow definition JSON - Assists with task definitions - Registers the workflow **Arguments:** `workflowName` (required), `description` (required) #### `monitor_workflow` Monitors a running workflow execution: - Shows current status and progress - Lists completed/running/pending tasks - Identifies warnings or issues - Estimates completion time **Arguments:** `workflowId` (required) **Benefits:** - Guided workflows for common tasks - Reduces cognitive load - Ensures best practices - Faster problem resolution ### 3. Enhanced Error Handling #### Better Error Messages - Clear, formatted error messages with emoji indicators (❌, ✅, 💡) - HTTP status codes included - Detailed error context #### Smart Suggestions Contextual suggestions based on error type: - **404 errors**: "The resource was not found. Please verify the ID/name is correct." - **400 errors**: "Invalid request. Please check the input parameters." - **500 errors with Elasticsearch**: "Elasticsearch is not configured. Try using list_workflows instead." - **Connection refused**: Shows the server URL and suggests verification - **Timeout**: Suggests server may be slow or unresponsive #### Input Validation - Workflow ID format validation (UUID) - Required field validation - Early validation before API calls #### Enhanced Success Messages Better formatted success messages with helpful tips: ``` ✅ Workflow started successfully! 🆔 Workflow ID: abc-123-def 📋 Workflow Name: demo_workflow 📌 Version: 1 💡 Tip: Use get_workflow_status with this ID to monitor progress. ``` #### Workflow Status Summaries Concise summaries before full JSON output: ``` 📋 Workflow: demo_workflow (v1) 🆔 ID: abc-123-def 📊 Status: RUNNING ⏱️ Started: 2025-12-28T07:52:37.802Z ⏳ Duration: 45s ``` **Benefits:** - Faster problem diagnosis - Reduced trial-and-error - Better user experience - Actionable guidance ## 📊 Impact Summary | Improvement | Lines Added | Key Features | |-------------|-------------|--------------| | Resources | ~100 | 4 resources, auto-refresh | | Prompts | ~150 | 4 guided workflows | | Error Handling | ~80 | Validation, suggestions, formatting | | **Total** | **~330** | **Significantly better UX** | ## 🎯 Usage Examples ### Using Resources ``` # In Claude Desktop "Show me all running workflows" # Claude will use the conductor://workflows/running resource ``` ### Using Prompts ``` "Use the troubleshoot_workflow prompt for workflow abc-123" # Claude will follow the guided troubleshooting steps ``` ### Better Error Messages **Before:** ``` Error executing get_workflow_status: [404] Not found ``` **After:** ``` ❌ Error executing get_workflow_status: [404] Workflow not found 💡 Suggestion: The resource was not found. Please verify the ID/name is correct. ``` ## 🔧 Technical Details ### New Dependencies None! All improvements use existing MCP SDK features. ### Breaking Changes None. All changes are backward compatible. ### Configuration Changes None required. Works with existing configuration. ## 📝 Next Steps (Future Improvements) 1. **Batch Operations** - Pause/resume/terminate multiple workflows 2. **Workflow Visualization** - Return DAG in visualizable format 3. **Metrics & Monitoring** - Execution statistics, SLA monitoring 4. **Workflow Templates** - Common workflow patterns library 5. **Response Caching** - Cache definitions to reduce API calls 6. **Authentication** - Support for API keys and OAuth ## 🧪 Testing Build and test the improvements: ```bash cd conductor-mcp npm run build npm test # (when tests are added) ``` ## 📚 Documentation - See `README.md` for tool documentation - See `ADMIN_UI_GUIDE.md` for UI access instructions - See `EXAMPLES.md` for usage examples