ros/n8n-mcp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: enhance start_here_workflow_guide and Claude Project Setup

Browse Source 
- Add comprehensive AI tools guide in start_here_workflow_guide
  - New 'ai_tools' topic with detailed AI workflow patterns
  - Key insight: ANY node can be used as an AI tool
  - $fromAI() expression examples and best practices
  - AI tool connection validation guidance

- Update recommended workflow to include validate_node_minimal
  - Quick required fields check before full validation
  - Performance tips for validation tools

- Enhance Claude Project Setup instructions
  - Clear 5-phase workflow process
  - Emphasis on AI tool integration
  - Validation best practices
  - Better tool usage examples

- Add validation_guide section to workflow guide
  - When to use each validation tool
  - Performance considerations
  - AI workflow validation patterns

These updates make it much clearer how to use the MCP tools effectively,
especially for AI workflows where ANY node can be connected as a tool.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
czlonkowski
2025-06-24 16:38:18 +02:00
parent aad1b69fb1
commit 0890264022
3 changed files with 196 additions and 44 deletions
Download Patch File Download Diff File Expand all files Collapse all files

108
README.md
View File

@@ -415,49 +415,87 @@ For the best results when using n8n-MCP with Claude Projects, use these system i
```markdown
You are an expert in n8n automation software. Your role is to answer questions about how to deliver specific functionalities that users ask for, or design and implement single nodes or entire workflows.
## Instructions
## Core Workflow Process
1. Read the user's question and analyze what functionality they're trying to achieve.
1. **ALWAYS start with**: `start_here_workflow_guide()` to understand best practices and available tools.
2. **ALWAYS** use the n8n-MCP tools in this order:
- `start_here_workflow_guide` - Get best practices and common patterns
- `search_nodes` - Find relevant nodes for the task
- `get_node_essentials` - Get essential configuration (prefer over get_node_info)
- `get_node_documentation` - Read full documentation before implementing
2. **Discovery Phase** - Find the right nodes:
- `search_nodes({query: 'keyword'})` - Search by functionality
- `list_nodes({category: 'trigger'})` - Browse by category
- `list_ai_tools()` - See AI-optimized nodes (but remember: ANY node can be an AI tool!)
3. First, check if standard n8n nodes can achieve the functionality. If so, propose these nodes and explain their configuration.
3. **Configuration Phase** - Get node details efficiently:
- `get_node_essentials(nodeType)` - Start here! Only 10-20 essential properties
- `search_node_properties(nodeType, 'auth')` - Find specific properties
- `get_node_for_task('send_email')` - Get pre-configured templates
- `get_node_documentation(nodeType)` - Human-readable docs when needed
4. If standard nodes aren't sufficient, propose a Code node:
- Explain why it's necessary
- Plan the solution architecture carefully
- Use JavaScript syntax required by n8n's Code node
- Access input data with `$input.all()` or `items[0].json`
- Return data in n8n's expected format
4. **Validation Phase** - Ensure correctness:
- `validate_node_minimal(nodeType, config)` - Quick required fields check
- `validate_node_operation(nodeType, config, profile)` - Full smart validation
- `validate_workflow(workflow)` - Complete workflow validation including AI connections
5. Structure your answer as:
a. Brief explanation of the solution
b. List of nodes and their configuration
c. Code examples if using Code node
d. Additional tips or considerations
e. **Single node JSON** if requested - provide copyable node JSON
f. **Full workflow JSON** if requested - provide complete workflow JSON
5. **AI Tool Integration** (when building AI workflows):
- `get_node_as_tool_info(nodeType)` - Learn how to use ANY node as AI tool
- Remember: Connect ANY node to AI Agent's 'ai_tool' port
- Use `$fromAI()` expressions for dynamic values
- Validate with `validate_workflow()` to check ai_tool connections
## Key Insights
- **ANY node can be an AI tool** - not just those with usableAsTool=true
- **Use validate_node_minimal first** - fastest way to check required fields
- **Avoid get_node_info** - returns 100KB+ of data; use get_node_essentials instead
- **Pre-built templates exist** - check get_node_for_task() for common scenarios
## Response Structure
1. **Analysis**: Brief explanation of the solution approach
2. **Node Selection**: Which nodes to use and why
3. **Configuration**:
- Use get_node_essentials for clean configs
- Show only necessary properties
- Include validation results
4. **Code Examples**: If using Code node, provide working JavaScript
5. **Validation**: Always validate before providing final solution
6. **Export Options**:
- Single node JSON if requested
- Complete workflow JSON for full solutions
## Example Patterns
### Standard Automation
```
1. search_nodes({query: 'slack'})
2. get_node_essentials('nodes-base.slack')
3. validate_node_minimal('nodes-base.slack', {resource:'message',operation:'post'})
4. get_node_for_task('send_slack_message') // for pre-configured version
```
### AI Agent with Tools
```
1. search_nodes({query: 'agent'})
2. get_node_as_tool_info('nodes-base.googleSheets') // ANY node as tool!
3. Configure AI Agent with tool connections
4. Use $fromAI() in tool node configurations
5. validate_workflow(fullWorkflow) // validates ai_tool connections
```
### Quick Task Solutions
```
1. list_tasks() // see all available templates
2. get_node_for_task('webhook_with_response')
3. validate_node_minimal() on the configuration
4. Provide ready-to-use solution
```
## Important Rules
- ALWAYS check node documentation via MCP before implementing
- Use `get_node_essentials` instead of `get_node_info` for faster responses
- Validate configurations with `validate_node_operation` before finalizing
- State clearly if you're unsure about any aspect
- Provide practical, working solutions that users can immediately use in n8n
## Example Workflow
1. User asks: "How do I send Slack messages when a Google Sheet updates?"
2. Use `search_nodes({ query: "slack" })` and `search_nodes({ query: "google sheets" })`
3. Use `get_node_essentials("nodes-base.googleSheetsTrigger")`
4. Use `get_node_essentials("nodes-base.slack")`
5. Read documentation for both nodes
6. Provide complete workflow with proper configuration
- Start with essentials, not full node info
- Validate incrementally (minimal → operation → workflow)
- For AI workflows, explain that ANY node can be a tool
- Always provide working, validated configurations
- State uncertainty clearly and suggest alternatives
```
Save these instructions in your Claude Project for optimal n8n workflow assistance.

130
src/mcp/server-update.ts
View File

@@ -1128,7 +1128,8 @@ Full documentation is being prepared. For now, use get_node_essentials for confi
"1. search_nodes({query:'slack'}) - Find nodes by keyword",
"2. get_node_essentials('nodes-base.slack') - Get only essential properties (<5KB)",
"3. get_node_for_task('send_slack_message') - Get pre-configured settings",
"4. validate_node_operation() - Validate before use"
"4. validate_node_minimal() - Quick check for required fields only",
"5. validate_node_operation() - Full validation with suggestions"
],
tip: "Avoid get_node_info unless you need ALL properties (100KB+ response)"
},
@@ -1136,7 +1137,25 @@ Full documentation is being prepared. For now, use get_node_essentials for confi
discovery: "list_nodes({category:'trigger'}) - Browse by category",
quick_config: "get_node_essentials() - 95% smaller than get_node_info",
tasks: "list_tasks() then get_node_for_task() - Pre-configured common tasks",
validation: "validate_node_operation() - Catch errors before execution"
validation: "validate_node_minimal() for quick checks, validate_node_operation() for full validation",
ai_tools: "get_node_as_tool_info() - Learn how to use ANY node as an AI tool"
},
ai_workflow_pattern: {
title: "AI Agent Workflows",
key_insight: "ANY node can be used as an AI tool - not just those marked with usableAsTool!",
steps: [
"1. Create an AI Agent node (e.g., @n8n/n8n-nodes-langchain.agent)",
"2. Connect ANY node to the AI Agent's 'ai_tool' port",
"3. Use get_node_as_tool_info() to understand tool configuration",
"4. Configure tool with $fromAI() expressions for dynamic values",
"5. validate_workflow() to check AI tool connections"
],
examples: [
"Slack node → AI Agent's tool port = AI can send Slack messages",
"Google Sheets → AI Agent's tool port = AI can read/write spreadsheets",
"HTTP Request → AI Agent's tool port = AI can call any API"
],
validation: "Use validate_workflow() to verify ai_tool connections are valid"
}
}
},
@@ -1148,7 +1167,8 @@ Full documentation is being prepared. For now, use get_node_essentials for confi
steps: [
"search_nodes or list_nodes to find nodes",
"get_node_essentials for configuration",
"validate_node_config before execution"
"validate_node_minimal for quick required field check",
"validate_node_operation for full validation"
]
},
{
@@ -1156,7 +1176,19 @@ Full documentation is being prepared. For now, use get_node_essentials for confi
steps: [
"list_tasks() to see available templates",
"get_node_for_task() for instant configuration",
"Fill in userMustProvide fields"
"Fill in userMustProvide fields",
"validate_node_minimal() to ensure all required fields present"
]
},
{
name: "AI Agent with Tools",
steps: [
"Create AI Agent node",
"search_nodes() to find tool nodes",
"get_node_as_tool_info() for each tool node",
"Connect nodes to ai_tool port",
"Configure with $fromAI() expressions",
"validate_workflow() to check everything"
]
}
]
@@ -1178,6 +1210,16 @@ Full documentation is being prepared. For now, use get_node_essentials for confi
core: ["httpRequest", "code", "set", "if", "merge", "splitInBatches"],
integrations: ["slack", "gmail", "googleSheets", "postgres", "mongodb"],
ai: ["agent", "openAi", "chainLlm", "documentLoader"]
},
ai_tool_usage: {
note: "ANY node from above can be used as an AI tool!",
popular_ai_tools: [
"slack - Send messages, create channels",
"googleSheets - Read/write data",
"httpRequest - Call any API",
"gmail - Send emails",
"postgres - Query databases"
]
}
},
known_issues: {
@@ -1197,17 +1239,62 @@ Full documentation is being prepared. For now, use get_node_essentials for confi
"get_node_essentials - <5KB responses",
"search_nodes - Indexed search",
"list_nodes - Direct queries",
"validate_node_minimal - Only required fields",
"start_here_workflow_guide - Static content"
],
slow: [
"get_node_info - 100KB+ responses",
"get_node_documentation - Can be large"
"get_node_documentation - Can be large",
"validate_workflow - Full workflow analysis"
]
},
tips: [
"Use get_node_essentials for 95% of use cases",
"Only use get_node_info when essentials lack needed property",
"Results are cached for repeated queries"
"Results are cached for repeated queries",
"Use validate_node_minimal before validate_node_operation"
]
},
ai_tools: {
title: "AI Tools & Agent Workflows",
key_concept: "In n8n, ANY node can be used as an AI tool - not just those marked with usableAsTool!",
how_it_works: {
"1. Connection": "Connect any node to an AI Agent's 'ai_tool' port",
"2. Configuration": "Use $fromAI() expressions to let AI provide dynamic values",
"3. Description": "Give tools clear names and descriptions in AI Agent settings",
"4. Validation": "Use validate_workflow() to verify ai_tool connections"
},
common_patterns: {
"Data Collection": {
nodes: ["googleSheets", "postgres", "mongodb"],
usage: "AI reads data to answer questions or make decisions"
},
"Actions & Notifications": {
nodes: ["slack", "gmail", "httpRequest"],
usage: "AI performs actions based on analysis"
},
"API Integration": {
nodes: ["httpRequest", "webhook"],
usage: "AI calls external services and APIs"
}
},
example_expressions: {
"Dynamic values": '{{ $fromAI("channel", "Slack channel to post to") }}',
"Complex data": '{{ $fromAI("query", "SQL query to execute") }}',
"Conditional": '{{ $fromAI("shouldNotify", "true/false to send notification") }}'
},
best_practices: [
"Test nodes individually before connecting as tools",
"Write detailed tool descriptions for better AI understanding",
"Use validate_workflow() to catch connection issues",
"Start simple - one or two tools, then expand",
"Monitor AI tool usage in workflow executions"
],
tools_to_use: [
"get_node_as_tool_info() - Understand any node's AI capabilities",
"list_ai_tools() - See nodes optimized for AI (263 available)",
"validate_workflow() - Verify ai_tool connections",
"get_node_essentials() - Configure tool nodes efficiently"
]
}
};
@@ -1225,22 +1312,49 @@ Full documentation is being prepared. For now, use get_node_essentials for confi
searchTips: guides.search_tips,
commonNodes: guides.common_nodes,
knownIssues: guides.known_issues,
performance: guides.performance
performance: guides.performance,
aiTools: guides.ai_tools
},
examples: {
"Find and configure Slack": [
"search_nodes({query:'slack'})",
"get_node_essentials('nodes-base.slack')",
"validate_node_minimal('nodes-base.slack', {resource:'message',operation:'post'})",
"get_node_for_task('send_slack_message')"
],
"Set up webhook trigger": [
"get_node_for_task('receive_webhook')",
"validate_node_minimal('nodes-base.webhook', config)",
"// Returns pre-configured webhook with instructions"
],
"HTTP API call": [
"get_node_essentials('nodes-base.httpRequest')",
"search_node_properties('nodes-base.httpRequest', 'auth')"
"search_node_properties('nodes-base.httpRequest', 'auth')",
"validate_node_operation('nodes-base.httpRequest', config)"
],
"AI Agent with Slack tool": [
"search_nodes({query:'agent'})",
"get_node_as_tool_info('nodes-base.slack')",
"// Connect Slack to AI Agent's ai_tool port",
"// Configure with $fromAI() expressions",
"validate_workflow(workflow)"
]
},
validation_guide: {
title: "Validation Tools Guide",
tools: {
"validate_node_minimal": "Fastest - only checks required fields",
"validate_node_operation": "Smart - checks based on selected operation",
"validate_workflow": "Complete - validates entire workflow including AI connections",
"validate_workflow_connections": "Structure - just checks node connections",
"validate_workflow_expressions": "Expressions - validates $json, $node, $fromAI"
},
when_to_use: {
"Building nodes": "Use validate_node_minimal first, then validate_node_operation",
"AI workflows": "Always use validate_workflow to check ai_tool connections",
"Quick checks": "validate_node_minimal when you just need required fields",
"Before deployment": "validate_workflow with all options enabled"
}
}
};
}

2
src/mcp/tools-update.ts
View File

@@ -15,7 +15,7 @@ export const n8nDocumentationToolsFinal: ToolDefinition[] = [
properties: {
topic: {
type: 'string',
enum: ['overview', 'workflow', 'search_tips', 'common_nodes', 'known_issues', 'performance'],
enum: ['overview', 'workflow', 'search_tips', 'common_nodes', 'known_issues', 'performance', 'ai_tools'],
description: 'Optional: Get specific guidance on a topic. Default returns complete overview.',
},
},