n8n-mcp-server: Instructions file for Claude Code

CLAUDE.md

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

Development Commands

# Install dependencies (using pnpm)
pnpm install

# Development with auto-reload
pnpm run dev          # stdio transport (default)
pnpm run dev:http     # HTTP transport on port 3000

# Build
pnpm run build        # Compile TypeScript to dist/
pnpm run clean        # Remove dist/ directory

# Type checking & Linting
pnpm run type-check   # Run TypeScript compiler without emitting
pnpm run lint         # Run ESLint
pnpm run lint:fix     # Fix ESLint errors automatically

# Code Quality
pnpm run knip         # Detect unused files, dependencies, exports
pnpm run knip:fix     # Auto-fix knip issues

# Testing
pnpm run test         # Run tests once
pnpm run test:watch   # Run tests in watch mode
pnpm run test:coverage # Run tests with coverage

# Production
pnpm start            # Run built code with stdio transport
pnpm start:http       # Run built code with HTTP transport

Recommended Development Workflow

HTTPモードでバックグラウンド起動を推奨

HTTPモードでバックグラウンド起動すると、コード修正が即座に反映され（HMR）、開発効率が大幅に向上します：

# バックグラウンドでHTTPサーバーを起動
pnpm run dev:http &

# または、別のターミナルで起動
pnpm run dev:http

利点:

• ファイル変更を検知して自動リロード（tsx --watch）
• MCPツールの動作確認がリアルタイムで可能
• ログ出力でツール登録状態を確認可能
• stdio transportと異なり、複数のクライアントから同時接続可能

Architecture Overview

This is a Model Context Protocol (MCP) server that bridges AI models with n8n workflow automation platform.

Core Architecture

Layer 1: Server Layer (src/server/)

1. MCPServerImpl (src/server/mcp-server.ts)

   • Main server orchestrator
   • Lifecycle: constructor → initialize() → start() → stop()
   • Manages two transport modes: stdio (default) and HTTP
   • Delegates tool management to ToolRegistry
   • Delegates HTTP handling to HttpTransportHandler

2. ToolRegistry (src/server/tool-registry.ts)

   • Centralized tool management system
   • Manual tool registration (no auto-discovery for safety)
   • Schema caching for performance (cleared via clearCache())
   • Provides getToolSchemas(), getToolByName(), setupToolHandlers()
   • Tool instances stored in Map<string, Tool>