feat(conversation-memory): improve MCP installation error handling

[baleen37]

Summary

• Automatic dependency installation with bundled wrapper
• Improved error messages with actionable fixes
• Comprehensive troubleshooting documentation

Changes

1. Auto-install dependencies via bundled wrapper (#1: 8b60373)

Problem: Users had to manually run npm install before using the plugin, causing friction.

Solution:

• Created mcp-server-wrapper.mjs that checks and installs dependencies automatically
• Updated .mcp.json to use wrapper instead of direct server execution
• Wrapper handles:
  • Node_modules existence check
  • Automatic npm install on first run
  • Build detection and automatic rebuild when needed
  • Signal forwarding for graceful shutdown

Benefits:

• Zero-friction first-run experience
• Automatic version updates (rebuilds when package.json changes)
• Cross-platform compatibility (Windows, macOS, Linux)

2. Improve MCP installation error messages (#2: 3ba59a8)

Problem: When installation fails, users only see "exit code 1" without knowing what went wrong.

Solution:

• Added stderr capture in runNpmInstall() and runBuild()
• Error pattern analysis for common issues:
  • Permission denied (EACCES): Shows sudo chown -R $(whoami) ~/.npm
  • Disk space full (ENOSPC): Guides user to free up space
  • Network errors (ETIMEDOUT, ECONNRESET, ENOTFOUND): Suggests checking connection
• Added Troubleshooting section to README with detailed solutions

Benefits:

• Users can self-diagnose and fix issues
• Reduced support burden
• Clear, actionable error messages

Modified Files

File	Lines Changed	Description
plugins/conversation-memory/.mcp.json	+1/-1	Use wrapper instead of direct server
plugins/conversation-memory/scripts/mcp-server-wrapper.mjs	+205	Auto-install wrapper with error handling
plugins/conversation-memory/scripts/build.mjs	+6/-4	Bundle wrapper to dist/
plugins/conversation-memory/dist/mcp-wrapper.mjs	+205	Bundled wrapper
plugins/conversation-memory/README.md	+64	Troubleshooting documentation
plugins/conversation-memory/dist/*.mjs	~450	Rebuilt bundles

Test Plan

• Clean install test: rm -rf node_modules && node dist/mcp-wrapper.mjs
• Build verification: npm run build
• Error message validation (manual testing needed for real errors)

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Enhanced error diagnostics for installation and build failures, including specific detection and recovery guidance for permission issues, disk space constraints, and network errors.

• Documentation

  • Expanded troubleshooting section with detailed guidance for common installation errors.
  • Added manual installation instructions and comprehensive architecture documentation.

[coderabbitai]

📝 Walkthrough

Walkthrough

Updated the conversation-memory plugin's MCP server wrapper distribution workflow by changing the entrypoint path in configuration, adding a build step to copy the wrapper to the dist directory, and enhancing the wrapper script with improved error diagnostics for installation and build failures.

Changes

Cohort / File(s)	Summary
Configuration Update plugins/conversation-memory/.mcp.json	Updated MCP server entrypoint path from scripts/mcp-server-wrapper.mjs to dist/mcp-wrapper.mjs.
Documentation plugins/conversation-memory/README.md	Added comprehensive Troubleshooting section covering EACCES, ENOSPC, and network timeout errors with fixes and manual installation steps. Expanded Architecture Notes with storage location, naming conventions, and embedding model specifications.
Build Process plugins/conversation-memory/scripts/build.mjs	Enhanced build script to copy wrapper from scripts/mcp-server-wrapper.mjs to dist/mcp-wrapper.mjs after CLI build using copyFile.
Error Handling & Diagnostics plugins/conversation-memory/scripts/mcp-server-wrapper.mjs	Added stderr output accumulation and enhanced error analysis for install/build failures, detecting and reporting permission (EACCES), disk space (ENOSPC), and network issues (ETIMEDOUT, ECONNRESET, ENOTFOUND) with actionable remediation guidance.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• fix(conversation-memory): include built dist files in git #351 — Updates the conversation-memory plugin's dist artifacts and entrypoints to ensure built wrapper files are included in the repository distribution.

Suggested labels

enhancement

Poem

🐰 A wrapper finds its way to dist,
With errors now diagnosed, not missed.
Build steps copy, docs expand,
Better troubleshooting takes a stand! ✨

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 66.67% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main objective of the PR: improving MCP installation error handling through enhanced error detection and user-friendly messages.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch fix/memory

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@plugins/conversation-memory/README.md`:
- Around line 329-357: The markdown has fenced code blocks inside numbered lists
without blank lines which trips the linter; update the README.md sections around
the "Try installing manually:" list item and the "Disk Space Full (ENOSPC)"
section to insert a blank line before each opening ```bash fence and a blank
line after each closing ``` fence (e.g., the npm proxy block, the manual install
block, and the npm cache / node_modules blocks) so the code fences are separated
from list text and headings; ensure the numbered list numbers and the "Disk
Space Full (ENOSPC)" heading remain unchanged while only adding the blank lines
around the triple-backtick blocks.

🧹 Nitpick comments (2)

plugins/conversation-memory/scripts/mcp-server-wrapper.mjs (2)

27-64: Error analysis logic looks good, minor cross-platform consideration.

The stderr capture and error pattern analysis provide helpful diagnostics. Two observations:

1. The EACCES fix (sudo chown -R $(whoami) ~/.npm) is Unix-specific. On Windows, this message won't help users.
2. When no pattern matches, users get no cause/fix guidance—consider adding a generic fallback.

💡 Optional: Add platform-aware messaging and fallback

         // Analyze error cause
         if (stderrOutput.includes('EACCES') || stderrOutput.includes('permission denied')) {
           console.error('Cause: Permission denied');
-          console.error('Fix: sudo chown -R $(whoami) ~/.npm');
+          if (process.platform === 'win32') {
+            console.error('Fix: Run terminal as Administrator');
+          } else {
+            console.error('Fix: sudo chown -R $(whoami) ~/.npm');
+          }
         } else if (stderrOutput.includes('ENOSPC')) {
           console.error('Cause: Disk space full');
           console.error('Fix: Free up disk space');
         } else if (/ETIMEDOUT|ECONNRESET|ENOTFOUND/i.test(stderrOutput)) {
           console.error('Cause: Network error');
           console.error('Fix: Check internet connection and retry');
+        } else {
+          console.error('Cause: See error output above');
         }

---

106-119: Duplicated error analysis; network check less relevant for builds.

This error analysis block is identical to the one in runNpmInstall. Consider extracting a shared helper. Also, network errors (ETIMEDOUT, ECONNRESET, ENOTFOUND) are unlikely during npm run build since builds typically don't fetch packages—this check may confuse users if it matches unrelated error text.

♻️ Extract shared error analysis helper

+function analyzeAndLogError(stderrOutput, context) {
+  if (stderrOutput.includes('EACCES') || stderrOutput.includes('permission denied')) {
+    console.error('Cause: Permission denied');
+    console.error('Fix: sudo chown -R $(whoami) ~/.npm');
+  } else if (stderrOutput.includes('ENOSPC')) {
+    console.error('Cause: Disk space full');
+    console.error('Fix: Free up disk space');
+  } else if (context === 'install' && /ETIMEDOUT|ECONNRESET|ENOTFOUND/i.test(stderrOutput)) {
+    console.error('Cause: Network error');
+    console.error('Fix: Check internet connection and retry');
+  }
+}

Then call analyzeAndLogError(stderrOutput, 'install') in runNpmInstall and analyzeAndLogError(stderrOutput, 'build') in runBuild.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Fix markdown formatting: add blank lines around fenced code blocks.

The linter flagged missing blank lines around code blocks in numbered lists (lines 331-334, 336, 349-353). This can cause rendering issues in some markdown parsers.

📝 Proposed fix for markdown formatting

 1. Check your internet connection
 2. If behind a corporate firewall, configure npm proxy:
+
    ```bash
    npm config set proxy http://your-proxy:port
    npm config set https-proxy http://your-proxy:port
    ```
+
 3. Try installing manually:
+
    ```bash
    cd plugins/conversation-memory
    npm install
    ```
+
 
 #### Disk Space Full (ENOSPC)
 
 **Symptoms:** Error messages containing "ENOSPC"
 
 **Fix:**
 
 1. Check available disk space: `df -h`
 2. Free up space by cleaning npm cache:
+
    ```bash
    npm cache clean --force
    ```
+
 3. Remove old node_modules:
+
    ```bash
    cd plugins/conversation-memory
    rm -rf node_modules
    npm install
    ```

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	1. Check your internet connection
	2. If behind a corporate firewall, configure npm proxy:
	```bash
	npm config set proxy http://your-proxy:port
	npm config set https-proxy http://your-proxy:port
	```
	3. Try installing manually:
	```bash
	cd plugins/conversation-memory
	npm install
	```
	#### Disk Space Full (ENOSPC)
	**Symptoms:** Error messages containing "ENOSPC"
	**Fix:**
	1. Check available disk space: `df -h`
	2. Free up space by cleaning npm cache:
	```bash
	npm cache clean --force
	```
	3. Remove old node_modules:
	```bash
	cd plugins/conversation-memory
	rm -rf node_modules
	npm install
	```
	1. Check your internet connection
	2. If behind a corporate firewall, configure npm proxy:

🧰 Tools

🪛 markdownlint-cli2 (0.20.0)

[warning] 331-331: Fenced code blocks should be surrounded by blank lines

(MD031, blanks-around-fences)

---

[warning] 334-334: Fenced code blocks should be surrounded by blank lines

(MD031, blanks-around-fences)

---

[warning] 336-336: Fenced code blocks should be surrounded by blank lines

(MD031, blanks-around-fences)

---

[warning] 349-349: Fenced code blocks should be surrounded by blank lines

(MD031, blanks-around-fences)

---

[warning] 351-351: Fenced code blocks should be surrounded by blank lines

(MD031, blanks-around-fences)

---

[warning] 353-353: Fenced code blocks should be surrounded by blank lines

(MD031, blanks-around-fences)

🤖 Prompt for AI Agents

In `@plugins/conversation-memory/README.md` around lines 329 - 357, The markdown
has fenced code blocks inside numbered lists without blank lines which trips the
linter; update the README.md sections around the "Try installing manually:" list
item and the "Disk Space Full (ENOSPC)" section to insert a blank line before
each opening ```bash fence and a blank line after each closing ``` fence (e.g.,
the npm proxy block, the manual install block, and the npm cache / node_modules
blocks) so the code fences are separated from list text and headings; ensure the
numbered list numbers and the "Disk Space Full (ENOSPC)" heading remain
unchanged while only adding the blank lines around the triple-backtick blocks.