Ridge

Ridge

Um servidor MCP que faz engenharia reversa de arquitetura a partir de uma árvore de diretórios. Aponte-o para código (Go, TypeScript, Python) e ele retorna serviços, pacotes, bancos de dados, filas, endpoints e suas relações como um grafo estruturado. Aponte-o para markdown (cofres do Obsidian, árvores de documentação) e wikilinks mais links relativos .md tornam-se arestas de dependência no mesmo modelo de grafo. Gere diagramas em 9 formatos, incluindo uma página D3 force-directed autocontida para grafos hub-spoke. Detecte desvios entre quaisquer dois branches, tags ou commits. Valide regras de arquitetura. Acompanhe como o sistema evolui ao longo do tempo.

Sem arquivos de configuração, sem diagramação manual. A análise estática constrói o modelo de arquitetura diretamente da árvore de origem.

Por quê

Diagramas de arquitetura ficam desatualizados no dia em que você os commita. Quando a IA gera código mais rápido do que os times conseguem compreender as mudanças, a lacuna entre a complexidade do sistema e o entendimento compartilhado cresce. Isso é dívida cognitiva, e ela se acumula silenciosamente.

A maioria dos times sabe que deveria revisar a arquitetura regularmente, verificar dependências circulares e detectar desvios estruturais entre branches. Na prática, essas tarefas são manuais o suficiente para que não aconteçam.

• Gera arquitetura a partir da árvore de origem (código ou markdown), então os diagramas estão sempre atualizados. Ninguém precisa mantê-los.
• arch_validate transforma "verificar dependências circulares" de um item de ação retroativo em uma tarefa de um único prompt.
• arch_drift compara a arquitetura entre quaisquer duas refs do git. Ele captura mudanças estruturais que a revisão de código não vê: uma nova dependência de banco de dados, um serviço que silenciosamente virou um monólito, um endpoint que ignora o API gateway.
• arch_drift_explain envolve esse diff em uma narrativa de 2 a 5 frases que você pode colar direto na descrição de um PR, no canal do standup ou na nota de release. Sem chamada de LLM; pura geração de template a partir do diff estruturado.

O caso de uso matador: onboarding em código que você não possui

O momento de maior valor para o Ridge é aquele que todo engenheiro enfrenta semanalmente: você precisa alterar uma base de código que seu time não construiu. O pontapé inicial antigo desse trabalho era ler o código-fonte, rastrear dependências e construir um modelo mental na sua cabeça. Quando um agente escreve o código, essa etapa desaparece, e com ela o entendimento. Então os agentes mudam sistemas que ninguém no time solicitante realmente compreende, e as decisões de arquitetura são tomadas por quem (ou o quê) escreve a primeira linha.

O Ridge substitui a etapa ausente. Aponte-o para a árvore desconhecida e arch_scan + arch_generate produzem um modelo de arquitetura atual — serviços, pacotes, infraestrutura, endpoints e suas arestas — que um engenheiro pode ler em minutos em vez de fazer engenharia reversa manualmente. O time proprietário pode reagir a isso, em vez de a um thread no Slack ou a um PR finalizado, para que o alinhamento aconteça antes de o código existir, e não depois.

Isso não é hipotético. A Miro demonstrou exatamente esse padrão na Canvas 26 ("Give Your Agentic Coding Tools the Full Picture", junho de 2026): um time de feature precisava adicionar ferramentas a um servidor MCP que outro time possuía, usou um agente para ler essa base de código e gerar um quadro de arquitetura, e o usou para fazer onboarding e alinhar com o time proprietário — sem esperar por um backlog. Mesmo problema, mesmo formato, chegando lá de forma independente. O Ridge torna isso o fluxo de trabalho padrão, em vez de um prompt pontual.

O que ele faz

Analisa arquivos-fonte com analisadores específicos por linguagem (Go via go/ast, TypeScript e Python via tree-sitter, markdown via extração de links baseada em regex) e constrói um grafo de arquitetura de nós e arestas.

Nós representam componentes: serviços, módulos, pacotes, bancos de dados, filas de mensagens, caches, APIs externas, endpoints HTTP e notas (arquivos markdown).

Arestas representam relações com pontuações de confiança: dependências (0,9), registros de endpoint (0,85), links de infraestrutura (0,8), chamadas de clientes HTTP (0,7). A confiança permite que consumidores filtrem por confiabilidade; imports resolvidos diretamente via AST pontuam mais alto do que correspondências heurísticas.

MCP (Model Context Protocol) permite que assistentes de IA chamem ferramentas externas. Este servidor dá ao seu assistente de IA 19 ferramentas de análise de arquitetura.

O que você obtém

Execute arch_scan em um projeto Go e receba um grafo de arquitetura estruturado:

{
  "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}
}

Em seguida, peça ao arch_generate um diagrama Mermaid, ao arch_validate para verificar dependências circulares, ou ao arch_dataflow para rastreamentos estruturados mostrando como as requisições fluem dos endpoints aos bancos de dados. A infraestrutura (bancos de dados, filas, caches) é detectada automaticamente a partir dos caminhos de import.

Por que não X

Quatro projetos compartilham partes desse espaço. Nenhum cobre da mesma forma.

CodeFlow (2,0 mil estrelas, MIT) é uma página React + D3 de arquivo único que analisa JS, TypeScript e Python no navegador. Ele lê da API do GitHub, renderiza um grafo de dependências em nível de arquivo e adiciona painéis para raio de explosão, varreduras de segurança e impacto de PR. Nativo do navegador, granularidade de arquivo. Sem suporte a Go; requer acesso a CDN; sem interface de agente.

CodeGraphContext (1,2 mil estrelas, alfa) é um servidor MCP em Python que indexa código em KuzuDB, FalkorDB ou Neo4j via tree-sitter. Suporte a 14 linguagens, modo dual CLI/MCP. Mesma superfície de agente que o ridge, sem detecção de endpoints, classificação de infraestrutura, narrativas de desvio ou varredura entre substratos (somente código, sem markdown).

Graphify (35 mil estrelas, MIT) é uma skill multi-harness que transforma qualquer pasta em um grafo de conhecimento consultável: 25 linguagens de código mais markdown, imagens e transcrição de vídeo. graph.json persistente, cache incremental SHA256, merge-graphs para composição entre repositórios. Escopo de skill, não MCP. Sem detecção de desvio, sem tipos de nó específicos de arquitetura, sem inferência de infraestrutura.

CocoIndex (9,7 mil estrelas, Apache-2.0) é um framework de indexação incremental com front em Python e núcleo em Rust que transforma bases de código, notas de reunião, caixas de entrada, Slack, PDFs e vídeos em blocos pesquisáveis vetorialmente para RAG. Código é um substrato entre muitos. Classe de problema diferente: o cocoindex responde "encontre código semanticamente semelhante à consulta Q"; o ridge responde "mostre-me o grafo estrutural e o que mudou arquiteturalmente entre duas refs." Use cocoindex quando quiser busca semântica por blocos entre substratos heterogêneos. Use o ridge quando quiser um modelo de arquitetura tipado com detecção de desvio.

No que o ridge foca. Transporte MCP voltado a agentes em todas as 19 ferramentas. Nativo em Go via go/ast. Narrativas de desvio: arch_drift_explain retorna um parágrafo pronto para PR em uma única chamada, sem ida e volta de LLM. Multi-substrato: código e markdown compartilham o mesmo modelo de grafo, então arch_blast_radius responde "se eu mudar internal/scanner, o que mais precisa de revisão?" em ambos. Ciente de infraestrutura (bancos de dados, filas, caches como nós tipados com pontuações de confiança).

O que o ridge não faz. Sem UI nativa no navegador. Sem ingestão multimodal (imagens, vídeo, áudio). Sem busca semântica por blocos para RAG. Se você quiser um visualizador em nível de arquivo para JS/TS/Python com UI, use o CodeFlow. Se quiser um grafo de conhecimento multimodal em escopo de skill, use o Graphify. Se quiser indexação vetorial incremental entre corpora heterogêneos, use o CocoIndex.

Exemplos de uso

Depois de configurado, pergunte ao seu LLM:

• "Escaneie a arquitetura de ~/Projects/my-app"
• "Gere um diagrama C4 deste projeto"
• "Existem dependências circulares ou violações de camadas?"
• "Anistie nossas violações existentes e depois falhe apenas nas novas" (usa o modo baseline do arch_validate)
• "Nossos aliases de caminho tsconfig e os alvos de replace do go.mod realmente existem?"
• "Compare a arquitetura entre a tag v1.0 e o branch main"
• "Como a arquitetura mudou desde o mês passado?"
• "A quais bancos de dados este serviço se conecta?"
• "Exporte a arquitetura como Excalidraw"
• "Explique as decisões de arquitetura nesta base de código"
• "Como devo melhorar esta arquitetura?"
• "Como estão o acoplamento e a instabilidade?"
• "Mostre-me rastreamentos de fluxo de dados dos endpoints da API para os bancos de dados"
• "Salve esta arquitetura como nossa baseline v2.0"
• "Escaneie este monorepo, mas limite a 500 arquivos e pule arquivos de teste"
• "Escaneie um cofre do Obsidian e encontre notas órfãs"
• "Renderize o diretório docs/ como um grafo force-directed mostrando hubs com grau>=10"
• "Se eu mudar internal/scanner, o que mais precisa de revisão?" (usa arch_blast_radius)

Ferramentas

Ferramentas principais

Ferramenta	O que ela faz
arch_scan	Escaneia um diretório de código ou markdown e retorna o grafo de arquitetura completo com arestas pontuadas por confiança
arch_generate	Gera um diagrama (Mermaid, PlantUML, C4, Structurizr, JSON, draw.io, Excalidraw, HTML, forcegraph)
arch_blast_radius	Encontra todo nó que depende transitivamente de um alvo — responde "se eu mudar X, o que mais precisa de revisão?"
arch_drift	Compara a arquitetura entre dois branches, tags ou commits
arch_drift_explain	Compara duas refs e retorna um resumo narrativo de 2 a 5 frases mais o diff estruturado — pronto para colar em descrições de PR
arch_dataflow	Rastreia o fluxo de dados de endpoints para armazenamentos de dados com rastreamentos de processo estruturados
arch_validate	Verifica dependências circulares, nós órfãos, violações de camadas e inconsistências de ambiente — com um modo baseline que anistia violações existentes e falha apenas nas novas
arch_recommend	Produz recomendações priorizadas de melhoria de arquitetura, cada uma com a evidência métrica que a acionou (valor + limite + nó) e um grau de confiança

Todas as 19 ferramentas

Ferramenta	Categoria	O que ela faz
arch_scan	análise	Escaneia um diretório de código ou markdown e retorna o grafo de arquitetura completo
arch_focus	análise	Escaneia um subdiretório ou serviço específico
arch_dependencies	análise	Mapeia dependências internas, externas e de infraestrutura
arch_blast_radius	análise	Encontra o conjunto transitivo de nós que dependem de um arquivo ou pacote alvo
arch_dataflow	análise	Rastreia o fluxo de dados com rastreamentos de processo entrada-terminal e pontuações de confiança
arch_boundaries	análise	Detecta limites e topologia de serviços (monólito, monorepo, microsserviços), com os sinais por trás do veredito, o motivo que o acionou e uma flag de ambiguidade para casos limítrofes
arch_explain	análise	Explica topologia, padrões, decisões-chave e riscos com evidência de código
arch_generate	diagrama	Gera um diagrama em 9 formatos
arch_diff	desvio	Compara a arquitetura atual com uma baseline salva
arch_drift	desvio	Compara a arquitetura entre duas refs do git
arch_drift_explain	desvio	Resumo narrativo do desvio entre duas refs do git (prosa pronta para colar)
arch_validate	validação	Verifica dependências circulares, órfãos, camadas e inconsistências de ambiente; o modo baseline ratcheteia bases de código legadas
arch_metrics	validação	Calcula pontuações de acoplamento, instabilidade e profundidade de dependência
arch_recommend	validação	Recomendações priorizadas de melhoria a partir de métricas + violações + padrões, com evidência + confiança por item
arch_history	histórico	Mostra como a arquitetura evoluiu ao longo do histórico do git
arch_snapshot	exportação	Salva a arquitetura atual como baseline para detecção de desvio
arch_registry_add	registro	Registra um repositório por alias para reuso entre chamadas de ferramentas
arch_registry_list	registro	Lista todos os repositórios registrados
arch_registry_remove	registro	Remove um alias de repositório registrado

Baseline de violações conhecidas (ratchet)

Adotar o arch_validate em uma base de código legada geralmente significa uma parede de violações pré-existentes e um check permanentemente vermelho. O modo baseline corrige o incentivo: anistie o que existe, falhe apenas no que é novo.

• baseline="write" salva as violações atuais em .arch-known-violations.json na raiz do repositório. Faça commit do arquivo para que todo o time compartilhe o ratchet.
• baseline="check" valida como de costume, mas valid reflete apenas violações ausentes da baseline. Novas violações vão para new_violations; a contagem de violações herdadas é reportada em conjunto.

A lista completa de violações permanece em violations de qualquer forma — uma baseline muda o veredito, nunca esconde descobertas. Chaves correspondentes em regra + assunto, para que uma atualização do ridge que reformule os detalhes das violações não invalide uma baseline já commitada. Substitua a localização do arquivo com baseline_file (restrito ao repositório escaneado).

Verificações de inconsistência de ambiente

arch_validate também verifica a resolução de módulos declarada contra o sistema de arquivos, capturando desvios de configuração que quebram builds sem nunca aparecer no grafo de importações:

Regra	Severidade	O que detecta
go_mod_replace_target_missing	alta	diretiva replace do go.mod apontando para um caminho local que não existe
tsconfig_baseurl_missing	alta	diretório baseUrl do tsconfig ausente — todo alias de caminho resolve contra ele
tsconfig_path_target_missing	média	alias paths do tsconfig mapeando para uma localização que não existe

O parsing do tsconfig tolera JSONC (comentários e vírgulas finais), e a varredura respeita a lista de exclusão do scanner (node_modules, vendor, ...).

Idiomas suportados

Idioma	Analisador	Detecção
Go	go/ast (stdlib)	Pacotes, imports, handlers HTTP, infraestrutura
TypeScript/TSX	tree-sitter	Módulos, imports, rotas Express/Fastify/Koa, infraestrutura
Python	tree-sitter	Módulos, imports, rotas Flask/FastAPI, infraestrutura
Markdown	extração de links via regex	Notas, wiki-links do Obsidian [[note]], links relativos [text](./file.md)

Detecção de infraestrutura

Os analisadores reconhecem pacotes de infraestrutura comuns e os classificam automaticamente:

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

Formatos de saída

Formato	Descrição
Mermaid	Sintaxe de fluxograma, renderiza no GitHub, Notion e na maioria dos visualizadores de markdown
PlantUML	Diagramas de componentes com notação UML
C4	Diagramas de contêiner C4-PlantUML com !include <C4/C4_Container>
Structurizr DSL	Modelo de workspace para ferramentas Structurizr
JSON	Dados estruturados com nós, arestas e metadados de topologia
draw.io	Formato XML, abre diretamente no diagrams.net
Excalidraw	Formato JSON, abre diretamente no Excalidraw
HTML	Página autocontida com o runtime Mermaid embutido inline (~900 KB de saída, sem requisições de rede)
forcegraph	Página autocontida dirigida por D3 com layout force-directed (~290 KB) com arrastar, zoom e pan; cor = componente conectado; tamanho do nó escala com o grau. Use para grafos hub-spoke (vaults de conhecimento, redes de dependência densas) onde o layout hierárquico do Mermaid produz uma faixa horizontal longa. Combine com min_degree=10 para manter apenas os hubs

Configuração

Pré-requisitos

• Go 1.24+
• Compilador C (para bindings CGo do tree-sitter; padrão em macOS e Linux)

Instalação

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

O binário é colocado em $GOPATH/bin (tipicamente ~/go/bin/ridge).

Ou compile a partir do código-fonte

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

Configure no Claude Code

Adicione ao seu ~/.claude.json:

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

Ou execute a partir do código-fonte:

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

Opcional: instale a skill do Claude Code incluída

skills/ridge/SKILL.md ensina a um agente qual das 19 ferramentas do ridge chamar para uma determinada pergunta (blast radius vs scan vs drift vs validate). Coloque-a no diretório de skills do seu Claude Code uma vez e o modelo para de adivinhar.

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

A skill é markdown simples com uma matriz de decisão de ferramentas e exemplos resolvidos. Leia-a diretamente se quiser o mesmo mapa na sua cabeça.

Controle de scan

Todas as ferramentas de scan aceitam parâmetros opcionais para lidar com codebases grandes:

Parâmetro	O que faz
max_files	Para após analisar N arquivos (retorna resultado parcial)
max_nodes	Para após descobrir N nós de arquitetura
timeout_secs	Cancela o scan após N segundos
workers	Workers de análise paralela (padrão: número de CPUs, máx. 8)
skip_dirs	Diretórios adicionais para pular (além dos padrões como node_modules, .git, vendor)
skip_globs	Padrões de arquivo para pular (ex.: *_test.go, *.spec.ts)

Resultados parciais incluem uma flag truncated: true para que você saiba que o grafo está incompleto. Chamadas sequenciais de ferramentas no mesmo caminho são cacheadas por 30 segundos.

Scan incremental

Scans repetidos no mesmo codebase são rápidos. O servidor rastreia horários de modificação de arquivos e hashes de conteúdo em ~/.mcp-context/ridge/. Em scans subsequentes, apenas arquivos que realmente mudaram são reanalisados; arquivos inalterados reutilizam resultados de análise em cache.

As estatísticas na resposta mostram o que aconteceu:

• files_analyzed — total de arquivos no codebase
• files_cached — arquivos pulados (inalterados desde o último scan)
• files_changed — arquivos reanalisados (novos, modificados ou excluídos)

O primeiro scan de um projeto com 500 arquivos leva alguns segundos. Scans de acompanhamento após editar 3 arquivos levam milissegundos.

Segurança

Restringindo raízes de scan (RIDGE_ALLOWED_DIRS)

Toda ferramenta de scan retorna amostras curtas e mascaradas de código-fonte de qualquer diretório para o qual for apontada. Por padrão, o ridge escaneia qualquer diretório legível, exceto uma denylist embutida de locais sensíveis (/etc, /proc, /sys, /dev e dotfiles do home como .ssh, .gnupg, .aws, .config/gcloud). Essa denylist é um piso, não uma allowlist: ela bloqueia caminhos conhecidamente sensíveis, mas ainda permite escanear qualquer outro lugar.

Para inverter isso para opt-in, defina RIDGE_ALLOWED_DIRS como uma lista separada por dois-pontos de caminhos absolutos de diretórios (estilo PATH). Quando definido, o ridge recusa qualquer scan cujo alvo resolva para uma localização fora desses diretórios:

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

Detalhes:

• Contenção resolvida por symlink. Tanto o alvo do scan quanto os diretórios na allowlist são resolvidos com filepath.EvalSymlinks antes da verificação de contenção, para que um symlink colocado em ou sob um diretório da allowlist não possa redirecionar um scan para um alvo externo.
• Falha fechada quando mal configurado. Se RIDGE_ALLOWED_DIRS estiver definido mas nenhuma de suas entradas resolver para um diretório real, todo scan é recusado em vez de reverter para permitir-tudo.
• Aviso na inicialização. Ao iniciar, o ridge registra se a allowlist está ativa (com os diretórios resolvidos) ou não definida. Uma allowlist não definida registra um aviso de uma linha para que o padrão permissivo fique visível nos logs do servidor.

A variável RIDGE_ALLOW_INREPO_RULES é separada: ela opta por carregar o .arch-rules.yaml do próprio repositório, que de outra forma é ignorado para impedir que um repositório escaneado rebaixe suas próprias violações de regras de arquitetura.

Desenvolvimento

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

Testes de integração

Execute contra codebases reais:

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

Ou use o script de teste smoke:

bash scripts/smoke-test.sh

Arquitetura

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

Licença

MIT