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 (2 Steps)

1. Install: npm install -g mcp-adr-analysis-server
2. Configure Client: Add to Claude Desktop, Cline, Cursor, or Windsurf — no API key required

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

That's it. The server runs in CE-MCP mode by default — your host LLM (Claude, GPT, etc.) executes the analysis using orchestration directives returned by the tools. No external API key needed.

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>

📖 VS Code Integration Guide → — step-by-step setup for Cline, Continue, and VS Code native MCP with example configs.

</details>

<details> <summary><b>Optional: OpenRouter Full Mode (legacy)</b></summary>

If you want the server to make its own AI calls (bypassing the host LLM), add an OpenRouter API key:

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

Sign up at OpenRouter.ai/keys. This mode is not recommended — CE-MCP produces equivalent results using your existing host LLM context.

</details>

<details> <summary><b>Optional: ADR Aggregator integration</b></summary>

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

Get your API key at adraggregator.com

</details>

📖 Full Configuration Guide → | Client Setup →

🚀 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 structured analysis and orchestration directives that your host LLM executes in context.

<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',
  {
    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 (do not drop below the coverage floor)
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

🌐 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 directives instead of results: This is expected in CE-MCP mode — your host LLM executes the directives. For server-side execution, set EXECUTION_MODE=full + OPENROUTER_API_KEY
• Module not found: Run npm install && npm run build
• Permission denied: Check file permissions and project path

📖 Complete Troubleshooting Guide →