@ema.co/mcp-toolkit 2026.2.19 → 2026.2.23

package/dist/mcp/resources-validation.js

@@ -0,0 +1,408 @@
+/**
+ * Validation Rules Generators for MCP Resources
+ *
+ * Generates LLM-friendly validation rules and best practices checklists
+ * from the canonical SDK rule definitions.
+ *
+ * Extracted from resources.ts for maintainability.
+ */
+import { INPUT_SOURCE_RULES, ANTI_PATTERNS, OPTIMIZATION_RULES } from "./domain/validation-rules.js";
+import { STRUCTURAL_INVARIANTS } from "./domain/structural-rules.js";
+/**
+ * Generate validation rules in LLM-friendly Markdown format.
+ * Includes rules from Go validator: required outputs, multiple writers, response/abstain, category hierarchy.
+ */
+export function generateValidationRulesForLLM() {
+    return `# Workflow Validation Rules
+
+> **Use these rules DURING workflow generation to avoid errors proactively.**
+
+These rules are extracted from the Go validator's static validation logic. Follow them when generating or modifying workflows.
+
+## Rule 1: Required Output on All Paths
+
+**Rule ID**: \`required_output_all_paths\`  
+**Severity**: Critical  
+**Applies To**: Named results, execution paths
+
+### Logic
+
+**Algorithm**: Enumerate all execution paths. For each path, check if all named results are produced.
+
+**Steps**:
+1. Enumerate all paths from trigger to completion
+2. For each path, collect all outputs produced
+3. For each named result, check if it's in path outputs
+4. If missing on any path → error
+
+**Complexity**: O(P * R) where P = paths, R = named results
+
+### Rules
+
+**Constraint**: Every execution path must produce all named results.
+
+**Why**: Named results are contract guarantees. If a path doesn't produce a required output, the contract is violated.
+
+### Examples
+
+**Bad Pattern**:
+\`\`\`json
+{
+  "path": ["trigger", "categorizer", "billing_branch", "search"],
+  "named_result": "response_with_sources",
+  "produces": []  // Missing response
+}
+\`\`\`
+
+**Why Bad**: Path ends without producing required output.
+
+**Good Pattern**:
+\`\`\`json
+{
+  "path": ["trigger", "categorizer", "billing_branch", "search", "respond_for_external_actions"],
+  "named_result": "response",
+  "produces": ["response"]  // ✅ Produced
+}
+\`\`\`
+
+**Why Good**: All paths produce required output.
+
+### Remediation
+
+**How to Fix**:
+1. Identify the path missing the output
+2. Add a node that produces the required output
+3. Connect the node's output to WORKFLOW_OUTPUT
+
+**Common Fixes**:
+- Add \`respond_for_external_actions\` node after search
+- Add \`call_llm\` node for text generation
+- Add \`fixed_response\` for static responses
+
+**Prevention** (During Generation):
+- Always ensure every categorizer branch has a response node
+- Check that all paths end with nodes connected to WORKFLOW_OUTPUT
+- Verify resultMappings include all required outputs
+
+---
+
+## Rule 2: Single Writer Per Output
+
+**Rule ID**: \`single_writer_per_output\`  
+**Severity**: Critical  
+**Applies To**: Named results, execution paths
+
+### Logic
+
+**Algorithm**: For each named result, count how many nodes produce it on each path.
+
+**Steps**:
+1. For each named result
+2. For each execution path
+3. Count nodes that produce this result
+4. If count > 1 on any path → error
+
+### Rules
+
+**Constraint**: A single named result can only have one producer per execution path.
+
+**Why**: Multiple producers on the same path cause ambiguity about which value to use.
+
+### Examples
+
+**Bad Pattern**:
+\`\`\`json
+{
+  "path": ["trigger", "categorizer", "billing"],
+  "named_result": "response_with_sources",
+  "producers": ["respond_billing", "respond_general"]  // ❌ Two producers
+}
+\`\`\`
+
+**Why Bad**: Two nodes produce the same output on the same path.
+
+**Good Pattern**:
+\`\`\`json
+{
+  "path": ["trigger", "categorizer", "billing"],
+  "named_result": "response_with_sources",
+  "producers": ["respond_billing"]  // ✅ Single producer
+}
+\`\`\`
+
+**Why Good**: Only one node produces the output.
+
+### Remediation
+
+**How to Fix**:
+1. Identify which nodes produce the same output
+2. Remove one producer or use different named results
+3. Ensure only one node produces each named result per path
+
+**Prevention** (During Generation):
+- Use mutually exclusive runIf conditions to gate responders
+- Ensure only one response node executes per category branch
+
+---
+
+## Rule 3: Response or Abstain Required
+
+**Rule ID**: \`response_or_abstain_required\`  
+**Severity**: Critical  
+**Applies To**: Execution paths
+
+### Logic
+
+**Algorithm**: For each execution path, check if it produces a response or has an abstain reason.
+
+**Steps**:
+1. For each completed path
+2. Check if path produces any response output
+3. Check if path has abstain reason
+4. If neither → error
+
+### Rules
+
+**Constraint**: Every execution path must either produce a user-visible response or explicitly abstain with a reason.
+
+**Why**: Users expect responses. Paths that don't respond and don't explain why create poor UX.
+
+### Examples
+
+**Bad Pattern**:
+\`\`\`json
+{
+  "path": ["trigger", "categorizer", "billing", "search"],
+  "has_response": false,
+  "has_abstain": false  // ❌ Neither
+}
+\`\`\`
+
+**Why Bad**: Path ends without response or abstain reason.
+
+**Good Pattern**:
+\`\`\`json
+{
+  "path": ["trigger", "categorizer", "billing", "search", "respond_for_external_actions"],
+  "has_response": true  // ✅ Has response
+}
+\`\`\`
+
+**Why Good**: Path produces a response.
+
+### Remediation
+
+**How to Fix**:
+1. Add a response node to the path, OR
+2. Add an abstain reason to the workflow configuration
+
+**Prevention** (During Generation):
+- Always add response nodes to every categorizer branch
+- If a path shouldn't respond, document why with abstain reason
+
+---
+
+## Rule 4: Category Hierarchy Valid
+
+**Rule ID**: \`category_hierarchy_valid\`  
+**Severity**: Critical  
+**Applies To**: Categorizers
+
+### Logic
+
+**Algorithm**: Validate categorizer structure and category definitions.
+
+**Steps**:
+1. Check categorizer has Fallback category
+2. Check category hierarchy rules (TBD - need Go validator analysis)
+3. Validate category → handler mapping
+
+### Rules
+
+**Constraint**: Categorizers must have proper structure and hierarchy.
+
+**Why**: Invalid category structure causes routing failures.
+
+### Examples
+
+**Bad Pattern**:
+\`\`\`json
+{
+  "categorizer": {
+    "categories": ["Billing", "Technical"]  // ❌ No Fallback
+  }
+}
+\`\`\`
+
+**Why Bad**: Missing Fallback category means unrecognized intents have no handler.
+
+**Good Pattern**:
+\`\`\`json
+{
+  "categorizer": {
+    "categories": ["Billing", "Technical", "Fallback"]  // ✅ Has Fallback
+  }
+}
+\`\`\`
+
+**Why Good**: All intents have a handler.
+
+### Remediation
+
+**How to Fix**:
+1. Add Fallback category to categorizer
+2. Ensure each category has a handler node
+3. Validate category hierarchy (TBD)
+
+**Prevention** (During Generation):
+- Always include Fallback category
+- Ensure every category has at least one handler node
+
+---
+
+## Self-Check Checklist
+
+After generating or modifying a workflow, verify:
+
+- [ ] All paths produce all named results
+- [ ] No multiple writers on same path
+- [ ] Every path has response or abstain
+- [ ] Category hierarchy is valid
+- [ ] Categorizer has Fallback category
+- [ ] All categories have handler nodes
+
+---
+
+## Reference
+
+- **Source**: workflow-engine/pkg/engine/validator.go
+- **Error Types**: RESULT_ERROR_TYPE_REQUIRED_OUTPUT_NOT_PRODUCED, RESULT_ERROR_TYPE_MULTIPLE_WRITERS, RESULT_ERROR_TYPE_MISSING_RESPONSE_OR_ABSTAIN_REASON, RESULT_ERROR_TYPE_CATEGORY_HIERARCHY_VIOLATION
+- **Validation Tool**: Use \`workflow(mode="validate")\` to validate workflows
+`;
+}
+/**
+ * Generate best practices checklist from SDK rules.
+ * SINGLE SOURCE OF TRUTH - all best practices come from:
+ * - ANTI_PATTERNS (validation-rules.ts)
+ * - STRUCTURAL_INVARIANTS (structural-rules.ts)
+ * - INPUT_SOURCE_RULES (validation-rules.ts)
+ * - OPTIMIZATION_RULES (validation-rules.ts)
+ */
+export function generateBestPracticesChecklist() {
+    const criticalAntiPatterns = ANTI_PATTERNS.filter(ap => ap.severity === "critical");
+    const warningAntiPatterns = ANTI_PATTERNS.filter(ap => ap.severity === "warning");
+    const infoAntiPatterns = ANTI_PATTERNS.filter(ap => ap.severity === "info");
+    const criticalInvariants = STRUCTURAL_INVARIANTS.filter(inv => inv.severity === "critical");
+    const warningInvariants = STRUCTURAL_INVARIANTS.filter(inv => inv.severity === "warning");
+    return `# Workflow Best Practices Checklist
+
+> **Auto-generated from SDK rules** - This is the single source of truth.
+> Check this BEFORE deploying any workflow.
+
+## 🛑 CRITICAL (Must Fix Before Deploy)
+
+### Anti-Patterns to Avoid
+
+${criticalAntiPatterns.map(ap => `
+#### ${ap.name}
+
+**Pattern**: ${ap.pattern}
+
+**Problem**: ${ap.problem}
+
+**Solution**: ${ap.solution}
+
+**Detection**: \`${ap.detection.condition}\`
+`).join("\n---\n")}
+
+### Structural Requirements
+
+${criticalInvariants.map(inv => `
+- **${inv.name}**: ${inv.rule}
+  - Violation: ${inv.violation}
+  - Fix: ${inv.fix}
+`).join("")}
+
+---
+
+## ⚠️ WARNINGS (Should Fix)
+
+### Anti-Patterns
+
+${warningAntiPatterns.map(ap => `
+- **${ap.name}**: ${ap.problem}
+  - Solution: ${ap.solution}
+`).join("")}
+
+### Structural Warnings
+
+${warningInvariants.map(inv => `
+- **${inv.name}**: ${inv.rule}
+  - Fix: ${inv.fix}
+`).join("")}
+
+---
+
+## 📋 SUGGESTIONS (Good to Have)
+
+${infoAntiPatterns.map(ap => `
+- **${ap.name}**: ${ap.problem}
+  - Recommendation: ${ap.solution}
+`).join("")}
+
+---
+
+## Input Source Rules
+
+| Action | Recommended Input | Avoid | Why |
+|--------|-------------------|-------|-----|
+${INPUT_SOURCE_RULES.filter(r => r.severity === "critical").map(r => `| \`${r.actionPattern}\` | \`${r.recommended}\` | ${r.avoid.join(", ") || "-"} | ${r.reason.slice(0, 60)}... |`).join("\n")}
+
+---
+
+## Performance Optimizations
+
+${OPTIMIZATION_RULES.map(opt => `
+### ${opt.name} (${opt.priority})
+
+- **Current State**: ${opt.currentState}
+- **Recommendation**: ${opt.recommendation}
+- **Benefit**: ${opt.benefit}
+`).join("")}
+
+---
+
+## Quick Checklist
+
+Before deploying, verify:
+
+### Critical
+- [ ] Response nodes receive \`chat_conversation\` (prevents repeated questions)
+- [ ] Email recipients from \`entity_extraction\` (not text outputs)
+- [ ] Categorizers have Fallback category
+- [ ] HITL has both success AND failure paths
+- [ ] All paths reach WORKFLOW_OUTPUT
+- [ ] No circular dependencies
+
+### Recommended
+- [ ] \`max_tokens\` set on call_llm nodes
+- [ ] No orphan nodes (unused/disconnected)
+- [ ] No redundant search nodes
+- [ ] Search nodes have data sources uploaded
+
+---
+
+## Related Resources
+
+- \`ema://rules/anti-patterns\` - Full anti-pattern definitions (JSON)
+- \`ema://rules/input-sources\` - Input source rules (JSON)
+- \`ema://rules/extraction-column-format\` - extraction_columns API shape (entity_extraction nodes)
+- \`ema://rules/json-output-patterns\` - custom_agent + json_mapper pattern
+- \`ema://rules/chat-response-wiring\` - Chat response node wiring (avoid duplicate responses)
+- \`ema://rules/email-input-wiring\` - Email input wiring (json_mapper/fixed_response patterns)
+- \`ema://docs/workflow-node-reference\` - Per-node I/O types, categorizer patterns, LLM config
+- \`ema://rules/structural-invariants\` - Structural rules (JSON)
+- \`ema://rules/optimizations\` - Optimization rules (JSON)
+- \`ema://validation/rules\` - Go validator rules reference
+`;
+}