[Bug]: MCP Server fails to start in Claude Desktop Cowork environment (better-sqlite3 native compilation blocked)

[kevintseng]

Component

MCP Server

Bug Description

[Bug] MCP Server fails to start in Claude Desktop Cowork environment (better-sqlite3 native compilation blocked)

Summary

MeMesh plugin (v2.8.10) installs successfully in Claude Desktop's Cowork mode but the MCP server cannot start because better-sqlite3 requires native compilation via node-gyp, which is blocked by two sandbox restrictions:

1. Read-only filesystem — .claude-plugin/memesh/ is mounted as read-only, preventing npm install from creating node_modules/
2. Network restriction — even when copied to a writable directory, node-gyp cannot download Node.js headers from nodejs.org (returns HTTP 403)

As a result, all memesh MCP tools are unavailable in Cowork sessions.

Environment

Item	Value
Plugin version	2.8.10
Platform	Claude Desktop — Cowork mode
OS (sandbox)	Ubuntu 22.04 LTS, ARM64 (aarch64)
Node.js	v22.22.0
npm	installed
Build tools	gcc, g++, make, python3 — all present

Steps to Reproduce

1. Install @pcircle/memesh plugin in Claude Desktop Cowork mode
2. Start a new Cowork session
3. Attempt to use any memesh MCP tool (e.g., buddy-remember, buddy-record-mistake)

Expected: MCP tools are available and functional.
Actual: No memesh MCP tools appear in the tool list. The MCP server fails to initialize because better-sqlite3 has no compiled native bindings.

Error Output

MeMesh Version

2.8.10

Claude Code Client

Other

Node.js Version

v20.0.0

Operating System

macOS

MCP Configuration

Additional Context

No response

[kevintseng]

🔄 Partially Addressed - PR #78 (Phase 1 Complete)

This issue is being addressed in multiple phases. Phase 1 (lazy loading) provides the foundation and error handling.

✅ Phase 1 Complete (PR #78)

What's Fixed:

1. ✅ No more silent crashes - MCP server provides clear error instead of failing silently
2. ✅ Helpful diagnostics - Error messages now explain exactly what went wrong
3. ✅ Fallback suggestions - Users get actionable next steps:

   Cannot create ConnectionPool: better-sqlite3 is unavailable.
   Error: Cannot find module 'better-sqlite3'
   Suggestion: Use Cloud-only mode with MEMESH_API_KEY
   

4. ✅ Adapter Pattern - Infrastructure ready for multiple SQLite backends

Error Handling (Before vs After):

Before ❌:

[MCP Server crashes silently]
- No error message visible
- All memesh tools disappear
- User has no idea what went wrong

After ✅:

Error: Cannot create ConnectionPool: better-sqlite3 is unavailable.
Error: The module was compiled against a different Node.js version
Suggestion: Run: npm rebuild better-sqlite3
  OR: Use Cloud-only mode by setting MEMESH_API_KEY environment variable

🔜 Phase 2: Cloud-Only Fallback Mode (Next PR)

What Will Be Fixed:

• ⏳ Automatic fallback to cloud mode when MEMESH_API_KEY is set
• ⏳ MCP server starts successfully even without better-sqlite3
• ⏳ Reduced functionality (memory API uses cloud instead of local SQLite)

Implementation Plan:

// Detect available modes on startup
const hasSQLite = await checkBetterSqlite3Availability();
const hasCloudAPI = !!process.env.MEMESH_API_KEY;

if (!hasSQLite && !hasCloudAPI) {
  throw new Error('No storage backend available. Set MEMESH_API_KEY for cloud mode.');
}

if (!hasSQLite && hasCloudAPI) {
  logger.warn('Running in Cloud-only mode - local memory features disabled');
  // Initialize with CloudMemoryAdapter instead
}

🔮 Phase 3: sql.js Fallback (Future)

What Will Be Fixed:

• Pure JavaScript SQLite via WebAssembly
• No native compilation required
• Works in any environment (even browsers)

Current Status for Cowork Environment

With Phase 1 (Current):

# In Cowork session
$ memesh --version
Error: Cannot create ConnectionPool: better-sqlite3 is unavailable.
Suggestion: Use Cloud-only mode with MEMESH_API_KEY

# Workaround until Phase 2:
$ export MEMESH_API_KEY="your-api-key"
$ memesh --version  # Will work after Phase 2 implementation

After Phase 2 (Next PR):

# In Cowork session with API key
$ export MEMESH_API_KEY="your-api-key"
$ memesh --version
2.8.11 (Cloud-only mode)

# MCP tools available:
- buddy-remember ✅ (uses cloud API)
- buddy-help ✅
- buddy-do ✅ (limited - no local memory)

Testing Phase 1 Changes

To verify Phase 1 improvements in your environment:

# 1. Update to latest version (after PR #78 merges)
npm install -g @pcircle/memesh@latest

# 2. Try to start - you should now see clear error
memesh --version

# Expected output:
# Error: better-sqlite3 is unavailable
# Suggestion: Use Cloud-only mode with MEMESH_API_KEY

Timeline

• ✅ Phase 1 (Lazy Loading) - Completed in PR fix: implement graceful degradation for native module failures (Phase 1) #78
• 🔜 Phase 2 (Cloud-only mode) - Next 1-2 weeks
• 🔮 Phase 3 (sql.js fallback) - Future enhancement

---

Keeping this issue open until Phase 2 provides full Cloud-only mode support for Cowork environment. 📋