mcp-adr-analysis-server

# 📦 MCP ADR Analysis Server Installation Guide **Complete installation guide for all environments and use cases** > **Version**: 2.1.0 | **Node.js**: ≥20.0.0 | **NPM**: ≥9.0.0 --- ## 📖 Table of Contents 1. [Quick Installation](#quick-installation) 2. [System Requirements](#system-requirements) 3. [Installation Methods](#installation-methods) 4. [MCP Client Configuration](#mcp-client-configuration) 5. [Environment Setup](#environment-setup) 6. [Verification](#verification) 7. [Troubleshooting](#troubleshooting) 8. [Uninstallation](#uninstallation) --- ## ⚡ Quick Installation ### For Most Users (NPM Global Install) ```bash # Install globally from NPM npm install -g mcp-adr-analysis-server@2.1.0 # Verify installation mcp-adr-analysis-server --version # Expected: MCP ADR Analysis Server v2.1.0 # Quick health check mcp-adr-analysis-server --test # Expected: ✅ Health check passed ``` ### For AI Assistants (MCP Client Setup) Add to your MCP client configuration: ```json { "mcpServers": { "adr-analysis": { "command": "mcp-adr-analysis-server", "env": { "PROJECT_PATH": "/path/to/your/project", "OPENROUTER_API_KEY": "your_api_key_here", "EXECUTION_MODE": "full" } } } } ``` --- ## 🖥️ System Requirements ### Minimum Requirements - **Operating System**: macOS, Linux, Windows (WSL2 recommended) - **Node.js**: ≥20.0.0 (LTS recommended) - **NPM**: ≥9.0.0 - **Memory**: 2GB RAM minimum, 4GB+ recommended - **Storage**: 500MB free space (1GB+ for development) - **Network**: Internet access for AI API calls ### Recommended Requirements - **Node.js**: Latest LTS (20.x) - **Memory**: 8GB+ RAM for large projects - **Storage**: 2GB+ free space - **CPU**: Multi-core processor for parallel analysis ### Platform-Specific Notes #### macOS ```bash # Install Node.js via Homebrew (recommended) brew install node@20 # Verify installation node --version # Should be ≥20.0.0 npm --version # Should be ≥9.0.0 ``` #### Linux (Ubuntu/Debian) ```bash # Install Node.js 20.x curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt-get install -y nodejs # Verify installation node --version npm --version ``` #### RHEL/CentOS/Fedora ```bash # Use the special RHEL installer curl -sSL https://raw.githubusercontent.com/tosin2013/mcp-adr-analysis-server/main/scripts/install-rhel.sh | bash ``` #### Windows ```powershell # Install Node.js from official website or use Chocolatey choco install nodejs --version=20.0.0 # Or use Windows Package Manager winget install OpenJS.NodeJS ``` --- ## 🔧 Installation Methods ### Method 1: NPM Global Installation (Recommended) **Best for**: Most users, AI assistants, production use ```bash # Install latest stable version npm install -g mcp-adr-analysis-server # Install specific version npm install -g mcp-adr-analysis-server@2.1.0 # Verify installation which mcp-adr-analysis-server mcp-adr-analysis-server --version ``` **Pros**: - Simple installation - Available system-wide - Automatic PATH configuration - Easy updates **Cons**: - Requires global npm permissions - Single version per system ### Method 2: Local Project Installation **Best for**: Project-specific usage, development teams ```bash # Navigate to your project cd /path/to/your/project # Install locally npm install mcp-adr-analysis-server@2.1.0 # Run via npx npx mcp-adr-analysis-server --version # Or add to package.json scripts echo '{"scripts": {"adr": "mcp-adr-analysis-server"}}' >> package.json npm run adr -- --version ``` ### Method 3: Development Installation (From Source) **Best for**: Contributors, advanced users, custom modifications ```bash # Clone repository git clone https://github.com/tosin2013/mcp-adr-analysis-server.git cd mcp-adr-analysis-server # Install dependencies npm install # Build from source npm run build # Run tests to verify npm test # Link globally (optional) npm link # Verify development installation mcp-adr-analysis-server --version ``` ### Method 4: Docker Installation **Best for**: Containerized environments, CI/CD pipelines ```bash # Pull Docker image (when available) docker pull tosin2013/mcp-adr-analysis-server:2.1.0 # Run in container docker run -it --rm \ -v $(pwd):/workspace \ -e OPENROUTER_API_KEY=your_key \ tosin2013/mcp-adr-analysis-server:2.1.0 \ analyze_project_ecosystem --projectPath=/workspace ``` --- ## 🤖 MCP Client Configuration ### Claude Desktop ```json // ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) // %APPDATA%\Claude\claude_desktop_config.json (Windows) { "mcpServers": { "adr-analysis": { "command": "mcp-adr-analysis-server", "env": { "PROJECT_PATH": "/Users/username/projects/my-project", "OPENROUTER_API_KEY": "sk-or-v1-...", "EXECUTION_MODE": "full", "LOG_LEVEL": "info" } } } } ``` ### Cline (VS Code Extension) ```json // .vscode/settings.json { "cline.mcpServers": { "adr-analysis": { "command": "mcp-adr-analysis-server", "env": { "PROJECT_PATH": "${workspaceFolder}", "OPENROUTER_API_KEY": "${env:OPENROUTER_API_KEY}", "EXECUTION_MODE": "full" } } } } ``` ### Cursor ```json // Cursor Settings > MCP Servers { "mcp.servers": { "adr-analysis": { "command": "mcp-adr-analysis-server", "args": [], "env": { "PROJECT_PATH": "/path/to/project", "OPENROUTER_API_KEY": "your_key", "EXECUTION_MODE": "full" } } } } ``` ### Windsurf ```json // Windsurf MCP Configuration { "mcpServers": { "adr-analysis": { "command": "mcp-adr-analysis-server", "env": { "PROJECT_PATH": "${workspaceRoot}", "OPENROUTER_API_KEY": "${OPENROUTER_API_KEY}", "EXECUTION_MODE": "full", "ENHANCED_MODE": "true" } } } } ``` --- ## 🌍 Environment Setup ### Required Environment Variables ```bash # Core Configuration export OPENROUTER_API_KEY="sk-or-v1-your-api-key-here" export PROJECT_PATH="/path/to/your/project" export EXECUTION_MODE="full" # Optional Configuration export ADR_DIRECTORY="./adrs" export LOG_LEVEL="info" export CACHE_ENABLED="true" export ENHANCED_MODE="true" export KNOWLEDGE_ENHANCEMENT="true" ``` ### Environment File Setup Create `.env` file in your project: ```bash # .env file for MCP ADR Analysis Server OPENROUTER_API_KEY=sk-or-v1-your-api-key-here PROJECT_PATH=/absolute/path/to/your/project EXECUTION_MODE=full ADR_DIRECTORY=./adrs LOG_LEVEL=info CACHE_ENABLED=true ENHANCED_MODE=true KNOWLEDGE_ENHANCEMENT=true MASKING_STRATEGY=partial SECURITY_SCAN_ENABLED=true ``` ### API Key Setup #### Get OpenRouter API Key 1. Visit [OpenRouter.ai](https://openrouter.ai/keys) 2. Sign up or log in 3. Create a new API key 4. Copy the key (starts with `sk-or-v1-`) #### Secure API Key Storage ```bash # Method 1: Environment variable (recommended) echo 'export OPENROUTER_API_KEY="sk-or-v1-your-key"' >> ~/.bashrc source ~/.bashrc # Method 2: .env file (project-specific) echo 'OPENROUTER_API_KEY=sk-or-v1-your-key' >> .env # Method 3: System keychain (macOS) security add-generic-password -a $USER -s openrouter-api -w "sk-or-v1-your-key" ``` --- ## ✅ Verification ### Basic Verification ```bash # 1. Check installation mcp-adr-analysis-server --version # Expected: MCP ADR Analysis Server v2.1.0 # 2. Verify configuration mcp-adr-analysis-server --config # Expected: Configuration summary # 3. Run health check mcp-adr-analysis-server --test # Expected: ✅ Health check passed - server can start successfully # 4. Check available tools mcp-adr-analysis-server --help # Expected: Usage information and available commands ``` ### Advanced Verification ```bash # Test MCP protocol functionality echo '{"method":"tools/list"}' | mcp-adr-analysis-server # Expected: JSON response with available tools # Test AI integration (requires API key) mcp-adr-analysis-server --test-ai # Expected: ✅ AI integration working # Test project analysis cd /path/to/test/project mcp-adr-analysis-server analyze_project_ecosystem # Expected: Project analysis results ``` ### MCP Client Verification #### Claude Desktop 1. Restart Claude Desktop after configuration 2. Look for "MCP" indicator in the interface 3. Try prompting: "What MCP tools are available?" 4. Expected: List including ADR analysis tools #### VS Code/Cline 1. Reload VS Code window 2. Open Command Palette (Cmd/Ctrl+Shift+P) 3. Look for "Cline: MCP" commands 4. Test with: "Analyze this project's architecture" --- ## 🔧 Troubleshooting ### Common Installation Issues #### 1. Permission Denied (EACCES) ```bash # Fix npm permissions sudo chown -R $(whoami) $(npm config get prefix)/{lib/node_modules,bin,share} # Or use npm's built-in fix npm config set prefix ~/.npm-global echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc source ~/.bashrc ``` #### 2. Node.js Version Issues ```bash # Check current version node --version # Install correct version via nvm curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash nvm install 20 nvm use 20 ``` #### 3. Command Not Found ```bash # Check if globally installed npm list -g mcp-adr-analysis-server # Check PATH echo $PATH # Reinstall if needed npm uninstall -g mcp-adr-analysis-server npm install -g mcp-adr-analysis-server@2.1.0 ``` #### 4. API Key Issues ```bash # Verify API key format echo $OPENROUTER_API_KEY | grep "sk-or-v1-" # Test API key curl -H "Authorization: Bearer $OPENROUTER_API_KEY" \ https://openrouter.ai/api/v1/auth/key ``` #### 5. Tree-sitter Parser Issues ```bash # Tree-sitter parsers may fail to load (non-critical) # Server will fall back to regex analysis # Check logs for warnings: mcp-adr-analysis-server --test 2>&1 | grep -i "tree-sitter" ``` ### Platform-Specific Issues #### macOS ```bash # Fix Xcode command line tools xcode-select --install # Fix Homebrew permissions sudo chown -R $(whoami) /usr/local/lib/node_modules ``` #### Linux ```bash # Fix build tools sudo apt-get install build-essential # Fix node-gyp issues npm config set python python3 ``` #### Windows ```powershell # Install Windows Build Tools npm install -g windows-build-tools # Fix path issues refreshenv ``` ### Getting Help If you encounter issues: 1. **Check Logs**: Run with `DEBUG=* mcp-adr-analysis-server` 2. **GitHub Issues**: [Report bugs](https://github.com/tosin2013/mcp-adr-analysis-server/issues) 3. **Documentation**: [Troubleshooting Guide](./troubleshooting.md) 4. **Community**: [Discussions](https://github.com/tosin2013/mcp-adr-analysis-server/issues) --- ## 🗑️ Uninstallation ### Remove Global Installation ```bash # Uninstall globally npm uninstall -g mcp-adr-analysis-server # Verify removal which mcp-adr-analysis-server # Expected: command not found ``` ### Remove Local Installation ```bash # Remove from project npm uninstall mcp-adr-analysis-server # Remove from package.json npm uninstall --save mcp-adr-analysis-server ``` ### Clean Up Configuration ```bash # Remove MCP client configurations # Claude Desktop rm ~/Library/Application\ Support/Claude/claude_desktop_config.json # Remove environment variables # Edit ~/.bashrc, ~/.zshrc, etc. and remove OPENROUTER_API_KEY lines # Clear npm cache npm cache clean --force ``` ### Remove Development Installation ```bash # If installed from source cd mcp-adr-analysis-server npm unlink # If linked globally rm -rf node_modules cd .. rm -rf mcp-adr-analysis-server ``` --- ## 🔄 Updates and Maintenance ### Updating to Latest Version ```bash # Update global installation npm update -g mcp-adr-analysis-server # Or reinstall specific version npm install -g mcp-adr-analysis-server@latest # Verify update mcp-adr-analysis-server --version ``` ### Checking for Updates ```bash # Check current version npm list -g mcp-adr-analysis-server # Check latest available version npm view mcp-adr-analysis-server version # Check outdated packages npm outdated -g ``` --- ## 📚 Next Steps After successful installation: 1. **📖 Read the [Prompting Guide](./prompting-guide.md)** - Learn effective prompting techniques 2. **🔧 Configure Your Environment** - Set up project-specific settings 3. **🚀 Try the [Quick Start Tutorial](../tutorials/01-first-steps.md)** - Get hands-on experience 4. **📋 Review [API Reference](../reference/api-reference.md)** - Explore available tools 5. **🤝 Join the Community** - Contribute and get support --- **🎉 Congratulations! Your MCP ADR Analysis Server is ready to use.** _This installation guide follows methodological pragmatism with systematic verification steps and explicit acknowledgment of platform-specific requirements and limitations._