Problem

AI-assisted workflow generation was failing when trying to create MCP nodes with validation errors:

Current Behavior

1. User requests AI to generate workflow with MCP nodes
2. ❌ AI generates MCP node with incorrect structure due to missing schema definition
3. ❌ Validation fails with errors:
   • MCP_INVALID_PARAMETERS: Parameters must be an array
   • MCP_INVALID_MODE: Invalid mode 'specificTool' (valid: manualParameterConfig, aiParameterConfig, aiToolSelection)

Expected Behavior

1. User requests AI to generate workflow with MCP nodes
2. ✅ AI references MCP node schema definition
3. ✅ AI generates correct MCP node structure
4. ✅ Validation passes and workflow is created successfully

Solution

Added complete MCP node type definition to workflow-schema.json to guide AI generation, and added commit message guidelines to prevent overly complex commit messages in the future.

Changes

File: resources/workflow-schema.json

• Added "mcp" to supportedNodeTypes array
• Added comprehensive nodeTypes.mcp definition with:
  • Required fields: serverId, toolName, validationStatus, outputPorts
  • Optional fields: toolDescription, parameters, parameterValues, mode
  • Field constraints:
    • parameters: Must be array of parameter schema objects [{name, type, description, required}]
    • mode: Must be one of manualParameterConfig, aiParameterConfig, aiToolSelection
  • AI generation guidance section with:
    • Explicit instructions to use manualParameterConfig mode
    • Parameter structure examples
    • Common tool names for popular MCP servers (Playwright, GitHub, Filesystem)
    • Complete working example

File: CLAUDE.md

• Added commit message guidelines section
• Emphasizes simple commit messages for squash merge workflow
• Conventional Commits format with 3-5 bullet points max
• Clear examples of what to avoid (long explanations, code blocks, test results)

Impact

• UX: AI workflow generation now correctly handles MCP nodes without validation errors
• Breaking Change: None - additive changes only
• Side Effects: None - existing workflows are unaffected
• Schema Size: 16KB → 21KB (~5KB increase from MCP definition)

Testing

• Manual E2E testing completed
  • Created workflow with MCP (Playwright) nodes via AI generation
  • Verified no MCP_INVALID_PARAMETERS or MCP_INVALID_MODE errors
  • Confirmed correct node structure generated with proper parameters array and mode field
• Code quality checks passed
  • npm run format && npm run lint && npm run check
  • npm run build succeeded

Notes

• Known Limitation: AI may generate non-existent tool names (e.g., tools not available in installed MCP servers). Tracked in Add validation for MCP tool names in AI-generated workflows #129 for future enhancement with runtime tool name validation.
• This fix unblocks AI-assisted workflow generation for MCP integration demos and README hero image creation.

🤖 Generated with Claude Code

Co-Authored-By: Claude noreply@anthropic.com