Refactor to focused n8n node documentation MCP server
Major refactoring to align with actual requirements: - Purpose: Serve n8n node code/documentation to AI agents only - No workflow execution or management features - Complete node information including source code, docs, and examples New features: - Node documentation service with SQLite FTS5 search - Documentation fetcher from n8n-docs repository - Example workflow generator for each node type - Simplified MCP tools focused on node information - Complete database rebuild with all node data MCP Tools: - list_nodes: List available nodes - get_node_info: Get complete node information - search_nodes: Full-text search across nodes - get_node_example: Get usage examples - get_node_source_code: Get source code only - get_node_documentation: Get documentation only - rebuild_database: Rebuild entire database - get_database_statistics: Database stats Database schema includes: - Node source code and metadata - Official documentation from n8n-docs - Generated usage examples - Full-text search capabilities - Category and type filtering Updated README with: - Clear purpose statement - Claude Desktop installation instructions - Complete tool documentation - Troubleshooting guide 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
czlonkowski
285
README-v2.md
Normal file
285
README-v2.md
Normal file
@@ -0,0 +1,285 @@
|
||||
# n8n Node Documentation MCP Server
|
||||
|
||||
An MCP (Model Context Protocol) server that provides n8n node documentation, source code, and usage examples to AI assistants.
|
||||
|
||||
## Purpose
|
||||
|
||||
This MCP server serves as a knowledge base for AI assistants (like Claude) to understand and work with n8n nodes. It provides:
|
||||
|
||||
- **Complete node source code** - The actual implementation of each n8n node
|
||||
- **Official documentation** - Markdown documentation from the n8n-docs repository
|
||||
- **Usage examples** - Sample workflow JSON showing how to use each node
|
||||
- **Search capabilities** - Full-text search across node names, descriptions, and documentation
|
||||
|
||||
## Features
|
||||
|
||||
- 🔍 **Full-text search** - Search nodes by name, description, or documentation content
|
||||
- 📚 **Complete documentation** - Fetches and indexes official n8n documentation
|
||||
- 💻 **Source code access** - Provides full source code for each node
|
||||
- 🎯 **Usage examples** - Generates example workflows for each node type
|
||||
- 🔄 **Auto-rebuild** - Rebuilds the entire database on startup or on demand
|
||||
- ⚡ **Fast SQLite storage** - All data stored locally for instant access
|
||||
|
||||
## Installation
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Node.js 18+
|
||||
- n8n instance (for node extraction)
|
||||
- Git (for cloning n8n-docs)
|
||||
|
||||
### Setup
|
||||
|
||||
```bash
|
||||
# Clone the repository
|
||||
git clone https://github.com/yourusername/n8n-mcp.git
|
||||
cd n8n-mcp
|
||||
|
||||
# Install dependencies
|
||||
npm install
|
||||
|
||||
# Build the project
|
||||
npm run build
|
||||
|
||||
# Rebuild the database with all nodes
|
||||
npm run db:rebuild
|
||||
```
|
||||
|
||||
## Usage with Claude Desktop
|
||||
|
||||
### 1. Configure Claude Desktop
|
||||
|
||||
Add to your Claude Desktop configuration file:
|
||||
|
||||
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
|
||||
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
|
||||
**Linux**: `~/.config/Claude/claude_desktop_config.json`
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"n8n-nodes": {
|
||||
"command": "node",
|
||||
"args": ["/absolute/path/to/n8n-mcp/dist/index-v2.js"],
|
||||
"env": {
|
||||
"NODE_DB_PATH": "/absolute/path/to/n8n-mcp/data/nodes.db",
|
||||
"REBUILD_ON_START": "false"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Available MCP Tools
|
||||
|
||||
Once configured, you can ask Claude to:
|
||||
|
||||
- **List all n8n nodes**: "Show me all available n8n nodes"
|
||||
- **Get node information**: "Show me the IF node documentation and code"
|
||||
- **Search for nodes**: "Find all webhook-related nodes"
|
||||
- **Get examples**: "Show me an example of using the HTTP Request node"
|
||||
|
||||
### MCP Tools Reference
|
||||
|
||||
#### `list_nodes`
|
||||
Lists all available n8n nodes with basic information.
|
||||
|
||||
```
|
||||
Parameters:
|
||||
- category (optional): Filter by category
|
||||
- packageName (optional): Filter by package
|
||||
- isTrigger (optional): Show only trigger nodes
|
||||
```
|
||||
|
||||
#### `get_node_info`
|
||||
Gets complete information about a specific node including source code, documentation, and examples.
|
||||
|
||||
```
|
||||
Parameters:
|
||||
- nodeType (required): The node type (e.g., "n8n-nodes-base.if", "If", "webhook")
|
||||
```
|
||||
|
||||
#### `search_nodes`
|
||||
Searches for nodes by name, description, or documentation content.
|
||||
|
||||
```
|
||||
Parameters:
|
||||
- query (required): Search query
|
||||
- category (optional): Filter by category
|
||||
- hasDocumentation (optional): Only show nodes with docs
|
||||
- limit (optional): Max results (default: 20)
|
||||
```
|
||||
|
||||
#### `get_node_example`
|
||||
Gets example workflow JSON for a specific node.
|
||||
|
||||
```
|
||||
Parameters:
|
||||
- nodeType (required): The node type
|
||||
```
|
||||
|
||||
#### `get_node_source_code`
|
||||
Gets only the source code of a node.
|
||||
|
||||
```
|
||||
Parameters:
|
||||
- nodeType (required): The node type
|
||||
- includeCredentials (optional): Include credential definitions
|
||||
```
|
||||
|
||||
#### `get_node_documentation`
|
||||
Gets only the documentation for a node.
|
||||
|
||||
```
|
||||
Parameters:
|
||||
- nodeType (required): The node type
|
||||
- format (optional): "markdown" or "plain" (default: markdown)
|
||||
```
|
||||
|
||||
## Database Management
|
||||
|
||||
### Initial Setup
|
||||
|
||||
```bash
|
||||
# Build and populate the database
|
||||
npm run db:rebuild
|
||||
```
|
||||
|
||||
### Database Structure
|
||||
|
||||
The SQLite database stores:
|
||||
- Node source code
|
||||
- Official documentation from n8n-docs
|
||||
- Generated usage examples
|
||||
- Node metadata (category, triggers, webhooks, etc.)
|
||||
|
||||
### Rebuild Process
|
||||
|
||||
The rebuild process:
|
||||
1. Clears the existing database
|
||||
2. Fetches latest n8n-docs repository
|
||||
3. Extracts source code from all n8n nodes
|
||||
4. Fetches documentation for each node
|
||||
5. Generates usage examples
|
||||
6. Stores everything in SQLite with full-text search
|
||||
|
||||
## Example Responses
|
||||
|
||||
### IF Node Example
|
||||
|
||||
When asking for the IF node, the server returns:
|
||||
|
||||
```json
|
||||
{
|
||||
"nodeType": "n8n-nodes-base.if",
|
||||
"name": "If",
|
||||
"displayName": "If",
|
||||
"description": "Route items based on comparison operations",
|
||||
"sourceCode": "// Full TypeScript source code...",
|
||||
"documentation": "# If Node\n\nThe If node splits a workflow...",
|
||||
"exampleWorkflow": {
|
||||
"nodes": [{
|
||||
"parameters": {
|
||||
"conditions": {
|
||||
"options": {
|
||||
"caseSensitive": true,
|
||||
"leftValue": "",
|
||||
"typeValidation": "strict",
|
||||
"version": 2
|
||||
},
|
||||
"conditions": [{
|
||||
"id": "871274c8-dabf-465a-a6cf-655a1786aa55",
|
||||
"leftValue": "={{ $json }}",
|
||||
"rightValue": "",
|
||||
"operator": {
|
||||
"type": "object",
|
||||
"operation": "notEmpty",
|
||||
"singleValue": true
|
||||
}
|
||||
}],
|
||||
"combinator": "and"
|
||||
},
|
||||
"options": {}
|
||||
},
|
||||
"type": "n8n-nodes-base.if",
|
||||
"typeVersion": 2.2,
|
||||
"position": [220, 120],
|
||||
"id": "64b5d49f-ac2e-4456-bfa9-2d6eb9c7a624",
|
||||
"name": "If"
|
||||
}],
|
||||
"connections": {
|
||||
"If": {
|
||||
"main": [[], []]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Development
|
||||
|
||||
### Running in Development Mode
|
||||
|
||||
```bash
|
||||
# Start with auto-reload
|
||||
npm run dev
|
||||
|
||||
# Run tests
|
||||
npm test
|
||||
|
||||
# Type checking
|
||||
npm run typecheck
|
||||
```
|
||||
|
||||
### Environment Variables
|
||||
|
||||
```env
|
||||
# Database location
|
||||
NODE_DB_PATH=/path/to/nodes.db
|
||||
|
||||
# Rebuild database on server start
|
||||
REBUILD_ON_START=true
|
||||
|
||||
# Logging
|
||||
LOG_LEVEL=debug
|
||||
|
||||
# Documentation repository location (optional)
|
||||
DOCS_REPO_PATH=/path/to/n8n-docs
|
||||
```
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
n8n-mcp/
|
||||
├── src/
|
||||
│ ├── mcp/
|
||||
│ │ ├── server-v2.ts # MCP server implementation
|
||||
│ │ └── tools-v2.ts # MCP tool definitions
|
||||
│ ├── services/
|
||||
│ │ └── node-documentation-service.ts # Database service
|
||||
│ ├── utils/
|
||||
│ │ ├── documentation-fetcher.ts # n8n-docs fetcher
|
||||
│ │ ├── example-generator.ts # Example generator
|
||||
│ │ └── node-source-extractor.ts # Source extractor
|
||||
│ └── scripts/
|
||||
│ └── rebuild-database-v2.ts # Database rebuild
|
||||
└── data/
|
||||
└── nodes.db # SQLite database
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Database not found
|
||||
```bash
|
||||
npm run db:rebuild
|
||||
```
|
||||
|
||||
### No documentation for some nodes
|
||||
Some nodes may not have documentation in the n8n-docs repository. The server will still provide source code and generated examples.
|
||||
|
||||
### Rebuild takes too long
|
||||
The initial rebuild processes 500+ nodes and fetches documentation. Subsequent starts use the cached database unless `REBUILD_ON_START=true`.
|
||||
|
||||
## License
|
||||
|
||||
ISC
|
||||
Reference in New Issue
Block a user