Structured Workflow MCP

Instructions

Implementation Reference

• src/tools/buildCustomWorkflow.ts:77-117 (handler)

  The exported handleBuildCustomWorkflow function serves as the primary handler for the 'build_custom_workflow' tool. It processes input parameters, detects optimal workflow types, provides suggestions for preset workflows, applies presets when specified, and delegates core logic to the internal implementation function.
  export async function handleBuildCustomWorkflow( params: { task: string; workflowType?: WorkflowType | 'custom'; selectedPhases?: Phase[]; iterationLimits?: any; outputPreferences?: any; userCheckpoints?: any; }, sessionManager: SessionManager ) { // Detect workflow type if not specified const detectedType = params.workflowType === 'custom' ? null : params.workflowType || detectWorkflowType(params.task); // If a workflow type is detected, suggest using the specific tool if (detectedType && !params.workflowType) { const workflowTools = { refactor: 'refactor_workflow', feature: 'create_feature_workflow', test: 'test_workflow', tdd: 'tdd_workflow' }; return { suggestion: `Based on your task description, consider using ${workflowTools[detectedType]} for an optimized ${detectedType} workflow`, detectedType, alternativeCommand: `${workflowTools[detectedType]}({ task: "${params.task}" })`, proceedingWithCustom: 'Proceeding with custom workflow configuration...', customWorkflow: await buildCustomWorkflowImplementation(params, sessionManager) }; } // Use preset if workflow type is specified if (params.workflowType && params.workflowType !== 'custom') { const preset = getWorkflowPreset(params.workflowType); params.selectedPhases = params.selectedPhases || preset.phases; params.iterationLimits = { ...preset.iterationLimits, ...params.iterationLimits }; } return buildCustomWorkflowImplementation(params, sessionManager); }
• src/tools/buildCustomWorkflow.ts:13-75 (schema)

  The createBuildCustomWorkflowTool function defines the tool's metadata, including name, description, and detailed inputSchema for parameters like task, workflowType, phases, limits, output preferences, and checkpoints.
  export function createBuildCustomWorkflowTool(): Tool { return { name: 'build_custom_workflow', description: 'Build a custom workflow with full control over phases and configuration. Use specific workflow tools (refactor_workflow, create_feature_workflow, etc.) for optimized presets.', inputSchema: { type: 'object', properties: { task: { type: 'string', description: 'Description of the programming task' }, workflowType: { type: 'string', enum: ['refactor', 'feature', 'test', 'tdd', 'custom'], description: 'Use a predefined workflow type or custom for full control', default: 'custom' }, selectedPhases: { type: 'array', items: { type: 'string', enum: ['SETUP', 'AUDIT_INVENTORY', 'COMPARE_ANALYZE', 'QUESTION_DETERMINE', 'WRITE_OR_REFACTOR', 'TEST', 'LINT', 'ITERATE', 'PRESENT'] }, description: 'Select which phases to include in your workflow', default: ['SETUP', 'AUDIT_INVENTORY', 'WRITE_OR_REFACTOR', 'TEST', 'LINT', 'PRESENT'] }, iterationLimits: { type: 'object', properties: { TEST: { type: 'number', default: 5, description: 'Max test failure cycles before user input' }, LINT: { type: 'number', default: 10, description: 'Max lint/fix cycles before user input' }, ITERATE: { type: 'number', default: 15, description: 'Max overall iterations before user input' } }, description: 'Set iteration limits before escalation to user input' }, outputPreferences: { type: 'object', properties: { formats: { type: 'array', items: { type: 'string', enum: ['markdown', 'json'] }, default: ['markdown'], description: 'Output formats for documentation' }, realTimeUpdates: { type: 'boolean', default: true }, generateDiagrams: { type: 'boolean', default: true }, includeCodeSnippets: { type: 'boolean', default: true }, outputDirectory: { type: 'string', default: 'workflow-output' } } }, userCheckpoints: { type: 'object', properties: { beforeMajorChanges: { type: 'boolean', default: true }, afterFailedIterations: { type: 'boolean', default: true }, beforeFinalPresentation: { type: 'boolean', default: false } } } }, required: ['task'] } }; }
• src/tools/buildCustomWorkflow.ts:119-283 (helper)

  Internal buildCustomWorkflowImplementation function containing the core logic for building the custom workflow: sets defaults, resolves directories, creates configuration, starts session, generates initial files and instructions, and returns comprehensive workflow setup data.
  async function buildCustomWorkflowImplementation( params: { task: string; workflowType?: WorkflowType | 'custom'; selectedPhases?: Phase[]; iterationLimits?: any; outputPreferences?: any; userCheckpoints?: any; }, sessionManager: SessionManager ) { // Set defaults for optional parameters const selectedPhases = params.selectedPhases || ['SETUP', 'AUDIT_INVENTORY', 'WRITE_OR_REFACTOR', 'TEST', 'LINT', 'PRESENT']; const iterationLimits = { TEST: 5, LINT: 10, ITERATE: 15, ...params.iterationLimits }; // Resolve output directory: if the incoming value is relative, make it absolute relative to working directory (CWD). const resolvedOutputDir = resolveOutputDirectory( params.outputPreferences?.outputDirectory || getDefaultOutputDirectory(), process.cwd() ); const outputPreferences = { formats: ['markdown'], realTimeUpdates: true, generateDiagrams: true, includeCodeSnippets: true, createProgressReport: true, createPhaseArtifacts: true, ...params.outputPreferences, outputDirectory: resolvedOutputDir }; const userCheckpoints = { beforeMajorChanges: true, afterFailedIterations: true, beforeFinalPresentation: false, ...params.userCheckpoints }; // Create workflow configuration const workflowConfig: WorkflowConfiguration = { selectedPhases: selectedPhases as Phase[], iterationLimits, outputPreferences, userCheckpoints, escalationTriggers: { enableUserInput: true, escalateOnIterationLimit: true, escalateOnErrors: true, escalateOnTime: false } }; // Start session with configuration const session = sessionManager.startSession(params.task, workflowConfig); // Validate directory access (read-only check) const dirValidation = validateDirectoryAccess(resolvedOutputDir); // Get the sanitized task name for subdirectory const sanitizedTaskName = sanitizeTaskName(params.task); // Construct the target directory path (no actual creation happens) const suggestedDirectory = resolvedOutputDir && sanitizedTaskName ? `${resolvedOutputDir}/${sanitizedTaskName}` : resolvedOutputDir; // Report validation issues but continue with the workflow const directoryWarning = !dirValidation.isValid ? { warning: 'DIRECTORY ACCESS ISSUE', message: `⚠️ Output directory may not be writable: ${dirValidation.error}`, impact: 'The AI agent will be instructed to create this directory. If it fails, artifacts will remain in-memory only.', resolution: [ 'Check directory permissions', 'Ensure the specified directory is writable' ] } : null; // Generate numbered file names for initial files const planningFileName = generateNumberedFileName({ phase: 'PLANNING', outputDirectory: suggestedDirectory, extension: 'md', includeDate: true }); // Generate initial output file instructions with numbered naming const initialOutputFiles: OutputFileInstruction[] = [ { path: `${suggestedDirectory}/${planningFileName}`, description: 'Initial workflow plan and configuration', required: true, format: 'markdown', template: generateWorkflowPlanTemplate(params.task, workflowConfig), validationRules: ['Must contain task description', 'Must list all selected phases', 'Must include iteration limits'] }, { path: `${suggestedDirectory}/workflow-status.json`, description: 'Machine-readable workflow progress', required: true, format: 'json', template: JSON.stringify(sessionManager.getWorkflowProgress(), null, 2) } ]; return { success: true, sessionId: session.id, message: '🚀 CUSTOM WORKFLOW BUILT SUCCESSFULLY', workflowConfiguration: { task: params.task, selectedPhases, phaseCount: selectedPhases.length, iterationLimits, outputPreferences, userCheckpoints, escalationEnabled: true }, ...(directoryWarning ? { directoryWarning } : {}), criticalInstructions: [ '⚠️ DIRECTIVE WORKFLOW: This is not suggestive guidance - you MUST follow the structured approach', '📋 PHASE VALIDATION: Each phase has specific completion requirements that must be met', '📁 OUTPUT REQUIREMENTS: You are required to create documentation files as specified', '🛑 SAFETY RULE: Files must be read before modification (this is enforced)', '⏱️ ITERATION LIMITS: Automatic escalation to user input when limits are reached' ], directoryCreated: { baseDirectory: outputPreferences.outputDirectory, taskDirectory: suggestedDirectory, sanitizedTaskName: sanitizedTaskName, message: `ℹ️ Suggested output directory path: ${suggestedDirectory}` }, requiredFirstActions: [ { action: 'CREATE_OUTPUT_DIRECTORY', instruction: `ℹ️ Create output directory if needed: "${suggestedDirectory}"`, completed: false, blocking: true }, { action: 'CREATE_INITIAL_FILES', instruction: 'You can now start creating phase output files using the numbered naming system', files: initialOutputFiles, blocking: false, note: 'Files will be automatically saved with numbered naming (01-audit-inventory-YYYY-MM-DD.md)' }, { action: 'BEGIN_FIRST_PHASE', instruction: `Call "${selectedPhases[0].toLowerCase()}_guidance" to begin the workflow`, blocking: true } ], nextPhase: { phase: selectedPhases[0], tool: `${selectedPhases[0].toLowerCase()}_guidance`, description: `Begin with the ${selectedPhases[0]} phase` }, validationRequirement: { message: '🔍 COMPLETION VALIDATION: You cannot proceed to the next phase until the current phase validation passes', enforcement: 'Use phase_output tool only after meeting all phase requirements' } }; }
• src/index.ts:137-157 (registration)

  Tool registration in the main server setup: createBuildCustomWorkflowTool() is included in the tools array provided to the MCP server for listing and calling.
  const tools = [ // Workflow entry points createRefactorWorkflowTool(), // Refactoring workflow createFeatureWorkflowTool(), // Feature creation workflow createTestWorkflowTool(), // Test writing workflow createTddWorkflowTool(), // TDD workflow createBuildCustomWorkflowTool(), // Custom workflow builder // Phase guidance tools ...createPhaseGuidanceTools(), // Handles both suggestive and directive modes createTestGuidanceTool(), // TEST phase guidance // Validation tools ...createValidationTools(), // Both validate_action and validate_phase_completion // Workflow management createUserInputRequiredTool(), // Escalation handling createWorkflowStatusTool(), // Workflow status createPhaseOutputTool(), // Phase output recording createDiscoverWorkflowToolsTool() // Tool discovery ];
• src/index.ts:177-183 (registration)

  Dispatch handler registration: The switch case for 'build_custom_workflow' calls the handleBuildCustomWorkflow function within the MCP server's CallToolRequestSchema handler.
  case 'build_custom_workflow': return { content: [{ type: 'text', text: JSON.stringify(await handleBuildCustomWorkflow(args as any, sessionManager), null, 2) }] };