mcp-adr-analysis-server

Servidor de Análisis de ADR (Registro de Decisiones Arquitectónicas) MCP (Protocolo de Contexto de Modelo)

Tus ADR te están mintiendo. Este servidor MCP lo detecta: la detección de desviaciones en vivo valida las decisiones arquitectónicas contra tu código real. Además, seguridad de contenido, memoria de decisiones y 63 herramientas impulsadas por el LLM de tu host a través de CE-MCP.

Tabla de contenidos

• ¿Qué es MCP?
• Requisitos previos
• Instalación rápida
• Configuración rápida
• Ejemplos de uso
• Casos de uso
• Stack tecnológico
• Estructura del proyecto
• Pruebas
• Integración con el Agregador de ADR
• Desarrollo
• Solución de problemas
• Seguridad y rendimiento
• Contribuciones
• Recursos
• Licencia

¿Qué es MCP?

El Protocolo de Contexto de Modelo (MCP) es un estándar abierto que permite la integración sin fricciones entre asistentes de IA y herramientas externas y fuentes de datos. Piénsalo como un adaptador universal que permite que asistentes de IA como Claude, Cline y Cursor se conecten a servidores especializados. Este servidor le da a tu asistente de IA la capacidad de detectar desviaciones de ADR contra código en vivo, enmascarar contenido sensible antes de que se filtre y recordar decisiones arquitectónicas entre conversaciones.

Resumen

Qué: Servidor MCP que valida decisiones arquitectónicas contra tu código real: detección de desviaciones, seguridad de contenido y memoria de decisiones
Quién: Asistentes de codificación con IA (Claude, Cline, Cursor, Windsurf), arquitectos empresariales, equipos de desarrollo
Por qué: Detecta ADR obsoletos antes de que causen incidentes en producción: validación en vivo contra evidencia de código, sin necesidad de clave API
Cómo: npm install -g mcp-adr-analysis-server → Añádelo a tu cliente MCP → Comienza a analizar

Características clave: Análisis AST con Tree-sitter • Enmascaramiento de contenido de seguridad • Detección de desviaciones • Directivas de orquestación CE-MCP • Validación de preparación para despliegue

Autor: Tosin Akinosho | Repositorio: GitHub | Versión: 2.14.12

✨ Capacidades principales

🔄 Detección de desviaciones - Valida las decisiones de ADR contra el código en vivo y la evidencia de infraestructura 🛡️ Seguridad de contenido - Detecta y enmascara secretos, PII y contenido sensible automáticamente 🧠 Memoria de decisiones - Seguimiento de sesión y uso de herramientas con recuperación puntuada por palabras clave 🏗️ Detección de tecnología - Identifica cualquier stack tecnológico y patrones arquitectónicos 📋 Gestión de ADR - Genera, sugiere y mantiene Registros de Decisiones Arquitectónicas 🔗 Vinculación inteligente de código - Descubrimiento de archivos de código relacionados con ADR y decisiones 🚀 Preparación para despliegue - Validación de pruebas con tolerancia cero y bloqueo estricto

📖 Ver capacidades completas → · 📜 Política de versiones → · 🗒️ Registro de cambios →

Requisitos previos

Antes de instalar, verifica que tienes:

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

Requerido:

• Node.js 20.0.0 o superior — Descargar o usar nvm/fnm
• npm 9.0.0 o superior (incluido con Node.js 20+)
• Un cliente compatible con MCP — Claude Desktop, Cline, Cursor o Windsurf

Requisitos de red

• Se requiere acceso a Internet durante npm install para la compilación de módulos nativos (tree-sitter analizadores de código incrementales para YAML y TypeScript)
• Si estás detrás de un proxy corporativo, establece las variables de entorno HTTP_PROXY y HTTPS_PROXY
• Alternativa sin conexión: Si las compilaciones nativas fallan, el servidor opera en modo reducido sin análisis de código tree-sitter

📦 Instalación 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: Al instalar desde el código fuente, se requiere npm run build antes de ejecutar el servidor, ya que el punto de entrada bin apunta a ./dist/src/index.js.

📖 Guía de instalación detallada → | Configuración RHEL →

⚡ Configuración rápida (2 pasos)

1. Instalar: npm install -g mcp-adr-analysis-server
2. Configurar el cliente: Añádelo a Claude Desktop, Cline, Cursor o Windsurf: no se requiere clave API

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

Eso es todo. El servidor se ejecuta en modo CE-MCP de forma predeterminada: tu LLM del host (Claude, GPT, etc.) ejecuta el análisis utilizando las directivas de orquestación devueltas por las herramientas. No se necesita clave API externa.

Usuarios de Claude Desktop: Guarda este JSON en ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) o %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"
      }
    }
  }
}

📖 Guía de configuración completa → | Configuración del cliente →

Modos de ejecución

¿Qué son las directivas CE-MCP? Cuando se llama a una herramienta, devuelve una directiva de orquestación estructurada que le dice a tu LLM del host qué analizar, qué datos recopilar y cómo formatear los resultados. El LLM del host (por ejemplo, Claude en Claude Desktop, o GPT en Cursor) ejecuta la directiva utilizando su ventana de contexto existente. Esto significa cero costos adicionales de API y mejores resultados porque el LLM ya tiene el contexto de tu conversación.

🚀 Ejemplos de uso

Solo pregunta a tu cliente MCP en lenguaje natural: no se requiere código:

"Analiza la arquitectura de este proyecto React y sugiere ADR para cualquier decisión implícita"

"Genera ADR a partir del archivo PRD.md y crea un todo.md con tareas de implementación"

"Revisa este código en busca de problemas de seguridad y proporciona recomendaciones de enmascaramiento"

El servidor devuelve análisis estructurado y directivas de orquestación que tu LLM del host ejecuta en 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
  }
);

📖 Guía de uso completa → | Referencia de API →

Pruébalo: Este repositorio incluye un directorio sample-project/ con ADR de ejemplo y código fuente. Apunta PROJECT_PATH a él para experimentar sin afectar tu propio código.

Nota: El proyecto de ejemplo solo está disponible cuando se clona desde el código fuente (Opción 3 arriba). Si instalaste a través de npm (Opción 1 o 2), crea tu propio proyecto de prueba o clona el repositorio por separado para acceder al ejemplo: git clone --depth 1 https://github.com/tosin2013/mcp-adr-analysis-server.git sample-test

🎯 Casos de uso

👨‍💻 Asistentes de Codificación con IA — Mejora Claude, Cline, Cursor con inteligencia arquitectónica
💬 IA Conversacional — Responde preguntas de arquitectura con puntuación de confianza
🤖 Agentes Autónomos — Análisis continuo y aplicación de reglas
🏢 Equipos Empresariales — Análisis de portafolio y planificación de migración

📖 Casos de uso detallados →

🛠️ Stack Tecnológico

Runtime: Node.js 20+ • Lenguaje: TypeScript • Framework: MCP SDK • Pruebas: Vitest (~49% de declaraciones, mínimo exigido) Búsqueda: ripgrep (búsqueda recursiva rápida de texto) + fast-glob (coincidencia de archivos) • Integración de IA: Directivas de orquestación CE-MCP (LLM anfitrión) • Análisis de código: tree-sitter (analizador de código incremental) + Smart Code Linking

📖 Detalles técnicos → | Manual de migración CE-MCP →

📁 Estructura del Proyecto

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

📖 Estructura completa →

🧪 Pruebas

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

📖 Guía de pruebas →

🌐 Integración con ADR Aggregator (Opcional)

ADR Aggregator es una plataforma para la visibilidad y gobernanza de ADR entre equipos. Proporciona:

• Grafos de conocimiento entre repositorios — Ve cómo las decisiones arquitectónicas se relacionan entre proyectos
• Paneles de gobernanza — Realiza seguimiento del cumplimiento de ADR, obsolescencia y ciclos de revisión
• Biblioteca de plantillas — Accede a plantillas de ADR específicas de dominio (seguridad, API, base de datos, etc.)
• Colaboración en equipo — Comparte decisiones arquitectónicas en toda la organización

Nota: ADR Aggregator es opcional. Todas las funciones principales de análisis funcionan sin él.

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

Herramientas Disponibles

Flujo de Trabajo para Repositorios Nuevos

# 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)

Beneficios: Visibilidad entre equipos • Alertas de obsolescencia • Seguimiento de cumplimiento • Grafo de conocimiento organizacional

📖 Guía de ADR Aggregator → | 📖 Guía de integración MCP →

🔧 Desarrollo

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

Estándares de calidad: Modo estricto de TypeScript • ESLint • Cobertura mínima exigida • Hooks de pre-commit

Visualización de Documentación Localmente

La documentación de la API se genera con 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

Luego abre http://localhost:8080 en tu navegador. La documentación en Markdown se encuentra en docs/ y se puede consultar directamente en GitHub.

📖 Guía de desarrollo → | Contribuciones →

🔧 Solución de Problemas

Problemas comunes:

• Sistemas RHEL: Usa el script de instalación especial
• Las herramientas devuelven directivas en lugar de resultados: Esto es esperado en modo CE-MCP — tu LLM anfitrión ejecuta las directivas. Para ejecución en el servidor, establece EXECUTION_MODE=full + OPENROUTER_API_KEY
• Módulo no encontrado: Ejecuta npm install && npm run build
• Permiso denegado: Verifica los permisos de archivos y la ruta del proyecto

📖 Guía completa de solución de problemas →

🔒 Seguridad y Rendimiento

Seguridad: Detección automática de secretos • Enmascaramiento de contenido • Procesamiento local • Cero confianza
Rendimiento: Caché multinivel • Análisis incremental • Procesamiento paralelo • Optimización de memoria

📖 Guía de seguridad → | Rendimiento →

🔐 Reporte de Vulnerabilidades de Seguridad

¿Encontraste un problema de seguridad? Por favor, lee nuestra Política de Seguridad para conocer los procedimientos de divulgación responsable. No crees problemas públicos para vulnerabilidades de seguridad.

🤝 Contribuciones

¡Agradecemos las contribuciones! Ya sea corrigiendo errores, añadiendo funciones o mejorando la documentación, tu ayuda es apreciada.

🌟 Inicio Rápido para Contribuyentes

1. Haz un fork del repositorio
2. Clona tu fork: git clone https://github.com/YOUR_USERNAME/mcp-adr-analysis-server.git
3. Crea una rama: git checkout -b feature/your-feature-name
4. Haz tus cambios con pruebas
5. Prueba: npm test (no bajes del mínimo de cobertura)
6. Envía una Pull Request

🗺️ Hoja de Ruta

El trabajo se rastrea en hitos de GitHub, y la pertenencia a un hito es lo que marca un problema como admitido.

La dirección arquitectónica se encuentra en docs/adrs/; el ritmo de lanzamiento está en RELEASES.md.

👶 ¿Primera Vez Contribuyendo?

¿Buscas un buen primer problema? Consulta nuestros buenos primeros problemas — ¡son tareas aptas para principiantes, perfectas para empezar!

¿Nuevo en código abierto? Nuestra Guía de Contribuciones te guía por todo el proceso paso a paso.

📝 Reporte de Problemas

Usa nuestras plantillas de problemas al reportar errores o solicitar funciones. Las plantillas nos ayudan a entender y resolver los problemas más rápido.

Estándares: TypeScript estricto • Cobertura mínima exigida • ESLint • Validación de seguridad • Cumplimiento de MCP

📖 Guía completa de contribuciones → | Código de conducta →

🔗 Recursos

Oficiales: Especificación MCP • MCP SDK
Comunidad: Registro MCP • Discord
Proyecto: ADRs • Progreso • Guía de publicación

📄 Licencia

Licencia MIT — consulta el archivo LICENSE para más detalles.

🙏 Agradecimientos

• Anthropic por crear el Model Context Protocol
• La comunidad MCP por la inspiración y las mejores prácticas
• Contribuyentes que ayudan a mejorar este proyecto

Hecho con ❤️ por Tosin Akinosho para análisis arquitectónico impulsado por IA

Empoderando a los asistentes de IA con detección de desviaciones, seguridad de contenido y memoria de decisiones mediante directivas de orquestación CE-MCP.