feat(tools): rename start_here to tools_documentation with depth control (v2.7.4)
- Renamed start_here_workflow_guide to tools_documentation for clarity - Added depth parameter to control documentation detail (essentials/full) - Converted output from JSON to LLM-friendly plain text format - Added per-tool documentation capability - Created two-tier documentation system: - Essentials: brief info with key parameters and tips - Full: comprehensive docs with examples and best practices - Documented 8 commonly used MCP tools - Removed 380+ lines of unused getWorkflowGuide method - Fixed duplicate tool definitions - Updated all documentation references - Added test script for tools documentation BREAKING CHANGE: start_here_workflow_guide renamed to tools_documentation 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
czlonkowski
25
CLAUDE.md
25
CLAUDE.md
@@ -6,7 +6,21 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
|
||||
|
||||
n8n-mcp is a comprehensive documentation and knowledge server that provides AI assistants with complete access to n8n node information through the Model Context Protocol (MCP). It serves as a bridge between n8n's workflow automation platform and AI models, enabling them to understand and work with n8n nodes effectively.
|
||||
|
||||
## ✅ Latest Updates (v2.7.0)
|
||||
## ✅ Latest Updates (v2.7.4)
|
||||
|
||||
### Update (v2.7.4) - Self-Documenting MCP Tools:
|
||||
- ✅ **RENAMED: start_here_workflow_guide → tools_documentation** - More descriptive name
|
||||
- ✅ **NEW: Depth parameter** - Control documentation detail level with "essentials" or "full"
|
||||
- ✅ **NEW: Per-tool documentation** - Get help for any specific tool by name
|
||||
- ✅ **Concise by default** - Essential info only, unless full depth requested
|
||||
- ✅ **LLM-friendly format** - Plain text, not JSON for better readability
|
||||
- ✅ **Two-tier documentation**:
|
||||
- **Essentials**: Brief description, key parameters, example, performance, 2-3 tips
|
||||
- **Full**: Complete documentation with all parameters, examples, use cases, best practices, pitfalls
|
||||
- ✅ **Quick reference** - Call without parameters for immediate help
|
||||
- ✅ **8 documented tools** - Comprehensive docs for most commonly used tools
|
||||
- ✅ **Performance guidance** - Clear indication of which tools are fast vs slow
|
||||
- ✅ **Error prevention** - Common pitfalls documented upfront
|
||||
|
||||
### Update (v2.7.0) - Diff-Based Workflow Editing with Transactional Updates:
|
||||
- ✅ **NEW: n8n_update_partial_workflow tool** - Update workflows using diff operations for precise, incremental changes
|
||||
@@ -128,11 +142,14 @@ src/
|
||||
│ ├── test-mcp-tools.ts # Test MCP tool enhancements (NEW in v2.5.1)
|
||||
│ ├── test-n8n-validate-workflow.ts # Test n8n_validate_workflow tool (NEW in v2.6.3)
|
||||
│ ├── test-typeversion-validation.ts # Test typeVersion validation (NEW in v2.6.1)
|
||||
│ ├── test-workflow-diff.ts # Test workflow diff engine (NEW in v2.7.0)
|
||||
│ ├── test-tools-documentation.ts # Test tools documentation (NEW in v2.7.3)
|
||||
│ ├── fetch-templates.ts # Fetch workflow templates from n8n.io (NEW in v2.4.1)
|
||||
│ └── test-templates.ts # Test template functionality (NEW in v2.4.1)
|
||||
├── mcp/
|
||||
│ ├── server-update.ts # MCP server with enhanced tools
|
||||
│ ├── tools-update.ts # Tool definitions including new essentials
|
||||
│ ├── server.ts # MCP server with enhanced tools
|
||||
│ ├── tools.ts # Tool definitions including new essentials
|
||||
│ ├── tools-documentation.ts # Tool documentation system (NEW in v2.7.3)
|
||||
│ └── index.ts # Main entry point with mode selection
|
||||
├── utils/
|
||||
│ ├── console-manager.ts # Console output isolation (NEW in v2.3.1)
|
||||
@@ -183,6 +200,7 @@ npm run test:n8n-manager # Test n8n management tools integration
|
||||
npm run test:n8n-validate-workflow # Test n8n_validate_workflow tool
|
||||
npm run test:typeversion-validation # Test typeVersion validation
|
||||
npm run test:workflow-diff # Test workflow diff engine
|
||||
npm run test:tools-documentation # Test MCP tools documentation system
|
||||
|
||||
# Workflow Validation Commands:
|
||||
npm run test:workflow-validation # Test workflow validation features
|
||||
@@ -308,6 +326,7 @@ The project implements MCP (Model Context Protocol) to expose n8n node documenta
|
||||
- `get_template` - **NEW** Get complete workflow JSON for import
|
||||
- `search_templates` - **NEW** Search templates by keywords
|
||||
- `get_templates_for_task` - **NEW** Get curated templates for common tasks
|
||||
- `tools_documentation` - **NEW v2.7.3** Get comprehensive documentation for MCP tools
|
||||
|
||||
### n8n Management Tools (NEW v2.6.0 - Requires API Configuration)
|
||||
These tools are only available when N8N_API_URL and N8N_API_KEY are configured:
|
||||
|
||||
@@ -68,7 +68,7 @@ Add an MCP Client node to your workflow with these settings:
|
||||
|
||||
### List Tools
|
||||
Shows all available MCP tools:
|
||||
- `start_here_workflow_guide`
|
||||
- `tools_documentation`
|
||||
- `list_nodes`
|
||||
- `get_node_info`
|
||||
- `search_nodes`
|
||||
|
||||
15
README.md
15
README.md
@@ -2,7 +2,7 @@
|
||||
|
||||
[](https://opensource.org/licenses/MIT)
|
||||
[](https://github.com/czlonkowski/n8n-mcp)
|
||||
[](https://github.com/czlonkowski/n8n-mcp)
|
||||
[](https://github.com/czlonkowski/n8n-mcp)
|
||||
[](https://github.com/czlonkowski/n8n-mcp/pkgs/container/n8n-mcp)
|
||||
|
||||
A Model Context Protocol (MCP) server that provides AI assistants with comprehensive access to n8n node documentation, properties, and operations. Deploy in minutes to give Claude and other AI assistants deep knowledge about n8n's 525+ workflow automation nodes.
|
||||
@@ -198,7 +198,7 @@ You are an expert in n8n automation software using n8n-MCP tools. Your role is t
|
||||
|
||||
## Core Workflow Process
|
||||
|
||||
1. **ALWAYS start with**: `start_here_workflow_guide()` to understand best practices and available tools.
|
||||
1. **ALWAYS start with**: `tools_documentation()` to understand best practices and available tools.
|
||||
|
||||
2. **Discovery Phase** - Find the right nodes:
|
||||
- `search_nodes({query: 'keyword'})` - Search by functionality
|
||||
@@ -343,7 +343,7 @@ When Claude, Anthropic's AI assistant, tested n8n-MCP, the results were transfor
|
||||
Once connected, Claude can use these powerful tools:
|
||||
|
||||
### Core Tools
|
||||
- **`start_here_workflow_guide`** - Essential guide and best practices (START HERE!)
|
||||
- **`tools_documentation`** - Get documentation for any MCP tool (START HERE!)
|
||||
- **`list_nodes`** - List all n8n nodes with filtering options
|
||||
- **`get_node_info`** - Get comprehensive information about a specific node
|
||||
- **`get_node_essentials`** - Get only essential properties with examples (10-20 properties instead of 200+)
|
||||
@@ -502,6 +502,15 @@ Current database coverage (n8n v1.99.1):
|
||||
|
||||
## 🔄 Recent Updates
|
||||
|
||||
### v2.7.4 - Self-Documenting MCP Tools
|
||||
- ✅ **RENAMED**: `start_here_workflow_guide` → `tools_documentation` for clarity
|
||||
- ✅ **NEW**: Depth parameter - Control documentation detail with "essentials" or "full"
|
||||
- ✅ **NEW**: Per-tool documentation - Get help for any specific MCP tool by name
|
||||
- ✅ **CONCISE**: Essential info by default, comprehensive docs on demand
|
||||
- ✅ **LLM-FRIENDLY**: Plain text format instead of JSON for better readability
|
||||
- ✅ **QUICK HELP**: Call without parameters for immediate quick reference
|
||||
- ✅ **8 TOOLS DOCUMENTED**: Complete documentation for most commonly used tools
|
||||
|
||||
### v2.7.0 - Diff-Based Workflow Editing with Transactional Updates
|
||||
- ✅ **NEW**: `n8n_update_partial_workflow` tool - Update workflows using diff operations
|
||||
- ✅ **RENAMED**: `n8n_update_workflow` → `n8n_update_full_workflow` for clarity
|
||||
|
||||
@@ -5,6 +5,60 @@ All notable changes to this project will be documented in this file.
|
||||
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
|
||||
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
||||
|
||||
## [2.7.4] - 2025-07-03
|
||||
|
||||
### Changed
|
||||
- Renamed `start_here_workflow_guide` tool to `tools_documentation` for better clarity
|
||||
- Converted tool output from JSON to LLM-friendly plain text format
|
||||
- Made documentation concise by default with "essentials" depth
|
||||
|
||||
### Added
|
||||
- `depth` parameter to control documentation detail level ("essentials" or "full")
|
||||
- Per-tool documentation - get help for any specific MCP tool
|
||||
- Two-tier documentation system:
|
||||
- Essentials: Brief description, key parameters, example, performance, tips
|
||||
- Full: Complete documentation with all details, examples, best practices
|
||||
- Quick reference mode when called without parameters
|
||||
- Documentation for 8 commonly used tools
|
||||
- Test script for tools documentation (`test:tools-documentation`)
|
||||
|
||||
### Removed
|
||||
- Removed duplicate `tools_documentation` tool definition
|
||||
- Removed unused `getWorkflowGuide` method (380+ lines)
|
||||
- Removed old `handlers-documentation.ts` file
|
||||
|
||||
## [2.7.3] - 2025-07-02
|
||||
|
||||
### Added
|
||||
- MCP Tools Documentation system (initial implementation)
|
||||
- `tools_documentation` tool for comprehensive MCP tool documentation
|
||||
- Documentation includes parameters, examples, best practices, and pitfalls
|
||||
- Search tools by keyword functionality
|
||||
- Browse tools by category
|
||||
- Quick reference guide with workflow patterns
|
||||
|
||||
### Fixed
|
||||
- Cleaned up redundant tool definitions
|
||||
|
||||
## [2.7.2] - 2025-07-01
|
||||
|
||||
### Fixed
|
||||
- HTTP deployment documentation improvements
|
||||
- Docker configuration updates with n8n API options
|
||||
|
||||
### Changed
|
||||
- Updated version handling in multiple configuration files
|
||||
|
||||
## [2.7.1] - 2025-06-30
|
||||
|
||||
### Fixed
|
||||
- Workflow diff engine edge cases
|
||||
- Transactional update processing improvements
|
||||
|
||||
### Added
|
||||
- Additional test coverage for diff operations
|
||||
- Debug scripts for update operations
|
||||
|
||||
## [2.7.0] - 2025-06-29
|
||||
|
||||
### Added
|
||||
@@ -257,6 +311,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
||||
- Basic n8n and MCP integration
|
||||
- Core workflow automation features
|
||||
|
||||
[2.7.4]: https://github.com/czlonkowski/n8n-mcp/compare/v2.7.3...v2.7.4
|
||||
[2.7.3]: https://github.com/czlonkowski/n8n-mcp/compare/v2.7.2...v2.7.3
|
||||
[2.7.2]: https://github.com/czlonkowski/n8n-mcp/compare/v2.7.1...v2.7.2
|
||||
[2.7.1]: https://github.com/czlonkowski/n8n-mcp/compare/v2.7.0...v2.7.1
|
||||
[2.7.0]: https://github.com/czlonkowski/n8n-mcp/compare/v2.6.3...v2.7.0
|
||||
[2.6.3]: https://github.com/czlonkowski/n8n-mcp/compare/v2.6.2...v2.6.3
|
||||
[2.6.2]: https://github.com/czlonkowski/n8n-mcp/compare/v2.6.1...v2.6.2
|
||||
|
||||
@@ -115,7 +115,7 @@ After restarting Claude Desktop:
|
||||
## 🔧 Available Tools (v2.5.1)
|
||||
|
||||
### Essential Tool - Start Here!
|
||||
- **`start_here_workflow_guide`** - Essential guide and best practices (ALWAYS use this first!)
|
||||
- **`tools_documentation`** - Get documentation for any MCP tool (ALWAYS use this first!)
|
||||
|
||||
### Core Tools
|
||||
- **`list_nodes`** - List all n8n nodes with filtering options
|
||||
|
||||
712
docs/mcp-tools-documentation.md
Normal file
712
docs/mcp-tools-documentation.md
Normal file
@@ -0,0 +1,712 @@
|
||||
# MCP Tools Documentation for LLMs
|
||||
|
||||
This document provides comprehensive documentation for the most commonly used MCP tools in the n8n-mcp server. Each tool includes parameters, return formats, examples, and best practices.
|
||||
|
||||
## Table of Contents
|
||||
1. [search_nodes](#search_nodes)
|
||||
2. [get_node_essentials](#get_node_essentials)
|
||||
3. [list_nodes](#list_nodes)
|
||||
4. [validate_node_minimal](#validate_node_minimal)
|
||||
5. [validate_node_operation](#validate_node_operation)
|
||||
6. [get_node_for_task](#get_node_for_task)
|
||||
7. [n8n_create_workflow](#n8n_create_workflow)
|
||||
8. [n8n_update_partial_workflow](#n8n_update_partial_workflow)
|
||||
|
||||
---
|
||||
|
||||
## search_nodes
|
||||
|
||||
**Brief Description**: Search for n8n nodes by keywords in names and descriptions.
|
||||
|
||||
### Parameters
|
||||
- `query` (string, required): Search term - single word recommended for best results
|
||||
- `limit` (number, optional): Maximum results to return (default: 20)
|
||||
|
||||
### Return Format
|
||||
```json
|
||||
{
|
||||
"nodes": [
|
||||
{
|
||||
"nodeType": "nodes-base.slack",
|
||||
"displayName": "Slack",
|
||||
"description": "Send messages to Slack channels"
|
||||
}
|
||||
],
|
||||
"totalFound": 5
|
||||
}
|
||||
```
|
||||
|
||||
### Common Use Cases
|
||||
1. **Finding integration nodes**: `search_nodes("slack")` to find Slack integration
|
||||
2. **Finding HTTP nodes**: `search_nodes("http")` for HTTP/webhook nodes
|
||||
3. **Finding database nodes**: `search_nodes("postgres")` for PostgreSQL nodes
|
||||
|
||||
### Examples
|
||||
```json
|
||||
// Search for Slack-related nodes
|
||||
{
|
||||
"query": "slack",
|
||||
"limit": 10
|
||||
}
|
||||
|
||||
// Search for webhook nodes
|
||||
{
|
||||
"query": "webhook",
|
||||
"limit": 20
|
||||
}
|
||||
```
|
||||
|
||||
### Performance Notes
|
||||
- Fast operation (cached results)
|
||||
- Single-word queries are more precise
|
||||
- Returns results with OR logic (any word matches)
|
||||
|
||||
### Best Practices
|
||||
- Use single words for precise results: "slack" not "send slack message"
|
||||
- Try shorter terms if no results: "sheet" instead of "spreadsheet"
|
||||
- Search is case-insensitive
|
||||
- Common searches: "http", "webhook", "email", "database", "slack"
|
||||
|
||||
### Common Pitfalls
|
||||
- Multi-word searches return too many results (OR logic)
|
||||
- Searching for exact phrases doesn't work
|
||||
- Node types aren't searchable here (use exact type with get_node_info)
|
||||
|
||||
### Related Tools
|
||||
- `list_nodes` - Browse nodes by category
|
||||
- `get_node_essentials` - Get node configuration after finding it
|
||||
- `list_ai_tools` - Find AI-capable nodes specifically
|
||||
|
||||
---
|
||||
|
||||
## get_node_essentials
|
||||
|
||||
**Brief Description**: Get only the 10-20 most important properties for a node with working examples.
|
||||
|
||||
### Parameters
|
||||
- `nodeType` (string, required): Full node type with prefix (e.g., "nodes-base.httpRequest")
|
||||
|
||||
### Return Format
|
||||
```json
|
||||
{
|
||||
"nodeType": "nodes-base.httpRequest",
|
||||
"displayName": "HTTP Request",
|
||||
"essentialProperties": [
|
||||
{
|
||||
"name": "method",
|
||||
"type": "options",
|
||||
"default": "GET",
|
||||
"options": ["GET", "POST", "PUT", "DELETE"],
|
||||
"required": true
|
||||
},
|
||||
{
|
||||
"name": "url",
|
||||
"type": "string",
|
||||
"required": true,
|
||||
"placeholder": "https://api.example.com/endpoint"
|
||||
}
|
||||
],
|
||||
"examples": [
|
||||
{
|
||||
"name": "Simple GET Request",
|
||||
"configuration": {
|
||||
"method": "GET",
|
||||
"url": "https://api.example.com/users"
|
||||
}
|
||||
}
|
||||
],
|
||||
"tips": [
|
||||
"Use expressions like {{$json.url}} to make URLs dynamic",
|
||||
"Enable 'Split Into Items' for array responses"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Common Use Cases
|
||||
1. **Quick node configuration**: Get just what you need without parsing 100KB+ of data
|
||||
2. **Learning node basics**: Understand essential properties with examples
|
||||
3. **Building workflows efficiently**: 95% smaller responses than get_node_info
|
||||
|
||||
### Examples
|
||||
```json
|
||||
// Get essentials for HTTP Request node
|
||||
{
|
||||
"nodeType": "nodes-base.httpRequest"
|
||||
}
|
||||
|
||||
// Get essentials for Slack node
|
||||
{
|
||||
"nodeType": "nodes-base.slack"
|
||||
}
|
||||
|
||||
// Get essentials for OpenAI node
|
||||
{
|
||||
"nodeType": "nodes-langchain.openAi"
|
||||
}
|
||||
```
|
||||
|
||||
### Performance Notes
|
||||
- Very fast (<5KB responses vs 100KB+ for full info)
|
||||
- Curated for 20+ common nodes
|
||||
- Automatic fallback for unconfigured nodes
|
||||
|
||||
### Best Practices
|
||||
- Always use this before get_node_info
|
||||
- Node type must include prefix: "nodes-base.slack" not "slack"
|
||||
- Check examples section for working configurations
|
||||
- Use tips section for common patterns
|
||||
|
||||
### Common Pitfalls
|
||||
- Forgetting the prefix in node type
|
||||
- Using wrong package name (n8n-nodes-base vs @n8n/n8n-nodes-langchain)
|
||||
- Case sensitivity in node types
|
||||
|
||||
### Related Tools
|
||||
- `get_node_info` - Full schema when essentials aren't enough
|
||||
- `search_node_properties` - Find specific properties
|
||||
- `get_node_for_task` - Pre-configured for common tasks
|
||||
|
||||
---
|
||||
|
||||
## list_nodes
|
||||
|
||||
**Brief Description**: List available n8n nodes with optional filtering by package, category, or capabilities.
|
||||
|
||||
### Parameters
|
||||
- `package` (string, optional): Filter by exact package name
|
||||
- `category` (string, optional): Filter by category (trigger, transform, output, input)
|
||||
- `developmentStyle` (string, optional): Filter by implementation style
|
||||
- `isAITool` (boolean, optional): Filter for AI-capable nodes
|
||||
- `limit` (number, optional): Maximum results (default: 50, max: 500)
|
||||
|
||||
### Return Format
|
||||
```json
|
||||
{
|
||||
"nodes": [
|
||||
{
|
||||
"nodeType": "nodes-base.webhook",
|
||||
"displayName": "Webhook",
|
||||
"description": "Receive HTTP requests",
|
||||
"categories": ["trigger"],
|
||||
"version": 2
|
||||
}
|
||||
],
|
||||
"total": 104,
|
||||
"hasMore": false
|
||||
}
|
||||
```
|
||||
|
||||
### Common Use Cases
|
||||
1. **Browse all triggers**: `list_nodes({category: "trigger", limit: 200})`
|
||||
2. **List all nodes**: `list_nodes({limit: 500})`
|
||||
3. **Find AI nodes**: `list_nodes({isAITool: true})`
|
||||
4. **Browse core nodes**: `list_nodes({package: "n8n-nodes-base"})`
|
||||
|
||||
### Examples
|
||||
```json
|
||||
// List all trigger nodes
|
||||
{
|
||||
"category": "trigger",
|
||||
"limit": 200
|
||||
}
|
||||
|
||||
// List all AI-capable nodes
|
||||
{
|
||||
"isAITool": true,
|
||||
"limit": 100
|
||||
}
|
||||
|
||||
// List nodes from core package
|
||||
{
|
||||
"package": "n8n-nodes-base",
|
||||
"limit": 200
|
||||
}
|
||||
```
|
||||
|
||||
### Performance Notes
|
||||
- Fast operation (cached results)
|
||||
- Default limit of 50 may miss nodes - use 200+
|
||||
- Returns metadata only, not full schemas
|
||||
|
||||
### Best Practices
|
||||
- Always set limit to 200+ for complete results
|
||||
- Use exact package names: "n8n-nodes-base" not "@n8n/n8n-nodes-base"
|
||||
- Categories are singular: "trigger" not "triggers"
|
||||
- Common categories: trigger (104), transform, output, input
|
||||
|
||||
### Common Pitfalls
|
||||
- Default limit (50) misses many nodes
|
||||
- Using wrong package name format
|
||||
- Multiple filters may return empty results
|
||||
|
||||
### Related Tools
|
||||
- `search_nodes` - Search by keywords
|
||||
- `list_ai_tools` - Specifically for AI nodes
|
||||
- `get_database_statistics` - Overview of all nodes
|
||||
|
||||
---
|
||||
|
||||
## validate_node_minimal
|
||||
|
||||
**Brief Description**: Quick validation checking only for missing required fields.
|
||||
|
||||
### Parameters
|
||||
- `nodeType` (string, required): Node type to validate (e.g., "nodes-base.slack")
|
||||
- `config` (object, required): Node configuration to check
|
||||
|
||||
### Return Format
|
||||
```json
|
||||
{
|
||||
"valid": false,
|
||||
"missingRequired": ["channel", "messageType"],
|
||||
"message": "Missing 2 required fields"
|
||||
}
|
||||
```
|
||||
|
||||
### Common Use Cases
|
||||
1. **Quick validation**: Check if all required fields are present
|
||||
2. **Pre-flight check**: Validate before creating workflow
|
||||
3. **Minimal overhead**: Fastest validation option
|
||||
|
||||
### Examples
|
||||
```json
|
||||
// Validate Slack message configuration
|
||||
{
|
||||
"nodeType": "nodes-base.slack",
|
||||
"config": {
|
||||
"resource": "message",
|
||||
"operation": "send",
|
||||
"text": "Hello World"
|
||||
// Missing: channel
|
||||
}
|
||||
}
|
||||
|
||||
// Validate HTTP Request
|
||||
{
|
||||
"nodeType": "nodes-base.httpRequest",
|
||||
"config": {
|
||||
"method": "POST"
|
||||
// Missing: url
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Performance Notes
|
||||
- Fastest validation option
|
||||
- No schema loading overhead
|
||||
- Returns only missing fields
|
||||
|
||||
### Best Practices
|
||||
- Use for quick checks during workflow building
|
||||
- Follow up with validate_node_operation for complex nodes
|
||||
- Check operation-specific requirements
|
||||
|
||||
### Common Pitfalls
|
||||
- Doesn't validate field values or types
|
||||
- Doesn't check operation-specific requirements
|
||||
- Won't catch configuration errors beyond missing fields
|
||||
|
||||
### Related Tools
|
||||
- `validate_node_operation` - Comprehensive validation
|
||||
- `validate_workflow` - Full workflow validation
|
||||
|
||||
---
|
||||
|
||||
## validate_node_operation
|
||||
|
||||
**Brief Description**: Comprehensive node configuration validation with operation awareness and helpful error messages.
|
||||
|
||||
### Parameters
|
||||
- `nodeType` (string, required): Node type to validate
|
||||
- `config` (object, required): Complete node configuration including operation fields
|
||||
- `profile` (string, optional): Validation profile (minimal, runtime, ai-friendly, strict)
|
||||
|
||||
### Return Format
|
||||
```json
|
||||
{
|
||||
"valid": false,
|
||||
"errors": [
|
||||
{
|
||||
"field": "channel",
|
||||
"message": "Channel is required to send Slack message",
|
||||
"suggestion": "Add channel: '#general' or '@username'"
|
||||
}
|
||||
],
|
||||
"warnings": [
|
||||
{
|
||||
"field": "unfurl_links",
|
||||
"message": "Consider setting unfurl_links: false for better performance"
|
||||
}
|
||||
],
|
||||
"examples": {
|
||||
"minimal": {
|
||||
"resource": "message",
|
||||
"operation": "send",
|
||||
"channel": "#general",
|
||||
"text": "Hello World"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Common Use Cases
|
||||
1. **Complex node validation**: Slack, Google Sheets, databases
|
||||
2. **Operation-specific checks**: Different rules per operation
|
||||
3. **Getting fix suggestions**: Helpful error messages with solutions
|
||||
|
||||
### Examples
|
||||
```json
|
||||
// Validate Slack configuration
|
||||
{
|
||||
"nodeType": "nodes-base.slack",
|
||||
"config": {
|
||||
"resource": "message",
|
||||
"operation": "send",
|
||||
"text": "Hello team!"
|
||||
},
|
||||
"profile": "ai-friendly"
|
||||
}
|
||||
|
||||
// Validate Google Sheets operation
|
||||
{
|
||||
"nodeType": "nodes-base.googleSheets",
|
||||
"config": {
|
||||
"operation": "append",
|
||||
"sheetId": "1234567890",
|
||||
"range": "Sheet1!A:Z"
|
||||
},
|
||||
"profile": "runtime"
|
||||
}
|
||||
```
|
||||
|
||||
### Performance Notes
|
||||
- Slower than minimal validation
|
||||
- Loads full node schema
|
||||
- Operation-aware validation rules
|
||||
|
||||
### Best Practices
|
||||
- Use "ai-friendly" profile for balanced validation
|
||||
- Check examples in response for working configurations
|
||||
- Follow suggestions to fix errors
|
||||
- Essential for complex nodes (Slack, databases, APIs)
|
||||
|
||||
### Common Pitfalls
|
||||
- Forgetting operation fields (resource, operation, action)
|
||||
- Using wrong profile (too strict or too lenient)
|
||||
- Ignoring warnings that could cause runtime issues
|
||||
|
||||
### Related Tools
|
||||
- `validate_node_minimal` - Quick required field check
|
||||
- `get_property_dependencies` - Understand field relationships
|
||||
- `validate_workflow` - Validate entire workflow
|
||||
|
||||
---
|
||||
|
||||
## get_node_for_task
|
||||
|
||||
**Brief Description**: Get pre-configured node settings for common automation tasks.
|
||||
|
||||
### Parameters
|
||||
- `task` (string, required): Task identifier (e.g., "post_json_request", "receive_webhook")
|
||||
|
||||
### Return Format
|
||||
```json
|
||||
{
|
||||
"task": "post_json_request",
|
||||
"nodeType": "nodes-base.httpRequest",
|
||||
"displayName": "HTTP Request",
|
||||
"configuration": {
|
||||
"method": "POST",
|
||||
"url": "={{ $json.api_endpoint }}",
|
||||
"responseFormat": "json",
|
||||
"options": {
|
||||
"bodyContentType": "json"
|
||||
},
|
||||
"bodyParametersJson": "={{ JSON.stringify($json) }}"
|
||||
},
|
||||
"userMustProvide": [
|
||||
"url - The API endpoint URL",
|
||||
"bodyParametersJson - The JSON data to send"
|
||||
],
|
||||
"tips": [
|
||||
"Use expressions to make values dynamic",
|
||||
"Enable 'Split Into Items' for batch processing"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Common Use Cases
|
||||
1. **Quick task setup**: Configure nodes for specific tasks instantly
|
||||
2. **Learning patterns**: See how to configure nodes properly
|
||||
3. **Common workflows**: Standard patterns like webhooks, API calls, database queries
|
||||
|
||||
### Examples
|
||||
```json
|
||||
// Get configuration for JSON POST request
|
||||
{
|
||||
"task": "post_json_request"
|
||||
}
|
||||
|
||||
// Get webhook receiver configuration
|
||||
{
|
||||
"task": "receive_webhook"
|
||||
}
|
||||
|
||||
// Get AI chat configuration
|
||||
{
|
||||
"task": "chat_with_ai"
|
||||
}
|
||||
```
|
||||
|
||||
### Performance Notes
|
||||
- Instant response (pre-configured templates)
|
||||
- No database lookups required
|
||||
- Includes working examples
|
||||
|
||||
### Best Practices
|
||||
- Use list_tasks first to see available options
|
||||
- Check userMustProvide section
|
||||
- Follow tips for best results
|
||||
- Common tasks: API calls, webhooks, database queries, AI chat
|
||||
|
||||
### Common Pitfalls
|
||||
- Not all tasks available (use list_tasks)
|
||||
- Configuration needs customization
|
||||
- Some fields still need user input
|
||||
|
||||
### Related Tools
|
||||
- `list_tasks` - See all available tasks
|
||||
- `get_node_essentials` - Alternative approach
|
||||
- `search_templates` - Find complete workflow templates
|
||||
|
||||
---
|
||||
|
||||
## n8n_create_workflow
|
||||
|
||||
**Brief Description**: Create a new workflow in n8n with nodes and connections.
|
||||
|
||||
### Parameters
|
||||
- `name` (string, required): Workflow name
|
||||
- `nodes` (array, required): Array of node definitions
|
||||
- `connections` (object, required): Node connections mapping
|
||||
- `settings` (object, optional): Workflow settings
|
||||
|
||||
### Return Format
|
||||
```json
|
||||
{
|
||||
"id": "workflow-uuid",
|
||||
"name": "My Workflow",
|
||||
"active": false,
|
||||
"createdAt": "2024-01-15T10:30:00Z",
|
||||
"updatedAt": "2024-01-15T10:30:00Z",
|
||||
"nodes": [...],
|
||||
"connections": {...}
|
||||
}
|
||||
```
|
||||
|
||||
### Common Use Cases
|
||||
1. **Automated workflow creation**: Build workflows programmatically
|
||||
2. **Template deployment**: Deploy pre-built workflow patterns
|
||||
3. **Multi-workflow systems**: Create interconnected workflows
|
||||
|
||||
### Examples
|
||||
```json
|
||||
// Create simple webhook → HTTP request workflow
|
||||
{
|
||||
"name": "Webhook to API",
|
||||
"nodes": [
|
||||
{
|
||||
"id": "webhook-1",
|
||||
"name": "Webhook",
|
||||
"type": "n8n-nodes-base.webhook",
|
||||
"typeVersion": 2,
|
||||
"position": [250, 300],
|
||||
"parameters": {
|
||||
"path": "/my-webhook",
|
||||
"httpMethod": "POST"
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "http-1",
|
||||
"name": "HTTP Request",
|
||||
"type": "n8n-nodes-base.httpRequest",
|
||||
"typeVersion": 4.2,
|
||||
"position": [450, 300],
|
||||
"parameters": {
|
||||
"method": "POST",
|
||||
"url": "https://api.example.com/process",
|
||||
"responseFormat": "json"
|
||||
}
|
||||
}
|
||||
],
|
||||
"connections": {
|
||||
"Webhook": {
|
||||
"main": [[{"node": "HTTP Request", "type": "main", "index": 0}]]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Performance Notes
|
||||
- API call to n8n instance required
|
||||
- Workflow created in inactive state
|
||||
- Must be manually activated in UI
|
||||
|
||||
### Best Practices
|
||||
- Always include typeVersion for nodes
|
||||
- Use node names (not IDs) in connections
|
||||
- Position nodes logically ([x, y] coordinates)
|
||||
- Test with validate_workflow first
|
||||
- Start simple, add complexity gradually
|
||||
|
||||
### Common Pitfalls
|
||||
- Missing typeVersion causes errors
|
||||
- Using node IDs instead of names in connections
|
||||
- Forgetting required node properties
|
||||
- Creating cycles in connections
|
||||
- Workflow can't be activated via API
|
||||
|
||||
### Related Tools
|
||||
- `validate_workflow` - Validate before creating
|
||||
- `n8n_update_partial_workflow` - Modify existing workflows
|
||||
- `n8n_trigger_webhook_workflow` - Execute workflows
|
||||
|
||||
---
|
||||
|
||||
## n8n_update_partial_workflow
|
||||
|
||||
**Brief Description**: Update workflows using diff operations for precise, incremental changes without sending the entire workflow.
|
||||
|
||||
### Parameters
|
||||
- `id` (string, required): Workflow ID to update
|
||||
- `operations` (array, required): Array of diff operations (max 5)
|
||||
- `validateOnly` (boolean, optional): Test without applying changes
|
||||
|
||||
### Return Format
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"workflow": {
|
||||
"id": "workflow-uuid",
|
||||
"name": "Updated Workflow",
|
||||
"nodes": [...],
|
||||
"connections": {...}
|
||||
},
|
||||
"appliedOperations": 3
|
||||
}
|
||||
```
|
||||
|
||||
### Common Use Cases
|
||||
1. **Add nodes to existing workflows**: Insert new functionality
|
||||
2. **Update node configurations**: Change parameters without full replacement
|
||||
3. **Manage connections**: Add/remove node connections
|
||||
4. **Quick edits**: Rename, enable/disable nodes, update settings
|
||||
|
||||
### Examples
|
||||
```json
|
||||
// Add a new node and connect it
|
||||
{
|
||||
"id": "workflow-123",
|
||||
"operations": [
|
||||
{
|
||||
"type": "addNode",
|
||||
"node": {
|
||||
"id": "set-1",
|
||||
"name": "Set Data",
|
||||
"type": "n8n-nodes-base.set",
|
||||
"typeVersion": 3,
|
||||
"position": [600, 300],
|
||||
"parameters": {
|
||||
"values": {
|
||||
"string": [{
|
||||
"name": "status",
|
||||
"value": "processed"
|
||||
}]
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
"type": "addConnection",
|
||||
"source": "HTTP Request",
|
||||
"target": "Set Data"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
// Update multiple properties
|
||||
{
|
||||
"id": "workflow-123",
|
||||
"operations": [
|
||||
{
|
||||
"type": "updateName",
|
||||
"name": "Production Workflow v2"
|
||||
},
|
||||
{
|
||||
"type": "updateNode",
|
||||
"nodeName": "Webhook",
|
||||
"changes": {
|
||||
"parameters.path": "/v2/webhook"
|
||||
}
|
||||
},
|
||||
{
|
||||
"type": "addTag",
|
||||
"tag": "production"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Performance Notes
|
||||
- 80-90% token savings vs full updates
|
||||
- Maximum 5 operations per request
|
||||
- Two-pass processing handles dependencies
|
||||
- Transactional: all or nothing
|
||||
|
||||
### Best Practices
|
||||
- Use validateOnly: true to test first
|
||||
- Keep operations under 5 for reliability
|
||||
- Operations can be in any order (v2.7.0+)
|
||||
- Use node names, not IDs in operations
|
||||
- For updateNode, use dot notation for nested paths
|
||||
|
||||
### Common Pitfalls
|
||||
- Exceeding 5 operations limit
|
||||
- Using node IDs instead of names
|
||||
- Forgetting required node properties in addNode
|
||||
- Not testing with validateOnly first
|
||||
|
||||
### Related Tools
|
||||
- `n8n_update_full_workflow` - Complete workflow replacement
|
||||
- `n8n_get_workflow` - Fetch current workflow state
|
||||
- `validate_workflow` - Validate changes before applying
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### Workflow Building Process
|
||||
1. **Discovery**: `search_nodes` → `list_nodes`
|
||||
2. **Configuration**: `get_node_essentials` → `get_node_for_task`
|
||||
3. **Validation**: `validate_node_minimal` → `validate_node_operation`
|
||||
4. **Creation**: `validate_workflow` → `n8n_create_workflow`
|
||||
5. **Updates**: `n8n_update_partial_workflow`
|
||||
|
||||
### Performance Tips
|
||||
- Use `get_node_essentials` instead of `get_node_info` (95% smaller)
|
||||
- Set high limits on `list_nodes` (200+)
|
||||
- Use single words in `search_nodes`
|
||||
- Validate incrementally while building
|
||||
|
||||
### Common Node Types
|
||||
- **Triggers**: webhook, schedule, emailReadImap, slackTrigger
|
||||
- **Core**: httpRequest, code, set, if, merge, splitInBatches
|
||||
- **Integrations**: slack, gmail, googleSheets, postgres, mongodb
|
||||
- **AI**: agent, openAi, chainLlm, documentLoader
|
||||
|
||||
### Error Prevention
|
||||
- Always include node type prefixes: "nodes-base.slack"
|
||||
- Use node names (not IDs) in connections
|
||||
- Include typeVersion in all nodes
|
||||
- Test with validateOnly before applying changes
|
||||
- Check userMustProvide sections in templates
|
||||
135
docs/tools-documentation-usage.md
Normal file
135
docs/tools-documentation-usage.md
Normal file
@@ -0,0 +1,135 @@
|
||||
# MCP Tools Documentation Usage Guide
|
||||
|
||||
The `tools_documentation` tool provides comprehensive documentation for all MCP tools, making it easy for LLMs to understand how to use the tools effectively.
|
||||
|
||||
## Basic Usage
|
||||
|
||||
### 1. Get Documentation for Specific Tools
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "tools_documentation",
|
||||
"arguments": {
|
||||
"tools": ["search_nodes", "get_node_essentials"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Returns detailed documentation including parameters, examples, and best practices for the specified tools.
|
||||
|
||||
### 2. Search Tools by Keyword
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "tools_documentation",
|
||||
"arguments": {
|
||||
"search": "validation"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Finds all tools related to validation, including their descriptions and use cases.
|
||||
|
||||
### 3. Browse Tools by Category
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "tools_documentation",
|
||||
"arguments": {
|
||||
"category": "workflow_management"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Available categories:
|
||||
- **discovery**: Tools for finding and exploring nodes
|
||||
- **configuration**: Tools for configuring nodes
|
||||
- **validation**: Tools for validating configurations
|
||||
- **workflow_management**: Tools for creating and updating workflows
|
||||
- **execution**: Tools for running workflows
|
||||
- **templates**: Tools for working with workflow templates
|
||||
|
||||
### 4. Get All Categories
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "tools_documentation",
|
||||
"arguments": {}
|
||||
}
|
||||
```
|
||||
|
||||
Returns a list of all categories and the tools in each category.
|
||||
|
||||
### 5. Include Quick Reference Guide
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "tools_documentation",
|
||||
"arguments": {
|
||||
"tools": ["n8n_create_workflow"],
|
||||
"includeQuickReference": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Includes a quick reference guide with workflow building process, performance tips, and common patterns.
|
||||
|
||||
## Response Format
|
||||
|
||||
The tool returns structured documentation with:
|
||||
|
||||
- **Parameters**: Complete parameter descriptions with types, requirements, and defaults
|
||||
- **Return Format**: Example of what the tool returns
|
||||
- **Common Use Cases**: Real-world scenarios where the tool is useful
|
||||
- **Examples**: Working examples with input and expected output
|
||||
- **Performance Notes**: Speed and efficiency considerations
|
||||
- **Best Practices**: Recommended usage patterns
|
||||
- **Common Pitfalls**: Mistakes to avoid
|
||||
- **Related Tools**: Other tools that work well together
|
||||
|
||||
## Example: Learning About search_nodes
|
||||
|
||||
Request:
|
||||
```json
|
||||
{
|
||||
"name": "tools_documentation",
|
||||
"arguments": {
|
||||
"tools": ["search_nodes"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Response includes:
|
||||
- How to search effectively (single words work best)
|
||||
- Performance characteristics (fast, cached)
|
||||
- Common searches (http, webhook, email, database, slack)
|
||||
- Pitfalls to avoid (multi-word searches use OR logic)
|
||||
- Related tools for next steps
|
||||
|
||||
## Tips for LLMs
|
||||
|
||||
1. **Start with categories**: Browse available tools by category to understand what's possible
|
||||
2. **Search by task**: Use search to find tools for specific tasks like "validation" or "workflow"
|
||||
3. **Learn tool combinations**: Check "Related Tools" to understand workflow patterns
|
||||
4. **Check examples**: Every tool has working examples to copy and modify
|
||||
5. **Avoid pitfalls**: Pay attention to "Common Pitfalls" to prevent errors
|
||||
|
||||
## Integration with Workflow Building
|
||||
|
||||
The documentation helps build workflows efficiently:
|
||||
|
||||
1. **Discovery Phase**: Use `search_nodes` and `list_nodes` documentation
|
||||
2. **Configuration Phase**: Learn from `get_node_essentials` examples
|
||||
3. **Validation Phase**: Understand validation tool options and profiles
|
||||
4. **Creation Phase**: Follow `n8n_create_workflow` best practices
|
||||
5. **Update Phase**: Master `n8n_update_partial_workflow` operations
|
||||
|
||||
## Performance Optimization
|
||||
|
||||
The documentation emphasizes performance:
|
||||
- Which tools are fast (essentials) vs slow (full info)
|
||||
- Optimal parameters (e.g., limit: 200+ for list_nodes)
|
||||
- Caching behavior
|
||||
- Token savings with partial updates
|
||||
|
||||
This documentation system ensures LLMs can use the MCP tools effectively without trial and error.
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "n8n-mcp",
|
||||
"version": "2.7.2",
|
||||
"version": "2.7.4",
|
||||
"description": "Integration between n8n workflow automation and Model Context Protocol (MCP)",
|
||||
"main": "dist/index.js",
|
||||
"scripts": {
|
||||
@@ -35,6 +35,7 @@
|
||||
"test:typeversion-validation": "node dist/scripts/test-typeversion-validation.js",
|
||||
"test:workflow-diff": "node dist/scripts/test-workflow-diff.js",
|
||||
"test:transactional-diff": "node dist/scripts/test-transactional-diff.js",
|
||||
"test:tools-documentation": "node dist/scripts/test-tools-documentation.js",
|
||||
"test:mcp:update-partial": "node dist/scripts/test-mcp-n8n-update-partial.js",
|
||||
"test:update-partial:debug": "node dist/scripts/test-update-partial-debug.js",
|
||||
"db:rebuild": "node dist/scripts/rebuild-database.js",
|
||||
|
||||
57
scripts/test-tools-documentation.ts
Normal file
57
scripts/test-tools-documentation.ts
Normal file
@@ -0,0 +1,57 @@
|
||||
import { N8NDocumentationMCPServer } from '../src/mcp/server';
|
||||
import path from 'path';
|
||||
|
||||
async function testToolsDocumentation() {
|
||||
const dbPath = path.join(__dirname, '..', 'nodes.db');
|
||||
const server = new N8NDocumentationMCPServer(dbPath);
|
||||
|
||||
console.log('=== Testing tools_documentation tool ===\n');
|
||||
|
||||
// Test 1: No parameters (quick reference)
|
||||
console.log('1. Testing without parameters (quick reference):');
|
||||
console.log('----------------------------------------');
|
||||
const quickRef = await server.executeTool('tools_documentation', {});
|
||||
console.log(quickRef);
|
||||
console.log('\n');
|
||||
|
||||
// Test 2: Overview with essentials depth
|
||||
console.log('2. Testing overview with essentials:');
|
||||
console.log('----------------------------------------');
|
||||
const overviewEssentials = await server.executeTool('tools_documentation', { topic: 'overview' });
|
||||
console.log(overviewEssentials);
|
||||
console.log('\n');
|
||||
|
||||
// Test 3: Overview with full depth
|
||||
console.log('3. Testing overview with full depth:');
|
||||
console.log('----------------------------------------');
|
||||
const overviewFull = await server.executeTool('tools_documentation', { topic: 'overview', depth: 'full' });
|
||||
console.log(overviewFull.substring(0, 500) + '...\n');
|
||||
|
||||
// Test 4: Specific tool with essentials
|
||||
console.log('4. Testing search_nodes with essentials:');
|
||||
console.log('----------------------------------------');
|
||||
const searchNodesEssentials = await server.executeTool('tools_documentation', { topic: 'search_nodes' });
|
||||
console.log(searchNodesEssentials);
|
||||
console.log('\n');
|
||||
|
||||
// Test 5: Specific tool with full documentation
|
||||
console.log('5. Testing search_nodes with full depth:');
|
||||
console.log('----------------------------------------');
|
||||
const searchNodesFull = await server.executeTool('tools_documentation', { topic: 'search_nodes', depth: 'full' });
|
||||
console.log(searchNodesFull.substring(0, 800) + '...\n');
|
||||
|
||||
// Test 6: Non-existent tool
|
||||
console.log('6. Testing non-existent tool:');
|
||||
console.log('----------------------------------------');
|
||||
const nonExistent = await server.executeTool('tools_documentation', { topic: 'fake_tool' });
|
||||
console.log(nonExistent);
|
||||
console.log('\n');
|
||||
|
||||
// Test 7: Another tool example
|
||||
console.log('7. Testing n8n_update_partial_workflow with essentials:');
|
||||
console.log('----------------------------------------');
|
||||
const updatePartial = await server.executeTool('tools_documentation', { topic: 'n8n_update_partial_workflow' });
|
||||
console.log(updatePartial);
|
||||
}
|
||||
|
||||
testToolsDocumentation().catch(console.error);
|
||||
@@ -24,6 +24,7 @@ import { WorkflowValidator } from '../services/workflow-validator';
|
||||
import { isN8nApiConfigured } from '../config/n8n-api';
|
||||
import * as n8nHandlers from './handlers-n8n-manager';
|
||||
import { handleUpdatePartialWorkflow } from './handlers-workflow-diff';
|
||||
import { getToolDocumentation, getToolsOverview } from './tools-documentation';
|
||||
import { PROJECT_VERSION } from '../utils/version';
|
||||
|
||||
interface NodeRow {
|
||||
@@ -191,8 +192,8 @@ export class N8NDocumentationMCPServer {
|
||||
|
||||
async executeTool(name: string, args: any): Promise<any> {
|
||||
switch (name) {
|
||||
case 'start_here_workflow_guide':
|
||||
return this.getWorkflowGuide(args.topic);
|
||||
case 'tools_documentation':
|
||||
return this.getToolsDocumentation(args.topic, args.depth);
|
||||
case 'list_nodes':
|
||||
return this.listNodes(args);
|
||||
case 'get_node_info':
|
||||
@@ -1180,385 +1181,14 @@ Full documentation is being prepared. For now, use get_node_essentials for confi
|
||||
};
|
||||
}
|
||||
|
||||
private async getWorkflowGuide(topic?: string): Promise<any> {
|
||||
const guides: Record<string, any> = {
|
||||
overview: {
|
||||
title: "n8n MCP Tools Quick Start Guide",
|
||||
sections: {
|
||||
recommended_workflow: {
|
||||
title: "Recommended Workflow",
|
||||
steps: [
|
||||
"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_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)"
|
||||
},
|
||||
essential_tools: {
|
||||
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_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",
|
||||
management: "n8n_create_workflow, n8n_list_workflows - Manage workflows (if API configured)"
|
||||
},
|
||||
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"
|
||||
},
|
||||
complete_workflow_lifecycle: {
|
||||
title: "Complete Workflow Lifecycle (NEW!)",
|
||||
overview: "With n8n management tools, you can now manage the entire workflow lifecycle:",
|
||||
phases: {
|
||||
"1. Discover": {
|
||||
tools: ["search_nodes", "list_nodes", "get_node_documentation"],
|
||||
purpose: "Find the right nodes for your automation"
|
||||
},
|
||||
"2. Build": {
|
||||
tools: ["get_node_essentials", "get_node_for_task", "search_node_properties"],
|
||||
purpose: "Configure nodes with the right settings"
|
||||
},
|
||||
"3. Validate": {
|
||||
tools: ["validate_node_minimal", "validate_node_operation", "validate_workflow", "n8n_validate_workflow"],
|
||||
purpose: "Ensure your workflow is correct before deployment",
|
||||
new: "n8n_validate_workflow - Validate workflows already in n8n by ID"
|
||||
},
|
||||
"4. Deploy": {
|
||||
tools: ["n8n_create_workflow", "n8n_update_workflow", "n8n_list_workflows"],
|
||||
purpose: "Create or update workflows in your n8n instance",
|
||||
requirement: "Requires N8N_API_URL and N8N_API_KEY configuration"
|
||||
},
|
||||
"5. Execute": {
|
||||
tools: ["n8n_trigger_webhook_workflow", "n8n_list_executions", "n8n_get_execution"],
|
||||
purpose: "Run workflows and monitor their execution",
|
||||
note: "Workflows must be activated manually in n8n UI"
|
||||
}
|
||||
},
|
||||
example_flow: [
|
||||
"1. search_nodes({query: 'slack'}) - Find Slack node",
|
||||
"2. get_node_essentials('nodes-base.slack') - Get configuration",
|
||||
"3. validate_node_operation() - Validate settings",
|
||||
"4. n8n_create_workflow() - Deploy to n8n",
|
||||
"5. n8n_validate_workflow({id: 'workflow-id'}) - Validate deployed workflow",
|
||||
"6. n8n_trigger_webhook_workflow() - Execute via webhook"
|
||||
]
|
||||
}
|
||||
}
|
||||
},
|
||||
workflow: {
|
||||
title: "Efficient Workflow Patterns",
|
||||
patterns: [
|
||||
{
|
||||
name: "Building from scratch",
|
||||
steps: [
|
||||
"search_nodes or list_nodes to find nodes",
|
||||
"get_node_essentials for configuration",
|
||||
"validate_node_minimal for quick required field check",
|
||||
"validate_node_operation for full validation"
|
||||
]
|
||||
},
|
||||
{
|
||||
name: "Common tasks",
|
||||
steps: [
|
||||
"list_tasks() to see available templates",
|
||||
"get_node_for_task() for instant configuration",
|
||||
"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"
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
search_tips: {
|
||||
title: "Search Best Practices",
|
||||
tips: [
|
||||
"search_nodes returns ANY word match (OR logic)",
|
||||
"'send slack message' finds nodes with 'send' OR 'slack' OR 'message'",
|
||||
"Single words are more precise: 'slack' vs 'slack message'",
|
||||
"Use list_nodes({category:'trigger'}) if search fails",
|
||||
"Node types need prefix: 'nodes-base.slack' not just 'slack'"
|
||||
]
|
||||
},
|
||||
common_nodes: {
|
||||
title: "Most Used Nodes",
|
||||
categories: {
|
||||
triggers: ["webhook", "schedule", "emailReadImap", "slackTrigger"],
|
||||
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: {
|
||||
title: "Known Issues & Workarounds",
|
||||
issues: [
|
||||
"Package names: Use 'n8n-nodes-base' NOT '@n8n/n8n-nodes-base'",
|
||||
"Duplicate properties: Check showWhen/hideWhen conditions",
|
||||
"Large responses: Use get_node_essentials instead of get_node_info",
|
||||
"Property search: Some nodes have 200+ properties, use search_node_properties",
|
||||
"Node not found: Try without prefix or lowercase"
|
||||
]
|
||||
},
|
||||
performance: {
|
||||
title: "Performance Guide",
|
||||
tools: {
|
||||
fast: [
|
||||
"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",
|
||||
"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",
|
||||
"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"
|
||||
]
|
||||
},
|
||||
n8n_management: {
|
||||
title: "n8n Workflow Management Tools (NEW!)",
|
||||
overview: "Manage n8n workflows directly through MCP. Create, update, execute, and monitor workflows programmatically.",
|
||||
requirements: {
|
||||
configuration: "Set N8N_API_URL and N8N_API_KEY environment variables",
|
||||
access: "n8n instance with API access enabled",
|
||||
version: "n8n v1.0.0 or higher"
|
||||
},
|
||||
available_tools: {
|
||||
workflow_management: [
|
||||
"n8n_create_workflow - Create new workflows with nodes and connections",
|
||||
"n8n_get_workflow - Get complete workflow by ID",
|
||||
"n8n_get_workflow_details - Get workflow with execution statistics",
|
||||
"n8n_update_workflow - Update existing workflows (requires full node array)",
|
||||
"n8n_delete_workflow - Delete workflows permanently",
|
||||
"n8n_list_workflows - List workflows with filtering"
|
||||
],
|
||||
execution_management: [
|
||||
"n8n_trigger_webhook_workflow - Execute workflows via webhook",
|
||||
"n8n_get_execution - Get execution details",
|
||||
"n8n_list_executions - List executions with status filtering",
|
||||
"n8n_delete_execution - Delete execution records"
|
||||
],
|
||||
system_tools: [
|
||||
"n8n_health_check - Check API connectivity",
|
||||
"n8n_list_available_tools - List all management tools"
|
||||
]
|
||||
},
|
||||
limitations: {
|
||||
"Workflow Activation": "Cannot activate/deactivate workflows via API - use n8n UI",
|
||||
"Direct Execution": "No direct execution - must use webhook triggers",
|
||||
"Update Requirements": "Updates require complete nodes array, not just changes",
|
||||
"Tags": "Read-only during creation/update"
|
||||
},
|
||||
workflow_examples: {
|
||||
"⚠️ CRITICAL: Connection Rules": {
|
||||
warning: "ALWAYS use node NAMES in connections, NEVER use node IDs!",
|
||||
explanation: "Using IDs will make nodes appear disconnected in n8n UI",
|
||||
wrong: {
|
||||
connections: {"1": {main: [[{node: "2", type: "main", index: 0}]]}} // ❌ WRONG - uses IDs
|
||||
},
|
||||
correct: {
|
||||
connections: {"Start": {main: [[{node: "Set", type: "main", index: 0}]]}} // ✅ CORRECT - uses names
|
||||
}
|
||||
},
|
||||
"Create Simple Workflow": {
|
||||
tools: ["n8n_create_workflow"],
|
||||
example: {
|
||||
name: "My Test Workflow",
|
||||
nodes: [
|
||||
{id: "1", name: "Start", type: "n8n-nodes-base.start", position: [250, 300]},
|
||||
{id: "2", name: "Set", type: "n8n-nodes-base.set", position: [450, 300]}
|
||||
],
|
||||
connections: {"Start": {main: [[{node: "Set", type: "main", index: 0}]]}} // ✅ Uses node names!
|
||||
}
|
||||
},
|
||||
"Execute via Webhook": {
|
||||
tools: ["n8n_trigger_webhook_workflow"],
|
||||
steps: [
|
||||
"1. Workflow must have webhook trigger node",
|
||||
"2. Workflow must be manually activated in UI",
|
||||
"3. Use webhook URL from workflow"
|
||||
]
|
||||
}
|
||||
},
|
||||
best_practices: [
|
||||
"⚠️ ALWAYS use node NAMES in connections, NEVER node IDs",
|
||||
"Always use n8n_health_check first to verify connectivity",
|
||||
"Fetch full workflow before updating (n8n_get_workflow)",
|
||||
"Validate workflows before creating (validate_workflow)",
|
||||
"Monitor executions after triggering webhooks",
|
||||
"Use descriptive workflow names for easy management"
|
||||
],
|
||||
integration_pattern: {
|
||||
title: "Complete Automation Pipeline",
|
||||
steps: [
|
||||
"1. Design: Use documentation tools to understand nodes",
|
||||
"2. Build: Configure nodes with get_node_essentials",
|
||||
"3. Validate: Use validate_workflow before deployment",
|
||||
"4. Deploy: Create with n8n_create_workflow",
|
||||
"5. Activate: Manually activate in n8n UI",
|
||||
"6. Execute: Trigger with n8n_trigger_webhook_workflow",
|
||||
"7. Monitor: Check status with n8n_list_executions"
|
||||
]
|
||||
}
|
||||
}
|
||||
};
|
||||
// Method removed - replaced by getToolsDocumentation
|
||||
|
||||
if (topic && guides[topic]) {
|
||||
return guides[topic];
|
||||
private async getToolsDocumentation(topic?: string, depth: 'essentials' | 'full' = 'essentials'): Promise<string> {
|
||||
if (!topic || topic === 'overview') {
|
||||
return getToolsOverview(depth);
|
||||
}
|
||||
|
||||
// Return complete overview
|
||||
return {
|
||||
title: "n8n MCP Tools Complete Guide",
|
||||
quickStart: guides.overview,
|
||||
sections: {
|
||||
workflow: guides.workflow,
|
||||
searchTips: guides.search_tips,
|
||||
commonNodes: guides.common_nodes,
|
||||
knownIssues: guides.known_issues,
|
||||
performance: guides.performance,
|
||||
aiTools: guides.ai_tools,
|
||||
n8nManagement: guides.n8n_management
|
||||
},
|
||||
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')",
|
||||
"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)"
|
||||
],
|
||||
"Complete Workflow Lifecycle": [
|
||||
"// 1. Discover & Design",
|
||||
"search_nodes({query: 'webhook'})",
|
||||
"get_node_essentials('nodes-base.webhook')",
|
||||
"// 2. Build & Validate",
|
||||
"const workflow = { nodes: [...], connections: {...} }",
|
||||
"validate_workflow(workflow)",
|
||||
"// 3. Deploy (requires API config)",
|
||||
"n8n_create_workflow(workflow)",
|
||||
"// 4. Execute",
|
||||
"n8n_trigger_webhook_workflow({webhookUrl: '...'})",
|
||||
"// 5. Monitor",
|
||||
"n8n_list_executions({workflowId: '...'})"
|
||||
]
|
||||
},
|
||||
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"
|
||||
}
|
||||
}
|
||||
};
|
||||
|
||||
return getToolDocumentation(topic, depth);
|
||||
}
|
||||
|
||||
// Add connect method to accept any transport
|
||||
|
||||
644
src/mcp/tools-documentation.ts
Normal file
644
src/mcp/tools-documentation.ts
Normal file
@@ -0,0 +1,644 @@
|
||||
interface ToolDocumentation {
|
||||
name: string;
|
||||
category: string;
|
||||
essentials: {
|
||||
description: string;
|
||||
keyParameters: string[];
|
||||
example: string;
|
||||
performance: string;
|
||||
tips: string[];
|
||||
};
|
||||
full: {
|
||||
description: string;
|
||||
parameters: Record<string, { type: string; description: string; required?: boolean }>;
|
||||
returns: string;
|
||||
examples: string[];
|
||||
useCases: string[];
|
||||
performance: string;
|
||||
bestPractices: string[];
|
||||
pitfalls: string[];
|
||||
relatedTools: string[];
|
||||
};
|
||||
}
|
||||
|
||||
export const toolsDocumentation: Record<string, ToolDocumentation> = {
|
||||
search_nodes: {
|
||||
name: 'search_nodes',
|
||||
category: 'discovery',
|
||||
essentials: {
|
||||
description: 'Search for n8n nodes by keyword across names, descriptions, and categories',
|
||||
keyParameters: ['query', 'limit'],
|
||||
example: 'search_nodes({query: "slack", limit: 10})',
|
||||
performance: 'Fast - uses indexed full-text search',
|
||||
tips: [
|
||||
'Uses OR logic - "send slack" finds nodes with ANY of these words',
|
||||
'Single words are more precise than phrases'
|
||||
]
|
||||
},
|
||||
full: {
|
||||
description: 'Performs full-text search across all n8n nodes using indexed search. Returns nodes matching ANY word in the query (OR logic). Searches through node names, display names, descriptions, and categories.',
|
||||
parameters: {
|
||||
query: { type: 'string', description: 'Search terms (words are ORed together)', required: true },
|
||||
limit: { type: 'number', description: 'Maximum results to return (default: 20)', required: false }
|
||||
},
|
||||
returns: 'Array of nodes with nodeType, displayName, description, category, and relevance score',
|
||||
examples: [
|
||||
'search_nodes({query: "slack"}) - Find all Slack-related nodes',
|
||||
'search_nodes({query: "webhook trigger", limit: 5}) - Find nodes with "webhook" OR "trigger"',
|
||||
'search_nodes({query: "ai"}) - Find AI-related nodes'
|
||||
],
|
||||
useCases: [
|
||||
'Finding nodes for specific integrations',
|
||||
'Discovering available functionality',
|
||||
'Exploring nodes by keyword when exact name unknown'
|
||||
],
|
||||
performance: 'Very fast - uses SQLite FTS5 full-text index. Typically <50ms even for complex queries.',
|
||||
bestPractices: [
|
||||
'Use single words for precise matches',
|
||||
'Try different variations if first search fails',
|
||||
'Use list_nodes for browsing by category',
|
||||
'Remember it\'s OR logic, not AND'
|
||||
],
|
||||
pitfalls: [
|
||||
'Multi-word queries may return too many results',
|
||||
'Doesn\'t search in node properties or operations',
|
||||
'Case-insensitive but doesn\'t handle typos'
|
||||
],
|
||||
relatedTools: ['list_nodes', 'get_node_essentials', 'get_node_info']
|
||||
}
|
||||
},
|
||||
|
||||
get_node_essentials: {
|
||||
name: 'get_node_essentials',
|
||||
category: 'configuration',
|
||||
essentials: {
|
||||
description: 'Get only the most important 10-20 properties for a node with examples',
|
||||
keyParameters: ['nodeType'],
|
||||
example: 'get_node_essentials("n8n-nodes-base.slack")',
|
||||
performance: 'Very fast - returns <5KB instead of 100KB+',
|
||||
tips: [
|
||||
'Use this instead of get_node_info for 95% of cases',
|
||||
'Includes working examples for common operations'
|
||||
]
|
||||
},
|
||||
full: {
|
||||
description: 'Returns a curated set of essential properties for a node, typically 10-20 most commonly used properties. Includes working examples and is 95% smaller than get_node_info. Designed for efficient node configuration.',
|
||||
parameters: {
|
||||
nodeType: { type: 'string', description: 'Full node type (e.g., "n8n-nodes-base.slack")', required: true }
|
||||
},
|
||||
returns: 'Object with node info, essential properties, examples, and common patterns',
|
||||
examples: [
|
||||
'get_node_essentials("n8n-nodes-base.httpRequest") - Get HTTP request essentials',
|
||||
'get_node_essentials("n8n-nodes-base.webhook") - Get webhook configuration',
|
||||
'get_node_essentials("n8n-nodes-base.slack") - Get Slack essentials'
|
||||
],
|
||||
useCases: [
|
||||
'Quickly configuring nodes without information overload',
|
||||
'Getting working examples for immediate use',
|
||||
'Understanding the most important node options',
|
||||
'Building workflows efficiently'
|
||||
],
|
||||
performance: 'Extremely fast - returns pre-filtered data. Response size <5KB vs 100KB+ for full node info.',
|
||||
bestPractices: [
|
||||
'Always try this before get_node_info',
|
||||
'Use included examples as starting points',
|
||||
'Check commonPatterns for typical configurations',
|
||||
'Combine with validate_node_minimal for quick validation'
|
||||
],
|
||||
pitfalls: [
|
||||
'May not include rarely-used properties',
|
||||
'Some advanced options might be missing',
|
||||
'Use search_node_properties if specific property not found'
|
||||
],
|
||||
relatedTools: ['get_node_info', 'search_node_properties', 'validate_node_minimal']
|
||||
}
|
||||
},
|
||||
|
||||
list_nodes: {
|
||||
name: 'list_nodes',
|
||||
category: 'discovery',
|
||||
essentials: {
|
||||
description: 'List all available n8n nodes with optional filtering',
|
||||
keyParameters: ['category', 'limit', 'onlyTriggers'],
|
||||
example: 'list_nodes({category: "communication", limit: 20})',
|
||||
performance: 'Fast - direct database query',
|
||||
tips: [
|
||||
'Great for browsing nodes by category',
|
||||
'Use onlyTriggers:true to find workflow starters'
|
||||
]
|
||||
},
|
||||
full: {
|
||||
description: 'Lists all available n8n nodes with comprehensive filtering options. Can filter by category, package, trigger status, and more. Returns complete node metadata.',
|
||||
parameters: {
|
||||
category: { type: 'string', description: 'Filter by category (e.g., "communication", "data")', required: false },
|
||||
limit: { type: 'number', description: 'Maximum results (default: 50)', required: false },
|
||||
offset: { type: 'number', description: 'Pagination offset', required: false },
|
||||
onlyTriggers: { type: 'boolean', description: 'Only show trigger nodes', required: false },
|
||||
onlyAITools: { type: 'boolean', description: 'Only show AI-capable nodes', required: false },
|
||||
package: { type: 'string', description: 'Filter by package name', required: false }
|
||||
},
|
||||
returns: 'Array of nodes with complete metadata including type, name, description, category',
|
||||
examples: [
|
||||
'list_nodes() - Get first 50 nodes',
|
||||
'list_nodes({category: "trigger"}) - All trigger nodes',
|
||||
'list_nodes({onlyAITools: true}) - Nodes marked as AI tools',
|
||||
'list_nodes({package: "n8n-nodes-base", limit: 100}) - Core nodes'
|
||||
],
|
||||
useCases: [
|
||||
'Browsing available nodes by category',
|
||||
'Finding all triggers or webhooks',
|
||||
'Discovering AI-capable nodes',
|
||||
'Getting overview of available integrations'
|
||||
],
|
||||
performance: 'Fast - uses indexed queries. Returns in <100ms even for large result sets.',
|
||||
bestPractices: [
|
||||
'Use categories for focused browsing',
|
||||
'Combine with search_nodes for keyword search',
|
||||
'Use pagination for large result sets',
|
||||
'Check onlyTriggers for workflow starting points'
|
||||
],
|
||||
pitfalls: [
|
||||
'No text search - use search_nodes for that',
|
||||
'Categories are predefined, not all nodes have them',
|
||||
'Large result sets without limit can be overwhelming'
|
||||
],
|
||||
relatedTools: ['search_nodes', 'list_ai_tools', 'get_node_essentials']
|
||||
}
|
||||
},
|
||||
|
||||
validate_node_minimal: {
|
||||
name: 'validate_node_minimal',
|
||||
category: 'validation',
|
||||
essentials: {
|
||||
description: 'Quick validation checking only required fields',
|
||||
keyParameters: ['nodeType', 'config'],
|
||||
example: 'validate_node_minimal("n8n-nodes-base.slack", {resource: "message", operation: "post"})',
|
||||
performance: 'Very fast - minimal checks only',
|
||||
tips: [
|
||||
'Use for quick validation during configuration',
|
||||
'Follow up with validate_node_operation for full validation'
|
||||
]
|
||||
},
|
||||
full: {
|
||||
description: 'Performs minimal validation checking only required fields. Fastest validation option, perfect for iterative configuration. Checks if all required fields are present without complex dependency validation.',
|
||||
parameters: {
|
||||
nodeType: { type: 'string', description: 'Full node type', required: true },
|
||||
config: { type: 'object', description: 'Node configuration to validate', required: true }
|
||||
},
|
||||
returns: 'Object with isValid boolean, missing required fields, and basic feedback',
|
||||
examples: [
|
||||
'validate_node_minimal("n8n-nodes-base.httpRequest", {url: "https://api.example.com"})',
|
||||
'validate_node_minimal("n8n-nodes-base.slack", {resource: "message", operation: "post", channel: "general"})'
|
||||
],
|
||||
useCases: [
|
||||
'Quick validation during iterative configuration',
|
||||
'Checking if minimum requirements are met',
|
||||
'Fast feedback loop while building',
|
||||
'Pre-validation before full check'
|
||||
],
|
||||
performance: 'Extremely fast - only checks required fields. Typically <10ms.',
|
||||
bestPractices: [
|
||||
'Use during configuration for quick feedback',
|
||||
'Follow with validate_node_operation for complete validation',
|
||||
'Great for iterative development',
|
||||
'Combine with get_node_essentials for requirements'
|
||||
],
|
||||
pitfalls: [
|
||||
'Doesn\'t check field dependencies',
|
||||
'Won\'t catch configuration conflicts',
|
||||
'Missing optional but recommended fields'
|
||||
],
|
||||
relatedTools: ['validate_node_operation', 'get_node_essentials', 'validate_workflow']
|
||||
}
|
||||
},
|
||||
|
||||
validate_node_operation: {
|
||||
name: 'validate_node_operation',
|
||||
category: 'validation',
|
||||
essentials: {
|
||||
description: 'Full validation with operation-aware checking and helpful suggestions',
|
||||
keyParameters: ['nodeType', 'config', 'profile'],
|
||||
example: 'validate_node_operation("n8n-nodes-base.slack", {resource: "message", operation: "post", channel: "general"})',
|
||||
performance: 'Moderate - comprehensive validation',
|
||||
tips: [
|
||||
'Provides specific error messages and fixes',
|
||||
'Use "strict" profile for production workflows'
|
||||
]
|
||||
},
|
||||
full: {
|
||||
description: 'Comprehensive validation that understands operation-specific requirements. Checks dependencies, validates field values, and provides helpful suggestions for fixing issues.',
|
||||
parameters: {
|
||||
nodeType: { type: 'string', description: 'Full node type', required: true },
|
||||
config: { type: 'object', description: 'Complete node configuration', required: true },
|
||||
profile: { type: 'string', description: 'Validation profile: "development" or "strict"', required: false }
|
||||
},
|
||||
returns: 'Detailed validation results with errors, warnings, suggestions, and fixes',
|
||||
examples: [
|
||||
'validate_node_operation("n8n-nodes-base.httpRequest", {method: "POST", url: "{{$json.url}}", bodyParametersUi: {...}})',
|
||||
'validate_node_operation("n8n-nodes-base.postgres", {operation: "executeQuery", query: "SELECT * FROM users"}, "strict")'
|
||||
],
|
||||
useCases: [
|
||||
'Final validation before deployment',
|
||||
'Understanding complex field dependencies',
|
||||
'Getting suggestions for configuration improvements',
|
||||
'Validating operation-specific requirements'
|
||||
],
|
||||
performance: 'Moderate speed - performs comprehensive checks. 50-200ms depending on complexity.',
|
||||
bestPractices: [
|
||||
'Use after validate_node_minimal passes',
|
||||
'Apply suggested fixes from response',
|
||||
'Use strict profile for production',
|
||||
'Check warnings even if validation passes'
|
||||
],
|
||||
pitfalls: [
|
||||
'Slower than minimal validation',
|
||||
'May be overkill for simple configurations',
|
||||
'Strict profile might be too restrictive for development'
|
||||
],
|
||||
relatedTools: ['validate_node_minimal', 'validate_workflow', 'get_property_dependencies']
|
||||
}
|
||||
},
|
||||
|
||||
get_node_for_task: {
|
||||
name: 'get_node_for_task',
|
||||
category: 'templates',
|
||||
essentials: {
|
||||
description: 'Get pre-configured node settings for common tasks',
|
||||
keyParameters: ['task'],
|
||||
example: 'get_node_for_task("send_slack_message")',
|
||||
performance: 'Instant - returns pre-built configurations',
|
||||
tips: [
|
||||
'Use list_tasks() to see all available tasks',
|
||||
'Look for userMustProvide fields to complete'
|
||||
]
|
||||
},
|
||||
full: {
|
||||
description: 'Returns pre-configured node settings for common automation tasks. Each template includes the correct node type, operation settings, and clear markers for what needs user input.',
|
||||
parameters: {
|
||||
task: { type: 'string', description: 'Task identifier (use list_tasks to see all)', required: true }
|
||||
},
|
||||
returns: 'Complete node configuration with parameters, position, and user guidance',
|
||||
examples: [
|
||||
'get_node_for_task("send_slack_message") - Slack message template',
|
||||
'get_node_for_task("receive_webhook") - Webhook trigger setup',
|
||||
'get_node_for_task("query_database") - Database query template'
|
||||
],
|
||||
useCases: [
|
||||
'Quickly setting up common automation patterns',
|
||||
'Learning correct node configurations',
|
||||
'Avoiding configuration mistakes',
|
||||
'Rapid workflow prototyping'
|
||||
],
|
||||
performance: 'Instant - returns static templates. No computation required.',
|
||||
bestPractices: [
|
||||
'Check userMustProvide fields for required inputs',
|
||||
'Use list_tasks() to discover available templates',
|
||||
'Validate with validate_node_minimal after filling in',
|
||||
'Use as starting point, then customize'
|
||||
],
|
||||
pitfalls: [
|
||||
'Templates are generic - customize for specific needs',
|
||||
'Not all tasks have templates',
|
||||
'Some fields marked userMustProvide are critical'
|
||||
],
|
||||
relatedTools: ['list_tasks', 'get_node_essentials', 'validate_node_minimal']
|
||||
}
|
||||
},
|
||||
|
||||
n8n_create_workflow: {
|
||||
name: 'n8n_create_workflow',
|
||||
category: 'workflow_management',
|
||||
essentials: {
|
||||
description: 'Create a new workflow in n8n via API',
|
||||
keyParameters: ['name', 'nodes', 'connections'],
|
||||
example: 'n8n_create_workflow({name: "My Workflow", nodes: [...], connections: {...}})',
|
||||
performance: 'API call - depends on n8n instance',
|
||||
tips: [
|
||||
'ALWAYS use node names in connections, never IDs',
|
||||
'Requires N8N_API_URL and N8N_API_KEY configuration'
|
||||
]
|
||||
},
|
||||
full: {
|
||||
description: 'Creates a new workflow in your n8n instance via API. Requires proper API configuration. Returns the created workflow with assigned ID.',
|
||||
parameters: {
|
||||
name: { type: 'string', description: 'Workflow name', required: true },
|
||||
nodes: { type: 'array', description: 'Array of node configurations', required: true },
|
||||
connections: { type: 'object', description: 'Node connections (use names!)', required: true },
|
||||
settings: { type: 'object', description: 'Workflow settings', required: false },
|
||||
tags: { type: 'array', description: 'Tag IDs (not names)', required: false }
|
||||
},
|
||||
returns: 'Created workflow object with id, name, nodes, connections, and metadata',
|
||||
examples: [
|
||||
`n8n_create_workflow({
|
||||
name: "Slack Notification",
|
||||
nodes: [
|
||||
{id: "1", name: "Webhook", type: "n8n-nodes-base.webhook", position: [250, 300]},
|
||||
{id: "2", name: "Slack", type: "n8n-nodes-base.slack", position: [450, 300], parameters: {...}}
|
||||
],
|
||||
connections: {
|
||||
"Webhook": {main: [[{node: "Slack", type: "main", index: 0}]]}
|
||||
}
|
||||
})`
|
||||
],
|
||||
useCases: [
|
||||
'Deploying workflows programmatically',
|
||||
'Automating workflow creation',
|
||||
'Migrating workflows between instances',
|
||||
'Creating workflows from templates'
|
||||
],
|
||||
performance: 'Depends on n8n instance and network. Typically 100-500ms.',
|
||||
bestPractices: [
|
||||
'CRITICAL: Use node NAMES in connections, not IDs',
|
||||
'Validate workflow before creating',
|
||||
'Use meaningful workflow names',
|
||||
'Check n8n_health_check before creating',
|
||||
'Handle API errors gracefully'
|
||||
],
|
||||
pitfalls: [
|
||||
'Using node IDs in connections breaks UI display',
|
||||
'Workflow not automatically activated',
|
||||
'Tags must exist (use tag IDs not names)',
|
||||
'API must be configured correctly'
|
||||
],
|
||||
relatedTools: ['validate_workflow', 'n8n_update_partial_workflow', 'n8n_list_workflows']
|
||||
}
|
||||
},
|
||||
|
||||
n8n_update_partial_workflow: {
|
||||
name: 'n8n_update_partial_workflow',
|
||||
category: 'workflow_management',
|
||||
essentials: {
|
||||
description: 'Update workflows using diff operations - only send changes, not entire workflow',
|
||||
keyParameters: ['id', 'operations'],
|
||||
example: 'n8n_update_partial_workflow({id: "123", operations: [{type: "updateNode", nodeId: "Slack", updates: {...}}]})',
|
||||
performance: '80-90% more efficient than full updates',
|
||||
tips: [
|
||||
'Maximum 5 operations per request',
|
||||
'Can reference nodes by name or ID'
|
||||
]
|
||||
},
|
||||
full: {
|
||||
description: 'Update existing workflows using diff operations. Much more efficient than full updates as it only sends the changes. Supports 13 different operation types.',
|
||||
parameters: {
|
||||
id: { type: 'string', description: 'Workflow ID to update', required: true },
|
||||
operations: { type: 'array', description: 'Array of diff operations (max 5)', required: true },
|
||||
validateOnly: { type: 'boolean', description: 'Only validate without applying', required: false }
|
||||
},
|
||||
returns: 'Updated workflow with applied changes and operation results',
|
||||
examples: [
|
||||
`// Update node parameters
|
||||
n8n_update_partial_workflow({
|
||||
id: "123",
|
||||
operations: [{
|
||||
type: "updateNode",
|
||||
nodeId: "Slack",
|
||||
updates: {parameters: {channel: "general"}}
|
||||
}]
|
||||
})`,
|
||||
`// Add connection between nodes
|
||||
n8n_update_partial_workflow({
|
||||
id: "123",
|
||||
operations: [{
|
||||
type: "addConnection",
|
||||
from: "HTTP Request",
|
||||
to: "Slack",
|
||||
fromOutput: "main",
|
||||
toInput: "main"
|
||||
}]
|
||||
})`
|
||||
],
|
||||
useCases: [
|
||||
'Updating node configurations',
|
||||
'Adding/removing connections',
|
||||
'Enabling/disabling nodes',
|
||||
'Moving nodes in canvas',
|
||||
'Updating workflow metadata'
|
||||
],
|
||||
performance: 'Very efficient - only sends changes. 80-90% less data than full updates.',
|
||||
bestPractices: [
|
||||
'Batch related operations together',
|
||||
'Use validateOnly:true to test first',
|
||||
'Reference nodes by name for clarity',
|
||||
'Keep under 5 operations per request',
|
||||
'Check operation results for success'
|
||||
],
|
||||
pitfalls: [
|
||||
'Maximum 5 operations per request',
|
||||
'Some operations have dependencies',
|
||||
'Node must exist for update operations',
|
||||
'Connection nodes must both exist'
|
||||
],
|
||||
relatedTools: ['n8n_get_workflow', 'n8n_update_full_workflow', 'validate_workflow']
|
||||
}
|
||||
}
|
||||
};
|
||||
|
||||
export function getToolDocumentation(toolName: string, depth: 'essentials' | 'full' = 'essentials'): string {
|
||||
const tool = toolsDocumentation[toolName];
|
||||
if (!tool) {
|
||||
return `Tool '${toolName}' not found. Use tools_documentation() to see available tools.`;
|
||||
}
|
||||
|
||||
if (depth === 'essentials') {
|
||||
const { essentials } = tool;
|
||||
return `# ${tool.name}
|
||||
|
||||
${essentials.description}
|
||||
|
||||
**Example**: ${essentials.example}
|
||||
|
||||
**Key parameters**: ${essentials.keyParameters.join(', ')}
|
||||
|
||||
**Performance**: ${essentials.performance}
|
||||
|
||||
**Tips**:
|
||||
${essentials.tips.map(tip => `- ${tip}`).join('\n')}
|
||||
|
||||
For full documentation, use: tools_documentation({topic: "${toolName}", depth: "full"})`;
|
||||
}
|
||||
|
||||
// Full documentation
|
||||
const { full } = tool;
|
||||
return `# ${tool.name}
|
||||
|
||||
${full.description}
|
||||
|
||||
## Parameters
|
||||
${Object.entries(full.parameters).map(([param, info]) =>
|
||||
`- **${param}** (${info.type}${info.required ? ', required' : ''}): ${info.description}`
|
||||
).join('\n')}
|
||||
|
||||
## Returns
|
||||
${full.returns}
|
||||
|
||||
## Examples
|
||||
${full.examples.map(ex => `\`\`\`javascript\n${ex}\n\`\`\``).join('\n\n')}
|
||||
|
||||
## Common Use Cases
|
||||
${full.useCases.map(uc => `- ${uc}`).join('\n')}
|
||||
|
||||
## Performance
|
||||
${full.performance}
|
||||
|
||||
## Best Practices
|
||||
${full.bestPractices.map(bp => `- ${bp}`).join('\n')}
|
||||
|
||||
## Common Pitfalls
|
||||
${full.pitfalls.map(p => `- ${p}`).join('\n')}
|
||||
|
||||
## Related Tools
|
||||
${full.relatedTools.map(t => `- ${t}`).join('\n')}`;
|
||||
}
|
||||
|
||||
export function getToolsOverview(depth: 'essentials' | 'full' = 'essentials'): string {
|
||||
if (depth === 'essentials') {
|
||||
return `# n8n MCP Tools Quick Reference
|
||||
|
||||
Welcome! Here's how to efficiently work with n8n nodes:
|
||||
|
||||
## Essential Workflow
|
||||
1. **Find**: search_nodes({query: "slack"})
|
||||
2. **Configure**: get_node_essentials("n8n-nodes-base.slack")
|
||||
3. **Validate**: validate_node_minimal() → validate_node_operation()
|
||||
4. **Deploy**: n8n_create_workflow() (if API configured)
|
||||
|
||||
## Key Tips
|
||||
- Always use get_node_essentials instead of get_node_info (95% smaller!)
|
||||
- Use node NAMES in connections, never IDs
|
||||
- Try get_node_for_task() for common patterns
|
||||
- Call validate_node_minimal() for quick checks
|
||||
|
||||
## Get Help
|
||||
- tools_documentation({topic: "search_nodes"}) - Get help for specific tool
|
||||
- tools_documentation({topic: "overview", depth: "full"}) - See complete guide
|
||||
- list_tasks() - See available task templates
|
||||
|
||||
Available tools: ${Object.keys(toolsDocumentation).join(', ')}`;
|
||||
}
|
||||
|
||||
// Full overview
|
||||
return `# n8n MCP Tools Complete Guide
|
||||
|
||||
## Overview
|
||||
The n8n MCP provides 39 tools to help you discover, configure, validate, and deploy n8n workflows. Tools are organized into categories for easy discovery.
|
||||
|
||||
## Tool Categories
|
||||
|
||||
### Discovery Tools
|
||||
- **search_nodes**: Find nodes by keyword (uses OR logic)
|
||||
- **list_nodes**: Browse nodes by category, package, or type
|
||||
- **list_ai_tools**: See all AI-capable nodes (263 available)
|
||||
|
||||
### Configuration Tools
|
||||
- **get_node_essentials**: Get key properties only (<5KB vs 100KB+)
|
||||
- **get_node_info**: Get complete node details (use sparingly)
|
||||
- **search_node_properties**: Find specific properties in large nodes
|
||||
- **get_property_dependencies**: Understand field relationships
|
||||
|
||||
### Validation Tools
|
||||
- **validate_node_minimal**: Quick required field check
|
||||
- **validate_node_operation**: Full operation-aware validation
|
||||
- **validate_workflow**: Complete workflow validation
|
||||
- **validate_workflow_connections**: Check node connections
|
||||
- **validate_workflow_expressions**: Validate n8n expressions
|
||||
|
||||
### Task & Template Tools
|
||||
- **list_tasks**: See available task templates
|
||||
- **get_node_for_task**: Get pre-configured nodes
|
||||
- **list_node_templates**: Find workflow templates
|
||||
- **search_templates**: Search template library
|
||||
|
||||
### Workflow Management (requires API config)
|
||||
- **n8n_create_workflow**: Create new workflows
|
||||
- **n8n_update_partial_workflow**: Efficient diff-based updates
|
||||
- **n8n_update_full_workflow**: Replace entire workflow
|
||||
- **n8n_list_workflows**: List workflows with filtering
|
||||
|
||||
## Recommended Patterns
|
||||
|
||||
### Building a Simple Workflow
|
||||
\`\`\`javascript
|
||||
// 1. Find what you need
|
||||
search_nodes({query: "webhook"})
|
||||
search_nodes({query: "slack"})
|
||||
|
||||
// 2. Get configurations
|
||||
get_node_essentials("n8n-nodes-base.webhook")
|
||||
get_node_essentials("n8n-nodes-base.slack")
|
||||
|
||||
// 3. Build and validate
|
||||
const workflow = {
|
||||
name: "My Webhook to Slack",
|
||||
nodes: [...],
|
||||
connections: {"Webhook": {main: [[{node: "Slack", type: "main", index: 0}]]}}
|
||||
};
|
||||
validate_workflow(workflow)
|
||||
|
||||
// 4. Deploy (if API configured)
|
||||
n8n_create_workflow(workflow)
|
||||
\`\`\`
|
||||
|
||||
### Using AI Tools
|
||||
Any node can be an AI tool! Connect it to an AI Agent's ai_tool port:
|
||||
\`\`\`javascript
|
||||
get_node_as_tool_info("n8n-nodes-base.slack")
|
||||
// Returns how to configure Slack as an AI tool
|
||||
\`\`\`
|
||||
|
||||
### Efficient Updates
|
||||
Use partial updates to save 80-90% bandwidth:
|
||||
\`\`\`javascript
|
||||
n8n_update_partial_workflow({
|
||||
id: "workflow-id",
|
||||
operations: [
|
||||
{type: "updateNode", nodeId: "Slack", updates: {parameters: {channel: "general"}}}
|
||||
]
|
||||
})
|
||||
\`\`\`
|
||||
|
||||
## Performance Guide
|
||||
- **Fastest**: get_node_essentials, validate_node_minimal, list_tasks
|
||||
- **Fast**: search_nodes, list_nodes, get_node_for_task
|
||||
- **Moderate**: validate_node_operation, n8n_update_partial_workflow
|
||||
- **Slow**: get_node_info (100KB+), validate_workflow (full analysis)
|
||||
|
||||
## Common Pitfalls to Avoid
|
||||
1. Using get_node_info when get_node_essentials would work
|
||||
2. Using node IDs instead of names in connections
|
||||
3. Not validating before creating workflows
|
||||
4. Searching with long phrases instead of keywords
|
||||
5. Forgetting to configure N8N_API_URL for management tools
|
||||
|
||||
## Getting More Help
|
||||
- Use tools_documentation({topic: "toolname"}) for any tool
|
||||
- Check CLAUDE.md for latest updates and examples
|
||||
- Run n8n_health_check() to verify API connectivity`;
|
||||
}
|
||||
|
||||
export function searchToolDocumentation(query: string): string[] {
|
||||
const results: string[] = [];
|
||||
const searchTerms = query.toLowerCase().split(' ');
|
||||
|
||||
for (const [toolName, tool] of Object.entries(toolsDocumentation)) {
|
||||
const searchText = `${toolName} ${tool.essentials.description} ${tool.category}`.toLowerCase();
|
||||
if (searchTerms.some(term => searchText.includes(term))) {
|
||||
results.push(toolName);
|
||||
}
|
||||
}
|
||||
|
||||
return results;
|
||||
}
|
||||
|
||||
export function getToolsByCategory(category: string): string[] {
|
||||
return Object.entries(toolsDocumentation)
|
||||
.filter(([_, tool]) => tool.category === category)
|
||||
.map(([name, _]) => name);
|
||||
}
|
||||
|
||||
export function getAllCategories(): string[] {
|
||||
const categories = new Set<string>();
|
||||
Object.values(toolsDocumentation).forEach(tool => {
|
||||
categories.add(tool.category);
|
||||
});
|
||||
return Array.from(categories);
|
||||
}
|
||||
@@ -8,15 +8,20 @@ import { ToolDefinition } from '../types';
|
||||
*/
|
||||
export const n8nDocumentationToolsFinal: ToolDefinition[] = [
|
||||
{
|
||||
name: 'start_here_workflow_guide',
|
||||
description: `START HERE! Essential guide for using n8n MCP tools effectively. Returns workflow recommendations, common patterns, performance tips, and known issues. Call this FIRST before using other tools to avoid common mistakes and work efficiently.`,
|
||||
name: 'tools_documentation',
|
||||
description: `Get documentation for n8n MCP tools. Call without parameters for quick start guide. Use topic parameter to get documentation for specific tools. Use depth='full' for comprehensive documentation.`,
|
||||
inputSchema: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
topic: {
|
||||
type: 'string',
|
||||
enum: ['overview', 'workflow', 'search_tips', 'common_nodes', 'known_issues', 'performance', 'ai_tools', 'n8n_management'],
|
||||
description: 'Optional: Get specific guidance on a topic. Default returns complete overview.',
|
||||
description: 'Tool name (e.g., "search_nodes") or "overview" for general guide. Leave empty for quick reference.',
|
||||
},
|
||||
depth: {
|
||||
type: 'string',
|
||||
enum: ['essentials', 'full'],
|
||||
description: 'Level of detail. "essentials" (default) for quick reference, "full" for comprehensive docs.',
|
||||
default: 'essentials',
|
||||
},
|
||||
},
|
||||
},
|
||||
|
||||
Reference in New Issue
Block a user