{"owner":"czlonkowski","repo":"n8n-mcp","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md","CLAUDE.md"],"files":{"AGENTS.md":"# Repository Guidelines\n\n> This file is committed to a public OSS repository. Never add API keys, credentials, private URLs, customer data, or private infrastructure details.\n\n## Project Overview\n\nn8n-mcp is a Model Context Protocol server that gives AI assistants access to n8n node documentation, workflow validation, and workflow management. Documentation and validation tools work offline against the bundled SQLite node database. Management tools prefixed with `n8n_` operate on a live n8n instance and require API configuration.\n\n## Project Structure & Module Organization\n\nCore TypeScript lives in `src/`. Important subsystems include:\n\n- `src/mcp/` — MCP server, request handlers, tool definitions and documentation, and bundled skills\n- `src/database/` — SQLite adapters, repositories, FTS5 search, and migrations\n- `src/loaders/`, `src/parsers/`, `src/mappers/` — node loading, metadata parsing, and documentation mapping\n- `src/services/` — validation, workflow diffing and autofix, node/version lookup, the n8n API client, and security scanners\n- `src/templates/` and `src/community/` — workflow-template and community-node ingestion and documentation\n- `src/telemetry/`, `src/triggers/`, and `src/n8n/` — telemetry, trigger detection, and the n8n community-node wrapper\n- `src/scripts/` — maintenance scripts compiled to `dist/scripts/`\n- `src/types/`, `src/constants/`, and `src/utils/` — shared types, constants, and helpers\n- `src/http-server*.ts` — HTTP transports and session persistence\n- `src/mcp-engine.ts` and `src/mcp-tools-engine.ts` — APIs for embedding the server\n\nTests mirror the source areas in `tests/unit/` and `tests/integration/`, with fixtures, factories, helpers, and mocks under `tests/`. React/Vite apps live in `ui-apps/src/`, repository utilities in `scripts/`, documentation in `docs/`, and generated skills and databases in `data/`. Treat `dist/`, coverage output, and `ui-apps/dist/` as generated; do not edit them directly.\n\n## Architecture & MCP Conventions\n\n- Route database operations through repository classes and keep business logic in the service layer.\n- Validation profiles are `minimal`, `runtime`, `ai-friendly`, and `strict`.\n- Prefer diff-based workflow changes through `n8n_update_partial_workflow`; do not replace a whole workflow when a focused operation is sufficient.\n- Offline documentation and validation tools include `search_nodes`, `get_node`, `validate_node`, `validate_workflow`, `search_templates`, `get_template`, and `tools_documentation`.\n- Live management tools use the `n8n_*` prefix and cover workflows, executions, tests, versions, autofix, templates, credentials, datatables, and audits.\n- Request the smallest useful `get_node` detail level: `minimal`, `standard`, or `full`.\n- Validate workflows before deploying them to n8n.\n\n## Build, Test, and Development Commands\n\n```bash\n# Install and build\nnpm install                    # Install root dependencies; repeat in ui-apps/ for UI work\nnpm run build                  # Compile production TypeScript to dist/\nnpm run build:all              # Sync skills, build UI apps, and compile the server\nnpm run typecheck              # Strict TypeScript check without emitting; npm run lint is an alias\n\n# Test\nnpm test                       # Run all Vitest tests\nnpm run test:unit              # Unit tests\nnpm run test:integration       # Integration tests\nnpm run test:e2e               # End-to-end tests\nnpm run test:coverage          # Coverage report\nnpm test -- tests/unit/services/property-filter.test.ts\n\n# Run and maintain\nnpm start                      # MCP server in stdio mode\nnpm run start:http             # MCP server in HTTP mode\nnpm run dev:http               # Rebuild and restart HTTP mode on source changes\nnpm run rebuild                # Rebuild the bundled node database\nnpm run validate               # Validate generated node data\nnpm run dev                    # Build, rebuild the database, and validate\n\n# Update bundled data\nnpm run update:n8n:check       # Dry-run n8n dependency update; follow MEMORY_N8N_UPDATE.md\nnpm run update:n8n             # Update n8n packages\nnpm run fetch:templates        # Fetch n8n.io templates; follow MEMORY_TEMPLATE_UPDATE.md\nnpm run fetch:community        # Upsert community nodes while preserving existing docs\nnpm run generate:docs:incremental # Generate docs for community nodes missing them\n```\n\nDatabase rebuilds take several minutes because of the n8n package size. HTTP mode requires valid auth configuration, and live n8n tests require configuration and a clean database state.\n\n## Coding Style & Naming Conventions\n\nUse strict TypeScript, two-space indentation, single quotes, and semicolons. Prefer `camelCase` for variables and functions, `PascalCase` for classes and types, and kebab-case filenames such as `workflow-auto-fixer.ts`. Use the configured `@/` and `@tests/` aliases where helpful. Keep modules focused, validate external input, and do not use hyperbolic or dramatic language in comments or documentation. No separate formatter is configured; `npm run typecheck` is the required static check.\n\n## Development & Testing Workflow\n\n- Run `npm run typecheck` after every code change and `npm run build` after MCP server changes.\n- After rebuilding server code, ask the user to reload the MCP server before testing the changed MCP behavior.\n- Name tests `*.test.ts` and place them in the matching test subtree. Use MSW for API mocking.\n- Run focused tests while iterating, `npm run test:unit` for the fast suite, and relevant integration or end-to-end tests for system behavior.\n- Run `npm run test:coverage` before substantial pull requests. Coverage thresholds are 75% for lines, functions, and statements and 70% for branches.\n- Do not mask flaky tests with retries.\n- When reviewing a GitHub issue, use `gh` to fetch the issue and all comments.\n\n## Sub-agents\n\n- When a task has genuinely independent subtasks, use appropriately specialized sub-agents in parallel.\n- Give each sub-agent a bounded scope and clear file ownership.\n- Sub-agents must not spawn additional sub-agents, commit, or push. The primary agent owns integration, verification, commits, and pushes.\n\n## Commit & Pull Request Guidelines\n\nUse Conventional Commit prefixes such as `feat:`, `fix:`, `docs:`, `chore:`, and scoped forms such as `ci(deps):`. Work on a feature branch and never commit directly to `main`. Keep commits narrowly scoped and do not include unrelated dirty-worktree changes.\n\nPRs should explain intent and verification, link relevant issues, include screenshots for UI changes, and enable “Allow edits by maintainers.” Add the following attribution to every commit message and PR description:\n\n`Conceived by Romuald Członkowski - www.aiadvisors.pl/en`\n\nThe attribution belongs only in commit messages and PR descriptions. Never add it to source, test, documentation, or other product file contents.\n\n## Security & Configuration\n\nStart from `.env.example` and keep local secrets untracked. Never commit credentials, API keys, private URLs, customer data, or sensitive configuration. Confirm the intended n8n instance before using live management tools, and validate workflows before deployment.\n","CLAUDE.md":"# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\n\n> **Note:** This file is committed to a public OSS repository. Never add sensitive information (API keys, internal URLs, credentials, private infrastructure details) here.\n\n## Project Overview\n\nn8n-mcp is an MCP (Model Context Protocol) server that gives AI assistants access to n8n node documentation, workflow validation, and workflow management. Documentation and validation tools work offline against a bundled SQLite database of node information; management tools (`n8n_*`) operate on a live n8n instance when API credentials are configured.\n\n## Common Development Commands\n\n```bash\n# Build\nnpm run build          # Compile TypeScript (always run after changes)\nnpm run build:all      # Sync skills pack + build UI apps + compile\nnpm run rebuild        # Rebuild node database from n8n packages\nnpm run validate       # Validate node data in database\nnpm run dev            # build + rebuild + validate\n\n# Testing\nnpm test               # Run all tests (vitest)\nnpm run test:unit      # Unit tests only\nnpm run test:integration # Integration tests\nnpm run test:e2e       # End-to-end tests\nnpm run test:coverage  # Coverage report\nnpm test -- tests/unit/services/property-filter.test.ts  # Single file\n\n# Type checking\nnpm run typecheck      # tsc --noEmit (npm run lint is an alias)\n\n# Running the server\nnpm start              # MCP server in stdio mode\nnpm run start:http     # MCP server in HTTP mode\nnpm run dev:http       # HTTP server with auto-reload\n\n# n8n dependency updates — follow MEMORY_N8N_UPDATE.md\nnpm run update:n8n:check  # Dry run\nnpm run update:n8n        # Update n8n packages\n\n# Templates and community nodes\nnpm run fetch:templates   # Fetch workflow templates from n8n.io — see MEMORY_TEMPLATE_UPDATE.md\nnpm run fetch:community   # Fetch/refresh community nodes (upserts; preserves existing docs)\nnpm run generate:docs:incremental  # Generate AI docs for community nodes missing them\n```\n\n## Architecture\n\nKey subsystems of `src/` (non-exhaustive — smaller directories are omitted). This file intentionally stays at subsystem level; for file-level detail, explore the directories.\n\n- `mcp/` — MCP server, tool definitions (`tools.ts`, `tools-n8n-manager.ts`), request handlers, per-tool documentation (`tool-docs/`), bundled skills (`skills/`)\n- `database/` — SQLite storage: universal adapter over better-sqlite3/sql.js, `node-repository.ts` data access, FTS5 full-text search, `migrations/`\n- `loaders/`, `parsers/`, `mappers/` — node processing pipeline: load nodes from n8n packages → parse metadata and properties → map external documentation\n- `services/` — business logic: config/workflow/expression validators, validation profiles, workflow diff engine, auto-fixer, node similarity and version services, n8n API client, security/audit scanners\n- `templates/` — fetching and storing workflow templates from n8n.io\n- `community/` — community node fetching and documentation generation\n- `telemetry/` — opt-in anonymous usage telemetry\n- `triggers/` — trigger detection and registry\n- `n8n/` — n8n community node wrapper (N8N_MODE)\n- `scripts/` — maintenance CLI scripts (rebuild, validate, template/community fetching), compiled to `dist/scripts/`\n- `types/`, `constants/`, `utils/` — shared types, type structures, helpers\n- `http-server.ts`, `http-server-single-session.ts` — HTTP mode with session persistence\n- `mcp-engine.ts`, `mcp-tools-engine.ts` — clean API for embedding the server in other services\n\n### Key design patterns\n\n1. **Repository pattern**: all database operations go through repository classes\n2. **Service layer**: business logic separated from data access\n3. **Validation profiles**: strictness levels `minimal`, `runtime`, `ai-friendly`, `strict`\n4. **Diff-based updates**: `n8n_update_partial_workflow` applies operation diffs, saving 80–90% of tokens vs full updates\n\n### MCP tools\n\nTwo groups:\n\n- **Documentation and validation** (offline, always available): `search_nodes`, `get_node`, `validate_node`, `validate_workflow`, `search_templates`, `get_template`, `tools_documentation`\n- **Management** (`n8n_*`, require n8n API configuration): workflow CRUD and partial updates, executions, workflow testing, versions, autofix, template deployment, credentials, datatables, instance audit\n\n`get_node` supports detail levels (`minimal`/`standard`/`full`) — request the smallest level that answers the question.\n\n## Development Workflow\n\n- After changing MCP server code: build, then ask the user to reload the MCP server before testing\n- Run `npm run typecheck` after every code change\n- Never commit directly to main — use feature branches and PRs\n- Add to every commit message and PR description: `Conceived by Romuald Członkowski - www.aiadvisors.pl/en`. The attribution belongs in commit messages and PR descriptions only — never in source, test, or documentation file contents\n- When reviewing issues, use the GH CLI (`gh`) to fetch the issue and all its comments\n- Do not use hyperbolic or dramatic language in comments and documentation\n\n### Sub-agents\n\n- When a task divides into independent subtasks, spawn sub-agents to handle them in parallel; pick the best agent type per its description\n- Sub-agents must not spawn further sub-agents\n- Sub-agents must not commit or push — do that yourself\n\n### Pitfalls\n\n- Database rebuilds take 2–3 minutes due to n8n package size\n- Integration tests require a clean database state\n- HTTP mode requires proper auth token configuration\n- Always validate workflows before deploying them to n8n\n"}}