purmemo-mcp 2.1.3 → 2.1.4

package/README.md

@@ -229,6 +229,66 @@ The following remain proprietary:
 - Workflow intelligence system
 - Performance optimization techniques
 
+## 🔧 Troubleshooting
+
+### Common Issues and Solutions
+
+#### "Server disconnected" or "Connection closed" errors
+This usually happens when the MCP server produces console output that interferes with the JSON protocol.
+
+**Solution**: Update to the latest version:
+```bash
+npx purmemo-mcp@latest setup
+```
+
+#### "Unexpected token" or "Unexpected end of JSON input" 
+This indicates console output is breaking the MCP protocol.
+
+**Quick fix**: Run diagnostics to identify the issue:
+```bash
+npx purmemo-mcp diagnose
+```
+
+#### Tools hang or timeout during authentication
+This happens when OAuth authentication blocks the MCP protocol.
+
+**Solution**: The latest version (2.1.3+) uses non-blocking authentication that returns helpful prompts instead of hanging.
+
+### Step-by-Step Debugging
+
+1. **Update to latest version**:
+   ```bash
+   npx purmemo-mcp@latest
+   ```
+
+2. **Run diagnostics**:
+   ```bash
+   npx purmemo-mcp diagnose
+   ```
+
+3. **Check Claude Desktop config**:
+   Ensure you're using `purmemo-mcp@^2.1.3` or later in your configuration:
+   ```json
+   {
+     "mcpServers": {
+       "purmemo": {
+         "command": "npx",
+         "args": ["-y", "purmemo-mcp@^2.1.3"],
+         "env": {
+           "PURMEMO_API_URL": "https://api.purmemo.ai",
+           "PURMEMO_OAUTH_CALLBACK_URL": "http://localhost:3456/callback",
+           "PURMEMO_FRONTEND_URL": "https://app.purmemo.ai"
+         }
+       }
+     }
+   }
+   ```
+
+4. **Restart Claude Desktop** completely:
+   - Quit with Cmd+Q (macOS) or close completely
+   - Reopen Claude Desktop
+   - Try connecting again
+
 ## 🆘 Support
 
 - 📧 Email: support@purmemo.ai

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "purmemo-mcp",
-  "version": "2.1.3",
+  "version": "2.1.4",
   "description": "Official Model Context Protocol (MCP) server for Purmemo - Seamless OAuth authentication for your AI-powered second brain",
   "main": "src/server-oauth.js",
   "type": "module",
@@ -19,8 +19,9 @@
     "setup": "node src/setup.js setup",
     "status": "node src/setup.js status",
     "logout": "node src/setup.js logout",
+    "diagnose": "node src/diagnose.js",
     "test": "echo \"No tests yet\"",
-    "postinstall": "node -e \"console.log('\\n🧠 pūrmemo MCP v2.0.0 installed!\\n\\nNew users: Run \\'npx purmemo-mcp setup\\' to connect your account.\\nExisting users: Your API key still works (backwards compatible).\\n')\""
+    "postinstall": "node -e \"console.log('\\n🧠 pūrmemo MCP v2.1.3 installed!\\n\\nNew users: Run \\'npx purmemo-mcp setup\\' to connect your account.\\nIf you have connection issues: Run \\'npx purmemo-mcp diagnose\\'\\n')\""
   },
   "keywords": [
     "mcp",

package/src/diagnose.js

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+/**
+ * Purmemo MCP Diagnostic Tool
+ * Helps users diagnose and fix common MCP connection issues
+ */
+
+import { spawn } from 'child_process';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+async function runDiagnostics() {
+    console.log('🔧 Purmemo MCP Diagnostic Tool');
+    console.log('================================\n');
+
+    // Test 1: Check if server starts without console output
+    console.log('1️⃣  Testing server startup (should be silent)...');
+    
+    const serverPath = join(__dirname, 'server-oauth.js');
+    const serverProcess = spawn('node', [serverPath], {
+        stdio: ['ignore', 'pipe', 'pipe']
+    });
+
+    let hasOutput = false;
+    let outputBuffer = '';
+
+    serverProcess.stdout.on('data', (data) => {
+        hasOutput = true;
+        outputBuffer += data.toString();
+    });
+
+    serverProcess.stderr.on('data', (data) => {
+        hasOutput = true;
+        outputBuffer += data.toString();
+    });
+
+    // Give server 2 seconds to start
+    await new Promise(resolve => setTimeout(resolve, 2000));
+    
+    if (hasOutput) {
+        console.log('❌ Server produces console output (will break MCP protocol)');
+        console.log('📝 Output detected:', outputBuffer.substring(0, 200) + '...');
+        console.log('🔧 This will cause "Unexpected token" errors in Claude Desktop');
+    } else {
+        console.log('✅ Server starts silently (MCP protocol compatible)');
+    }
+
+    serverProcess.kill();
+
+    // Test 2: Check package.json version
+    console.log('\n2️⃣  Checking package version...');
+    
+    try {
+        const packagePath = join(__dirname, '..', 'package.json');
+        const { readFile } = await import('fs/promises');
+        const packageData = JSON.parse(await readFile(packagePath, 'utf8'));
+        
+        if (packageData.version >= '2.1.3') {
+            console.log(`✅ Using fixed version: ${packageData.version}`);
+        } else {
+            console.log(`⚠️  Using old version: ${packageData.version}`);
+            console.log('🔧 Please update to version 2.1.3 or higher');
+        }
+    } catch (error) {
+        console.log('❌ Could not check package version:', error.message);
+    }
+
+    // Test 3: Check environment variables
+    console.log('\n3️⃣  Checking environment configuration...');
+    
+    const requiredEnvs = [
+        'PURMEMO_API_URL',
+        'PURMEMO_OAUTH_CALLBACK_URL', 
+        'PURMEMO_FRONTEND_URL'
+    ];
+
+    let envIssues = 0;
+    for (const env of requiredEnvs) {
+        if (process.env[env]) {
+            console.log(`✅ ${env}: ${process.env[env]}`);
+        } else {
+            console.log(`⚠️  ${env}: Not set (will use defaults)`);
+            envIssues++;
+        }
+    }
+
+    if (envIssues === 0) {
+        console.log('✅ All environment variables properly configured');
+    }
+
+    // Final recommendation
+    console.log('\n🎯 Final Diagnosis:');
+    
+    if (!hasOutput && envIssues === 0) {
+        console.log('✅ Your MCP server should work perfectly with Claude Desktop!');
+        console.log('📱 If you still have issues, try restarting Claude Desktop');
+    } else {
+        console.log('⚠️  Issues detected that may cause Claude Desktop connection failures');
+        console.log('🔧 Please address the issues above and run diagnostics again');
+    }
+
+    console.log('\n📚 For help: https://github.com/coladapo/purmemo-mcp/issues');
+}
+
+runDiagnostics().catch(console.error);