mcp-workflow-server-enhanced
Version:
Enhanced MCP Workflow Server with smart problem routing, comprehensive validation, guide compliance, and robust error handling. Intelligently routes to appropriate AI functions based on problem type.
306 lines (284 loc) • 8.49 kB
text/typescript
import { z } from 'zod';
import { GuideCompliance, ValidationMetadata, WorkflowContext } from './types.js';
/**
* Guide Compliance Validation Framework
*
* This module implements comprehensive validation for guide compliance,
* including all 13 maxims and 3 heuristics verification.
*/
export interface ValidationCheckpoint {
name: string;
description: string;
validator: (context: any) => Promise<boolean>;
required: boolean;
maxim?: string;
heuristic?: string;
}
/**
* Validation checkpoints for guide compliance
*/
export const VALIDATION_CHECKPOINTS: ValidationCheckpoint[] = [
{
name: 'primed_cognition',
description: 'Verify that structured thinking and reasoning was applied',
validator: async (context) => {
return context?.metadata?.cognitiveAnalysis !== undefined;
},
required: true,
maxim: 'PrimedCognition',
},
{
name: 'appropriate_complexity',
description: 'Ensure solution complexity is appropriate for the problem',
validator: async (context) => {
return context?.metadata?.complexityAssessment !== undefined;
},
required: true,
maxim: 'AppropriateComplexity',
},
{
name: 'clear_communication',
description: 'Verify clear and comprehensive communication',
validator: async (context) => {
return context?.result?.explanation !== undefined;
},
required: true,
maxim: 'ClearCommunication',
},
{
name: 'purposeful_tool_leveraging',
description: 'Confirm strategic use of available tools',
validator: async (context) => {
return context?.metadata?.toolsUsed?.length > 0;
},
required: false,
maxim: 'PurposefulToolLeveraging',
},
{
name: 'autonomy',
description: 'Verify autonomous problem resolution',
validator: async (context) => {
return context?.metadata?.autonomousResolution === true;
},
required: true,
maxim: 'Autonomy',
},
{
name: 'resilience',
description: 'Ensure error handling and robustness',
validator: async (context) => {
return context?.metadata?.errorHandling !== undefined;
},
required: true,
maxim: 'Resilience',
},
{
name: 'consistency',
description: 'Verify consistent patterns and reuse',
validator: async (context) => {
return context?.metadata?.consistencyCheck === true;
},
required: true,
maxim: 'Consistency',
},
{
name: 'solid_principles',
description: 'Verify SOLID principles application',
validator: async (context) => {
return context?.metadata?.solidCompliance !== undefined;
},
required: false,
heuristic: 'SOLID',
},
{
name: 'smart_goals',
description: 'Ensure goals are SMART (Specific, Measurable, etc.)',
validator: async (context) => {
return context?.metadata?.smartGoals !== undefined;
},
required: true,
heuristic: 'SMART',
},
];
/**
* Validate guide compliance for a workflow step
*/
export async function validateGuideCompliance(
stepName: string,
input: any,
output: any,
context: WorkflowContext
): Promise<GuideCompliance> {
const validationResults = [];
const maximsApplied = [];
const heuristicsApplied = [];
for (const checkpoint of VALIDATION_CHECKPOINTS) {
try {
const passed = await checkpoint.validator({ input, output, context, stepName });
validationResults.push({
checkpoint: checkpoint.name,
passed,
details: passed ? 'Validation passed' : `Failed: ${checkpoint.description}`,
});
if (passed) {
if (checkpoint.maxim && !maximsApplied.includes(checkpoint.maxim)) {
maximsApplied.push(checkpoint.maxim as any);
}
if (checkpoint.heuristic && !heuristicsApplied.includes(checkpoint.heuristic)) {
heuristicsApplied.push(checkpoint.heuristic as any);
}
}
} catch (error) {
validationResults.push({
checkpoint: checkpoint.name,
passed: false,
details: `Validation error: ${error.message}`,
});
}
}
// Calculate compliance score
const totalCheckpoints = VALIDATION_CHECKPOINTS.length;
const passedCheckpoints = validationResults.filter(r => r.passed).length;
const complianceScore = Math.round((passedCheckpoints / totalCheckpoints) * 100);
return {
maximsApplied,
heuristicsApplied,
complianceScore,
validationCheckpoints: validationResults,
};
}
/**
* Validate input schema with enhanced error reporting
*/
export function validateInputSchema<T>(
schema: z.ZodSchema<T>,
input: unknown,
stepName: string
): { success: true; data: T } | { success: false; errors: string[] } {
try {
const result = schema.parse(input);
return { success: true, data: result };
} catch (error) {
if (error instanceof z.ZodError) {
const errors = error.errors.map(err =>
`${stepName}: ${err.path.join('.')} - ${err.message}`
);
return { success: false, errors };
}
return { success: false, errors: [`${stepName}: Unknown validation error`] };
}
}
/**
* Create validation metadata for a workflow step
*/
export function createValidationMetadata(
stepName: string,
inputValidated: boolean,
validationErrors?: string[],
guideCompliance?: GuideCompliance
): ValidationMetadata {
return {
inputValidated,
schemaVersion: '1.0.0',
validationTimestamp: new Date().toISOString(),
validationErrors,
guideCompliance,
};
}
/**
* Validate workflow stage transition
*/
export async function validateStageTransition(
fromStage: string,
toStage: string,
context: WorkflowContext
): Promise<{ canProceed: boolean; issues: string[] }> {
const issues: string[] = [];
// Check if previous stage completed successfully
const previousResult = context.stepResults?.[fromStage];
if (!previousResult) {
issues.push(`Previous stage '${fromStage}' has no results`);
}
// Check guide compliance for previous stage
const guideCompliance = context.guideCompliance;
if (!guideCompliance || guideCompliance.complianceScore < 70) {
issues.push(`Guide compliance score too low: ${guideCompliance?.complianceScore || 0}%`);
}
// Stage-specific validation
switch (toStage) {
case 'research':
if (!previousResult?.improvedPrompt) {
issues.push('Improved prompt required for research stage');
}
break;
case 'cognitive':
if (!previousResult?.researchData) {
issues.push('Research data required for cognitive stage');
}
break;
case 'planner':
if (!previousResult?.cognitiveAnalysis) {
issues.push('Cognitive analysis required for planning stage');
}
break;
case 'task-generation':
if (!previousResult?.plan) {
issues.push('Plan required for task generation stage');
}
break;
case 'implementation':
if (!previousResult?.tasks || previousResult.tasks.length === 0) {
issues.push('Tasks required for implementation stage');
}
break;
}
return {
canProceed: issues.length === 0,
issues,
};
}
/**
* Enhanced error handling with guide compliance
*/
export class ValidationError extends Error {
constructor(
message: string,
public step: string,
public validationErrors: string[],
public guideCompliance?: GuideCompliance
) {
super(message);
this.name = 'ValidationError';
}
}
/**
* Rollback mechanism for failed validations
*/
export async function rollbackToLastValidState(
context: WorkflowContext,
targetStep: string
): Promise<WorkflowContext> {
// Find the last successfully validated step
const steps = ['improve-prompt', 'research', 'cognitive', 'planner', 'task-generation', 'implementation'];
const targetIndex = steps.indexOf(targetStep);
if (targetIndex === -1) {
throw new Error(`Invalid target step: ${targetStep}`);
}
// Create new context with state rolled back to target step
const rolledBackContext: WorkflowContext = {
...context,
currentStep: targetStep as any,
stepResults: Object.fromEntries(
Object.entries(context.stepResults || {}).filter(([step]) =>
steps.indexOf(step) <= targetIndex
)
),
metadata: {
...context.metadata,
rollbackPerformed: true,
rollbackTimestamp: new Date().toISOString(),
rollbackReason: 'Validation failure',
},
};
return rolledBackContext;
}