mirror of
https://github.com/czlonkowski/n8n-mcp.git
synced 2026-02-06 13:33:11 +00:00
Compare commits
1 Commits
fix/sql-js
...
update/n8n
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
04e601b172 |
113
CHANGELOG.md
113
CHANGELOG.md
@@ -7,103 +7,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|||||||
|
|
||||||
## [Unreleased]
|
## [Unreleased]
|
||||||
|
|
||||||
## [2.22.10] - 2025-11-04
|
## [2.22.8] - 2025-11-03
|
||||||
|
|
||||||
### 🐛 Bug Fixes
|
|
||||||
|
|
||||||
**sql.js Fallback: Fixed Database Health Check Crash**
|
|
||||||
|
|
||||||
Fixed critical startup crash when the server falls back to sql.js adapter (used when better-sqlite3 fails to load, such as Node.js version mismatches between build and runtime).
|
|
||||||
|
|
||||||
#### Problem
|
|
||||||
|
|
||||||
When Claude Desktop was configured to use a different Node.js version than the one used to build the project:
|
|
||||||
- better-sqlite3 fails to load due to NODE_MODULE_VERSION mismatch (e.g., built with Node v22, running with Node v20)
|
|
||||||
- System gracefully falls back to sql.js adapter (pure JavaScript, no native dependencies)
|
|
||||||
- **BUT** the database health check crashed with "no such module: fts5" error
|
|
||||||
- Server exits immediately after startup, preventing connection
|
|
||||||
|
|
||||||
**Error Details:**
|
|
||||||
```
|
|
||||||
[ERROR] Database health check failed: Error: no such module: fts5
|
|
||||||
at e.handleError (sql-wasm.js:90:371)
|
|
||||||
at e.prepare (sql-wasm.js:89:104)
|
|
||||||
at SQLJSAdapter.prepare (database-adapter.js:202:30)
|
|
||||||
at N8NDocumentationMCPServer.validateDatabaseHealth (server.js:251:42)
|
|
||||||
```
|
|
||||||
|
|
||||||
**Root Cause:** The health check attempted to query the FTS5 (Full-Text Search) table, which is not available in sql.js. The error was not caught, causing the server to exit.
|
|
||||||
|
|
||||||
#### Solution
|
|
||||||
|
|
||||||
Wrapped the FTS5 health check in a try-catch block to handle sql.js gracefully:
|
|
||||||
|
|
||||||
```typescript
|
|
||||||
// Check if FTS5 table exists (wrap in try-catch for sql.js compatibility)
|
|
||||||
try {
|
|
||||||
const ftsExists = this.db.prepare(`
|
|
||||||
SELECT name FROM sqlite_master
|
|
||||||
WHERE type='table' AND name='nodes_fts'
|
|
||||||
`).get();
|
|
||||||
|
|
||||||
if (!ftsExists) {
|
|
||||||
logger.warn('FTS5 table missing - search performance will be degraded...');
|
|
||||||
} else {
|
|
||||||
const ftsCount = this.db.prepare('SELECT COUNT(*) as count FROM nodes_fts').get();
|
|
||||||
if (ftsCount.count === 0) {
|
|
||||||
logger.warn('FTS5 index is empty - search will not work properly...');
|
|
||||||
}
|
|
||||||
}
|
|
||||||
} catch (ftsError) {
|
|
||||||
// FTS5 not supported (e.g., sql.js fallback) - this is OK, just warn
|
|
||||||
logger.warn('FTS5 not available - using fallback search. For better performance, ensure better-sqlite3 is properly installed.');
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Impact
|
|
||||||
|
|
||||||
**Before Fix:**
|
|
||||||
- ❌ Server crashed immediately when using sql.js fallback
|
|
||||||
- ❌ Claude Desktop connection failed with Node.js version mismatches
|
|
||||||
- ❌ No way to use the MCP server without matching Node.js versions exactly
|
|
||||||
|
|
||||||
**After Fix:**
|
|
||||||
- ✅ Server starts successfully with sql.js fallback
|
|
||||||
- ✅ Works with any Node.js version (graceful degradation)
|
|
||||||
- ✅ Clear warning about FTS5 unavailability in logs
|
|
||||||
- ✅ Users can choose between sql.js (slower, works everywhere) or rebuilding better-sqlite3 (faster, requires matching Node version)
|
|
||||||
|
|
||||||
#### Performance Notes
|
|
||||||
|
|
||||||
When using sql.js fallback:
|
|
||||||
- Full-text search (FTS5) is not available, falls back to LIKE queries
|
|
||||||
- Slightly slower search performance (~10-30ms vs ~5ms with FTS5)
|
|
||||||
- All other functionality works identically
|
|
||||||
- Database operations work correctly
|
|
||||||
|
|
||||||
**Recommendation:** For best performance, ensure better-sqlite3 loads successfully by matching Node.js versions or rebuilding:
|
|
||||||
```bash
|
|
||||||
# If Node version mismatch, rebuild better-sqlite3
|
|
||||||
npm rebuild better-sqlite3
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Files Changed
|
|
||||||
|
|
||||||
**Modified (1 file):**
|
|
||||||
- `src/mcp/server.ts` (lines 299-317) - Added try-catch around FTS5 health check
|
|
||||||
|
|
||||||
#### Testing
|
|
||||||
|
|
||||||
- ✅ Tested with Node v20.17.0 (Claude Desktop version)
|
|
||||||
- ✅ Tested with Node v22.17.0 (build version)
|
|
||||||
- ✅ Server starts successfully in both cases
|
|
||||||
- ✅ sql.js fallback works correctly with graceful FTS5 degradation
|
|
||||||
- ✅ All 6 startup checkpoints pass
|
|
||||||
- ✅ Database health check passes with warning
|
|
||||||
|
|
||||||
Conceived by Romuald Członkowski - [www.aiadvisors.pl/en](https://www.aiadvisors.pl/en)
|
|
||||||
|
|
||||||
## [2.22.9] - 2025-11-04
|
|
||||||
|
|
||||||
### 🔄 Dependencies Update
|
### 🔄 Dependencies Update
|
||||||
|
|
||||||
@@ -123,21 +27,6 @@ Updated n8n and all related dependencies to the latest versions:
|
|||||||
- 103 nodes from @n8n/n8n-nodes-langchain
|
- 103 nodes from @n8n/n8n-nodes-langchain
|
||||||
- All node metadata synchronized with latest n8n release
|
- All node metadata synchronized with latest n8n release
|
||||||
|
|
||||||
### 🐛 Bug Fixes
|
|
||||||
|
|
||||||
**n8n 1.118.1+ Compatibility: Fixed versionCounter API Rejection**
|
|
||||||
|
|
||||||
Fixed integration test failures caused by n8n 1.118.1 API change where `versionCounter` property is returned in GET responses but rejected in PUT requests.
|
|
||||||
|
|
||||||
**Impact**:
|
|
||||||
- Integration tests were failing with "request/body must NOT have additional properties" error
|
|
||||||
- Workflow update operations via n8n API were failing
|
|
||||||
|
|
||||||
**Solution**:
|
|
||||||
- Added `versionCounter` to property exclusion list in `cleanWorkflowForUpdate()` (src/services/n8n-validation.ts:136)
|
|
||||||
- Added `versionCounter?: number` type definition to Workflow and WorkflowExport interfaces
|
|
||||||
- Added test coverage to prevent regression
|
|
||||||
|
|
||||||
### ✅ Verification
|
### ✅ Verification
|
||||||
|
|
||||||
- Database rebuild completed successfully
|
- Database rebuild completed successfully
|
||||||
|
|||||||
@@ -1,87 +1,5 @@
|
|||||||
# n8n Update Process - Quick Reference
|
# n8n Update Process - Quick Reference
|
||||||
|
|
||||||
## ⚡ Recommended Fast Workflow (2025-11-04)
|
|
||||||
|
|
||||||
**CRITICAL FIRST STEP**: Check existing releases to avoid version conflicts!
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 1. CHECK EXISTING RELEASES FIRST (prevents version conflicts!)
|
|
||||||
gh release list | head -5
|
|
||||||
# Look at the latest version - your new version must be higher!
|
|
||||||
|
|
||||||
# 2. Switch to main and pull
|
|
||||||
git checkout main && git pull
|
|
||||||
|
|
||||||
# 3. Check for updates (dry run)
|
|
||||||
npm run update:n8n:check
|
|
||||||
|
|
||||||
# 4. Run update and skip tests (we'll test in CI)
|
|
||||||
yes y | npm run update:n8n
|
|
||||||
|
|
||||||
# 5. Create feature branch
|
|
||||||
git checkout -b update/n8n-X.X.X
|
|
||||||
|
|
||||||
# 6. Update version in package.json (must be HIGHER than latest release!)
|
|
||||||
# Edit: "version": "2.XX.X" (not the version from the release list!)
|
|
||||||
|
|
||||||
# 7. Update CHANGELOG.md
|
|
||||||
# - Change version number to match package.json
|
|
||||||
# - Update date to today
|
|
||||||
# - Update dependency versions
|
|
||||||
|
|
||||||
# 8. Update README badge
|
|
||||||
# Edit line 8: Change n8n version badge to new n8n version
|
|
||||||
|
|
||||||
# 9. Commit and push
|
|
||||||
git add -A
|
|
||||||
git commit -m "chore: update n8n to X.X.X and bump version to 2.XX.X
|
|
||||||
|
|
||||||
- Updated n8n from X.X.X to X.X.X
|
|
||||||
- Updated n8n-core from X.X.X to X.X.X
|
|
||||||
- Updated n8n-workflow from X.X.X to X.X.X
|
|
||||||
- Updated @n8n/n8n-nodes-langchain from X.X.X to X.X.X
|
|
||||||
- Rebuilt node database with XXX nodes (XXX from n8n-nodes-base, XXX from @n8n/n8n-nodes-langchain)
|
|
||||||
- Updated README badge with new n8n version
|
|
||||||
- Updated CHANGELOG with dependency changes
|
|
||||||
|
|
||||||
Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en
|
|
||||||
|
|
||||||
🤖 Generated with [Claude Code](https://claude.com/claude-code)
|
|
||||||
|
|
||||||
Co-Authored-By: Claude <noreply@anthropic.com>"
|
|
||||||
|
|
||||||
git push -u origin update/n8n-X.X.X
|
|
||||||
|
|
||||||
# 10. Create PR
|
|
||||||
gh pr create --title "chore: update n8n to X.X.X" --body "Updates n8n and all related dependencies to the latest versions..."
|
|
||||||
|
|
||||||
# 11. After PR is merged, verify release triggered
|
|
||||||
gh release list | head -1
|
|
||||||
# If the new version appears, you're done!
|
|
||||||
# If not, the version might have already been released - bump version again and create new PR
|
|
||||||
```
|
|
||||||
|
|
||||||
### Why This Workflow?
|
|
||||||
|
|
||||||
✅ **Fast**: Skip local tests (2-3 min saved) - CI runs them anyway
|
|
||||||
✅ **Safe**: Unit tests in CI verify compatibility
|
|
||||||
✅ **Clean**: All changes in one PR with proper tracking
|
|
||||||
✅ **Automatic**: Release workflow triggers on merge if version is new
|
|
||||||
|
|
||||||
### Common Issues
|
|
||||||
|
|
||||||
**Problem**: Release workflow doesn't trigger after merge
|
|
||||||
**Cause**: Version number was already released (check `gh release list`)
|
|
||||||
**Solution**: Create new PR bumping version by one patch number
|
|
||||||
|
|
||||||
**Problem**: Integration tests fail in CI with "unauthorized"
|
|
||||||
**Cause**: n8n test instance credentials expired (infrastructure issue)
|
|
||||||
**Solution**: Ignore if unit tests pass - this is not a code problem
|
|
||||||
|
|
||||||
**Problem**: CI takes 8+ minutes
|
|
||||||
**Reason**: Integration tests need live n8n instance (slow)
|
|
||||||
**Normal**: Unit tests (~2 min) + integration tests (~6 min) = ~8 min total
|
|
||||||
|
|
||||||
## Quick One-Command Update
|
## Quick One-Command Update
|
||||||
|
|
||||||
For a complete update with tests and publish preparation:
|
For a complete update with tests and publish preparation:
|
||||||
@@ -181,14 +99,12 @@ This command:
|
|||||||
|
|
||||||
## Important Notes
|
## Important Notes
|
||||||
|
|
||||||
1. **ALWAYS check existing releases first** - Use `gh release list` to see what versions are already released. Your new version must be higher!
|
1. **Always run on main branch** - Make sure you're on main and it's clean
|
||||||
2. **Release workflow only triggers on version CHANGE** - If you merge a PR with an already-released version (e.g., 2.22.8), the workflow won't run. You'll need to bump to a new version (e.g., 2.22.9) and create another PR.
|
2. **The update script is smart** - It automatically syncs all n8n dependencies to compatible versions
|
||||||
3. **Integration test failures in CI are usually infrastructure issues** - If unit tests pass but integration tests fail with "unauthorized", this is typically because the test n8n instance credentials need updating. The code itself is fine.
|
3. **Tests are required** - The publish script now runs tests automatically
|
||||||
4. **Skip local tests - let CI handle them** - Running tests locally adds 2-3 minutes with no benefit since CI runs them anyway. The fast workflow skips local tests.
|
4. **Database rebuild is automatic** - The update script handles this for you
|
||||||
5. **The update script is smart** - It automatically syncs all n8n dependencies to compatible versions
|
5. **Template sanitization is automatic** - Any API tokens in workflow templates are replaced with placeholders
|
||||||
6. **Database rebuild is automatic** - The update script handles this for you
|
6. **Docker image builds automatically** - Pushing to GitHub triggers the workflow
|
||||||
7. **Template sanitization is automatic** - Any API tokens in workflow templates are replaced with placeholders
|
|
||||||
8. **Docker image builds automatically** - Pushing to GitHub triggers the workflow
|
|
||||||
|
|
||||||
## GitHub Push Protection
|
## GitHub Push Protection
|
||||||
|
|
||||||
@@ -199,27 +115,11 @@ As of July 2025, GitHub's push protection may block database pushes if they cont
|
|||||||
3. If push is still blocked, use the GitHub web interface to review and allow the push
|
3. If push is still blocked, use the GitHub web interface to review and allow the push
|
||||||
|
|
||||||
## Time Estimate
|
## Time Estimate
|
||||||
|
|
||||||
### Fast Workflow (Recommended)
|
|
||||||
- Local work: ~2-3 minutes
|
|
||||||
- npm install and database rebuild: ~2-3 minutes
|
|
||||||
- File edits (CHANGELOG, README, package.json): ~30 seconds
|
|
||||||
- Git operations (commit, push, create PR): ~30 seconds
|
|
||||||
- CI testing after PR creation: ~8-10 minutes (runs automatically)
|
|
||||||
- Unit tests: ~2 minutes
|
|
||||||
- Integration tests: ~6 minutes (may fail with infrastructure issues - ignore if unit tests pass)
|
|
||||||
- Other checks: ~1 minute
|
|
||||||
|
|
||||||
**Total hands-on time: ~3 minutes** (then wait for CI)
|
|
||||||
|
|
||||||
### Full Workflow with Local Tests
|
|
||||||
- Total time: ~5-7 minutes
|
- Total time: ~5-7 minutes
|
||||||
- Test suite: ~2.5 minutes
|
- Test suite: ~2.5 minutes
|
||||||
- npm install and database rebuild: ~2-3 minutes
|
- npm install and database rebuild: ~2-3 minutes
|
||||||
- The rest: seconds
|
- The rest: seconds
|
||||||
|
|
||||||
**Note**: The fast workflow is recommended since CI runs the same tests anyway.
|
|
||||||
|
|
||||||
## Troubleshooting
|
## Troubleshooting
|
||||||
|
|
||||||
If tests fail:
|
If tests fail:
|
||||||
|
|||||||
@@ -54,10 +54,6 @@ Collected data is used solely to:
|
|||||||
- Identify common error patterns
|
- Identify common error patterns
|
||||||
- Improve tool performance and reliability
|
- Improve tool performance and reliability
|
||||||
- Guide development priorities
|
- Guide development priorities
|
||||||
- Train machine learning models for workflow generation
|
|
||||||
|
|
||||||
All ML training uses sanitized, anonymized data only.
|
|
||||||
Users can opt-out at any time with `npx n8n-mcp telemetry disable`
|
|
||||||
|
|
||||||
## Data Retention
|
## Data Retention
|
||||||
- Data is retained for analysis purposes
|
- Data is retained for analysis purposes
|
||||||
|
|||||||
@@ -1,6 +1,6 @@
|
|||||||
{
|
{
|
||||||
"name": "n8n-mcp",
|
"name": "n8n-mcp",
|
||||||
"version": "2.22.10",
|
"version": "2.22.8",
|
||||||
"description": "Integration between n8n workflow automation and Model Context Protocol (MCP)",
|
"description": "Integration between n8n workflow automation and Model Context Protocol (MCP)",
|
||||||
"main": "dist/index.js",
|
"main": "dist/index.js",
|
||||||
"types": "dist/index.d.ts",
|
"types": "dist/index.d.ts",
|
||||||
|
|||||||
@@ -1,6 +1,6 @@
|
|||||||
{
|
{
|
||||||
"name": "n8n-mcp-runtime",
|
"name": "n8n-mcp-runtime",
|
||||||
"version": "2.22.10",
|
"version": "2.22.8",
|
||||||
"description": "n8n MCP Server Runtime Dependencies Only",
|
"description": "n8n MCP Server Runtime Dependencies Only",
|
||||||
"private": true,
|
"private": true,
|
||||||
"dependencies": {
|
"dependencies": {
|
||||||
|
|||||||
@@ -296,8 +296,7 @@ export class N8NDocumentationMCPServer {
|
|||||||
throw new Error('Database is empty. Run "npm run rebuild" to populate node data.');
|
throw new Error('Database is empty. Run "npm run rebuild" to populate node data.');
|
||||||
}
|
}
|
||||||
|
|
||||||
// Check if FTS5 table exists (wrap in try-catch for sql.js compatibility)
|
// Check if FTS5 table exists
|
||||||
try {
|
|
||||||
const ftsExists = this.db.prepare(`
|
const ftsExists = this.db.prepare(`
|
||||||
SELECT name FROM sqlite_master
|
SELECT name FROM sqlite_master
|
||||||
WHERE type='table' AND name='nodes_fts'
|
WHERE type='table' AND name='nodes_fts'
|
||||||
@@ -311,10 +310,6 @@ export class N8NDocumentationMCPServer {
|
|||||||
logger.warn('FTS5 index is empty - search will not work properly. Please run: npm run rebuild');
|
logger.warn('FTS5 index is empty - search will not work properly. Please run: npm run rebuild');
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
} catch (ftsError) {
|
|
||||||
// FTS5 not supported (e.g., sql.js fallback) - this is OK, just warn
|
|
||||||
logger.warn('FTS5 not available - using fallback search. For better performance, ensure better-sqlite3 is properly installed.');
|
|
||||||
}
|
|
||||||
|
|
||||||
logger.info(`Database health check passed: ${nodeCount.count} nodes loaded`);
|
logger.info(`Database health check passed: ${nodeCount.count} nodes loaded`);
|
||||||
} catch (error) {
|
} catch (error) {
|
||||||
|
|||||||
@@ -133,7 +133,6 @@ export function cleanWorkflowForUpdate(workflow: Workflow): Partial<Workflow> {
|
|||||||
createdAt,
|
createdAt,
|
||||||
updatedAt,
|
updatedAt,
|
||||||
versionId,
|
versionId,
|
||||||
versionCounter, // Added: n8n 1.118.1+ returns this but rejects it in updates
|
|
||||||
meta,
|
meta,
|
||||||
staticData,
|
staticData,
|
||||||
// Remove fields that cause API errors
|
// Remove fields that cause API errors
|
||||||
|
|||||||
@@ -66,7 +66,6 @@ export interface Workflow {
|
|||||||
updatedAt?: string;
|
updatedAt?: string;
|
||||||
createdAt?: string;
|
createdAt?: string;
|
||||||
versionId?: string;
|
versionId?: string;
|
||||||
versionCounter?: number; // Added: n8n 1.118.1+ returns this in GET responses
|
|
||||||
meta?: {
|
meta?: {
|
||||||
instanceId?: string;
|
instanceId?: string;
|
||||||
};
|
};
|
||||||
@@ -153,7 +152,6 @@ export interface WorkflowExport {
|
|||||||
tags?: string[];
|
tags?: string[];
|
||||||
pinData?: Record<string, unknown>;
|
pinData?: Record<string, unknown>;
|
||||||
versionId?: string;
|
versionId?: string;
|
||||||
versionCounter?: number; // Added: n8n 1.118.1+
|
|
||||||
meta?: Record<string, unknown>;
|
meta?: Record<string, unknown>;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|||||||
@@ -313,7 +313,6 @@ describe('n8n-validation', () => {
|
|||||||
createdAt: '2023-01-01',
|
createdAt: '2023-01-01',
|
||||||
updatedAt: '2023-01-01',
|
updatedAt: '2023-01-01',
|
||||||
versionId: 'v123',
|
versionId: 'v123',
|
||||||
versionCounter: 5, // n8n 1.118.1+ field
|
|
||||||
meta: { test: 'data' },
|
meta: { test: 'data' },
|
||||||
staticData: { some: 'data' },
|
staticData: { some: 'data' },
|
||||||
pinData: { pin: 'data' },
|
pinData: { pin: 'data' },
|
||||||
@@ -334,7 +333,6 @@ describe('n8n-validation', () => {
|
|||||||
expect(cleaned).not.toHaveProperty('createdAt');
|
expect(cleaned).not.toHaveProperty('createdAt');
|
||||||
expect(cleaned).not.toHaveProperty('updatedAt');
|
expect(cleaned).not.toHaveProperty('updatedAt');
|
||||||
expect(cleaned).not.toHaveProperty('versionId');
|
expect(cleaned).not.toHaveProperty('versionId');
|
||||||
expect(cleaned).not.toHaveProperty('versionCounter'); // n8n 1.118.1+ compatibility
|
|
||||||
expect(cleaned).not.toHaveProperty('meta');
|
expect(cleaned).not.toHaveProperty('meta');
|
||||||
expect(cleaned).not.toHaveProperty('staticData');
|
expect(cleaned).not.toHaveProperty('staticData');
|
||||||
expect(cleaned).not.toHaveProperty('pinData');
|
expect(cleaned).not.toHaveProperty('pinData');
|
||||||
@@ -351,22 +349,6 @@ describe('n8n-validation', () => {
|
|||||||
expect(cleaned.settings).toEqual({ executionOrder: 'v1' });
|
expect(cleaned.settings).toEqual({ executionOrder: 'v1' });
|
||||||
});
|
});
|
||||||
|
|
||||||
it('should exclude versionCounter for n8n 1.118.1+ compatibility', () => {
|
|
||||||
const workflow = {
|
|
||||||
name: 'Test Workflow',
|
|
||||||
nodes: [],
|
|
||||||
connections: {},
|
|
||||||
versionId: 'v123',
|
|
||||||
versionCounter: 5, // n8n 1.118.1 returns this but rejects it in PUT
|
|
||||||
} as any;
|
|
||||||
|
|
||||||
const cleaned = cleanWorkflowForUpdate(workflow);
|
|
||||||
|
|
||||||
expect(cleaned).not.toHaveProperty('versionCounter');
|
|
||||||
expect(cleaned).not.toHaveProperty('versionId');
|
|
||||||
expect(cleaned.name).toBe('Test Workflow');
|
|
||||||
});
|
|
||||||
|
|
||||||
it('should add empty settings object for cloud API compatibility', () => {
|
it('should add empty settings object for cloud API compatibility', () => {
|
||||||
const workflow = {
|
const workflow = {
|
||||||
name: 'Test Workflow',
|
name: 'Test Workflow',
|
||||||
|
|||||||
Reference in New Issue
Block a user