Back to search
repo-atlas
MCP serverGitHub
Deterministic zero-LLM codebase orientation map generator, git blast-radius analyzer, and ultra-lean 3-tool MCP server.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/pie527645-cloud--repo-atlas)HTML
<a href="/listings/pie527645-cloud--repo-atlas"><img src="/api/listings/pie527645-cloud--repo-atlas/badge.svg" alt="findsafeskills safety rating" /></a>Install
i
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
Requires **Node.js >= 20.18.1**.
git clone https://github.com/pie527645-cloud/repo-atlas.git cd repo-atlas npm install npm run build
Verify the build and test suite:
npm run lint npm test
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 140 lines
- # @pie527645-cloud/repo-atlas
- Deterministic codebase orientation map generator, reverse-import blast-radius analyzer, CI drift verifier, and ultra-lean 3-tool Model Context Protocol (MCP) server.
- `repo-atlas` gives developers and AI coding agents an accurate, token-budgeted structural map of a repository in milliseconds without burning context windows on full-file reads or heavy multi-dozen-tool MCP schemas.
- ## Key Capabilities
- - **Deterministic Token-Budgeted Orientation Maps**: Generates byte-identical Markdown (`REPO_ATLAS.md`) or structured JSON sorted lexicographically across platforms and line endings, strictly bounded within `Math.ceil(chars / 4) <= budgetTokens`.
- - **TypeScript & JavaScript AST Extraction**: Uses `ts.createSourceFile` to extract exported functions, classes, interfaces, type aliases, enums, and constants with concise single-line signatures, exact `file:line` locations, ES/CommonJS local import edges (`import`, `export ... from`, `require`), and `process.env` references.
- - **Polyglot Linear Scanner**: Scans Python (`.py`), Go (`.go`), Rust (`.rs`), and `package.json` (`scripts`, `bin`, `exports`, `dependencies`), plus environment variable usage (`os.environ`, `os.getenv`, `os.Getenv`, `std::env::var`) in guaranteed linear time without backtracking regular expressions.
- - **Dependency Graph Intelligence**: Computes module fan-in / fan-out hub rankings, detects circular dependency cycles via Tarjan Strongly Connected Components (SCC), and maps test files to covered source modules.
- - **Reverse-Import Blast Radius (`diff`)**: Computes direct and transitive reverse dependents plus recommended test files to run from `git diff` or an explicit `--files` list (even outside git repositories).
- - **CI Drift Gate (`check`)**: Verifies that `REPO_ATLAS.md` matches the current repository state (exiting `0` when synchronized and `1` when missing or stale).
- - **3-Tool Read-Only MCP Server**: Exposes `get_repo_overview`, `find_symbol`, and `blast_radius` over stdio with strict root containment.
- ## Architecture
- ```mermaid
- flowchart TD
- CLI["CLI (dist/cli.js)<br/>map | diff | check | mcp"] --> Guard["Path Containment Guard<br/>(src/path-guard.ts)"]
- MCP["MCP Server (dist/mcp.js)<br/>get_repo_overview | find_symbol | blast_radius"] --> Guard
- Guard --> Walker["Deterministic Walker & Linear .gitignore<br/>(<= 512 KB cap, binary skip)"]
- Walker --> TS["TS / JS AST Extractor<br/>(ts.createSourceFile)"]
- Walker --> Poly["Polyglot Linear Scanner<br/>(Python, Go, Rust, package.json, env vars)"]
- TS --> Resolver["Local Import Resolver<br/>(ESM .js->.ts, CJS, tsconfig paths, Go/Py/Rust)"]
- Poly --> Resolver
- Resolver --> Graph["Dependency Graph Engine<br/>(Hubs, Tarjan SCC Cycles, Test Mapper)"]
- Graph --> Atlas["Budgeted Atlas Renderer<br/>(Markdown & JSON)"]
- Graph --> Blast["Blast Radius & Git Diff<br/>(spawn shell: false)"]
- ```
- ## Installation (From Source)
- Requires **Node.js >= 20.18.1**.
- ```bash
- git clone https://github.com/pie527645-cloud/repo-atlas.git
- cd repo-atlas
- npm install
- npm run build
- ```
- Verify the build and test suite:
- ```bash
- npm run lint
- npm test
- ```
- ## CLI Usage
- Run the compiled CLI directly with `node`:
- ### 1. Generate a Repository Orientation Map (`map`)
- ```bash
- # Print a 4000-token markdown atlas to stdout
- node /abs/path/to/repo-atlas/dist/cli.js map /path/to/target-repo --budget 4000
- # Write REPO_ATLAS.md inside the target repository
- node /abs/path/to/repo-atlas/dist/cli.js map /path/to/target-repo --budget 4000 --out REPO_ATLAS.md
- # Emit structured JSON summary
- node /abs/path/to/repo-atlas/dist/cli.js map /path/to/target-repo --format json
- ```
- ### 2. Analyze Change Blast Radius (`diff`)
- ```bash
- # Analyze uncommitted + untracked git changes relative to HEAD
- node /abs/path/to/repo-atlas/dist/cli.js diff /path/to/target-repo --base HEAD
- # Compare against another git revision in JSON format
- node /abs/path/to/repo-atlas/dist/cli.js diff /path/to/target-repo --base main --format json
- # Analyze explicit files (works both inside and outside git repositories)
- node /abs/path/to/repo-atlas/dist/cli.js diff /path/to/target-repo --files src/graph.ts,src/walker.ts
- ```
- ### 3. Verify CI Drift (`check`)
- ```bash
- # Exit 0 if REPO_ATLAS.md is up to date, or exit 1 if missing or stale
- node /abs/path/to/repo-atlas/dist/cli.js check /path/to/target-repo --file REPO_ATLAS.md --budget 4000
- ```
- ### 4. Start the Stdio MCP Server (`mcp`)
- ```bash
- node /abs/path/to/repo-atlas/dist/cli.js mcp --root /path/to/target-repo
- # or directly via the dedicated MCP binary entrypoint:
- node /abs/path/to/repo-atlas/dist/mcp.js --root /path/to/target-repo
- ```
- ## MCP Server Configuration
- Configure your MCP client (such as Claude Desktop, Claude Code, Cursor, or Windsurf) using the absolute path to the built `dist/mcp.js` entrypoint:
- ```json
- {
- "mcpServers": {
- "repo-atlas": {
- "command": "node",
- "args": [
- "/abs/path/to/repo-atlas/dist/mcp.js",
- "--root",
- "/abs/path/to/target-repo"
- ],
- "env": {
- "REPO_ATLAS_ROOT": "/abs/path/to/target-repo"
- }
- }
- }
- }
- ```
- Root resolution precedence:
- 1. `--root` command-line argument
- 2. `REPO_ATLAS_ROOT` environment variable
- 3. `process.cwd()`
- ### Exposed MCP Tools (3 Tools)
- | Tool | Parameters | Description |
- | --- | --- | --- |
- | `get_repo_overview` | `path?` (string), `budgetTokens?` (integer, default `4000`) | Returns a deterministic Markdown architecture and symbol overview of the repository or a strictly confined subdirectory within the specified budget. |
- | `find_symbol` | `query` (string), `limit?` (integer, default `25`) | Searches exported functions, classes, interfaces, types, structs, traits, and constants across the repository, returning exact `file:line` locations and signatures. |
- | `blast_radius` | `files` (string[]) | Computes direct and transitive reverse-import dependents and recommended test files for a list of repository-relative file paths. |
- ## Security & Determinism Guarantees
- - **Strict Path Traversal Containment**: Every user- or tool-supplied path (`path`, `--out`, `--file`, `--files`, `blast_radius.files`) is normalized and checked against `fs.realpathSync(rootDir)`. Parent directory escapes (`..`), cross-drive / UNC paths, control characters, and symlinks or junctions resolving outside `rootDir` are rejected with `PathContainmentError`.
- - **Bounded Memory & Zero Backtracking**: Individual file reads enforce a strict `512 KB` cap (`524,288` bytes), binary files are skipped via extension and null-byte detection, and `.gitignore` / polyglot scanners run in guaranteed linear time without backtracking regular expressions.
- - **Command-Injection-Safe Git Execution**: Git queries invoke `spawn('git', args, { shell: false })` with validated base revision syntax (rejecting leading `-` option injection) and explicit `--` argument delimiters.
- - **Cross-Platform Determinism**: All paths are normalized to POSIX `/` separators, `\r\n` line endings are normalized to `\n`, and collections use ASCII code-point ordering rather than locale-dependent collation.
- ## License
- MIT
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.