Skip to main content

🔧 How-To: Troubleshoot Common Issues

Goal: Solve problems quickly and get back to productive architecture analysis.

When to use this guide: When you encounter errors, unexpected behavior, or need to diagnose issues with the MCP ADR Analysis Server.

🔄 Troubleshooting Workflow​

🚨 Emergency Quick Fixes​

"Tool not found" or "Unknown tool" errors​

Problem: AI assistant can't find MCP tools
Quick Fix:

# 1. Verify server is installed
mcp-adr-analysis-server --version

# 2. Check server status
mcp-adr-analysis-server --test

# 3. Restart your MCP client

"Permission denied" errors​

Problem: Server can't read/write files
Quick Fix:

# 1. Check directory permissions
ls -la ./

# 2. Create missing directories
mkdir -p ./adrs

# 3. Fix permissions if needed
chmod 755 ./

AI seems confused or gives poor results​

Problem: Context degradation or AI confusion
Quick Fix:

{
  "tool": "troubleshoot_guided_workflow",
  "parameters": {
    "operation": "run_diagnostics"
  }
}

Server installed but nothing happens​

Problem: You installed the server but don't see any tools or analysis capabilities. Quick Fix: The MCP ADR Analysis Server is not a standalone application — it requires an MCP-compatible client to connect to it.

Install one of the following MCP clients:

  • Claude Desktop — Anthropic's desktop app with built-in MCP support
  • Cline — VS Code extension
  • Cursor — AI-powered code editor with MCP support
  • Windsurf — AI-powered IDE by Codeium

After installing a client, add the server to its MCP configuration (see Quick Setup).

🔍 Systematic Diagnosis​

Step 1: Verify Installation​

# Check Node.js version (should be ≥20.0.0)
node --version

# Check server installation
which mcp-adr-analysis-server
mcp-adr-analysis-server --version

# Test basic functionality
mcp-adr-analysis-server --test

Expected outputs:

  • Node.js: v20.x.x or higher
  • Server version: MCP ADR Analysis Server v2.1.0 (or current version)
  • Test: ✅ Server health check passed

Step 2: Validate Configuration​

Check your MCP client configuration:

{
  "mcpServers": {
    "adr-analysis": {
      "command": "mcp-adr-analysis-server",
      "env": {
        "PROJECT_PATH": "/absolute/path/to/project",
        "OPENROUTER_API_KEY": "your_openrouter_api_key_here",
        "EXECUTION_MODE": "full",
        "AI_MODEL": "anthropic/claude-3-sonnet",
        "ADR_DIRECTORY": "./adrs",
        "LOG_LEVEL": "DEBUG"
      }
    }
  }
}

Common configuration issues:

  • ❌ "PROJECT_PATH": "." (relative path)
  • ✅ "PROJECT_PATH": "/Users/you/project" (absolute path)
  • ❌ Missing OPENROUTER_API_KEY (required for AI features)
  • ❌ Missing EXECUTION_MODE (should be "full" for AI or "prompt-only" for basic)
  • ❌ Missing ADR_DIRECTORY
  • ❌ Wrong command name

Step 3: Test Basic Functionality​

Run this diagnostic sequence:

// 1. Test AI execution status
{
  "tool": "check_ai_execution_status"
}

// 2. Test file operations
{
  "tool": "list_directory",
  "parameters": {
    "path": "."
  }
}

// 3. Test analysis capabilities
{
  "tool": "analyze_project_ecosystem",
  "parameters": {
    "projectPath": ".",
    "recursiveDepth": "shallow"
  }
}

🐛 Specific Problem Solutions​

Analysis Returns Empty or Poor Results​

Symptoms:

  • "No architectural patterns detected"
  • "Project analysis incomplete"
  • Generic or unhelpful recommendations

Solution 1: Enhanced Analysis Mode

{
  "tool": "analyze_project_ecosystem",
  "parameters": {
    "projectPath": ".",
    "enhancedMode": true,
    "knowledgeEnhancement": true,
    "recursiveDepth": "comprehensive",
    "includeEnvironment": true
  }
}

Solution 2: Check Project Structure

# Ensure you have a proper project structure
ls -la
# Should see: package.json, src/, ./, etc.

# Check for hidden files that might indicate project type
ls -la | grep -E "\.(git|env|config)"

Solution 3: Verify Project Path

{
  "tool": "read_file",
  "parameters": {
    "path": "package.json"
  }
}

ADR Generation Fails​

Symptoms:

  • "Cannot generate ADR"
  • "Missing decision data"
  • Generated ADRs are incomplete

Solution 1: Use Structured Decision Data

{
  "tool": "generate_adr_from_decision",
  "parameters": {
    "decisionData": {
      "title": "Clear, specific decision title",
      "context": "Detailed background and problem statement",
      "decision": "Specific choice made",
      "rationale": "Why this decision was made",
      "consequences": ["Positive outcome 1", "Challenge 1", "Tradeoff 1"]
    }
  }
}

Solution 2: Get ADR Suggestions First

{
  "tool": "suggest_adrs",
  "parameters": {
    "projectPath": ".",
    "analysisScope": "all",
    "maxSuggestions": 5
  }
}

Tool Execution Hangs or Times Out​

Symptoms:

  • Tools never complete
  • Long delays without responses
  • Timeout errors

Solution 1: Check AI Service Status

{
  "tool": "check_ai_execution_status"
}

Solution 2: Use Simpler Operations

// Instead of comprehensive analysis, start with basic
{
  "tool": "analyze_project_ecosystem",
  "parameters": {
    "projectPath": ".",
    "recursiveDepth": "shallow",
    "enhancedMode": false
  }
}

Solution 3: Clear Cache

{
  "tool": "manage_cache",
  "parameters": {
    "action": "clear"
  }
}

Security Analysis Issues​

Symptoms:

  • "No sensitive content detected" (when you know there is some)
  • False positives in security scans
  • Content masking not working

Solution 1: Specify Content Type

{
  "tool": "analyze_content_security",
  "parameters": {
    "content": "your content here",
    "contentType": "code", // or "configuration", "logs", etc.
    "userDefinedPatterns": ["your-custom-pattern-.*"]
  }
}

Solution 2: Configure Custom Patterns

{
  "tool": "configure_custom_patterns",
  "parameters": {
    "projectPath": ".",
    "existingPatterns": ["api[_-]?key", "secret[_-]?token"]
  }
}

TODO/Progress Tracking Problems​

Symptoms:

  • TODO.md not generated
  • Progress tracking inaccurate
  • Tasks not syncing with ADRs

Solution 1: Regenerate TODO with Full Options

{
  "tool": "generate_adr_todo",
  "parameters": {
    "adrDirectory": "./adrs",
    "todoFormat": "both",
    "includePriorities": true,
    "includeTimestamps": true
  }
}

Solution 2: Verify ADR Directory

# Check ADR files exist
ls -la ././adrs/
# Should see .md files like 001-decision-name.md

# Check ADR format
head -20 ././adrs/001-*.md

Solution 3: Manual Progress Sync

{
  "tool": "compare_adr_progress",
  "parameters": {
    "todoPath": "TODO.md",
    "adrDirectory": "./adrs",
    "includeEnvironmentCheck": true
  }
}

🎯 Performance Optimization​

Slow Analysis Performance​

Problem: Tools take too long to complete
Solutions:

  1. Reduce Analysis Scope
{
  "tool": "analyze_project_ecosystem",
  "parameters": {
    "recursiveDepth": "medium", // instead of "comprehensive"
    "enhancedMode": false // for faster results
  }
}
  1. Use Targeted Analysis
// Instead of full project analysis, focus on specific areas
{
  "tool": "suggest_adrs",
  "parameters": {
    "analysisScope": "technology", // focus on just technology decisions
    "maxSuggestions": 3
  }
}
  1. Cache Management
// Clear old cache if it's causing slowdowns
{
  "tool": "manage_cache",
  "parameters": {
    "action": "cleanup"
  }
}

Memory Issues​

Problem: Server crashes or runs out of memory
Solutions:

  1. Process Large Projects in Chunks
# Instead of analyzing entire project at once
# Focus on subdirectories
  1. Increase Node.js Memory Limit
export NODE_OPTIONS="--max-old-space-size=4096"
mcp-adr-analysis-server

🔧 Advanced Diagnostics​

Enable Debug Logging​

// In your MCP client configuration
{
  "env": {
    "LOG_LEVEL": "DEBUG",
    "VERBOSE": "true"
  }
}

System Information Gathering​

{
  "tool": "analyze_environment",
  "parameters": {
    "includeOptimizations": true
  }
}

Cache Analysis​

{
  "tool": "manage_cache",
  "parameters": {
    "action": "stats"
  }
}

🆘 When All Else Fails​

Nuclear Options​

  1. Complete Reset
# Uninstall and reinstall
npm uninstall -g mcp-adr-analysis-server
npm install -g mcp-adr-analysis-server

# Clear all cache
rm -rf .mcp-adr-cache/
  1. Restart from Scratch
# Backup your work
cp -r ././adrs/ ~/backup-./adrs/

# Start fresh
rm -rf ./
mkdir -p ./adrs
  1. Environment Reset
# Clear environment variables
unset PROJECT_PATH ADR_DIRECTORY LOG_LEVEL

# Start with minimal configuration
export PROJECT_PATH="$(pwd)"
export ADR_DIRECTORY="./adrs"

Get Help​

  1. Check Server Health
{
  "tool": "troubleshoot_guided_workflow",
  "parameters": {
    "operation": "run_diagnostics"
  }
}
  1. Report Issues
  1. Community Support

Firecrawl Integration Issues​

Firecrawl is an optional dependency for web research capabilities. The server works perfectly without it.

"Firecrawl connection failed" or timeouts​

Problem: Web search tools return errors or hang. Solution:

# 1. Verify Firecrawl is enabled
echo $FIRECRAWL_ENABLED   # Should be "true"

# 2. Check API key (cloud service)
echo $FIRECRAWL_API_KEY    # Should start with "fc-"

# 3. Check connectivity (self-hosted)
curl "$FIRECRAWL_BASE_URL/health"

Missing Firecrawl environment variables​

Problem: You set FIRECRAWL_ENABLED=true but web search tools return empty results. Solution: Ensure you also set the API key:

export FIRECRAWL_ENABLED="true"
export FIRECRAWL_API_KEY="fc-your-api-key-here"

Do I need Firecrawl?​

No. Firecrawl is entirely optional. Without it, the server uses local-only analysis. Enable it only if you need web research capabilities for ADR generation. See the Firecrawl Setup Guide for details.

MCP Client Compatibility​

Issues specific to different MCP clients.

Claude Desktop not connecting​

Problem: Claude Desktop doesn't show MCP tools. Solution:

# 1. Verify config file location
# macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
# Windows: %APPDATA%\Claude\claude_desktop_config.json

# 2. Validate JSON syntax
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | python3 -m json.tool

# 3. Restart Claude Desktop completely (Cmd+Q on macOS, not just close window)

Cursor/Cline tools not appearing​

Problem: MCP tools don't show in VS Code-based clients. Solution:

  1. Check the MCP settings in your editor settings
  2. Reload the window (Cmd+Shift+P → "Reload Window")
  3. Check the Output panel for MCP-related errors

"Command not found" in MCP client​

Problem: The client can't find mcp-adr-analysis-server. Solution:

# 1. Use absolute path to the command
which mcp-adr-analysis-server
# Use this path in your config

# 2. Or use npx
{
  "command": "npx",
  "args": ["mcp-adr-analysis-server"]
}

For detailed client-specific setup, see the MCP Client Compatibility Guide.

✅ Prevention Tips​

Regular Maintenance​

# Weekly health check
mcp-adr-analysis-server --test

# Monthly cleanup
{
  "tool": "manage_cache",
  "parameters": {
    "action": "cleanup"
  }
}

Best Practices​

  1. Always use absolute paths in configuration
  2. Keep Node.js updated (≥20.0.0)
  3. Monitor disk space (cache can grow large)
  4. Backup ADRs regularly (they're valuable documentation!)

Problem not listed here? → File an Issue with detailed information about your problem.