An MCP server that reverse-engineers architecture from a directory tree. Point it at code (Go, TypeScript, Python) and it returns services, packages, databases, queues, endpoints, and their relationships as a structured graph. Point it at markdown (Obsidian vaults, doc trees) and wiki-links plus relative links become dependency edges in the same graph model. Generate diagrams in 9 formats including a self-contained D3 force-directed page for hub-spoke graphs. Detect drift between any two branches, tags, or commits. Validate architecture rules. Track how the system evolves over time.
MCP server that reverse-engineers architecture from code (Go, TypeScript, Python) and markdown into a structured graph. Detects drift between any two branches, tags, or commits
स्टार
7
टूल
—
अपटाइम
—
.md
No configuration files, no manual diagramming. Static analysis builds the architecture model directly from the source tree.
Why
Architecture diagrams go stale the day you commit them. When AI generates code faster than teams can comprehend the changes, the gap between system complexity and shared understanding grows. This is cognitive debt, and it compounds silently.
Most teams know they should review architecture regularly, check for circular dependencies, and catch structural drift between branches. In practice, these tasks are manual enough that they don't happen.
Generates architecture from the source tree (code or markdown), so diagrams are always current. No one has to maintain them.
arch_validate turns "check for circular dependencies" from a retro action item into a one-prompt task.
arch_drift compares architecture between any two git refs. It catches structural changes that code review misses: a new database dependency, a service that quietly became a monolith, an endpoint that bypasses the API gateway.
arch_drift_explain wraps that diff in a 2-5 sentence narrative you can paste straight into a PR description, standup channel, or release note. No LLM call; pure templating from the structured diff.
The killer use case: onboarding onto code you don't own
The single highest-value moment for Ridge is the one every engineer hits weekly: you have to change a codebase your team didn't build. The old kickoff for that work was reading the source, tracing dependencies, and building a mental model in your head. When an agent writes the code, that step disappears, and with it the understanding. So agents change systems nobody on the calling team actually comprehends, and architecture decisions get made by whoever (or whatever) writes the first line.
Ridge replaces the missing step. Point it at the unfamiliar tree and arch_scan + arch_generate produce a current architecture model — services, packages, infra, endpoints, and their edges — that an engineer can read in minutes instead of reverse-engineering by hand. The owning team can react to that, rather than to a Slack thread or a finished PR, so alignment happens before code exists instead of after.
This isn't hypothetical. Miro demoed the identical pattern at Canvas 26 ("Give Your Agentic Coding Tools the Full Picture," June 2026): a feature team needed to add tools to an MCP server another team owned, used an agent to read that codebase and generate an architecture board, and used it to onboard themselves and align with the owning team — without waiting on a backlog. Same problem, same shape, independently arrived at. Ridge makes that the default workflow rather than a one-off prompt.
What it does
Parses source files with language-specific analyzers (Go via go/ast, TypeScript and Python via tree-sitter, markdown via regex-based link extraction) and builds an architecture graph of nodes and edges.
Then ask arch_generate for a Mermaid diagram, arch_validate to check for circular dependencies, or arch_dataflow for structured traces showing how requests flow from endpoints to databases. Infrastructure (databases, queues, caches) is detected automatically from import paths.
Why not X
Four projects share parts of this space. None cover it the same way.
CodeFlow (2.0k stars, MIT) is a single-file React + D3 page that parses JS, TypeScript, and Python in the browser. It reads from GitHub's API, renders a file-level dependency graph, and adds panels for blast radius, security scans, and PR impact. Browser-native, file-granular. No Go support; requires CDN access; no agent interface.
CodeGraphContext (1.2k stars, alpha) is a Python MCP server that indexes code into KuzuDB, FalkorDB, or Neo4j via tree-sitter. 14-language support, dual CLI/MCP mode. Same agent surface as ridge, without endpoint detection, infrastructure classification, drift narratives, or cross-substrate scanning (code-only, no markdown).
Graphify (35k stars, MIT) is a multi-harness skill that turns any folder into a queryable knowledge graph: 25 code languages plus markdown, images, and video transcription. Persistent graph.json, SHA256 incremental cache, merge-graphs for cross-repo composition. Skill-scope, not MCP. No drift detection, no architecture-specific node types, no infrastructure inference.
CocoIndex (9.7k stars, Apache-2.0) is a Python-front, Rust-core incremental indexing framework that turns codebases, meeting notes, inboxes, Slack, PDFs, and videos into vector-searchable chunks for RAG. Code is one substrate of many. Different problem class: cocoindex answers "find me code semantically similar to query Q"; ridge answers "show me the structural graph and what changed architecturally between two refs." Use cocoindex when you want semantic chunk search across heterogeneous substrates. Use ridge when you want a typed architecture model with drift detection.
What ridge focuses on. Agent-facing MCP transport across all 19 tools. Go-native via go/ast. Drift narratives: arch_drift_explain returns a paste-ready PR paragraph in one call, no LLM round-trip. Cross-substrate: code and markdown share the same graph model, so arch_blast_radius answers "if I change internal/scanner, what else needs review?" across both. Infrastructure-aware (databases, queues, caches as typed nodes with confidence scores).
What ridge doesn't do. No browser-native UI. No multimodal ingest (images, video, audio). No semantic chunk search for RAG. If you want a file-level visualizer for JS/TS/Python with a UI, use CodeFlow. If you want a multimodal knowledge graph at skill scope, use Graphify. If you want incremental vector indexing across heterogeneous corpora, use CocoIndex.
Usage examples
Once configured, ask your LLM:
"Scan the architecture of ~/Projects/my-app"
"Generate a C4 diagram of this project"
"Are there any circular dependencies or layering violations?"
"Grandfather our existing violations, then fail only on new ones" (uses arch_validate baseline mode)
Find every node that transitively depends on a target — answers "if I change X, what else needs review?"
arch_drift
Compare architecture between two branches, tags, or commits
arch_drift_explain
Compare two refs and return a 2-5 sentence narrative summary plus the structured diff — paste-ready for PR descriptions
arch_dataflow
Trace data flow from endpoints to data stores with structured process traces
arch_validate
Check for circular dependencies, orphan nodes, layering violations, and environment inconsistencies — with a baseline mode that grandfathers existing violations and fails only on new ones
arch_recommend
Produce prioritized architecture improvement recommendations, each carrying the triggering metric evidence (value + threshold + node) and a confidence grade
All 19 tools
Tool
Category
What it does
arch_scan
analysis
Scan a codebase or markdown directory and return the full architecture graph
arch_focus
analysis
Scan a specific subdirectory or service
arch_dependencies
analysis
Map internal, external, and infrastructure dependencies
arch_blast_radius
analysis
Find the transitive set of nodes that depend on a target file or package
arch_dataflow
analysis
Trace data flow with entry-to-terminal process traces and confidence scores
arch_boundaries
analysis
Detect service boundaries and topology (monolith, monorepo, microservices), with the signals behind the verdict, the reason it fired, and an ambiguity flag for borderline calls
arch_explain
analysis
Explain topology, patterns, key decisions, and risks with code evidence
arch_generate
diagram
Generate a diagram in 9 formats
arch_diff
drift
Compare current architecture against a saved baseline
arch_drift
drift
Compare architecture between two git refs
arch_drift_explain
drift
Narrative summary of drift between two git refs (paste-ready prose)
Compute coupling, instability, and dependency depth scores
arch_recommend
validation
Prioritized improvement recommendations from metrics + violations + patterns, with per-rec evidence + confidence
arch_history
history
Show how architecture evolved over git history
arch_snapshot
export
Save current architecture as a baseline for drift detection
arch_registry_add
registry
Register a repo by alias for reuse across tool calls
arch_registry_list
registry
List all registered repos
arch_registry_remove
registry
Remove a registered repo alias
Known-violations baseline (ratchet)
Adopting arch_validate on a legacy codebase usually means a wall of pre-existing violations and a permanently red check. The baseline mode fixes the incentive: grandfather what exists, fail only on what's new.
baseline="write" saves the current violations to .arch-known-violations.json at the repo root. Commit the file so the whole team shares the ratchet.
baseline="check" validates as usual, but valid reflects only violations absent from the baseline. New ones land in new_violations; the grandfathered count is reported alongside.
The full violation list stays in violations either way — a baseline changes the verdict, never hides findings. Matching keys on rule + subject, so a ridge upgrade that rewords violation details won't invalidate a committed baseline. Override the file location with baseline_file (contained to the scanned repo).
Environment inconsistency checks
arch_validate also cross-checks declared module resolution against the filesystem, catching config drift that breaks builds without ever showing up in the import graph:
Rule
Severity
What it catches
go_mod_replace_target_missing
high
go.mod replace directive pointing at a local path that doesn't exist
tsconfig_baseurl_missing
high
tsconfig baseUrl directory missing — every path alias resolves against it
tsconfig_path_target_missing
medium
tsconfig paths alias mapping to a location that doesn't exist
tsconfig parsing tolerates JSONC (comments and trailing commas), and the walk honors the scanner's skip list (node_modules, vendor, ...).
Flowchart syntax, renders in GitHub, Notion, most markdown viewers
PlantUML
Component diagrams with UML notation
C4
C4-PlantUML container diagrams with !include <C4/C4_Container>
Structurizr DSL
Workspace model for Structurizr tooling
JSON
Structured data with nodes, edges, topology metadata
draw.io
XML format, open directly in diagrams.net
Excalidraw
JSON format, open directly in Excalidraw
HTML
Self-contained page with the Mermaid runtime embedded inline (~900 KB output, no network requests)
forcegraph
Self-contained D3-driven force-directed page (~290 KB) with drag, zoom, pan; color = connected component; node size scales with degree. Use for hub-spoke graphs (knowledge vaults, dense dependency networks) where Mermaid's hierarchical layout produces a long horizontal stripe. Pair with min_degree=10 to keep only hubs
Setup
Prerequisites
Go 1.24+
C compiler (for tree-sitter CGo bindings; standard on macOS and Linux)
Install
go install github.com/olgasafonova/ridge/cmd/ridge@latest
The binary lands in $GOPATH/bin (typically ~/go/bin/ridge).
Or build from source
git clone https://github.com/olgasafonova/ridge.git
cd ridge
make build
skills/ridge/SKILL.md teaches an agent which of the 19 ridge tools to call for a given question (blast radius vs scan vs drift vs validate). Drop it into your Claude Code skills directory once and the model stops guessing.
cp -r skills/ridge ~/.claude/skills/
The skill is plain markdown with a tool-decision matrix and worked examples. Read it directly if you want the same map in your head.
Scan control
All scan tools accept optional parameters for handling large codebases:
Parameter
What it does
max_files
Stop after analyzing N files (returns partial result)
max_nodes
Stop after discovering N architecture nodes
timeout_secs
Cancel scan after N seconds
workers
Parallel analysis workers (default: CPU count, max 8)
skip_dirs
Additional directories to skip (beyond defaults like node_modules, .git, vendor)
skip_globs
File patterns to skip (e.g. *_test.go, *.spec.ts)
Partial results include a truncated: true flag so you know the graph is incomplete. Sequential tool calls on the same path are cached for 30 seconds.
Incremental scanning
Repeat scans on the same codebase are fast. The server tracks file modification times and content hashes in ~/.mcp-context/ridge/. On subsequent scans, only files that actually changed get re-analyzed; unchanged files reuse cached analysis results.
The stats in the response show what happened:
files_analyzed — total files in the codebase
files_cached — files skipped (unchanged since last scan)
files_changed — files re-analyzed (new, modified, or deleted)
First scan of a 500-file project takes a few seconds. Follow-up scans after editing 3 files take milliseconds.
Security
Restricting scan roots (RIDGE_ALLOWED_DIRS)
Every scan tool returns short, masked source samples from whatever directory it is pointed at. By default ridge will scan any readable directory except a built-in denylist of sensitive locations (/etc, /proc, /sys, /dev, and home dotfiles like .ssh, .gnupg, .aws, .config/gcloud). That denylist is a floor, not an allowlist: it blocks known-sensitive paths but still permits scanning anywhere else.
To flip this to opt-in, set RIDGE_ALLOWED_DIRS to a colon-separated list of absolute directory paths (PATH-style). When set, ridge refuses any scan whose target resolves to a location outside those directories:
Symlink-resolved containment. Both the scan target and the allowlisted directories are resolved with filepath.EvalSymlinks before the containment check, so a symlink placed at or under an allowlisted directory cannot redirect a scan to an outside target.
Fail closed when misconfigured. If RIDGE_ALLOWED_DIRS is set but none of its entries resolve to a real directory, every scan is refused rather than reverting to permit-all.
Startup notice. On launch, ridge logs whether the allowlist is active (with the resolved directories) or unset. An unset allowlist logs a one-line warning so the permissive default is visible in the server logs.
The RIDGE_ALLOW_INREPO_RULES variable is separate: it opts into loading a repo's own .arch-rules.yaml, which is otherwise ignored to prevent a scanned repo from downgrading its own architecture-rule violations.
Development
make check # fmt-check + vet + tests (with race detector)
make build # Build binary
make test # Tests only
MCP server that reverse-engineers architecture from code (Go, TypeScript, Python) and markdown into a structured graph. Detects drift between any two branches, tags, or commits
अभी टूल सूची नहीं है। रिमोट सर्वर को पहले हेल्थ चेक के बाद सूची मिलती है।
FAQ
सवाल
Ridge कैसे इंस्टॉल करें?
इस पेज पर Cursor, Claude Desktop, Claude Code या VS Code के लिए stdio कॉन्फ़िग कॉपी करें। यह पब्लिशर का इंस्टॉल इस्तेमाल करता है, PlugMCP प्रॉक्सी नहीं।
क्या Ridge के लिए API key चाहिए?
इस रिकॉर्ड में कोई ज़रूरी एनवायरनमेंट वेरिएबल दर्ज नहीं है।
Ridge कौन सा ट्रांसपोर्ट इस्तेमाल करता है?
Ridge stdio पर लोकल चलता है।
Ridge की पिछली जाँच कब हुई थी?
पिछली जाँच 2026-11-10 को हुई। MCP server that reverse-engineers architecture from code (Go, TypeScript, Python) and markdown into a structured graph. Detects drift between any two branches, tags, or commits