ros/n8n-mcp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
b476d3627544f7b8ce9a72f445098e6b32572b2f
n8n-mcp/CLAUDE.md

7.5 KiB
Raw Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

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.

✅ Refactor Complete (v2.3)

Latest Update (v2.3) - Universal Node.js Compatibility:

  • ✅ Automatic database adapter fallback system implemented
  • ✅ Works with ANY Node.js version (no more v20.17.0 requirement)
  • ✅ Seamless fallback from better-sqlite3 to sql.js
  • ✅ No manual configuration needed for Claude Desktop
  • ✅ Maintains full functionality with either adapter

✅ Previous Achievements (v2.2)

The major refactor has been successfully completed based on IMPLEMENTATION_PLAN.md v2.2

Achieved Goals:

  • ✅ Fixed property/operation extraction (452/458 nodes have properties)
  • ✅ Added AI tool detection (35 AI tools detected)
  • ✅ Full support for @n8n/n8n-nodes-langchain package
  • ✅ Proper VersionedNodeType handling
  • ✅ Fixed documentation mapping issues

Current Architecture:

src/
├── loaders/
│   └── node-loader.ts         # NPM package loader for both packages
├── parsers/
│   ├── node-parser.ts         # Enhanced parser with version support
│   └── property-extractor.ts  # Dedicated property/operation extraction
├── mappers/
│   └── docs-mapper.ts         # Documentation mapping with fixes
├── database/
│   ├── schema.sql             # SQLite schema
│   └── node-repository.ts     # Data access layer
├── scripts/
│   ├── rebuild.ts             # Database rebuild with validation
│   ├── validate.ts            # Node validation
│   └── test-nodes.ts          # Critical node tests
└── mcp/
    └── server.ts              # MCP server with enhanced tools

Key Metrics:

  • 458 nodes successfully loaded (100%)
  • 452 nodes with properties (98.7%)
  • 265 nodes with operations (57.9%)
  • 406 nodes with documentation (88.6%)
  • 35 AI-capable tools detected
  • All critical nodes pass validation

Key Commands

# Development
npm install          # Install dependencies
npm run build        # Build TypeScript (required before running)
npm run dev          # Run in development mode with auto-reload
npm test             # Run Jest tests
npm run typecheck    # TypeScript type checking
npm run lint         # Check TypeScript types (alias for typecheck)

# Core Commands:
npm run rebuild      # Rebuild node database
npm run validate     # Validate critical nodes
npm run test-nodes   # Test critical node properties/operations

# Legacy Commands (deprecated):
npm run db:rebuild   # Old rebuild command
npm run db:init      # Initialize empty database
npm run docs:rebuild # Rebuild documentation from TypeScript source

# Production
npm start            # Run built application

High-Level Architecture

The project implements MCP (Model Context Protocol) to expose n8n node documentation, source code, and examples to AI assistants. Key architectural components:

Core Services

  • NodeDocumentationService (src/services/node-documentation-service.ts): Main database service using SQLite with FTS5 for fast searching
  • MCP Server (src/mcp/server.ts): Implements MCP protocol with tools for querying n8n nodes
  • Node Source Extractor (src/utils/node-source-extractor.ts): Extracts node implementations from n8n packages
  • Enhanced Documentation Fetcher (src/utils/enhanced-documentation-fetcher.ts): Fetches and parses official n8n documentation

MCP Tools Available

  • list_nodes - List all available n8n nodes with filtering
  • get_node_info - Get comprehensive information about a specific node (properties, operations, credentials)
  • search_nodes - Full-text search across all node documentation
  • list_ai_tools - List all AI-capable nodes (usableAsTool: true)
  • get_node_documentation - Get parsed documentation from n8n-docs
  • get_database_statistics - Get database usage statistics and metrics

Database Structure

Uses SQLite with enhanced schema:

  • nodes table: Core node information with FTS5 indexing
  • node_documentation: Parsed markdown documentation
  • node_examples: Generated workflow examples
  • node_source_code: Complete TypeScript/JavaScript implementations

Important Development Notes

Initial Setup Requirements

  1. Clone n8n-docs: git clone https://github.com/n8n-io/n8n-docs.git ../n8n-docs
  2. Install Dependencies: npm install
  3. Build: npm run build
  4. Rebuild Database: npm run rebuild
  5. Validate: npm run test-nodes

Node.js Version Compatibility

The project now features automatic database adapter fallback for universal Node.js compatibility:

  1. Primary adapter: Uses better-sqlite3 for optimal performance when available
  2. Fallback adapter: Automatically switches to sql.js (pure JavaScript) if:
    • Native modules fail to load
    • Node.js version mismatch detected
    • Running in Claude Desktop or other restricted environments

This means the project works with ANY Node.js version without manual intervention. The adapter selection is automatic and transparent.

Implementation Status

  • ✅ Property/operation extraction for 98.7% of nodes
  • ✅ Support for both n8n-nodes-base and @n8n/n8n-nodes-langchain
  • ✅ AI tool detection (35 tools with usableAsTool property)
  • ✅ Versioned node support (HTTPRequest, Code, etc.)
  • ✅ Documentation coverage for 88.6% of nodes
  • ⏳ Version history tracking (deferred - only current version)
  • ⏳ Workflow examples (deferred - using documentation)

Testing Workflow

npm run build        # Always build first
npm test             # Run all tests
npm run typecheck    # Verify TypeScript types

Docker Development

# Local development with stdio
docker-compose -f docker-compose.local.yml up

# HTTP server mode
docker-compose -f docker-compose.http.yml up

Authentication (HTTP mode)

When running in HTTP mode, use Bearer token authentication:

Authorization: Bearer your-auth-token

Architecture Patterns

Service Layer Pattern

All major functionality is implemented as services in src/services/. When adding new features:

  1. Create a service class with clear responsibilities
  2. Use dependency injection where appropriate
  3. Implement proper error handling with custom error types
  4. Add comprehensive logging using the logger utility

MCP Tool Implementation

When adding new MCP tools:

  1. Define the tool in src/mcp/tools.ts
  2. Implement handler in src/mcp/server.ts
  3. Add proper input validation
  4. Return structured responses matching MCP expectations

Database Access Pattern

  • Use prepared statements for all queries
  • Implement proper transaction handling
  • Use FTS5 for text searching
  • Cache frequently accessed data in memory

Environment Configuration

Required environment variables (see .env.example):

# Server Configuration
NODE_ENV=development
PORT=3000
AUTH_TOKEN=your-secure-token

# MCP Configuration  
MCP_SERVER_NAME=n8n-documentation-mcp
MCP_SERVER_VERSION=1.0.0

# Logging
LOG_LEVEL=info

License Note

This project uses the Sustainable Use License. Key points:

  • ✅ Free for internal business and personal use
  • ✅ Modifications allowed for own use
  • ❌ Cannot host as a service without permission
  • ❌ Cannot include in commercial products without permission