mcp-adr-analysis-server

Servidor de Análise de ADR (Registro de Decisão Arquitetural) MCP (Protocolo de Contexto de Modelo)

Seus ADRs estão mentindo para você. Este servidor MCP detecta isso — a detecção de desvio em tempo real valida decisões arquiteturais contra seu código real. Além disso, segurança de conteúdo, memória de decisões e 63 ferramentas alimentadas pelo LLM do seu host via CE-MCP.

Sumário

• O que é MCP?
• Pré-requisitos
• Instalação Rápida
• Configuração Rápida
• Exemplos de Uso
• Casos de Uso
• Stack de Tecnologias
• Estrutura do Projeto
• Testes
• Integração com o Agregador de ADR
• Desenvolvimento
• Solução de Problemas
• Segurança e Desempenho
• Contribuindo
• Recursos
• Licença

O que é MCP?

O Protocolo de Contexto de Modelo (MCP) é um padrão aberto que permite integração perfeita entre assistentes de IA e ferramentas externas e fontes de dados. Pense nele como um adaptador universal que permite que assistentes de IA como Claude, Cline e Cursor se conectem a servidores especializados. Este servidor dá ao seu assistente de IA a capacidade de detectar desvios de ADR em relação ao código ativo, mascarar conteúdo sensível antes que ele vaze e lembrar decisões arquiteturais entre conversas.

Resumo

O quê: Servidor MCP que valida decisões arquiteturais contra seu código real — detecção de desvio, segurança de conteúdo e memória de decisões
Quem: Assistentes de codificação com IA (Claude, Cline, Cursor, Windsurf), arquitetos empresariais, equipes de desenvolvimento
Por quê: Detecte ADRs desatualizados antes que causem incidentes de produção — validação em tempo real com evidências de código, sem necessidade de chave de API
Como: npm install -g mcp-adr-analysis-server → Adicione ao seu cliente MCP → Comece a analisar

Principais recursos: Análise de AST com Tree-sitter • Mascaramento de conteúdo de segurança • Detecção de desvio • Diretrizes de orquestração CE-MCP • Validação de prontidão para implantação

Autor: Tosin Akinosho | Repositório: GitHub | Versão: 2.14.12

✨ Capacidades Principais

🔄 Detecção de Desvio - Valide decisões de ADR contra código ativo e evidências de infraestrutura 🛡️ Segurança de Conteúdo - Detecte e mascare segredos, PII e conteúdo sensível automaticamente 🧠 Memória de Decisões - Rastreamento de sessão e uso de ferramentas com recuperação pontuada por palavras-chave 🏗️ Detecção de Tecnologias - Identifique qualquer stack de tecnologia e padrões arquiteturais 📋 Gerenciamento de ADR - Gere, sugira e mantenha Registros de Decisão Arquitetural 🔗 Vinculação Inteligente de Código - Descoberta de arquivos de código relacionados a ADRs e decisões 🚀 Prontidão para Implantação - Validação de testes com tolerância zero e bloqueio rígido

📖 Ver Capacidades Completas → · 📜 Política de versões → · 🗒️ Registro de alterações →

Pré-requisitos

Antes de instalar, verifique se você tem:

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

Obrigatório:

• Node.js 20.0.0 ou superior — Baixar ou use nvm/fnm
• npm 9.0.0 ou superior (incluído com Node.js 20+)
• Um cliente compatível com MCP — Claude Desktop, Cline, Cursor ou Windsurf

Requisitos de Rede

• Acesso à internet necessário durante npm install para compilação de módulos nativos (tree-sitter analisadores de código incrementais para YAML e TypeScript)
• Se estiver atrás de um proxy corporativo, defina as variáveis de ambiente HTTP_PROXY e HTTPS_PROXY
• Fallback offline: Se as compilações nativas falharem, o servidor opera em modo reduzido sem análise de código tree-sitter

📦 Instalação Rápida

# 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: 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 4: RHEL 9/10 systems (special installer)
curl -sSL https://raw.githubusercontent.com/tosin2013/mcp-adr-analysis-server/main/scripts/install-rhel.sh | bash

Nota: Ao instalar a partir do código-fonte, npm run build é necessário antes de executar o servidor, pois o ponto de entrada bin aponta para ./dist/src/index.js.

📖 Guia de Instalação Detalhado → | Configuração RHEL →

⚡ Configuração Rápida (2 Passos)

1. Instale: npm install -g mcp-adr-analysis-server
2. Configure o Cliente: Adicione ao Claude Desktop, Cline, Cursor ou Windsurf — nenhuma chave de API necessária

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

É isso. O servidor executa em modo CE-MCP por padrão — seu LLM do host (Claude, GPT, etc.) executa a análise usando as diretrizes de orquestração retornadas pelas ferramentas. Nenhuma chave de API externa necessária.

Usuários do Claude Desktop: Salve este JSON em ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) ou %APPDATA%\Claude\claude_desktop_config.json (Windows).

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

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

📖 Guia de Configuração Completo → | Configuração do Cliente →

Modos de Execução

O que são diretrizes CE-MCP? Quando uma ferramenta é chamada, ela retorna uma diretriz de orquestração estruturada que diz ao seu LLM do host o que analisar, quais dados coletar e como formatar os resultados. O LLM do host (por exemplo, Claude no Claude Desktop, ou GPT no Cursor) executa a diretriz usando sua janela de contexto existente. Isso significa zero custos adicionais de API e melhores resultados porque o LLM já tem o contexto da sua conversa.

🚀 Exemplos de Uso

Basta perguntar ao seu cliente MCP em linguagem natural — nenhum código necessário:

"Analise a arquitetura deste projeto React e sugira ADRs para quaisquer decisões implícitas"

"Gere ADRs a partir do arquivo PRD.md e crie um todo.md com tarefas de implementação"

"Verifique este código em busca de problemas de segurança e forneça recomendações de mascaramento"

O servidor retorna análise estruturada e diretrizes de orquestração que seu LLM do host executa em contexto.

// 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
  }
);

📖 Guia de Uso Completo → | Referência da API →

Experimente: Este repositório inclui um diretório sample-project/ com ADRs de exemplo e código-fonte. Aponte PROJECT_PATH para ele para experimentar sem afetar seu próprio código.

Nota: O projeto de exemplo está disponível apenas quando clonado a partir do código-fonte (Opção 3 acima). Se você instalou via npm (Opção 1 ou 2), crie seu próprio projeto de teste ou clone o repositório separadamente para acessar o exemplo: git clone --depth 1 https://github.com/tosin2013/mcp-adr-analysis-server.git sample-test

🎯 Casos de Uso

👨‍💻 Assistentes de Codificação com IA — Aprimore Claude, Cline, Cursor com inteligência arquitetural
💬 IA Conversacional — Responda perguntas de arquitetura com pontuação de confiança
🤖 Agentes Autônomos — Análise contínua e aplicação de regras
🏢 Equipes Empresariais — Análise de portfólio e planejamento de migração

📖 Casos de Uso Detalhados →

🛠️ Pilha de Tecnologia

Runtime: Node.js 20+ • Linguagem: TypeScript • Framework: MCP SDK • Testes: Vitest (~49% de declarações, piso obrigatório) Busca: ripgrep (busca recursiva rápida de texto) + fast-glob (correspondência de arquivos) • Integração com IA: Diretrizes de orquestração CE-MCP (LLM host) • Análise de Código: tree-sitter (parser incremental de código) + Smart Code Linking

📖 Detalhes Técnicos → | Playbook de Migração CE-MCP →

📁 Estrutura do Projeto

src/tools/     # 64 MCP tools with annotated metadata
docs/adrs/     # Architectural Decision Records
tests/         # ~49% statement coverage, floor enforced in CI
.github/       # CI/CD automation

📖 Estrutura Completa →

🧪 Testes

npm test              # Run all tests
npm run test:coverage # Coverage report

📖 Guia de Testes →

🌐 Integração com ADR Aggregator (Opcional)

ADR Aggregator é uma plataforma para visibilidade e governança de ADRs entre equipes. Ela oferece:

• Grafos de conhecimento entre repositórios — Veja como decisões arquiteturais se relacionam entre projetos
• Painéis de governança — Acompanhe conformidade de ADRs, obsolescência e ciclos de revisão
• Biblioteca de modelos — Acesse modelos de ADR específicos por domínio (segurança, API, banco de dados, etc.)
• Colaboração em equipe — Compartilhe decisões arquiteturais em toda a organização

Nota: O ADR Aggregator é opcional. Todos os recursos principais de análise funcionam sem ele.

# Set your API key (get one at adraggregator.com)
export ADR_AGGREGATOR_API_KEY="agg_your_key_here"

Ferramentas Disponíveis

Fluxo de Trabalho para Novos Repositórios

# 1. Analyze codebase for implicit architectural decisions
suggest_adrs(analysisType: 'implicit_decisions')

# 2. Generate ADR files from suggestions
generate_adr_from_decision(decisionData)

# 3. Save ADRs to docs/adrs/

# 4. (Optional) Sync to adraggregator.com
sync_to_aggregator(full_sync: true)

Benefícios: Visibilidade entre equipes • Alertas de obsolescência • Rastreamento de conformidade • Grafo de conhecimento em toda a organização

📖 Guia do ADR Aggregator → | 📖 Guia de Integração MCP →

🔧 Desenvolvimento

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

Padrões de Qualidade: Modo estrito do TypeScript • ESLint • Piso de cobertura obrigatório • Hooks de pré-commit

Visualizando a Documentação Localmente

A documentação da API é gerada com TypeDoc:

npm install          # Required once after cloning (installs typedoc)
npm run docs:build   # Generate API docs into docs/api/
npm run docs:serve   # Serve locally via Python HTTP server

Em seguida, abra http://localhost:8080 no seu navegador. A documentação em Markdown fica em docs/ e pode ser navegada diretamente no GitHub.

📖 Guia de Desenvolvimento → | Contribuindo →

🔧 Solução de Problemas

Problemas Comuns:

• Sistemas RHEL: Use o script de instalação especial
• Ferramentas retornam diretrizes em vez de resultados: Isso é esperado no modo CE-MCP — seu LLM host executa as diretrizes. Para execução no servidor, defina EXECUTION_MODE=full + OPENROUTER_API_KEY
• Módulo não encontrado: Execute npm install && npm run build
• Permissão negada: Verifique as permissões de arquivo e o caminho do projeto

📖 Guia Completo de Solução de Problemas →

🔒 Segurança e Desempenho

Segurança: Detecção automática de segredos • Mascaramento de conteúdo • Processamento local • Confiança zero
Desempenho: Cache em múltiplos níveis • Análise incremental • Processamento paralelo • Otimização de memória

📖 Guia de Segurança → | Desempenho →

🔐 Relato de Vulnerabilidades de Segurança

Encontrou um problema de segurança? Leia nossa Política de Segurança para procedimentos de divulgação responsável. Não crie issues públicas para vulnerabilidades de segurança.

🤝 Contribuindo

Aceitamos contribuições! Seja corrigindo bugs, adicionando recursos ou melhorando a documentação, sua ajuda é apreciada.

🌟 Início Rápido para Contribuidores

1. Faça um fork do repositório
2. Clone seu fork: git clone https://github.com/YOUR_USERNAME/mcp-adr-analysis-server.git
3. Crie um branch: git checkout -b feature/your-feature-name
4. Faça suas alterações com testes
5. Teste: npm test (não caia abaixo do piso de cobertura)
6. Envie um Pull Request

🗺️ Roadmap

O trabalho é acompanhado nos marcos do GitHub, e a participação em um marco é o que marca uma issue como admitida.

A direção arquitetural está em docs/adrs/; o ritmo de lançamentos está em RELEASES.md.

👶 Primeira Vez Contribuindo?

Procurando uma boa primeira issue? Confira nossas boas primeiras issues — são tarefas amigáveis para iniciantes, perfeitas para começar!

Novo em open source? Nosso Guia de Contribuição orienta você por todo o processo passo a passo.

📝 Relatando Issues

Use nossos modelos de issue ao relatar bugs ou solicitar recursos. Os modelos nos ajudam a entender e resolver problemas mais rapidamente.

Padrões: TypeScript estrito • Piso de cobertura obrigatório • ESLint • Validação de segurança • Conformidade com MCP

📖 Guia Completo de Contribuição → | Código de Conduta →

🔗 Recursos

Oficiais: Especificação MCP • MCP SDK
Comunidade: Registro MCP • Discord
Projeto: ADRs • Progresso • Guia de Publicação

📄 Licença

Licença MIT — consulte o arquivo LICENSE para detalhes.

🙏 Agradecimentos

• Anthropic por criar o Model Context Protocol
• A Comunidade MCP por inspiração e melhores práticas
• Contribuidores que ajudam a tornar este projeto melhor

Construído com ❤️ por Tosin Akinosho para análise arquitetural orientada por IA

Empoderando assistentes de IA com detecção de desvios, segurança de conteúdo e memória de decisões por meio de diretrizes de orquestração CE-MCP.