{"_id":"n8n-validator-mcp","_rev":"2-0bc22d1533a249a4e7478e5d3b9a3e99","name":"n8n-validator-mcp","dist-tags":{"latest":"1.0.2"},"versions":{"1.0.1":{"name":"n8n-validator-mcp","version":"1.0.1","keywords":["mcp","n8n","validation","node","workflow","automation","modelcontextprotocol","claude","ai"],"author":{"url":"https://github.com/andrewlwn77","name":"andrewlwn77"},"license":"MIT","_id":"n8n-validator-mcp@1.0.1","maintainers":[{"name":"andrewlwn77","email":"andrewlwn@gmail.com"}],"homepage":"https://github.com/andrewlwn77/n8n-validator-mcp#readme","bugs":{"url":"https://github.com/andrewlwn77/n8n-validator-mcp/issues"},"bin":{"n8n-validator-mcp":"build/index.js"},"dist":{"shasum":"13fb29b7b465f88886a721dd60e650541bc25f5c","tarball":"https://registry.npmjs.org/n8n-validator-mcp/-/n8n-validator-mcp-1.0.1.tgz","fileCount":64,"integrity":"sha512-y/3mkyq/Miw5U1WRFa7Y1F1VH8YggLCv0AXrRVGbSbrp5Oj8pjJFppCsSO7JopAbxXIS2Ch+8W04F0Ff/Ft6Mw==","signatures":[{"sig":"MEUCIQDkRTVCHqoRljb9j23EiyNkEKzlXEGKwqxfrzMy4KYRgwIgTN2hBDLjFVcyFvPKJpuM/tP+xnHJIGPH7EBiIDmkamY=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":144410},"main":"build/index.js","type":"module","types":"./build/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"2013fe205c904e38053ffdb299713f666c0fc516","scripts":{"dev":"tsc --watch","lint":"npx eslint src --ext .ts || echo 'Linting skipped - ESLint config needs migration'","test":"npm run build && npm run test:compile && jest","build":"tsc","start":"node ./build/index.js","pretest":"","lint:fix":"npx eslint src --ext .ts --fix || echo 'Linting skipped - ESLint config needs migration'","test:unit":"npm run build && npm run test:compile && jest tests/unit","test:watch":"npm run build && npm run test:compile && jest --watch","postversion":"git push && git push --tags","test:compile":"tsc --project tsconfig.test.json","test:coverage":"npm run build && npm run test:compile && jest --coverage","prepublishOnly":"npm run build","test:integration":"npm run build && npm run test:compile && jest tests/integration"},"_npmUser":{"name":"andrewlwn77","email":"andrewlwn@gmail.com"},"repository":{"url":"git+https://github.com/andrewlwn77/n8n-validator-mcp.git","type":"git"},"_npmVersion":"10.9.2","description":"MCP server for validating n8n nodes against official specifications","directories":{},"_nodeVersion":"22.13.1","dependencies":{"zod":"^3.25.76","typescript":"^5.8.3","@modelcontextprotocol/sdk":"^1.15.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.2","jest":"^30.0.4","eslint":"^8.57.0","ts-jest":"^29.4.0","@types/jest":"^30.0.0","@types/node":"^20.19.8","@jest/globals":"^30.0.4","@typescript-eslint/parser":"^8.0.0","@typescript-eslint/eslint-plugin":"^8.0.0"},"_npmOperationalInternal":{"tmp":"tmp/n8n-validator-mcp_1.0.1_1753029923938_0.8143923865612264","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"n8n-validator-mcp","version":"1.0.2","description":"MCP server for validating n8n nodes against official specifications","main":"build/index.js","type":"module","bin":{"n8n-validator-mcp":"build/index.js"},"scripts":{"build":"tsc","dev":"tsc --watch","start":"node ./build/index.js","test":"npm run build && npm run test:compile && jest","test:compile":"tsc --project tsconfig.test.json","test:unit":"npm run build && npm run test:compile && jest tests/unit","test:integration":"npm run build && npm run test:compile && jest tests/integration","test:watch":"npm run build && npm run test:compile && jest --watch","test:coverage":"npm run build && npm run test:compile && jest --coverage","lint":"npx eslint src --ext .ts || echo 'Linting skipped - ESLint config needs migration'","lint:fix":"npx eslint src --ext .ts --fix || echo 'Linting skipped - ESLint config needs migration'","pretest":"","prepublishOnly":"npm run build","postversion":"git push && git push --tags"},"keywords":["mcp","n8n","validation","node","workflow","automation","modelcontextprotocol","claude","ai"],"author":{"name":"andrewlwn77","url":"https://github.com/andrewlwn77"},"license":"MIT","engines":{"node":">=18.0.0"},"dependencies":{"@modelcontextprotocol/sdk":"^1.15.1","typescript":"^5.8.3","zod":"^3.25.76"},"devDependencies":{"@jest/globals":"^30.0.4","@types/jest":"^30.0.0","@types/node":"^20.19.8","@typescript-eslint/eslint-plugin":"^8.0.0","@typescript-eslint/parser":"^8.0.0","eslint":"^8.57.0","jest":"^30.0.4","ts-jest":"^29.4.0","tsx":"^4.19.2"},"publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/andrewlwn77/n8n-validator-mcp.git"},"bugs":{"url":"https://github.com/andrewlwn77/n8n-validator-mcp/issues"},"homepage":"https://github.com/andrewlwn77/n8n-validator-mcp#readme","_id":"n8n-validator-mcp@1.0.2","gitHead":"8c8b5a224882788538e684de8ff7297354a0f866","types":"./build/index.d.ts","_nodeVersion":"22.13.1","_npmVersion":"10.9.2","dist":{"integrity":"sha512-Lja5n2lhbZgrx/stKRNESdEblJZZCP8LumTXR/WlkqQqAHc1H4bxMfvgvm7t2+tghWS/gGobskxIc7LJ1ME09g==","shasum":"cdb5a09feaa5b6feac214eef2408a0a2d3a3b98e","tarball":"https://registry.npmjs.org/n8n-validator-mcp/-/n8n-validator-mcp-1.0.2.tgz","fileCount":64,"unpackedSize":146539,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDiJbeIglFN9uyw3TnlxTYKejtqRL0bH0Blu/N4gV67FwIgbTgxbZQZFKuS8j2l+12PuJKnT40Pg78zS7xKCPA0gaE="}]},"_npmUser":{"name":"andrewlwn77","email":"andrewlwn@gmail.com"},"directories":{},"maintainers":[{"name":"andrewlwn77","email":"andrewlwn@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/n8n-validator-mcp_1.0.2_1753143173569_0.40392737785839317"},"_hasShrinkwrap":false}},"time":{"created":"2025-07-20T16:45:23.877Z","modified":"2025-07-22T00:12:53.952Z","1.0.1":"2025-07-20T16:45:24.142Z","1.0.2":"2025-07-22T00:12:53.758Z"},"bugs":{"url":"https://github.com/andrewlwn77/n8n-validator-mcp/issues"},"author":{"name":"andrewlwn77","url":"https://github.com/andrewlwn77"},"license":"MIT","homepage":"https://github.com/andrewlwn77/n8n-validator-mcp#readme","keywords":["mcp","n8n","validation","node","workflow","automation","modelcontextprotocol","claude","ai"],"repository":{"type":"git","url":"git+https://github.com/andrewlwn77/n8n-validator-mcp.git"},"description":"MCP server for validating n8n nodes against official specifications","maintainers":[{"name":"andrewlwn77","email":"andrewlwn@gmail.com"}],"readme":"# n8n Validator MCP\n\nA comprehensive Model Context Protocol (MCP) server for validating n8n workflow nodes against their official specifications.\n\n## Overview\n\nThe n8n Validator MCP provides AI development tools with the capability to validate n8n node implementations, fetch official specifications, and compare node differences. This eliminates the frustration of generic \"validation failed\" errors by providing specific, actionable feedback.\n\n## Features\n\n### 🔍 **Node Validation**\n- Validates local n8n nodes against official specifications\n- Detailed error reporting with specific paths and expected values\n- Compliance scoring from 0-100\n- Supports all n8n node types and versions\n\n### 📋 **Specification Fetching**\n- Fetches official n8n node specifications from GitHub\n- Parses TypeScript definitions into structured data\n- Supports version-specific specifications\n- Intelligent caching for performance\n\n### 🔄 **Node Comparison**\n- Compare two node implementations side-by-side\n- Categorizes differences (missing, extra, different values)\n- Deep object comparison with nested property support\n- Clear formatting for easy understanding\n\n## Installation\n\n### Method 1: Claude Desktop Extensions (Recommended - 2025)\n\nThe easiest way to install this MCP server is through Claude Desktop Extensions:\n\n1. **Update Claude Desktop** to the latest version\n2. **Open Settings** → **Extensions** in Claude Desktop\n3. **Search** for \"n8n Validator MCP\" in the extensions directory\n4. **Click Install** - no configuration required!\n\nDesktop Extensions provide one-click installation with automatic updates and no dependency management.\n\n### Method 2: NPX Installation (Recommended for 2025)\n\nThe modern approach using npx without global installation:\n\n#### Prerequisites\n- **Node.js 18+** installed on your system\n- **Claude Desktop** app (macOS/Windows)\n\n#### Configure Claude Desktop\n1. **Open Claude Desktop** → **Settings** → **Developer**\n2. **Click \"Edit Config\"** to open `claude_desktop_config.json`\n3. **Add the server configuration**:\n\n```json\n{\n  \"mcpServers\": {\n    \"n8n-validator\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"n8n-validator-mcp\"]\n    }\n  }\n}\n```\n\n4. **Restart Claude Desktop** to load the server\n5. **Verify installation** by looking for the 🔨 hammer icon in Claude Desktop\n\n### Method 3: Global NPM Installation (Legacy)\n\nFor users who prefer global installation:\n\n#### Install the Package\n```bash\nnpm install -g n8n-validator-mcp\n```\n\n#### Configure Claude Desktop\n```json\n{\n  \"mcpServers\": {\n    \"n8n-validator\": {\n      \"command\": \"n8n-validator-mcp\",\n      \"args\": []\n    }\n  }\n}\n```\n\n#### Troubleshooting Installation\n\n**Common Issues:**\n- **Node.js version**: Ensure you have Node.js 18+ installed (`node --version`)\n- **NPX not found**: Verify npx is available (`npx --version`)\n- **PATH issues**: On Windows, you may need `\"command\": \"cmd\"` with `\"/c\"` in args\n- **Restart required**: Always restart Claude Desktop after configuration changes\n\n**Advanced Configuration for Windows:**\n```json\n{\n  \"mcpServers\": {\n    \"n8n-validator\": {\n      \"command\": \"cmd\",\n      \"args\": [\"/c\", \"npx\", \"-y\", \"n8n-validator-mcp\"]\n    }\n  }\n}\n```\n\n**WSL Configuration:**\n```json\n{\n  \"mcpServers\": {\n    \"n8n-validator\": {\n      \"command\": \"wsl.exe\",\n      \"args\": [\"bash\", \"-c\", \"npx -y n8n-validator-mcp\"]\n    }\n  }\n}\n```\n\n**Verify Installation:**\n```bash\n# Check Node.js and npx\nnode --version\nnpx --version\n\n# Test the package directly\nnpx -y n8n-validator-mcp --help\n```\n\n## Usage\n\n### With Claude Desktop\n\nOnce installed via either method, the n8n Validator MCP integrates seamlessly with Claude Desktop. Use natural language commands:\n\n```\n\"Validate this GitHub node implementation\"\n\"Show me what's wrong with my Slack node\"\n\"Compare my local node with the official specification\"\n\"Fetch the specification for the HTTP Request node\"\n```\n\n### Example Validation Output\n\n```\n# n8n Node Validation Result\n\n## Validation Status: ❌ INVALID\n## Compliance Score: 60/100\n\n### Errors (4)\n- **missing_property** at `displayName`: Required property 'displayName' is missing\n- **missing_property** at `description`: Required property 'description' is missing\n- **invalid_value** at `name`: Node name 'Template Selection Trigger' does not match specification 'webhook'\n  Expected: \"webhook\"\n  Actual: \"Template Selection Trigger\"\n- **invalid_value** at `name`: Node name must start with a letter and contain only alphanumeric characters\n  Expected: \"alphanumeric name starting with letter\"\n  Actual: \"Template Selection Trigger\"\n\n### Summary\nYour n8n node implementation has 4 errors that need to be fixed.\n\n### Recommendations\nPlease fix the errors listed above to ensure your node works correctly with n8n.\n```\n\n### Alternative Configuration Methods\n\n#### Using Claude Code CLI\n```bash\n# Register with user scope (persistent)\nclaude mcp add-json n8n-validator --scope user '{\n  \"command\": \"npx\",\n  \"args\": [\"-y\", \"n8n-validator-mcp\"]\n}'\n\n# Register with local scope (temporary)\nclaude mcp add-json n8n-validator --scope local '{\n  \"command\": \"npx\",\n  \"args\": [\"-y\", \"n8n-validator-mcp\"]\n}'\n```\n\n#### VS Code Configuration\nFor VS Code users, create `.vscode/mcp.json`:\n```json\n{\n  \"servers\": {\n    \"n8n-validator\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"n8n-validator-mcp\"]\n    }\n  }\n}\n```\n\n### Direct Usage\n\n```bash\n# Start the MCP server directly\nnpx -y n8n-validator-mcp\n\n# The server provides three tools:\n# - validate_n8n_node: Validate a node against official specs\n# - fetch_node_spec: Get official node specifications\n# - compare_nodes: Compare two node implementations\n```\n\n## MCP Tools\n\n### validate_n8n_node\n\nValidates a local n8n node implementation against its official specification.\n\n**Parameters:**\n- `nodeJson` (string): The JSON string of the n8n node to validate\n- `nodeType` (string): The type of node (e.g., \"Github\", \"Slack\", \"HTTP Request\")\n- `nodeVersion` (string, optional): Version of the node to validate against\n\n**Returns:**\n- Detailed validation report with errors, warnings, and compliance score\n- Specific error paths and expected vs actual values\n- Actionable recommendations for fixes\n\n### fetch_node_spec\n\nFetches the official specification for an n8n node from the repository.\n\n**Parameters:**\n- `nodeType` (string): The type of node to fetch specification for\n- `nodeVersion` (string, optional): Version of the node spec to fetch\n\n**Returns:**\n- Formatted specification with parsed TypeScript definitions\n- Property details and structure information\n- File paths and version information\n\n### compare_nodes\n\nCompares two n8n node implementations and highlights differences.\n\n**Parameters:**\n- `localNode` (string): Local n8n node JSON string\n- `specNode` (string): Official specification node JSON string\n\n**Returns:**\n- Detailed comparison report with categorized differences\n- Side-by-side value comparison\n- Summary of changes needed\n\n## Development\n\n### Prerequisites\n- Node.js 18+\n- TypeScript 5.0+\n- GitHub access for fetching specifications\n\n### Setup\n```bash\ngit clone <repository-url>\ncd n8n-validator-mcp\nnpm install\nnpm run build\n```\n\n### Testing\n```bash\nnpm test                # Run all tests\nnpm run test:unit      # Run unit tests\nnpm run test:integration # Run integration tests\nnpm run test:coverage   # Run with coverage\n```\n\n### Building\n```bash\nnpm run build     # Compile TypeScript\nnpm run dev       # Watch mode for development\n```\n\n## Architecture\n\nThe n8n Validator MCP follows a modular monolith architecture:\n\n```\nsrc/\n├── tools/              # MCP tool implementations\n├── services/           # Core business logic\n├── infrastructure/     # Cross-cutting concerns\n├── server/            # MCP server setup\n└── types/             # TypeScript definitions\n```\n\n### Key Components\n\n- **Validation Engine**: Core validation logic with comprehensive error reporting\n- **GitHub Client**: Robust API integration with caching and rate limiting\n- **TypeScript Parser**: Parses n8n node definitions from TypeScript source\n- **Comparison Service**: Deep object comparison for node differences\n- **Error Handler**: Centralized error handling with user-friendly messages\n- **Cache Manager**: Intelligent caching with TTL and LRU eviction\n\n## Configuration\n\n### Environment Variables\n\n- `GITHUB_TOKEN`: GitHub API token for higher rate limits (optional)\n\n### Performance\n\n- **Validation**: < 3 seconds for typical nodes\n- **Specification Fetching**: < 2 seconds with caching\n- **Node Comparison**: < 1 second for most comparisons\n- **Cache Hit Rate**: > 90% for repeated requests\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes with tests\n4. Run the test suite\n5. Submit a pull request\n\n## License\n\nMIT License - see LICENSE file for details\n\n## Support\n\nFor issues and questions:\n- GitHub Issues: Report bugs and request features\n- Documentation: See `/docs` directory for detailed guides\n- Examples: Check `/tests/fixtures` for sample usage\n\n## Roadmap\n\n- **AST-based Parsing**: Upgrade from regex to proper TypeScript AST parsing\n- **Advanced Validation**: Deep property validation and credential checking\n- **Performance Optimization**: Enhanced caching and request batching\n- **IDE Integration**: VS Code extension for real-time validation\n- **Custom Rules**: User-defined validation rules and constraints\n\n---\n\nBuilt with the BMAD Method for comprehensive, production-ready software development.","readmeFilename":"README.md"}