193 lines
6.9 KiB
Markdown
193 lines
6.9 KiB
Markdown
# 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.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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
This project requires Node.js v20.17.0 for Claude Desktop compatibility. If using a different Node version locally:
|
|
|
|
1. Install Node v20.17.0 via nvm: `nvm install 20.17.0`
|
|
2. Use the provided wrapper script: `mcp-server-v20.sh`
|
|
3. Or switch Node version: `nvm use 20.17.0`
|
|
|
|
### 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
|
|
```bash
|
|
npm run build # Always build first
|
|
npm test # Run all tests
|
|
npm run typecheck # Verify TypeScript types
|
|
```
|
|
|
|
### Docker Development
|
|
```bash
|
|
# 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 |