MCP Troubleshooting Guide for @j0kz/mcp-agents

Systematic approach to diagnosing and resolving MCP tool issues.

When to Use This Skill

• Tools not appearing in editor after installation

• "Module not found" or import errors

• MCP servers not responding

• Commands not recognized by AI

• Config file issues

• Installation failures

• Cache-related problems

Evidence Base

Current State:

• README.md troubleshooting section with common issues

• Clear cache workflow (npm cache clean --force )

• Platform-specific config paths (Claude Code, Cursor, Windsurf, Qoder, VS Code, Roo)

• Installation validation steps

• 632+ tests for validation

Quick Fix (90% Success Rate)

The 3-minute solution that fixes most issues:

1. Clear npm cache

npm cache clean --force

2. Reinstall tools

npx @j0kz/mcp-agents@latest

3. Fully restart editor (close ALL windows)

4. Test by asking AI: "What MCP tools are available?"

Installation Guide

For complete platform-specific installation instructions:

cat .claude/skills/mcp-troubleshooting/references/installation-guide.md

Quick Install Verification

Check installation

ls -la ~/.config/claude/mcp-servers/ # Claude Code (Mac/Linux) ls -la ~/AppData/Roaming/Claude/mcp-servers/ # Claude Code (Windows)

Verify config exists

cat ~/.config/claude/mcp-servers-config.json # Mac/Linux cat ~/AppData/Roaming/Claude/mcp-servers-config.json # Windows

Test a tool directly

npx @j0kz/smart-reviewer@latest review test.ts

Platform Configuration

For detailed platform-specific configuration:

cat .claude/skills/mcp-troubleshooting/references/platform-config-guide.md

Config File Locations

Editor Mac/Linux Windows

Claude Code ~/.config/claude/

%APPDATA%\Claude\

Cursor ~/.cursor/

%APPDATA%\Cursor\

Windsurf ~/.windsurf/

%APPDATA%\Windsurf\

VS Code ~/.vscode/

%APPDATA%\Code\

Common Issues & Solutions

Issue 1: Tools Not Appearing

Symptoms: AI doesn't recognize MCP commands

Solution:

1. Check config file exists

cat ~/.config/claude/mcp-servers-config.json

2. Verify tools are listed

Should see 9 entries for @j0kz tools

3. Restart editor completely

Close ALL windows, not just reload

4. Ask AI to list tools

"What MCP tools are available?"

Issue 2: Module Not Found

Symptoms: Error: Cannot find module '@j0kz/...'

Solution:

1. Clear cache

npm cache clean --force

2. Remove old installations

rm -rf ~/.npm/_npx/ rm -rf node_modules/

3. Reinstall

npx @j0kz/mcp-agents@latest --force

4. Use @latest tag

npx @j0kz/smart-reviewer@latest # Always use @latest

Issue 3: Permission Denied

Symptoms: EACCES or permission errors

Solution:

Mac/Linux: Fix npm permissions

sudo chown -R $(whoami) ~/.npm sudo chown -R $(whoami) /usr/local/lib/node_modules

Windows: Run as Administrator

Right-click terminal → Run as Administrator

npx @j0kz/mcp-agents@latest

Issue 4: Config Not Updating

Symptoms: Old tools still showing after update

Solution:

1. Backup existing config

cp ~/.config/claude/mcp-servers-config.json ~/mcp-backup.json

2. Remove and reinstall

rm ~/.config/claude/mcp-servers-config.json npx @j0kz/mcp-agents@latest

3. Force restart editor

Task Manager → End all editor processes

Debugging Strategies

For comprehensive debugging approaches:

cat .claude/skills/mcp-troubleshooting/references/debugging-strategies.md

Debug Commands

Check npm global packages

npm list -g --depth=0

View npm cache

npm cache ls

Test specific tool version

npx @j0kz/smart-reviewer@1.0.36 --version

Enable verbose logging

DEBUG=* npx @j0kz/smart-reviewer@latest review test.ts

Check Node version (should be 18+)

node --version

Error Messages Explained

"Tool not found"

• Config file missing or corrupted

• Editor needs full restart

• Installation incomplete

"Cannot execute binary"

• Node.js version too old (need 18+)

• Platform mismatch (ARM vs x64)

• Corrupted npm cache

"ENOENT: no such file"

• Path in config is wrong

• Tool not installed properly

• Windows path escaping issue

"Timeout waiting for response"

• Tool crashed during execution

• Memory limit exceeded

• Infinite loop in code being analyzed

Advanced Troubleshooting

Manual Config Edit

// Example mcp-servers-config.json entry { "@j0kz/smart-reviewer": { "command": "npx", "args": ["@j0kz/smart-reviewer-mcp@latest"], "description": "Smart code review with auto-fix" } }

Environment Variables

Set Node memory limit

export NODE_OPTIONS="--max-old-space-size=4096"

Enable debug output

export DEBUG=mcp:*

Use specific npm registry

export NPM_CONFIG_REGISTRY=https://registry.npmjs.org/

Network Issues

Behind proxy

npm config set proxy http://proxy.company.com:8080 npm config set https-proxy http://proxy.company.com:8080

Clear proxy

npm config delete proxy npm config delete https-proxy

Use different registry

npm config set registry https://registry.npmjs.org/

Recovery Procedures

Complete Reset

1. Backup config

cp ~/.config/claude/mcp-servers-config.json ~/backup-mcp.json

2. Clean everything

npm cache clean --force rm -rf ~/.npm/_npx/ rm ~/.config/claude/mcp-servers-config.json

3. Fresh install

npx @j0kz/mcp-agents@latest

4. Restart editor

Rollback to Previous Version

If latest version has issues

npx @j0kz/mcp-agents@1.0.35 # Use specific version

Or install globally

npm install -g @j0kz/mcp-agents@1.0.35

Getting Help

Self-Diagnosis

Run health check

npx @j0kz/mcp-agents@latest --health

Version info

npx @j0kz/mcp-agents@latest --version

List installed tools

cat ~/.config/claude/mcp-servers-config.json | grep "@j0kz"

Report Issues

If problems persist:

• Check GitHub Issues: https://github.com/j0KZ/mcp-agents/issues

• Include:

• Error message (full text)

• Platform (OS, Node version)

• Editor (Claude Code, Cursor, etc.)

• Steps to reproduce

• Config file contents

Prevention Tips

• Always use @latest tag in commands

• Fully restart editor after config changes

• Keep Node.js updated (v18+ required)

• Clear cache periodically if issues arise

• Don't edit config while editor is running

• Use one editor at a time for MCP tools

• Check firewall/antivirus isn't blocking npm

Quick Test: After troubleshooting, ask AI: "Use smart-reviewer to analyze a TypeScript file"