MCP分析服务器

Prerequisites

Before installing, verify you have:

node --version  # Should show v20.0.0 or higher
npm --version   # Should show 9.0.0 or higher (included with Node.js 20+)

Required:

• Node.js 20.0.0 or higher — Download or use nvm/fnm
• npm 9.0.0 or higher (included with Node.js 20+)
• An MCP-compatible client — Claude Desktop, Cline, Cursor, or Windsurf

Network Requirements

• Internet access required during npm install for native module compilation (tree-sitter incremental code parsers for YAML and TypeScript)
• If behind a corporate proxy, set HTTP_PROXY and HTTPS_PROXY environment variables
• Offline fallback: If native builds fail, the server operates in reduced mode without tree-sitter code analysis

📦 Quick Installation

```bash

Option 1: Global installation (recommended for frequent use)

npm install -g mcp-adr-analysis-server

Option 2: Use npx (no installation required)

npx mcp-adr-analysis-server

Option 4: RHEL 9/10 systems (special installer)

curl -sSL https://raw.githubusercontent.com/tosin2013/mcp-adr-analysis-server/main/scripts/install-rhel.sh | bash ```

Note: When installing from source, npm run build is required before running the server since the bin entry points to ./dist/src/index.js.

📖 Detailed Installation Guide → | RHEL Setup →

⚡ Quick Setup (3 Steps)

1. Get API Key: Sign up at OpenRouter.ai/keys — OpenRouter is an API gateway that provides access to multiple AI models (Claude, GPT, etc.) through a single key. _No API key? The server still works in prompt-only mode — see Execution Modes below.
2. Set Environment: OPENROUTER_API_KEY=your_key + EXECUTION_MODE=full
3. Configure Client: Add to Claude Desktop, Cline, Cursor, or Windsurf

{
  "mcpServers": {
    "adr-analysis": {
      "command": "mcp-adr-analysis-server",
      "env": {
        "PROJECT_PATH": "/path/to/your/project",
        "OPENROUTER_API_KEY": "your_key_here",
        "EXECUTION_MODE": "full"
      }
    }
  }
}

Claude Desktop users: Save this JSON to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows).

<details> <summary><b>Config locations for other clients</b></summary>

</details>

<details> <summary><b>With ADR Aggregator (Optional)</b></summary>

{
  "mcpServers": {
    "adr-analysis": {
      "command": "mcp-adr-analysis-server",
      "env": {
        "PROJECT_PATH": "/path/to/your/project",
        "OPENROUTER_API_KEY": "your_key_here",
        "EXECUTION_MODE": "full",
        "ADR_AGGREGATOR_API_KEY": "agg_your_key_here"
      }
    }
  }
}

Get your API key at adraggregator.com

</details>

📖 Full Configuration Guide → | Client Setup →

🔥 Firecrawl Integration (Optional — Skip for Getting Started)

Enhanced web research capabilities for comprehensive architectural analysis.

Note: You don't need Firecrawl for basic ADR analysis. The server works fully without it. Only configure Firecrawl if you need web research features like the perform_research tool with external sources.

<details> <summary><b>When is Firecrawl useful?</b></summary>

• ADR research — automatically pull best practices from official docs when generating ADRs
• Technology evaluation — compare frameworks by crawling their documentation and changelogs
• Security audits — check CVE databases and security advisories for your dependencies
• Migration planning — gather migration guides and breaking-change notes from upstream projects

</details>

```bash

🚀 Usage Examples

Just ask your MCP client in natural language — no code required:

"Analyze this React project's architecture and suggest ADRs for any implicit decisions"

"Generate ADRs from the PRD.md file and create a todo.md with implementation tasks"

"Check this codebase for security issues and provide masking recommendations"

The server returns actual analysis results instead of prompts to submit elsewhere!

<details> <summary><b>Programmatic Usage (Advanced)</b></summary>

If you're integrating the server into your own tooling via the MCP SDK:

// Basic project analysis
const analysis = await analyzeProjectEcosystem({
  projectPath: '/path/to/project',
  analysisType: 'comprehensive',
});

// Generate ADRs from requirements
const adrs = await generateAdrsFromPrd({
  prdPath: 'docs/PRD.md',
  outputDirectory: 'docs/adrs',
});

// Smart Code Linking - Find code related to ADR decisions
const relatedCode = await findRelatedCode(
  'docs/adrs/001-auth-system.md',
  'We will implement JWT authentication with Express middleware',
  '/path/to/project',
  {
    useAI: true, // AI-powered keyword extraction
    useRipgrep: true, // Fast text search
    maxFiles: 10, // Limit results
    includeContent: true, // Include file contents
  }
);

</details>

📖 Complete Usage Guide → | API Reference →

Try it out: This repo includes a sample-project/ directory with example ADRs and source code. Point PROJECT_PATH at it to experiment without affecting your own codebase. Note: The sample project is only available when cloning from source (Option 3 above). If you installed via npm (Option 1 or 2), create your own test project or clone the repo separately to access the sample: git clone --depth 1 https://github.com/tosin2013/mcp-adr-analysis-server.git sample-test

🎯 Use Cases

👨‍💻 AI Coding Assistants - Enhance Claude, Cline, Cursor with architectural intelligence 💬 Conversational AI - Answer architecture questions with confidence scoring 🤖 Autonomous Agents - Continuous analysis and rule enforcement 🏢 Enterprise Teams - Portfolio analysis and migration planning

📖 Detailed Use Cases →

🌟 Quick Start for Contributors

1. Fork the repository
2. Clone your fork: git clone https://github.com/YOUR_USERNAME/mcp-adr-analysis-server.git
3. Create a branch: git checkout -b feature/your-feature-name
4. Make your changes with tests
5. Test: npm test (maintain >80% coverage)
6. Submit a Pull Request

Option 3: From source (for development or customization)

git clone https://github.com/tosin2013/mcp-adr-analysis-server.git cd mcp-adr-analysis-server && npm install && npm run build

Option 1: Cloud service (recommended)

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

Option 2: Self-hosted

export FIRECRAWL_ENABLED="true" export FIRECRAWL_BASE_URL="http://localhost:3000"

Option 3: Disabled (default - server works without web search)

```

📖 Firecrawl Setup Guide →

🌐 ADR Aggregator Integration (Optional)

ADR Aggregator is a platform for cross-team ADR visibility and governance. It provides:

• Cross-repository knowledge graphs — See how architectural decisions relate across projects
• Governance dashboards — Track ADR compliance, staleness, and review cycles
• Template library — Access domain-specific ADR templates (security, API, database, etc.)
• Team collaboration — Share architectural decisions organization-wide

Note: ADR Aggregator is optional. All core analysis features work without it.

```bash

4. (Optional) Sync to adraggregator.com

sync_to_aggregator(full_sync: true) ```

Benefits: Cross-team visibility • Staleness alerts • Compliance tracking • Organization-wide knowledge graph

📖 ADR Aggregator Guide → | 📖 MCP Integration Guide →

Set your API key (get one at adraggregator.com)

export ADR_AGGREGATOR_API_KEY="agg_your_key_here" ```

Workflow for New Repos

```bash

🔧 Troubleshooting

Common Issues:

• RHEL Systems: Use special installer script
• Tools return prompts: Set EXECUTION_MODE=full + API key
• Module not found: Run npm install && npm run build
• Permission denied: Check file permissions and project path

📖 Complete Troubleshooting Guide →