ros/n8n-mcp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add simplified MCP V2 plan focused on MVP fixes

Browse Source 
- Create 3-day plan to fix critical issues only
- Focus on deployment, search, and deduplication
- Remove overengineered 4-week plan versions
- Add rollback strategy and test endpoints
- Total new code: ~62 lines instead of enterprise architecture

Ship the fixes, not the framework.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
czlonkowski
2025-06-16 14:27:18 +02:00
parent 1884d5babf
commit 12a255ace1
2 changed files with 440 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

146
docs/IMMEDIATE_DEPLOYMENT_ACTION.md Normal file
View File

@@ -0,0 +1,146 @@
# Immediate Deployment Action Plan
## 🚀 Quick Fix: Test if Tools are Actually Working
Based on the analysis, your implemented tools ARE working but the Docker image is outdated. Here's how to verify and fix:
## Option 1: Local Testing (Fastest)
```bash
# 1. Stop current Docker container
docker compose down
# 2. Run locally with npm
cd /Users/romualdczlonkowski/Pliki/n8n-mcp/n8n-mcp
npm run build
npm run start:http
# 3. Test with curl
curl -X POST http://localhost:3000/mcp \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"method": "tools/list",
"id": 1
}'
```
You should see all 12 tools including:
- get_node_essentials
- search_node_properties
- get_node_for_task
- list_tasks
- validate_node_config
- get_property_dependencies
## Option 2: Update Docker Image
```bash
# 1. Build new image with latest code
docker build -t ghcr.io/czlonkowski/n8n-mcp:v2.4.0 .
docker build -t ghcr.io/czlonkowski/n8n-mcp:latest .
# 2. Test locally
docker run -p 3000:3000 -e USE_FIXED_HTTP=true ghcr.io/czlonkowski/n8n-mcp:latest
# 3. Push to registry (if you have access)
docker push ghcr.io/czlonkowski/n8n-mcp:v2.4.0
docker push ghcr.io/czlonkowski/n8n-mcp:latest
```
## Option 3: Quick Local Docker Test
```bash
# 1. Update docker-compose.yml to build locally
cat > docker-compose.override.yml << 'EOF'
services:
n8n-mcp:
build: .
image: n8n-mcp:local
EOF
# 2. Rebuild and start
docker compose build
docker compose up -d
# 3. Check health
curl http://localhost:3000/health
```
## Claude Desktop Testing
After updating:
1. **Completely quit Claude Desktop** (not just close window)
2. **Clear any cache**:
```bash
# macOS
rm -rf ~/Library/Caches/com.anthropic.claude*
```
3. **Restart Claude Desktop**
4. **Test the new tools**:
- "List all available MCP tools"
- "Use get_node_essentials for HTTP Request"
- "Use get_node_for_task to configure a post_json_request"
## Diagnostic Script
```bash
# Save this as test-mcp-tools.sh
#!/bin/bash
echo "Testing MCP Tools Availability..."
# Test tool list
curl -s -X POST http://localhost:3000/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"tools/list","id":1}' | \
jq '.result.tools[].name' | sort
echo -e "\nTesting get_node_essentials..."
curl -s -X POST http://localhost:3000/mcp \
-H "Content-Type: application/json" \
-d '{
"jsonrpc":"2.0",
"method":"tools/call",
"params":{
"name":"get_node_essentials",
"arguments":{"nodeType":"nodes-base.httpRequest"}
},
"id":2
}' | jq '.result.content[0].text' -r | jq '.requiredProperties, .commonProperties' | head -20
```
## Expected Results
If everything is working, you should see:
1. **12 tools** in the tool list
2. **get_node_essentials** returns ~6 properties (not 200+)
3. **No errors** about missing tools
## If Tools Still Don't Appear
1. **Check which server file is being used**:
```bash
grep -n "from './server" dist/mcp/index.js
```
Should show: `from './server-update'`
2. **Verify the tools are in the compiled code**:
```bash
grep -c "get_node_essentials" dist/mcp/tools-update.js
```
Should show: 3 or more
3. **Check if there's a caching issue**:
- Add `?v=2` to your MCP URL in Claude Desktop config
- Or change the server name temporarily
## Next Steps
Once you confirm the tools are working:
1. Document the deployment process that worked
2. Update CI/CD to automate image builds
3. Proceed with V2 improvements (deduplication, etc.)
The tools ARE implemented - we just need to get the latest code deployed!

294
docs/MCP_V2_FINAL_PLAN.md Normal file
View File

@@ -0,0 +1,294 @@
# MCP V2 Final Plan - MVP Approach
## Executive Summary
Forget the 4-week enterprise architecture. Here's how to fix everything in 3 days.
## Day 1 (Monday) - Deploy & Debug
### 1. Fix Deployment (1 hour)
```bash
# Just build and push
docker build -t ghcr.io/czlonkowski/n8n-mcp:latest .
docker push ghcr.io/czlonkowski/n8n-mcp:latest
```
### 2. Add Version & Test Endpoints (30 min)
```typescript
// In http-server-fixed.ts
app.get('/version', (req, res) => {
res.json({
version: '2.4.1',
buildTime: new Date().toISOString(),
tools: n8nDocumentationToolsFinal.map(t => t.name),
commit: process.env.GIT_COMMIT || 'unknown'
});
});
app.get('/test-tools', async (req, res) => {
try {
const result = await server.executeTool('get_node_essentials', { nodeType: 'nodes-base.httpRequest' });
res.json({ status: 'ok', hasData: !!result, toolCount: n8nDocumentationToolsFinal.length });
} catch (error) {
res.json({ status: 'error', message: error.message });
}
});
```
### 3. Debug list_nodes (1 hour)
```typescript
// Add ONE line to see what's broken
private async listNodes(filters: any = {}): Promise<any> {
console.log('DEBUG list_nodes:', { filters, query, params }); // ADD THIS
// ... rest of code
}
```
### 4. Debug list_ai_tools (30 min)
```sql
-- Run this query to check
SELECT COUNT(*) as ai_count FROM nodes WHERE is_ai_tool = 1;
-- If 0, the column isn't populated. Fix in rebuild script.
```
## Day 2 (Tuesday) - Core Fixes
### 1. Fix Multi-Word Search (2 hours)
```typescript
// Replace the search function in server-update.ts
private async searchNodes(query: string, limit: number = 20): Promise<any> {
// Split query into words
// Handle exact phrase searches with quotes
if (query.startsWith('"') && query.endsWith('"')) {
const exactPhrase = query.slice(1, -1);
const nodes = this.db!.prepare(`
SELECT * FROM nodes
WHERE node_type LIKE ? OR display_name LIKE ? OR description LIKE ?
ORDER BY display_name
LIMIT ?
`).all(`%${exactPhrase}%`, `%${exactPhrase}%`, `%${exactPhrase}%`, limit) as NodeRow[];
return { query, results: this.formatNodeResults(nodes), totalCount: nodes.length };
}
// Split into words for normal search
const words = query.toLowerCase().split(/\s+/).filter(w => w.length > 0);
if (words.length === 0) {
return { query, results: [], totalCount: 0 };
}
// Build conditions for each word
const conditions = words.map(() =>
'(node_type LIKE ? OR display_name LIKE ? OR description LIKE ?)'
).join(' OR ');
const params = words.flatMap(w => [`%${w}%`, `%${w}%`, `%${w}%`]);
params.push(limit);
const nodes = this.db!.prepare(`
SELECT DISTINCT * FROM nodes
WHERE ${conditions}
ORDER BY display_name
LIMIT ?
`).all(...params) as NodeRow[];
return {
query,
results: nodes.map(node => ({
nodeType: node.node_type,
displayName: node.display_name,
description: node.description,
category: node.category,
package: node.package_name
})),
totalCount: nodes.length
};
}
```
### 2. Simple Property Deduplication (2 hours)
```typescript
// Add to PropertyFilter.ts
static deduplicateProperties(properties: any[]): any[] {
const seen = new Map<string, any>();
return properties.filter(prop => {
// Create unique key from name + conditions
const conditions = JSON.stringify(prop.displayOptions || {});
const key = `${prop.name}_${conditions}`;
if (seen.has(key)) {
return false; // Skip duplicate
}
seen.set(key, prop);
return true;
});
}
// Use in getEssentials
static getEssentials(allProperties: any[], nodeType: string): FilteredProperties {
// Deduplicate first
const uniqueProperties = this.deduplicateProperties(allProperties);
// ... rest of existing code
}
```
### 3. Fix Package Name Mismatch (1 hour)
```typescript
// In listNodes, be more flexible with package names
if (filters.package) {
// Handle both formats
const packageVariants = [
filters.package,
`@n8n/${filters.package}`,
filters.package.replace('@n8n/', '')
];
query += ' AND package_name IN (' + packageVariants.map(() => '?').join(',') + ')';
params.push(...packageVariants);
}
```
## Day 3 (Wednesday) - Polish & Test
### 1. Add Simple Memory Cache (2 hours)
```typescript
// Super simple cache - no frameworks needed
class SimpleCache {
private cache = new Map<string, { data: any; expires: number }>();
constructor() {
// Clean up expired entries every minute
setInterval(() => {
const now = Date.now();
for (const [key, item] of this.cache.entries()) {
if (item.expires < now) this.cache.delete(key);
}
}, 60000);
}
get(key: string): any {
const item = this.cache.get(key);
if (!item || item.expires < Date.now()) {
this.cache.delete(key);
return null;
}
return item.data;
}
set(key: string, data: any, ttlSeconds: number = 300): void {
this.cache.set(key, {
data,
expires: Date.now() + (ttlSeconds * 1000)
});
}
clear(): void {
this.cache.clear();
}
}
// Use in server
const cache = new SimpleCache();
// Example in getNodeEssentials
const cacheKey = `essentials:${nodeType}`;
const cached = cache.get(cacheKey);
if (cached) return cached;
// ... get data ...
cache.set(cacheKey, result, 3600); // Cache for 1 hour
```
### 2. Add Basic Documentation Fallback (1 hour)
```typescript
// In getNodeDocumentation
if (!node.documentation) {
const essentials = await this.getNodeEssentials(nodeType);
return {
nodeType: node.node_type,
displayName: node.display_name,
documentation: `
# ${node.display_name}
${node.description || 'No description available.'}
## Common Properties
${essentials.commonProperties.map(p =>
`### ${p.displayName}\n${p.description || `Type: ${p.type}`}`
).join('\n\n')}
## Note
Full documentation is being prepared. For now, use get_node_essentials for configuration help.
`,
hasDocumentation: false
};
}
```
### 3. Testing Checklist (2 hours)
- [ ] Rebuild and deploy Docker image
- [ ] Test all tools appear in Claude Desktop
- [ ] Test multi-word search: "send slack message"
- [ ] Test list_nodes with package filter
- [ ] Test list_ai_tools returns 263 nodes
- [ ] Verify no duplicate properties in webhook/email nodes
- [ ] Check response times with cache
## Total Time: 3 Days
### Day 1: 3 hours of actual work
### Day 2: 5 hours of actual work
### Day 3: 5 hours of actual work
## Rollback Plan
```bash
# Before starting, tag current version
docker pull ghcr.io/czlonkowski/n8n-mcp:latest
docker tag ghcr.io/czlonkowski/n8n-mcp:latest ghcr.io/czlonkowski/n8n-mcp:v2.4.0-backup
# If anything breaks, instant rollback:
docker tag ghcr.io/czlonkowski/n8n-mcp:v2.4.0-backup ghcr.io/czlonkowski/n8n-mcp:latest
docker push ghcr.io/czlonkowski/n8n-mcp:latest
```
## What We're NOT Doing
- ❌ No complex deployment verifiers
- ❌ No semantic search
- ❌ No AI documentation generators
- ❌ No workflow assistants
- ❌ No real-time validators
- ❌ No enterprise caching frameworks
- ❌ No complex service architectures
## Success Metrics
- ✅ All tools visible in Claude Desktop
- ✅ Multi-word search works
- ✅ No duplicate properties
- ✅ list_nodes and list_ai_tools return results
- ✅ Basic caching improves performance
## Code Changes Summary
1. **http-server-fixed.ts**: Add version endpoint (5 lines)
2. **server-update.ts**: Fix search (20 lines), add debug logs (2 lines)
3. **property-filter.ts**: Add deduplication (15 lines)
4. **New file: simple-cache.ts**: Basic cache (20 lines)
Total new code: ~62 lines
## Next Steps After MVP
Only after everything above works perfectly:
1. Monitor actual performance - add better caching IF needed
2. Collect user feedback on search - improve IF needed
3. Generate better docs for AI nodes IF users complain
But not before. Ship the fixes first.