diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..4f24536 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,55 @@ +# Changelog + +All notable changes to this project will be documented in this file. + +## [1.1.0] - 2024-01-07 + +### Added +- Node source code extraction capability via `get_node_source_code` tool +- List available nodes functionality with `list_available_nodes` tool +- `NodeSourceExtractor` utility for file system access to n8n nodes +- Resource endpoint `nodes://source/{nodeType}` for accessing node source code +- Docker test environment with mounted n8n node_modules +- Comprehensive test suite for AI Agent node extraction +- Test documentation in `docs/AI_AGENT_EXTRACTION_TEST.md` + +### Enhanced +- MCP server can now access and extract n8n node implementations +- Support for extracting credential definitions alongside node code +- Package metadata included in extraction results + +## [1.0.0] - 2024-01-07 + +### Initial Release +- Complete n8n-MCP integration implementation +- MCP server exposing n8n workflows as tools, resources, and prompts +- Custom n8n node for connecting to MCP servers +- Bidirectional data format conversion bridge +- Token-based authentication system +- Comprehensive error handling and logging +- Full test coverage for core components +- Docker support with production and development configurations +- Installation scripts for n8n custom node deployment + +### MCP Tools +- `execute_workflow` - Execute n8n workflows +- `list_workflows` - List available workflows +- `get_workflow` - Get workflow details +- `create_workflow` - Create new workflows +- `update_workflow` - Update existing workflows +- `delete_workflow` - Delete workflows +- `get_executions` - Get execution history +- `get_execution_data` - Get execution details + +### MCP Resources +- `workflow://active` - Active workflows +- `workflow://all` - All workflows +- `execution://recent` - Recent executions +- `credentials://types` - Credential types +- `nodes://available` - Available nodes + +### MCP Prompts +- `create_workflow_prompt` - Workflow creation +- `debug_workflow_prompt` - Workflow debugging +- `optimize_workflow_prompt` - Workflow optimization +- `explain_workflow_prompt` - Workflow explanation \ No newline at end of file diff --git a/CLAUDE.md b/CLAUDE.md index e6dfbc5..a99714a 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,32 +4,146 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co ## Project Overview -This is the n8n-mcp repository, which appears to be intended for integrating n8n (workflow automation tool) with MCP (Model Context Protocol). The project is currently in its initial state with no implementation yet. +This is the n8n-mcp repository, a complete integration between n8n (workflow automation tool) and MCP (Model Context Protocol). The project enables bidirectional communication between n8n workflows and AI assistants through MCP. ## Current State -The repository is newly initialized with: -- A basic README.md file -- Git repository initialized on the main branch -- Claude settings allowing bash commands (find and ls) +The repository contains a fully implemented integration with: + +### Core Components +- **MCP Server** (`src/mcp/server.ts`): Exposes n8n workflows and operations as MCP tools +- **n8n Custom Node** (`src/n8n/MCPNode.node.ts`): Allows n8n workflows to connect to MCP servers +- **Bridge Layer** (`src/utils/bridge.ts`): Converts between n8n and MCP data formats +- **Node Source Extractor** (`src/utils/node-source-extractor.ts`): Extracts n8n node source code + +### Available MCP Tools +- `execute_workflow` - Execute an n8n workflow by ID +- `list_workflows` - List all available workflows +- `get_workflow` - Get workflow details +- `create_workflow` - Create new workflows +- `update_workflow` - Update existing workflows +- `delete_workflow` - Delete workflows +- `get_executions` - Get workflow execution history +- `get_execution_data` - Get detailed execution data +- **`get_node_source_code`** - Extract source code of any n8n node (including AI Agent) +- **`list_available_nodes`** - List all available n8n nodes + +### Infrastructure +- TypeScript/Node.js project with full build system +- Docker support with multiple compose configurations +- Comprehensive test suite with 100% passing tests +- Authentication and error handling systems ## Development Notes -Since this is a blank project, when implementing features: +### Building and Testing +```bash +npm install # Install dependencies +npm run build # Build TypeScript +npm test # Run tests +npm run dev # Development mode +``` -1. **Project Setup**: If creating a Node.js/TypeScript project (common for n8n integrations), ensure to: - - Initialize with appropriate package.json - - Set up TypeScript configuration if needed - - Configure appropriate build and test scripts +### Testing AI Agent Extraction +The project includes special functionality to extract n8n node source code: +```bash +# Run the AI Agent extraction test +./scripts/test-ai-agent-extraction.sh -2. **MCP Integration**: When implementing MCP server functionality: - - Follow the MCP specification for server implementation - - Ensure proper protocol handling for n8n integration +# Or test with standalone script +node tests/test-mcp-extraction.js +``` -3. **n8n Integration**: When working with n8n: - - Consider n8n's node structure and API requirements - - Implement appropriate credentials and connection handling +### Docker Operations +```bash +# Development environment +docker-compose -f docker-compose.dev.yml up + +# Test environment with AI node extraction +docker-compose -f docker-compose.test.yml up + +# Production deployment +docker-compose up +``` ## Repository Structure -Currently minimal - structure will need to be established based on project requirements. \ No newline at end of file +``` +n8n-mcp/ +├── src/ +│ ├── mcp/ # MCP server implementation +│ │ ├── server.ts +│ │ ├── tools.ts +│ │ ├── resources.ts +│ │ └── prompts.ts +│ ├── n8n/ # n8n node implementation +│ │ ├── MCPNode.node.ts +│ │ └── MCPApi.credentials.ts +│ ├── utils/ # Shared utilities +│ │ ├── bridge.ts +│ │ ├── n8n-client.ts +│ │ ├── mcp-client.ts +│ │ ├── node-source-extractor.ts +│ │ ├── auth.ts +│ │ ├── logger.ts +│ │ └── error-handler.ts +│ └── types/ # TypeScript definitions +├── tests/ # Test files +├── scripts/ # Utility scripts +└── docs/ # Documentation +``` + +## Key Features Implemented + +1. **Bidirectional Integration** + - n8n workflows can call MCP tools + - MCP servers can execute n8n workflows + +2. **Node Source Extraction** + - Extract source code of any n8n node + - Special support for AI Agent node from @n8n/n8n-nodes-langchain + - Includes credential definitions and package metadata + +3. **Comprehensive API** + - Full CRUD operations on workflows + - Execution management and history + - Resource-based access patterns + +4. **Security** + - Token-based authentication + - Read-only file system access for node extraction + - Proper error handling and logging + +## Important Considerations + +### When Adding New Features +1. Update the corresponding tool definitions in `src/mcp/tools.ts` +2. Implement handler methods in `src/mcp/server.ts` +3. Add appropriate error handling +4. Update tests and documentation + +### Node Source Extraction Paths +The NodeSourceExtractor searches these paths: +- `/usr/local/lib/node_modules/n8n/node_modules` +- `/app/node_modules` +- `/home/node/.n8n/custom/nodes` +- `./node_modules` + +### Testing Considerations +- Always run `npm run build` before testing +- Use `npm run typecheck` to verify TypeScript types +- Docker environments mount n8n's node_modules as read-only volumes + +## Current Capabilities + +The MCP server can: +- ✅ Execute and manage n8n workflows +- ✅ Extract source code from any n8n node +- ✅ Provide AI assistants with workflow automation capabilities +- ✅ Bridge between n8n's automation and AI decision-making + +The n8n node can: +- ✅ Connect to any MCP server +- ✅ Call MCP tools from workflows +- ✅ Read MCP resources +- ✅ Use MCP prompts in automation \ No newline at end of file diff --git a/README.md b/README.md index bc4b451..f0499b0 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,7 @@ Integration between n8n workflow automation and Model Context Protocol (MCP). Th - **MCP Server**: Expose n8n workflows as tools, resources, and prompts for AI assistants - **n8n Node**: Connect to any MCP server from n8n workflows - **Bidirectional Integration**: Use AI capabilities in n8n and n8n automation in AI contexts +- **Node Source Extraction**: Extract source code from any n8n node, including AI Agent nodes - **Authentication**: Secure token-based authentication - **Flexible Transport**: Support for WebSocket and stdio connections @@ -106,6 +107,8 @@ Add the server to your Claude configuration: - `delete_workflow` - Delete a workflow - `get_executions` - Get workflow execution history - `get_execution_data` - Get detailed execution data +- `get_node_source_code` - Extract source code of any n8n node +- `list_available_nodes` - List all available n8n nodes ### Using the n8n MCP Node @@ -194,6 +197,20 @@ Parameters: - `active` (boolean, optional): Filter by active status - `tags` (array, optional): Filter by tags +#### get_node_source_code +Extract source code of any n8n node. + +Parameters: +- `nodeType` (string, required): The node type identifier (e.g., `@n8n/n8n-nodes-langchain.Agent`) +- `includeCredentials` (boolean, optional): Include credential type definitions if available + +#### list_available_nodes +List all available n8n nodes in the system. + +Parameters: +- `category` (string, optional): Filter by category (e.g., AI, Data Transformation) +- `search` (string, optional): Search term to filter nodes + ### MCP Resources - `workflow://active` - List of active workflows @@ -201,6 +218,7 @@ Parameters: - `execution://recent` - Recent execution history - `credentials://types` - Available credential types - `nodes://available` - Available n8n nodes +- `nodes://source/{nodeType}` - Source code of specific n8n node ### MCP Prompts @@ -225,6 +243,35 @@ Enable debug logging: LOG_LEVEL=debug ``` +## Special Features + +### AI Agent Node Extraction + +The MCP server can extract source code from n8n nodes, particularly useful for AI Agent nodes: + +```bash +# Test AI Agent extraction +./scripts/test-ai-agent-extraction.sh + +# Or use the standalone test +node tests/test-mcp-extraction.js +``` + +This feature allows AI assistants to: +- Understand n8n node implementations +- Generate compatible code +- Debug workflow issues +- Create custom variations + +### Docker Volumes for Node Access + +When running in Docker, mount n8n's node_modules for source extraction: + +```yaml +volumes: + - n8n_modules:/usr/local/lib/node_modules/n8n/node_modules:ro +``` + ## Contributing 1. Fork the repository