Skip to main content
Glama

mcp-adr-analysis-server

by tosin2013
README.mdโ€ข10.6 kB
# MCP ADR Analysis Server [![GitHub](https://img.shields.io/badge/github-tosin2013/mcp--adr--analysis--server-blue.svg?style=flat&logo=github)](https://github.com/tosin2013/mcp-adr-analysis-server) [![License](https://img.shields.io/badge/license-MIT-brightgreen)](LICENSE) [![NPM Version](https://img.shields.io/npm/v/mcp-adr-analysis-server)](https://www.npmjs.com/package/mcp-adr-analysis-server) [![Node.js](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen)](https://nodejs.org/) [![TypeScript](https://img.shields.io/badge/TypeScript-5.9+-blue)](https://www.typescriptlang.org/) [![Good First Issues](https://img.shields.io/github/issues/tosin2013/mcp-adr-analysis-server/good%20first%20issue?label=good%20first%20issues&color=7057ff)](https://github.com/tosin2013/mcp-adr-analysis-server/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) > **AI-powered architectural analysis for intelligent development workflows.** Returns actual analysis results, not prompts to submit elsewhere. ## TL;DR **What:** MCP server that provides AI-powered architectural decision analysis and ADR management **Who:** AI coding assistants (Claude, Cline, Cursor), enterprise architects, development teams **Why:** Get immediate architectural insights instead of prompts, with 95% confidence scoring **How:** `npm install -g mcp-adr-analysis-server` โ†’ Configure with OpenRouter API โ†’ Start analyzing **Key Features:** Tree-sitter AST analysis โ€ข Security content masking โ€ข Test-driven development โ€ข Deployment readiness validation --- **Author**: [Tosin Akinosho](https://github.com/tosin2013) | **Repository**: [GitHub](https://github.com/tosin2013/mcp-adr-analysis-server.git) ## What is MCP? The Model Context Protocol enables seamless integration between AI assistants and external tools. This server enhances AI assistants with deep architectural analysis capabilities, enabling intelligent code generation, decision tracking, and development workflow automation. ## โœจ Core Capabilities ๐Ÿค– **AI-Powered Analysis** - Immediate architectural insights with OpenRouter.ai integration ๐Ÿ—๏ธ **Technology Detection** - Identify any tech stack and architectural patterns ๐Ÿ“‹ **ADR Management** - Generate, suggest, and maintain Architectural Decision Records ๐Ÿ”— **Smart Code Linking** - AI-powered discovery of code files related to ADRs and decisions ๐Ÿ›ก๏ธ **Security & Compliance** - Detect and mask sensitive content automatically ๐Ÿงช **TDD Integration** - Two-phase Test-Driven Development with validation ๐Ÿš€ **Deployment Readiness** - Zero-tolerance test validation with hard blocking ๐Ÿ“– **[View Full Capabilities โ†’](docs/explanation/)** ## ๐Ÿ“ฆ 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 3: RHEL 9/10 systems (special installer) curl -sSL https://raw.githubusercontent.com/tosin2013/mcp-adr-analysis-server/main/scripts/install-rhel.sh | bash ``` ๐Ÿ“– **[Detailed Installation Guide โ†’](docs/tutorials/01-first-steps.md)** | **[RHEL Setup โ†’](scripts/install-rhel.sh)** ## โšก Quick Setup (3 Steps) 1. **Get API Key**: [OpenRouter.ai/keys](https://openrouter.ai/keys) 2. **Set Environment**: `OPENROUTER_API_KEY=your_key` + `EXECUTION_MODE=full` 3. **Configure Client**: Add to Claude Desktop, Cline, Cursor, or Windsurf ```json { "mcpServers": { "adr-analysis": { "command": "mcp-adr-analysis-server", "env": { "PROJECT_PATH": "/path/to/your/project", "OPENROUTER_API_KEY": "your_key_here", "EXECUTION_MODE": "full" } } } } ``` ๐Ÿ“– **[Full Configuration Guide โ†’](docs/reference/mcp-client-config.md)** | **[Client Setup โ†’](docs/reference/environment-config.md)** ## ๐Ÿš€ Usage Examples **Ask Claude (or any MCP client):** > "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! ```typescript // 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 } ); ``` ๐Ÿ“– **[Complete Usage Guide โ†’](docs/tutorials/)** | **[API Reference โ†’](docs/reference/)** ## ๐ŸŽฏ 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 โ†’](docs/explanation/mcp-concepts.md)** ## ๐Ÿ› ๏ธ Technology Stack **Runtime:** Node.js 20+ โ€ข **Language:** TypeScript โ€ข **Framework:** MCP SDK โ€ข **Testing:** Jest (>80% coverage) **Search:** ripgrep + fast-glob โ€ข **AI Integration:** OpenRouter.ai โ€ข **Web Research:** Firecrawl โ€ข **Code Analysis:** Smart Code Linking ๐Ÿ“– **[Technical Details โ†’](docs/explanation/server-architecture.md)** ## ๐Ÿ“ Project Structure ``` src/tools/ # 23 MCP tools for analysis docs/adrs/ # Architectural Decision Records tests/ # >80% test coverage .github/ # CI/CD automation ``` ๐Ÿ“– **[Full Structure โ†’](docs/diataxis-index.md)** ## ๐Ÿงช Testing ```bash npm test # Run all tests (>80% coverage) npm run test:coverage # Coverage report ``` ๐Ÿ“– **[Testing Guide โ†’](docs/how-to-guides/troubleshooting.md)** ## ๐Ÿ”ฅ Firecrawl Integration (Optional) **Enhanced web research capabilities for comprehensive architectural analysis.** ```bash # 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) ``` **Benefits:** Real-time research โ€ข Enhanced ADRs โ€ข Best practices discovery โ€ข Intelligent web scraping ๐Ÿ“– **[Firecrawl Setup Guide โ†’](docs/reference/environment-config.md#firecrawl-configuration)** ## ๐Ÿ”ง Development ```bash git clone https://github.com/tosin2013/mcp-adr-analysis-server.git cd mcp-adr-analysis-server npm install && npm run build && npm test ``` **Quality Standards:** TypeScript strict mode โ€ข ESLint โ€ข >80% test coverage โ€ข Pre-commit hooks ๐Ÿ“– **[Development Guide โ†’](docs/how-to-guides/getting-started-workflow-guidance.md)** | **[Contributing โ†’](CONTRIBUTING.md)** ## ๐Ÿ”ง 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 โ†’](docs/troubleshooting.md)** ## ๐Ÿ”’ Security & Performance **Security:** Automatic secret detection โ€ข Content masking โ€ข Local processing โ€ข Zero trust **Performance:** Multi-level caching โ€ข Incremental analysis โ€ข Parallel processing โ€ข Memory optimization ๐Ÿ“– **[Security Guide โ†’](docs/explanation/security-philosophy.md)** | **[Performance โ†’](docs/explanation/performance-design.md)** ### ๐Ÿ” Security Vulnerability Reporting Found a security issue? Please read our [Security Policy](SECURITY.md) for responsible disclosure procedures. **Do not** create public issues for security vulnerabilities. ## ๐Ÿค Contributing We welcome contributions! Whether you're fixing bugs, adding features, or improving documentation, your help is appreciated. ### ๐ŸŒŸ 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 ### ๐Ÿ‘ถ First Time Contributing? Looking for a good first issue? Check out our [**good first issues**](https://github.com/tosin2013/mcp-adr-analysis-server/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) - these are beginner-friendly tasks perfect for getting started! **New to open source?** Our [Contributing Guide](CONTRIBUTING.md) walks you through the entire process step-by-step. ### ๐Ÿ“ Reporting Issues Use our [**issue templates**](https://github.com/tosin2013/mcp-adr-analysis-server/issues/new/choose) when reporting bugs or requesting features. Templates help us understand and resolve issues faster. **Standards:** TypeScript strict โ€ข >80% coverage โ€ข ESLint โ€ข Security validation โ€ข MCP compliance ๐Ÿ“– **[Full Contributing Guide โ†’](CONTRIBUTING.md)** | **[Code of Conduct โ†’](docs/community/CODE_OF_CONDUCT.md)** ## ๐Ÿ”— Resources **Official:** [MCP Specification](https://modelcontextprotocol.io/) โ€ข [MCP SDK](https://github.com/modelcontextprotocol/typescript-sdk) **Community:** [MCP Registry](https://github.com/modelcontextprotocol/servers) โ€ข [Discord](https://discord.gg/modelcontextprotocol) **Project:** [ADRs](./docs/adrs/) โ€ข [Progress](./docs/release-dashboard.md) โ€ข [Publishing Guide](./docs/how-to-guides/NPM_PUBLISHING.md) ## ๐Ÿ“„ License MIT License - see [LICENSE](LICENSE) file for details. ## ๐Ÿ™ Acknowledgments - **Anthropic** for creating the Model Context Protocol - **The MCP Community** for inspiration and best practices - **Contributors** who help make this project better --- **Built with โค๏ธ by [Tosin Akinosho](https://github.com/tosin2013) for AI-driven architectural analysis** _Empowering AI assistants with deep architectural intelligence and decision-making capabilities._

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/tosin2013/mcp-adr-analysis-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server