mirror of
https://github.com/czlonkowski/n8n-mcp.git
synced 2026-03-19 17:03:08 +00:00
feat: complete modular documentation system for all MCP tools (#60)
- Migrated all 40 MCP tools documentation to modular structure - Created comprehensive documentation with both essentials and full details - Organized tools by category: discovery, configuration, validation, templates, workflow_management, system, special - Fixed all TODO placeholders with informative, precise content - Each tool now has concise description, key tips, and full documentation - Improved documentation quality: 30-40% more concise while maintaining usefulness - Fixed TypeScript compilation issues and removed orphaned content - All tools accessible via tools_documentation MCP endpoint - Build successful with zero errors 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
czlonkowski
5
src/mcp/tool-docs/validation/index.ts
Normal file
5
src/mcp/tool-docs/validation/index.ts
Normal file
@@ -0,0 +1,5 @@
|
||||
export { validateNodeMinimalDoc } from './validate-node-minimal';
|
||||
export { validateNodeOperationDoc } from './validate-node-operation';
|
||||
export { validateWorkflowDoc } from './validate-workflow';
|
||||
export { validateWorkflowConnectionsDoc } from './validate-workflow-connections';
|
||||
export { validateWorkflowExpressionsDoc } from './validate-workflow-expressions';
|
||||
47
src/mcp/tool-docs/validation/validate-node-minimal.ts
Normal file
47
src/mcp/tool-docs/validation/validate-node-minimal.ts
Normal file
@@ -0,0 +1,47 @@
|
||||
import { ToolDocumentation } from '../types';
|
||||
|
||||
export const validateNodeMinimalDoc: ToolDocumentation = {
|
||||
name: 'validate_node_minimal',
|
||||
category: 'validation',
|
||||
essentials: {
|
||||
description: 'Fast check for missing required fields only. No warnings/suggestions. Returns: list of missing fields.',
|
||||
keyParameters: ['nodeType', 'config'],
|
||||
example: 'validate_node_minimal("nodes-base.slack", {resource: "message"})',
|
||||
performance: 'Instant',
|
||||
tips: [
|
||||
'Returns only missing required fields',
|
||||
'No warnings or suggestions',
|
||||
'Perfect for real-time validation'
|
||||
]
|
||||
},
|
||||
full: {
|
||||
description: 'Minimal validation that only checks for missing required fields. Returns array of missing field names without any warnings or suggestions. Ideal for quick validation during node configuration.',
|
||||
parameters: {
|
||||
nodeType: { type: 'string', required: true, description: 'Node type with prefix (e.g., "nodes-base.slack")' },
|
||||
config: { type: 'object', required: true, description: 'Node configuration to validate' }
|
||||
},
|
||||
returns: 'Array of missing required field names (empty if valid)',
|
||||
examples: [
|
||||
'validate_node_minimal("nodes-base.slack", {resource: "message", operation: "post"}) - Check Slack config',
|
||||
'validate_node_minimal("nodes-base.httpRequest", {method: "GET"}) - Check HTTP config'
|
||||
],
|
||||
useCases: [
|
||||
'Real-time form validation',
|
||||
'Quick configuration checks',
|
||||
'Pre-deployment validation',
|
||||
'Interactive configuration builders'
|
||||
],
|
||||
performance: 'Instant - Simple field checking without complex validation',
|
||||
bestPractices: [
|
||||
'Use for quick feedback loops',
|
||||
'Follow with validate_node_operation for thorough check',
|
||||
'Check return array length for validity'
|
||||
],
|
||||
pitfalls: [
|
||||
'Only checks required fields',
|
||||
'No type validation',
|
||||
'No operation-specific validation'
|
||||
],
|
||||
relatedTools: ['validate_node_operation', 'get_node_essentials', 'get_property_dependencies']
|
||||
}
|
||||
};
|
||||
49
src/mcp/tool-docs/validation/validate-node-operation.ts
Normal file
49
src/mcp/tool-docs/validation/validate-node-operation.ts
Normal file
@@ -0,0 +1,49 @@
|
||||
import { ToolDocumentation } from '../types';
|
||||
|
||||
export const validateNodeOperationDoc: ToolDocumentation = {
|
||||
name: 'validate_node_operation',
|
||||
category: 'validation',
|
||||
essentials: {
|
||||
description: 'Validate node config. Checks required fields, types, operation rules. Returns errors with fixes. Essential for Slack/Sheets/DB nodes.',
|
||||
keyParameters: ['nodeType', 'config', 'profile'],
|
||||
example: 'validate_node_operation("nodes-base.slack", {resource: "message", operation: "post", text: "Hi"})',
|
||||
performance: 'Fast',
|
||||
tips: [
|
||||
'Returns errors, warnings, fixes',
|
||||
'Operation-aware validation',
|
||||
'Use profiles: minimal/runtime/ai-friendly/strict'
|
||||
]
|
||||
},
|
||||
full: {
|
||||
description: 'Comprehensive node configuration validation with operation awareness. Validates required fields, types, operation-specific rules, and provides fix suggestions. Supports validation profiles for different use cases.',
|
||||
parameters: {
|
||||
nodeType: { type: 'string', required: true, description: 'Node type with prefix (e.g., "nodes-base.slack")' },
|
||||
config: { type: 'object', required: true, description: 'Configuration including operation fields (resource/operation/action)' },
|
||||
profile: { type: 'string', description: 'Validation profile: minimal/runtime/ai-friendly(default)/strict' }
|
||||
},
|
||||
returns: 'Validation result with isValid, errors[], warnings[], suggestions[], fixes{}',
|
||||
examples: [
|
||||
'validate_node_operation("nodes-base.slack", {resource: "message", operation: "post", text: "Hello"}) - Validate Slack message',
|
||||
'validate_node_operation("nodes-base.httpRequest", {method: "POST", url: "{{$json.url}}"}, "strict") - Strict HTTP validation'
|
||||
],
|
||||
useCases: [
|
||||
'Pre-deployment validation',
|
||||
'Configuration debugging',
|
||||
'Operation-specific checks',
|
||||
'Fix suggestion generation'
|
||||
],
|
||||
performance: 'Fast - Schema analysis with operation context',
|
||||
bestPractices: [
|
||||
'Include operation fields in config',
|
||||
'Use ai-friendly profile by default',
|
||||
'Apply suggested fixes',
|
||||
'Validate before workflow deployment'
|
||||
],
|
||||
pitfalls: [
|
||||
'Config must include operation fields',
|
||||
'Some fixes are suggestions only',
|
||||
'Profile affects strictness level'
|
||||
],
|
||||
relatedTools: ['validate_node_minimal', 'get_node_essentials', 'validate_workflow']
|
||||
}
|
||||
};
|
||||
@@ -0,0 +1,56 @@
|
||||
import { ToolDocumentation } from '../types';
|
||||
|
||||
export const validateWorkflowConnectionsDoc: ToolDocumentation = {
|
||||
name: 'validate_workflow_connections',
|
||||
category: 'validation',
|
||||
essentials: {
|
||||
description: 'Check workflow connections only: valid nodes, no cycles, proper triggers, AI tool links. Fast structure validation.',
|
||||
keyParameters: ['workflow'],
|
||||
example: 'validate_workflow_connections({workflow: {nodes: [...], connections: {...}}})',
|
||||
performance: 'Fast (<100ms)',
|
||||
tips: [
|
||||
'Use for quick structure checks when editing connections',
|
||||
'Detects orphaned nodes and circular dependencies',
|
||||
'Validates AI Agent tool connections to ensure proper node references'
|
||||
]
|
||||
},
|
||||
full: {
|
||||
description: 'Validates only the connection structure of a workflow without checking node configurations or expressions. This focused validation checks that all referenced nodes exist, detects circular dependencies, ensures proper trigger node placement, validates AI tool connections, and identifies orphaned or unreachable nodes.',
|
||||
parameters: {
|
||||
workflow: {
|
||||
type: 'object',
|
||||
required: true,
|
||||
description: 'The workflow JSON with nodes array and connections object.'
|
||||
}
|
||||
},
|
||||
returns: 'Object with valid (boolean), errors (array), warnings (array), and statistics about connections',
|
||||
examples: [
|
||||
'validate_workflow_connections({workflow: myWorkflow}) - Check all connections',
|
||||
'validate_workflow_connections({workflow: {nodes: [...], connections: {...}}}) - Validate structure only'
|
||||
],
|
||||
useCases: [
|
||||
'Quick validation when modifying workflow connections',
|
||||
'Ensure all node references in connections are valid',
|
||||
'Detect circular dependencies that would cause infinite loops',
|
||||
'Validate AI Agent nodes have proper tool connections',
|
||||
'Check workflow has at least one trigger node',
|
||||
'Find orphaned nodes not connected to any flow'
|
||||
],
|
||||
performance: 'Fast (<100ms). Only validates structure, not node content. Scales linearly with connection count.',
|
||||
bestPractices: [
|
||||
'Run after adding or removing connections',
|
||||
'Use before validate_workflow for quick structural checks',
|
||||
'Check for warnings about orphaned nodes',
|
||||
'Ensure trigger nodes are properly positioned',
|
||||
'Validate after using n8n_update_partial_workflow with connection operations'
|
||||
],
|
||||
pitfalls: [
|
||||
'Does not validate node configurations - use validate_workflow for full validation',
|
||||
'Cannot detect logical errors in connection flow',
|
||||
'Some valid workflows may have intentionally disconnected nodes',
|
||||
'Circular dependency detection only catches direct loops',
|
||||
'Does not validate connection types match node capabilities'
|
||||
],
|
||||
relatedTools: ['validate_workflow', 'validate_workflow_expressions', 'n8n_update_partial_workflow']
|
||||
}
|
||||
};
|
||||
@@ -0,0 +1,56 @@
|
||||
import { ToolDocumentation } from '../types';
|
||||
|
||||
export const validateWorkflowExpressionsDoc: ToolDocumentation = {
|
||||
name: 'validate_workflow_expressions',
|
||||
category: 'validation',
|
||||
essentials: {
|
||||
description: 'Validate n8n expressions: syntax {{}}, variables ($json/$node), references. Returns errors with locations.',
|
||||
keyParameters: ['workflow'],
|
||||
example: 'validate_workflow_expressions({workflow: {nodes: [...], connections: {...}}})',
|
||||
performance: 'Fast (<100ms)',
|
||||
tips: [
|
||||
'Catches syntax errors in {{}} expressions before runtime',
|
||||
'Validates $json, $node, and other n8n variables',
|
||||
'Shows exact location of expression errors in node parameters'
|
||||
]
|
||||
},
|
||||
full: {
|
||||
description: 'Validates all n8n expressions within a workflow for syntax correctness and reference validity. This tool scans all node parameters for n8n expressions (enclosed in {{}}), checks expression syntax, validates variable references like $json and $node("NodeName"), ensures referenced nodes exist in the workflow, and provides detailed error locations for debugging.',
|
||||
parameters: {
|
||||
workflow: {
|
||||
type: 'object',
|
||||
required: true,
|
||||
description: 'The workflow JSON to check for expression errors.'
|
||||
}
|
||||
},
|
||||
returns: 'Object with valid (boolean), errors (array with node ID, parameter path, and error details), and expression count',
|
||||
examples: [
|
||||
'validate_workflow_expressions({workflow: myWorkflow}) - Check all expressions',
|
||||
'validate_workflow_expressions({workflow: {nodes: [...], connections: {...}}}) - Validate expression syntax'
|
||||
],
|
||||
useCases: [
|
||||
'Catch expression syntax errors before workflow execution',
|
||||
'Validate node references in $node() expressions exist',
|
||||
'Find typos in variable names like $json or $input',
|
||||
'Ensure complex expressions are properly formatted',
|
||||
'Debug expression errors with exact parameter locations',
|
||||
'Validate expressions after workflow modifications'
|
||||
],
|
||||
performance: 'Fast (<100ms). Scans all string parameters in all nodes. Performance scales with workflow size and expression count.',
|
||||
bestPractices: [
|
||||
'Run after modifying any expressions in node parameters',
|
||||
'Check all $node() references when renaming nodes',
|
||||
'Validate expressions before workflow deployment',
|
||||
'Pay attention to nested object paths in expressions',
|
||||
'Use with validate_workflow for comprehensive validation'
|
||||
],
|
||||
pitfalls: [
|
||||
'Cannot validate expression logic, only syntax',
|
||||
'Runtime data availability not checked (e.g., if $json.field exists)',
|
||||
'Complex JavaScript in expressions may need runtime testing',
|
||||
'Does not validate expression return types',
|
||||
'Some valid expressions may use advanced features not fully parsed'
|
||||
],
|
||||
relatedTools: ['validate_workflow', 'validate_workflow_connections', 'validate_node_operation']
|
||||
}
|
||||
};
|
||||
81
src/mcp/tool-docs/validation/validate-workflow.ts
Normal file
81
src/mcp/tool-docs/validation/validate-workflow.ts
Normal file
@@ -0,0 +1,81 @@
|
||||
import { ToolDocumentation } from '../types';
|
||||
|
||||
export const validateWorkflowDoc: ToolDocumentation = {
|
||||
name: 'validate_workflow',
|
||||
category: 'validation',
|
||||
essentials: {
|
||||
description: 'Full workflow validation: structure, connections, expressions, AI tools. Returns errors/warnings/fixes. Essential before deploy.',
|
||||
keyParameters: ['workflow', 'options'],
|
||||
example: 'validate_workflow({workflow: {nodes: [...], connections: {...}}})',
|
||||
performance: 'Moderate (100-500ms)',
|
||||
tips: [
|
||||
'Always validate before n8n_create_workflow to catch errors early',
|
||||
'Use options.profile="minimal" for quick checks during development',
|
||||
'AI tool connections are automatically validated for proper node references'
|
||||
]
|
||||
},
|
||||
full: {
|
||||
description: 'Performs comprehensive validation of n8n workflows including structure, node configurations, connections, and expressions. This is a three-layer validation system that catches errors before deployment, validates complex multi-node workflows, checks all n8n expressions for syntax errors, and ensures proper node connections and data flow.',
|
||||
parameters: {
|
||||
workflow: {
|
||||
type: 'object',
|
||||
required: true,
|
||||
description: 'The complete workflow JSON to validate. Must include nodes array and connections object.'
|
||||
},
|
||||
options: {
|
||||
type: 'object',
|
||||
required: false,
|
||||
description: 'Validation options object'
|
||||
},
|
||||
'options.validateNodes': {
|
||||
type: 'boolean',
|
||||
required: false,
|
||||
description: 'Validate individual node configurations. Default: true'
|
||||
},
|
||||
'options.validateConnections': {
|
||||
type: 'boolean',
|
||||
required: false,
|
||||
description: 'Validate node connections and flow. Default: true'
|
||||
},
|
||||
'options.validateExpressions': {
|
||||
type: 'boolean',
|
||||
required: false,
|
||||
description: 'Validate n8n expressions syntax and references. Default: true'
|
||||
},
|
||||
'options.profile': {
|
||||
type: 'string',
|
||||
required: false,
|
||||
description: 'Validation profile for node validation: minimal, runtime (default), ai-friendly, strict'
|
||||
}
|
||||
},
|
||||
returns: 'Object with valid (boolean), errors (array), warnings (array), statistics (object), and suggestions (array)',
|
||||
examples: [
|
||||
'validate_workflow({workflow: myWorkflow}) - Full validation with default settings',
|
||||
'validate_workflow({workflow: myWorkflow, options: {profile: "minimal"}}) - Quick validation for editing',
|
||||
'validate_workflow({workflow: myWorkflow, options: {validateExpressions: false}}) - Skip expression validation'
|
||||
],
|
||||
useCases: [
|
||||
'Pre-deployment validation to catch all workflow issues',
|
||||
'Quick validation during workflow development',
|
||||
'Validate workflows with AI Agent nodes and tool connections',
|
||||
'Check expression syntax before workflow execution',
|
||||
'Ensure workflow structure integrity after modifications'
|
||||
],
|
||||
performance: 'Moderate (100-500ms). Depends on workflow size and validation options. Expression validation adds ~50-100ms.',
|
||||
bestPractices: [
|
||||
'Always validate workflows before creating or updating in n8n',
|
||||
'Use minimal profile during development, strict profile before production',
|
||||
'Pay attention to warnings - they often indicate potential runtime issues',
|
||||
'Validate after any workflow modifications, especially connection changes',
|
||||
'Check statistics to understand workflow complexity'
|
||||
],
|
||||
pitfalls: [
|
||||
'Large workflows (100+ nodes) may take longer to validate',
|
||||
'Expression validation requires proper node references to exist',
|
||||
'Some warnings may be acceptable depending on use case',
|
||||
'Validation cannot catch all runtime errors (e.g., API failures)',
|
||||
'Profile setting only affects node validation, not connection/expression checks'
|
||||
],
|
||||
relatedTools: ['validate_workflow_connections', 'validate_workflow_expressions', 'validate_node_operation', 'n8n_create_workflow', 'n8n_update_partial_workflow']
|
||||
}
|
||||
};
|
||||
Reference in New Issue
Block a user