Ridge

Ridge

Un servidor MCP que reconstruye la arquitectura a partir de un árbol de directorios. Apúntalo a código (Go, TypeScript, Python) y devuelve servicios, paquetes, bases de datos, colas, endpoints y sus relaciones como un grafo estructurado. Apúntalo a markdown (bóvedas de Obsidian, árboles de documentación) y los wiki-links más los enlaces relativos .md se convierten en aristas de dependencia en el mismo modelo de grafo. Genera diagramas en 9 formatos, incluida una página D3 de fuerza dirigida autocontenida para grafos hub-spoke. Detecta deriva entre dos ramas, etiquetas o commits. Valida reglas de arquitectura. Haz un seguimiento de cómo evoluciona el sistema con el tiempo.

Sin archivos de configuración, sin diagramación manual. El análisis estático construye el modelo de arquitectura directamente desde el árbol de fuentes.

Por qué

Los diagramas de arquitectura quedan obsoletos el mismo día en que los confirmas. Cuando la IA genera código más rápido de lo que los equipos pueden comprender los cambios, la brecha entre la complejidad del sistema y el entendimiento compartido crece. Esto es deuda cognitiva, y se acumula en silencio.

La mayoría de los equipos saben que deberían revisar la arquitectura con regularidad, comprobar las dependencias circulares y detectar la deriva estructural entre ramas. En la práctica, estas tareas son lo bastante manuales como para que no se hagan.

• Genera arquitectura desde el árbol de fuentes (código o markdown), así los diagramas están siempre actualizados. Nadie tiene que mantenerlos.
• arch_validate convierte "comprobar dependencias circulares" de un elemento de acción retro en una tarea de un solo prompt.
• arch_drift compara la arquitectura entre dos refs de git cualesquiera. Detecta cambios estructurales que la revisión de código pasa por alto: una nueva dependencia de base de datos, un servicio que silenciosamente se convirtió en monolito, un endpoint que elude la puerta de enlace de la API.
• arch_drift_explain envuelve ese diff en una narrativa de 2 a 5 frases que puedes pegar directamente en una descripción de PR, canal de standup o nota de versión. Sin llamada a LLM; puro plantillado a partir del diff estructurado.

El caso de uso estrella: incorporación a código que no es tuyo

El momento de mayor valor para Ridge es el que todo ingeniero vive cada semana: tienes que modificar una base de código que tu equipo no construyó. El antiguo arranque de ese trabajo era leer el código fuente, rastrear dependencias y construir un modelo mental en tu cabeza. Cuando un agente escribe el código, ese paso desaparece, y con él la comprensión. Así, los agentes cambian sistemas que nadie en el equipo solicitante comprende realmente, y las decisiones de arquitectura las toma quien (o lo que) escribe la primera línea.

Ridge reemplaza el paso que falta. Apúntalo al árbol desconocido y arch_scan + arch_generate producen un modelo de arquitectura actual — servicios, paquetes, infraestructura, endpoints y sus aristas — que un ingeniero puede leer en minutos en lugar de hacer ingeniería inversa a mano. El equipo propietario puede reaccionar a eso, en lugar de a un hilo de Slack o a un PR terminado, de modo que la alineación ocurre antes de que exista el código, no después.

Esto no es hipotético. Miro demostró el mismo patrón en Canvas 26 ("Dale a tus herramientas de codificación agénticas el panorama completo", junio de 2026): un equipo de funcionalidades necesitaba añadir herramientas a un servidor MCP que otro equipo poseía, usó un agente para leer esa base de código y generar un tablero de arquitectura, y lo usó para incorporarse y alinearse con el equipo propietario — sin esperar a un backlog. Mismo problema, misma forma, llegado de forma independiente. Ridge convierte eso en el flujo de trabajo predeterminado en lugar de un prompt puntual.

Qué hace

Analiza archivos fuente con analizadores específicos por lenguaje (Go mediante go/ast, TypeScript y Python mediante tree-sitter, markdown mediante extracción de enlaces basada en regex) y construye un grafo de arquitectura de nodos y aristas.

Los nodos representan componentes: servicios, módulos, paquetes, bases de datos, colas de mensajes, cachés, APIs externas, endpoints HTTP y notas (archivos markdown).

Las aristas representan relaciones con puntuaciones de confianza: dependencias (0.9), registros de endpoints (0.85), enlaces de infraestructura (0.8), llamadas de cliente HTTP (0.7). La confianza permite a los consumidores filtrar por fiabilidad; las importaciones resueltas directamente por AST puntúan más alto que las coincidencias heurísticas.

MCP (Model Context Protocol) permite a los asistentes de IA llamar a herramientas externas. Este servidor le da a tu asistente de IA 19 herramientas de análisis de arquitectura.

Qué obtienes

Ejecuta arch_scan en un proyecto Go y obtén un grafo de arquitectura estructurado:

{
  "topology": "monorepo",
  "nodes": [
    {"id": "pkg:api/server", "name": "server", "type": "package", "language": "go"},
    {"id": "pkg:worker/processor", "name": "processor", "type": "package", "language": "go"},
    {"id": "infra:postgresql", "name": "PostgreSQL", "type": "database"},
    {"id": "infra:redis", "name": "Redis", "type": "cache"},
    {"id": "infra:nats", "name": "NATS", "type": "queue"}
  ],
  "edges": [
    {"source": "pkg:api/server", "target": "infra:postgresql", "type": "read_write", "confidence": 0.8},
    {"source": "pkg:api/server", "target": "infra:redis", "type": "read_write", "confidence": 0.8},
    {"source": "pkg:worker/processor", "target": "infra:nats", "type": "subscribe", "confidence": 0.8}
  ],
  "stats": {"files_analyzed": 47, "files_cached": 38, "files_changed": 9, "nodes_found": 12, "edges_found": 23, "duration_ms": 340}
}

Luego pide a arch_generate un diagrama Mermaid, a arch_validate que compruebe dependencias circulares, o a arch_dataflow trazas estructuradas que muestren cómo fluyen las solicitudes desde los endpoints hasta las bases de datos. La infraestructura (bases de datos, colas, cachés) se detecta automáticamente a partir de las rutas de importación.

Por qué no X

Cuatro proyectos comparten partes de este espacio. Ninguno lo cubre de la misma manera.

CodeFlow (2.0k estrellas, MIT) es una página de un solo archivo React + D3 que analiza JS, TypeScript y Python en el navegador. Lee desde la API de GitHub, renderiza un grafo de dependencias a nivel de archivo y añade paneles para radio de explosión, escaneos de seguridad e impacto de PR. Nativo de navegador, granularidad de archivo. Sin soporte para Go; requiere acceso a CDN; sin interfaz de agente.

CodeGraphContext (1.2k estrellas, alfa) es un servidor MCP en Python que indexa código en KuzuDB, FalkorDB o Neo4j mediante tree-sitter. Soporte de 14 lenguajes, modo dual CLI/MCP. La misma superficie de agente que ridge, sin detección de endpoints, clasificación de infraestructura, narrativas de deriva ni escaneo entre sustratos (solo código, sin markdown).

Graphify (35k estrellas, MIT) es una skill multi-harness que convierte cualquier carpeta en un grafo de conocimiento consultable: 25 lenguajes de código más markdown, imágenes y transcripción de vídeo. graph.json persistente, caché incremental SHA256, merge-graphs para composición entre repos. Ámbito de skill, no MCP. Sin detección de deriva, sin tipos de nodo específicos de arquitectura, sin inferencia de infraestructura.

CocoIndex (9.7k estrellas, Apache-2.0) es un framework de indexación incremental con frontend en Python y núcleo en Rust que convierte bases de código, notas de reuniones, bandejas de entrada, Slack, PDFs y vídeos en fragmentos consultables por vector para RAG. El código es un sustrato entre muchos. Clase de problema diferente: cocoindex responde "encuéntrame código semánticamente similar a la consulta Q"; ridge responde "muéstrame el grafo estructural y qué cambió arquitectónicamente entre dos refs." Usa cocoindex cuando quieras búsqueda semántica de fragmentos entre sustratos heterogéneos. Usa ridge cuando quieras un modelo de arquitectura tipado con detección de deriva.

En qué se centra ridge. Transporte MCP orientado a agentes en las 19 herramientas. Nativo de Go mediante go/ast. Narrativas de deriva: arch_drift_explain devuelve un párrafo de PR listo para pegar en una sola llamada, sin ida y vuelta de LLM. Entre sustratos: el código y el markdown comparten el mismo modelo de grafo, así que arch_blast_radius responde "si cambio internal/scanner, ¿qué más necesita revisión?" en ambos. Consciente de infraestructura (bases de datos, colas, cachés como nodos tipados con puntuaciones de confianza).

Lo que ridge no hace. Sin UI nativa de navegador. Sin ingesta multimodal (imágenes, vídeo, audio). Sin búsqueda semántica de fragmentos para RAG. Si quieres un visualizador a nivel de archivo para JS/TS/Python con UI, usa CodeFlow. Si quieres un grafo de conocimiento multimodal a nivel de skill, usa Graphify. Si quieres indexación vectorial incremental en corpus heterogéneos, usa CocoIndex.

Ejemplos de uso

Una vez configurado, pide a tu LLM:

• "Escanea la arquitectura de ~/Projects/my-app"
• "Genera un diagrama C4 de este proyecto"
• "¿Hay dependencias circulares o violaciones de capas?"
• "Acepta nuestras violaciones existentes y falla solo con las nuevas" (usa el modo de línea base de arch_validate)
• "¿Nuestros alias de ruta de tsconfig y los objetivos de replace de go.mod existen realmente?"
• "Compara la arquitectura entre la etiqueta v1.0 y la rama main"
• "¿Cómo ha cambiado la arquitectura desde el mes pasado?"
• "¿A qué bases de datos se conecta este servicio?"
• "Exporta la arquitectura como Excalidraw"
• "Explica las decisiones de arquitectura en esta base de código"
• "¿Cómo debería mejorar esta arquitectura?"
• "¿Cómo están el acoplamiento y la inestabilidad?"
• "Muéstrame trazas de flujo de datos desde endpoints de API hasta bases de datos"
• "Guarda esta arquitectura como nuestra línea base v2.0"
• "Escanea este monorepo pero limítalo a 500 archivos y omite los archivos de prueba"
• "Escanea una bóveda de Obsidian y encuentra notas huérfanas"
• "Renderiza el directorio docs/ como un grafo de fuerza dirigida que muestre hubs con grado>=10"
• "Si cambio internal/scanner, ¿qué más necesita revisión?" (usa arch_blast_radius)

Herramientas

Herramientas clave

Herramienta	Qué hace
arch_scan	Escanea un directorio de código o markdown y devuelve el grafo de arquitectura completo con aristas puntuadas por confianza
arch_generate	Genera un diagrama (Mermaid, PlantUML, C4, Structurizr, JSON, draw.io, Excalidraw, HTML, forcegraph)
arch_blast_radius	Encuentra todos los nodos que dependen transitivamente de un objetivo — responde "si cambio X, ¿qué más necesita revisión?"
arch_drift	Compara la arquitectura entre dos ramas, etiquetas o commits
arch_drift_explain	Compara dos refs y devuelve un resumen narrativo de 2 a 5 frases más el diff estructurado — listo para pegar en descripciones de PR
arch_dataflow	Traza el flujo de datos desde endpoints hasta almacenes de datos con trazas de proceso estructuradas
arch_validate	Comprueba dependencias circulares, nodos huérfanos, violaciones de capas e inconsistencias de entorno — con un modo de línea base que acepta violaciones existentes y falla solo con las nuevas
arch_recommend	Produce recomendaciones de mejora de arquitectura priorizadas, cada una con la evidencia métrica desencadenante (valor + umbral + nodo) y una calificación de confianza

Las 19 herramientas

Herramienta	Categoría	Qué hace
arch_scan	análisis	Escanea un directorio de código o markdown y devuelve el grafo de arquitectura completo
arch_focus	análisis	Escanea un subdirectorio o servicio específico
arch_dependencies	análisis	Mapea dependencias internas, externas y de infraestructura
arch_blast_radius	análisis	Encuentra el conjunto transitivo de nodos que dependen de un archivo o paquete objetivo
arch_dataflow	análisis	Traza el flujo de datos con trazas de proceso de entrada a terminal y puntuaciones de confianza
arch_boundaries	análisis	Detecta límites de servicio y topología (monolito, monorepo, microservicios), con las señales detrás del veredicto, la razón por la que se activó y una bandera de ambigüedad para casos límite
arch_explain	análisis	Explica topología, patrones, decisiones clave y riesgos con evidencia de código
arch_generate	diagrama	Genera un diagrama en 9 formatos
arch_diff	deriva	Compara la arquitectura actual contra una línea base guardada
arch_drift	deriva	Compara la arquitectura entre dos refs de git
arch_drift_explain	deriva	Resumen narrativo de la deriva entre dos refs de git (prosa lista para pegar)
arch_validate	validación	Comprueba dependencias circulares, huérfanos, capas e inconsistencias de entorno; el modo de línea base acepta violaciones existentes y falla solo con las nuevas en bases de código heredadas
arch_metrics	validación	Calcula puntuaciones de acoplamiento, inestabilidad y profundidad de dependencia
arch_recommend	validación	Recomendaciones de mejora priorizadas a partir de métricas + violaciones + patrones, con evidencia + confianza por recomendación
arch_history	historial	Muestra cómo evolucionó la arquitectura a lo largo del historial de git
arch_snapshot	exportación	Guarda la arquitectura actual como línea base para la detección de deriva
arch_registry_add	registro	Registra un repositorio por alias para reutilizarlo entre llamadas de herramientas
arch_registry_list	registro	Lista todos los repositorios registrados
arch_registry_remove	registro	Elimina un alias de repositorio registrado

Línea base de violaciones conocidas (trinquete)

Adoptar arch_validate en una base de código heredada suele significar un muro de violaciones preexistentes y una marca roja permanente. El modo de línea base corrige el incentivo: acepta lo que existe, falla solo con lo nuevo.

• baseline="write" guarda las violaciones actuales en .arch-known-violations.json en la raíz del repositorio. Haz commit del archivo para que todo el equipo comparta el trinquete.
• baseline="check" valida como siempre, pero valid refleja solo las violaciones ausentes de la línea base. Las nuevas aparecen en new_violations; el recuento de las preexistentes se informa junto a ellas.

La lista completa de violaciones permanece en violations de cualquier manera: una línea base cambia el veredicto, nunca oculta hallazgos. Las claves coinciden por regla + sujeto, de modo que una actualización de ridge que reformule los detalles de una violación no invalidará una línea base confirmada. Sobrescribe la ubicación del archivo con baseline_file (restringido al repositorio escaneado).

Comprobaciones de inconsistencias de entorno

arch_validate también contrasta la resolución de módulos declarada contra el sistema de archivos, detectando desviaciones de configuración que rompen compilaciones sin aparecer jamás en el grafo de importaciones:

Regla	Severidad	Qué detecta
go_mod_replace_target_missing	alta	directiva replace de go.mod que apunta a una ruta local que no existe
tsconfig_baseurl_missing	alta	directorio baseUrl de tsconfig faltante: cada alias de ruta se resuelve contra él
tsconfig_path_target_missing	media	alias paths de tsconfig que mapea a una ubicación que no existe

El análisis de tsconfig tolera JSONC (comentarios y comas finales), y el recorrido respeta la lista de omisión del escáner (node_modules, vendor, ...).

Lenguajes compatibles

Lenguaje	Analizador	Detección
Go	go/ast (stdlib)	Paquetes, importaciones, manejadores HTTP, infraestructura
TypeScript/TSX	tree-sitter	Módulos, importaciones, rutas Express/Fastify/Koa, infraestructura
Python	tree-sitter	Módulos, importaciones, rutas Flask/FastAPI, infraestructura
Markdown	extracción de enlaces con regex	Notas, wiki-links de Obsidian [[note]], enlaces relativos [text](./file.md)

Detección de infraestructura

Los analizadores reconocen paquetes de infraestructura comunes y los clasifican automáticamente:

Categoría	Go	TypeScript	Python
Base de datos	database/sql, gorm, pgx, sqlx	pg, prisma, typeorm, mongoose, sequelize, drizzle-orm	sqlalchemy, django.db, pymongo, psycopg2, peewee, tortoise
Cola	amqp, kafka, nats	kafkajs, bullmq, amqplib, nats	celery, kombu, pika, kafka, rq
Caché	redis, memcache	ioredis, redis, keyv	redis, pymemcache, aiocache
Cliente HTTP	net/http (client)	axios, node-fetch, got, undici	requests, httpx, aiohttp, urllib3

Formatos de salida

Formato	Descripción
Mermaid	Sintaxis de diagramas de flujo, se renderiza en GitHub, Notion y la mayoría de visores de markdown
PlantUML	Diagramas de componentes con notación UML
C4	Diagramas de contenedores C4-PlantUML con !include <C4/C4_Container>
Structurizr DSL	Modelo de workspace para herramientas Structurizr
JSON	Datos estructurados con nodos, aristas y metadatos de topología
draw.io	Formato XML, se abre directamente en diagrams.net
Excalidraw	Formato JSON, se abre directamente en Excalidraw
HTML	Página autocontenida con el runtime de Mermaid incrustado en línea (~900 KB de salida, sin solicitudes de red)
forcegraph	Página autocontenida dirigida por D3 con diseño de fuerzas (~290 KB) con arrastre, zoom y paneo; color = componente conectado; el tamaño del nodo escala con el grado. Úsalo para grafos hub-spoke (bóvedas de conocimiento, redes de dependencias densas) donde el diseño jerárquico de Mermaid produce una franja horizontal larga. Combínalo con min_degree=10 para conservar solo los hubs

Configuración

Requisitos previos

• Go 1.24+
• Compilador de C (para los bindings CGo de tree-sitter; estándar en macOS y Linux)

Instalación

go install github.com/olgasafonova/ridge/cmd/ridge@latest

El binario se coloca en $GOPATH/bin (normalmente ~/go/bin/ridge).

O compilar desde el código fuente

git clone https://github.com/olgasafonova/ridge.git
cd ridge
make build

Configurar en Claude Code

Añade a tu ~/.claude.json:

{
  "mcpServers": {
    "ridge": {
      "command": "/path/to/ridge",
      "args": []
    }
  }
}

O ejecutar desde el código fuente:

{
  "mcpServers": {
    "ridge": {
      "command": "go",
      "args": ["run", "./cmd/ridge"],
      "cwd": "/path/to/ridge"
    }
  }
}

Opcional: instalar la skill incluida de Claude Code

skills/ridge/SKILL.md enseña a un agente cuál de las 19 herramientas de ridge llamar para una pregunta determinada (blast radius vs scan vs drift vs validate). Colócala una vez en tu directorio de skills de Claude Code y el modelo dejará de adivinar.

cp -r skills/ridge ~/.claude/skills/

La skill es markdown simple con una matriz de decisión de herramientas y ejemplos resueltos. Léela directamente si quieres tener el mismo mapa en tu cabeza.

Control de escaneo

Todas las herramientas de escaneo aceptan parámetros opcionales para manejar bases de código grandes:

Parámetro	Qué hace
max_files	Detenerse tras analizar N archivos (devuelve resultado parcial)
max_nodes	Detenerse tras descubrir N nodos de arquitectura
timeout_secs	Cancelar el escaneo tras N segundos
workers	Trabajadores de análisis en paralelo (predeterminado: número de CPU, máximo 8)
skip_dirs	Directorios adicionales para omitir (además de los predeterminados como node_modules, .git, vendor)
skip_globs	Patrones de archivo para omitir (p. ej. *_test.go, *.spec.ts)

Los resultados parciales incluyen una marca truncated: true para que sepas que el grafo está incompleto. Las llamadas secuenciales de herramientas sobre la misma ruta se almacenan en caché durante 30 segundos.

Escaneo incremental

Los escaneos repetidos sobre la misma base de código son rápidos. El servidor rastrea los tiempos de modificación de archivos y los hashes de contenido en ~/.mcp-context/ridge/. En escaneos posteriores, solo los archivos que realmente cambiaron se vuelven a analizar; los archivos sin cambios reutilizan los resultados de análisis en caché.

Las estadísticas en la respuesta muestran lo que ocurrió:

• files_analyzed — archivos totales en la base de código
• files_cached — archivos omitidos (sin cambios desde el último escaneo)
• files_changed — archivos reanalizados (nuevos, modificados o eliminados)

El primer escaneo de un proyecto de 500 archivos tarda unos segundos. Los escaneos posteriores tras editar 3 archivos tardan milisegundos.

Seguridad

Restringir raíces de escaneo (RIDGE_ALLOWED_DIRS)

Cada herramienta de escaneo devuelve muestras cortas y enmascaradas del código fuente de cualquier directorio al que se apunte. Por defecto, ridge escaneará cualquier directorio legible excepto una lista de denegación integrada de ubicaciones sensibles (/etc, /proc, /sys, /dev y archivos de puntos del directorio home como .ssh, .gnupg, .aws, .config/gcloud). Esa lista de denegación es un piso, no una lista de permitidos: bloquea rutas conocidas como sensibles pero aún permite escanear en cualquier otro lugar.

Para convertir esto en opt-in, establece RIDGE_ALLOWED_DIRS a una lista separada por dos puntos de rutas de directorio absolutas (estilo PATH). Cuando está establecida, ridge rechaza cualquier escaneo cuyo destino se resuelva a una ubicación fuera de esos directorios:

{
  "mcpServers": {
    "ridge": {
      "command": "/path/to/ridge",
      "args": [],
      "env": {
        "RIDGE_ALLOWED_DIRS": "/home/you/Projects:/home/you/work/repos"
      }
    }
  }
}

Detalles:

• Contención resuelta por symlink. Tanto el destino del escaneo como los directorios permitidos se resuelven con filepath.EvalSymlinks antes de la comprobación de contención, de modo que un symlink colocado en o bajo un directorio permitido no puede redirigir un escaneo a un destino externo.
• Cierre seguro ante mala configuración. Si RIDGE_ALLOWED_DIRS está establecida pero ninguna de sus entradas se resuelve a un directorio real, se rechaza todo escaneo en lugar de volver a permitir todo.
• Aviso de inicio. Al arrancar, ridge registra si la lista de permitidos está activa (con los directorios resueltos) o sin establecer. Una lista de permitidos sin establecer registra una advertencia de una línea para que el valor predeterminado permisivo sea visible en los registros del servidor.

La variable RIDGE_ALLOW_INREPO_RULES es independiente: opta por cargar el .arch-rules.yaml propio de un repositorio, que de otro modo se ignora para evitar que un repositorio escaneado degrade sus propias violaciones de reglas de arquitectura.

Desarrollo

make check       # fmt-check + vet + tests (with race detector)
make build       # Build binary
make test        # Tests only

Pruebas de integración

Ejecutar contra bases de código reales:

go test -tags integration -race -v ./tests/

O usar el script de prueba de humo:

bash scripts/smoke-test.sh

Arquitectura

cmd/ridge/          Entry point (stdio MCP transport)
internal/
  model/                   ArchGraph, Node, Edge, Diff types
  scanner/                 File walker, incremental change detection, analyzer orchestration
  analyzer/golang/         Go static analysis (go/ast)
  analyzer/typescript/     TypeScript analysis (tree-sitter)
  analyzer/python/         Python analysis (tree-sitter)
  analyzer/markdown/       Markdown link extraction (wiki-links, relative .md links)
  detector/                Boundary detection, topology, validation, metrics, recommendations, process traces
  drift/                   Snapshot comparison, git ref diffing, history
  render/                  Mermaid, PlantUML, C4, Structurizr, JSON, draw.io, Excalidraw, HTML, forcegraph
  infra/                   Cache, persistent state (~/.mcp-context/)
tools/                     MCP tool definitions and handlers

Licencia

MIT