mcp-adr-analysis-server

# 🔌 How-To: MCP Client Compatibility **Goal**: Configure the MCP ADR Analysis Server to work seamlessly with any MCP-compatible AI assistant or IDE. **When to use this guide**: When you want to set up the MCP ADR Analysis Server with your preferred AI assistant (Claude Desktop, Cline, Cursor, Gemini, etc.) or IDE. --- ## 🎯 Quick Compatibility Matrix | AI Assistant/IDE | MCP Support | Config File | Command | Status | | ------------------ | ----------------- | ---------------------------- | ----------------------------- | ---------------- | | **Claude Desktop** | ✅ Native | `claude_desktop_config.json` | `mcp-adr-analysis-server` | **Recommended** | | **Cline** | ✅ Extension | `cline_mcp_settings.json` | `npx mcp-adr-analysis-server` | **Full Support** | | **Cursor** | ✅ Native | `.cursor/mcp.json` | `npx mcp-adr-analysis-server` | **Full Support** | | **Gemini** | ✅ Native | `gemini_mcp_config.json` | `mcp-adr-analysis-server` | **Full Support** | | **Continue.dev** | ✅ Extension | `.continue/config.json` | `npx mcp-adr-analysis-server` | **Full Support** | | **Aider** | ✅ Native | `.aider_config.yaml` | `mcp-adr-analysis-server` | **Full Support** | | **Windsurf** | ✅ Native | `mcp_config.json` | `mcp-adr-analysis-server` | **Full Support** | | **VS Code** | ✅ Via Extensions | Various | `npx mcp-adr-analysis-server` | **Full Support** | --- ## 🚀 Universal Setup Steps ### **Step 1: Install the Server** ```bash # Option 1: Global installation (recommended) npm install -g mcp-adr-analysis-server # Option 2: Local installation (for development) npm install mcp-adr-analysis-server ``` ### **Step 2: Verify Installation** ```bash # Test global installation mcp-adr-analysis-server --version # Test with npx npx mcp-adr-analysis-server --version # Test server functionality mcp-adr-analysis-server --test ``` ### **Step 3: Configure Environment Variables** ```bash # Set required environment variables export PROJECT_PATH="/absolute/path/to/your/project" export OPENROUTER_API_KEY="your_openrouter_api_key_here" export EXECUTION_MODE="full" # Optional: Enable Firecrawl for web research (recommended) export FIRECRAWL_ENABLED="true" export FIRECRAWL_API_KEY="fc-your-api-key-here" ``` ### **Step 4: Choose Your Client Configuration** Select the configuration that matches your preferred AI assistant or IDE: --- ## 🖥️ Claude Desktop (Recommended) **Best for**: General use, best AI integration, most stable ### Configuration Location - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` - **Linux**: `~/.config/Claude/claude_desktop_config.json` ### Basic Configuration ```json { "mcpServers": { "adr-analysis": { "command": "mcp-adr-analysis-server", "env": { "PROJECT_PATH": "/absolute/path/to/your/project", "OPENROUTER_API_KEY": "your_openrouter_api_key_here", "EXECUTION_MODE": "full", "FIRECRAWL_ENABLED": "true", "FIRECRAWL_API_KEY": "fc-your-api-key-here" } } } } ``` ### Advantages - ✅ Native MCP support - ✅ Best AI integration - ✅ Stable and reliable - ✅ Easy configuration --- ## 🔧 Cline (VS Code Extension) **Best for**: VS Code development, team collaboration ### Configuration Location **File**: `cline_mcp_settings.json` (in workspace or global settings) ### Basic Configuration ```json { "mcpServers": { "adr-analysis": { "command": "npx", "args": ["mcp-adr-analysis-server"], "env": { "PROJECT_PATH": "${workspaceFolder}", "OPENROUTER_API_KEY": "${env:OPENROUTER_API_KEY}", "EXECUTION_MODE": "full", "FIRECRAWL_ENABLED": "true", "FIRECRAWL_API_KEY": "${env:FIRECRAWL_API_KEY}" } } } } ``` ### Advantages - ✅ VS Code integration - ✅ Workspace-aware - ✅ Team-friendly - ✅ Environment variable support --- ## 🎯 Cursor **Best for**: AI-powered coding, modern development workflow ### Configuration Location **File**: `.cursor/mcp.json` (in project root) ### Basic Configuration ```json { "mcpServers": { "adr-analysis": { "command": "npx", "args": ["mcp-adr-analysis-server"], "env": { "PROJECT_PATH": ".", "OPENROUTER_API_KEY": "your_openrouter_api_key_here", "EXECUTION_MODE": "full" } } } } ``` ### Advantages - ✅ AI-native IDE - ✅ Built-in MCP support - ✅ Modern interface - ✅ Fast performance --- ## 🤖 Gemini (Google AI) **Best for**: Google AI ecosystem, multimodal capabilities ### Configuration Location **File**: `gemini_mcp_config.json` (in project root or user config directory) ### Basic Configuration ```json { "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": "google/gemini-pro-1.5" } } } } ``` ### Advantages - ✅ Google AI integration - ✅ Multimodal capabilities - ✅ Large context windows - ✅ Advanced reasoning --- ## 🔄 Continue.dev (VS Code Extension) **Best for**: VS Code users, open-source alternative ### Configuration Location **File**: `config.json` (in `.continue` directory) ### Basic Configuration ```json { "mcpServers": [ { "name": "adr-analysis", "command": "npx", "args": ["mcp-adr-analysis-server"], "env": { "PROJECT_PATH": "${workspaceFolder}", "OPENROUTER_API_KEY": "${env:OPENROUTER_API_KEY}", "EXECUTION_MODE": "full" } } ] } ``` ### Advantages - ✅ Open-source - ✅ VS Code integration - ✅ Extensible - ✅ Community-driven --- ## 🛠️ Aider (Command Line) **Best for**: Command-line users, automation, CI/CD ### Configuration Location **File**: `.aider_config.yaml` (in project root or home directory) ### Basic Configuration ```yaml mcp_servers: - name: 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' ``` ### Advantages - ✅ Command-line interface - ✅ Automation-friendly - ✅ CI/CD integration - ✅ Lightweight --- ## 🌊 Windsurf **Best for**: Professional development, enterprise features ### Configuration Location **File**: `~/.codeium/windsurf/mcp_config.json` ### Basic Configuration ```json { "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" } } } } ``` ### Advantages - ✅ Professional features - ✅ Enterprise support - ✅ Advanced AI capabilities - ✅ Performance optimized --- ## 🧪 Testing Your Configuration ### **Step 1: Test Server Installation** ```bash # Verify the server is installed and working mcp-adr-analysis-server --version mcp-adr-analysis-server --test ``` ### **Step 2: Test Client Connection** ```bash # Test with your specific client # For Claude Desktop: Restart Claude Desktop # For VS Code: Reload window # For Cursor: Restart Cursor ``` ### **Step 3: Verify Tools Availability** In your AI assistant, try: ``` "List the available MCP tools for ADR analysis" ``` Expected response should include tools like: - `analyze_project_ecosystem` - `generate_adrs_from_prd` - `analyze_content_security` - And 34+ other tools --- ## 🚨 Common Issues & Solutions ### **"Server not found" or "Unknown tool"** ```bash # Solution 1: Verify installation which mcp-adr-analysis-server npm list -g mcp-adr-analysis-server # Solution 2: Check PATH echo $PATH | grep -E "(node|npm)" # Solution 3: Restart your AI client ``` ### **"Permission denied" errors** ```json { "env": { "PROJECT_PATH": "/absolute/path/not/relative" } } ``` ### **"Tools return prompts instead of results"** ```json { "env": { "EXECUTION_MODE": "full", "OPENROUTER_API_KEY": "required_for_ai_features" } } ``` ### **"Command not found: npx"** ```bash # Install Node.js and npm # Then verify installation node --version npm --version ``` ### **Environment variables not working** ```bash # Check if variables are set echo $PROJECT_PATH echo $OPENROUTER_API_KEY # Set them in your shell profile export PROJECT_PATH="/absolute/path/to/project" export OPENROUTER_API_KEY="your_key_here" ``` --- ## 🔧 Advanced Configuration ### **Multi-Project Setup** ```json { "mcpServers": { "adr-frontend": { "command": "mcp-adr-analysis-server", "env": { "PROJECT_PATH": "/Users/username/frontend-project", "OPENROUTER_API_KEY": "your_key_here", "EXECUTION_MODE": "full", "ADR_DIRECTORY": "./adrs" } }, "adr-backend": { "command": "mcp-adr-analysis-server", "env": { "PROJECT_PATH": "/Users/username/backend-project", "OPENROUTER_API_KEY": "your_key_here", "EXECUTION_MODE": "full", "ADR_DIRECTORY": "architecture/decisions" } } } } ``` ### **Performance Optimization** ```json { "env": { "AI_CACHE_ENABLED": "true", "AI_CACHE_TTL": "3600", "MAX_FILES_PER_ANALYSIS": "500", "LOG_LEVEL": "WARN" } } ``` ### **Security Configuration** ```json { "env": { "ENABLE_CONTENT_MASKING": "true", "MASKING_LEVEL": "strict", "FIRECRAWL_ENABLED": "true", "FIRECRAWL_API_KEY": "your_firecrawl_key" } } ``` --- ## 📚 Further Reading - **[Complete MCP Client Configuration](../reference/mcp-client-config.md)** - Detailed configuration reference - **[Environment Configuration](../reference/environment-config.md)** - Environment variables guide - **[Installation Guide](./installation-guide.md)** - Complete installation instructions - **[Troubleshooting Guide](./troubleshooting.md)** - Common issues and solutions --- **Need help with a specific client?** → **[Join the Discussion](https://github.com/tosin2013/mcp-adr-analysis-server/issues)** **Having compatibility issues?** → **[Check Troubleshooting](./troubleshooting.md#mcp-client-compatibility)**