Skip to content
Back to search

repo-atlas

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/pie527645-cloud--repo-atlas/badge.svg)](/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
  1. # @pie527645-cloud/repo-atlas
  2. Deterministic codebase orientation map generator, reverse-import blast-radius analyzer, CI drift verifier, and ultra-lean 3-tool Model Context Protocol (MCP) server.
  3. `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.
  4. ## Key Capabilities
  5. - **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`.
  6. - **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.
  7. - **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.
  8. - **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.
  9. - **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).
  10. - **CI Drift Gate (`check`)**: Verifies that `REPO_ATLAS.md` matches the current repository state (exiting `0` when synchronized and `1` when missing or stale).
  11. - **3-Tool Read-Only MCP Server**: Exposes `get_repo_overview`, `find_symbol`, and `blast_radius` over stdio with strict root containment.
  12. ## Architecture
  13. ```mermaid
  14. flowchart TD
  15. CLI["CLI (dist/cli.js)<br/>map | diff | check | mcp"] --> Guard["Path Containment Guard<br/>(src/path-guard.ts)"]
  16. MCP["MCP Server (dist/mcp.js)<br/>get_repo_overview | find_symbol | blast_radius"] --> Guard
  17. Guard --> Walker["Deterministic Walker & Linear .gitignore<br/>(<= 512 KB cap, binary skip)"]
  18. Walker --> TS["TS / JS AST Extractor<br/>(ts.createSourceFile)"]
  19. Walker --> Poly["Polyglot Linear Scanner<br/>(Python, Go, Rust, package.json, env vars)"]
  20. TS --> Resolver["Local Import Resolver<br/>(ESM .js->.ts, CJS, tsconfig paths, Go/Py/Rust)"]
  21. Poly --> Resolver
  22. Resolver --> Graph["Dependency Graph Engine<br/>(Hubs, Tarjan SCC Cycles, Test Mapper)"]
  23. Graph --> Atlas["Budgeted Atlas Renderer<br/>(Markdown & JSON)"]
  24. Graph --> Blast["Blast Radius & Git Diff<br/>(spawn shell: false)"]
  25. ```
  26. ## Installation (From Source)
  27. Requires **Node.js >= 20.18.1**.
  28. ```bash
  29. git clone https://github.com/pie527645-cloud/repo-atlas.git
  30. cd repo-atlas
  31. npm install
  32. npm run build
  33. ```
  34. Verify the build and test suite:
  35. ```bash
  36. npm run lint
  37. npm test
  38. ```
  39. ## CLI Usage
  40. Run the compiled CLI directly with `node`:
  41. ### 1. Generate a Repository Orientation Map (`map`)
  42. ```bash
  43. # Print a 4000-token markdown atlas to stdout
  44. node /abs/path/to/repo-atlas/dist/cli.js map /path/to/target-repo --budget 4000
  45. # Write REPO_ATLAS.md inside the target repository
  46. node /abs/path/to/repo-atlas/dist/cli.js map /path/to/target-repo --budget 4000 --out REPO_ATLAS.md
  47. # Emit structured JSON summary
  48. node /abs/path/to/repo-atlas/dist/cli.js map /path/to/target-repo --format json
  49. ```
  50. ### 2. Analyze Change Blast Radius (`diff`)
  51. ```bash
  52. # Analyze uncommitted + untracked git changes relative to HEAD
  53. node /abs/path/to/repo-atlas/dist/cli.js diff /path/to/target-repo --base HEAD
  54. # Compare against another git revision in JSON format
  55. node /abs/path/to/repo-atlas/dist/cli.js diff /path/to/target-repo --base main --format json
  56. # Analyze explicit files (works both inside and outside git repositories)
  57. node /abs/path/to/repo-atlas/dist/cli.js diff /path/to/target-repo --files src/graph.ts,src/walker.ts
  58. ```
  59. ### 3. Verify CI Drift (`check`)
  60. ```bash
  61. # Exit 0 if REPO_ATLAS.md is up to date, or exit 1 if missing or stale
  62. node /abs/path/to/repo-atlas/dist/cli.js check /path/to/target-repo --file REPO_ATLAS.md --budget 4000
  63. ```
  64. ### 4. Start the Stdio MCP Server (`mcp`)
  65. ```bash
  66. node /abs/path/to/repo-atlas/dist/cli.js mcp --root /path/to/target-repo
  67. # or directly via the dedicated MCP binary entrypoint:
  68. node /abs/path/to/repo-atlas/dist/mcp.js --root /path/to/target-repo
  69. ```
  70. ## MCP Server Configuration
  71. Configure your MCP client (such as Claude Desktop, Claude Code, Cursor, or Windsurf) using the absolute path to the built `dist/mcp.js` entrypoint:
  72. ```json
  73. {
  74. "mcpServers": {
  75. "repo-atlas": {
  76. "command": "node",
  77. "args": [
  78. "/abs/path/to/repo-atlas/dist/mcp.js",
  79. "--root",
  80. "/abs/path/to/target-repo"
  81. ],
  82. "env": {
  83. "REPO_ATLAS_ROOT": "/abs/path/to/target-repo"
  84. }
  85. }
  86. }
  87. }
  88. ```
  89. Root resolution precedence:
  90. 1. `--root` command-line argument
  91. 2. `REPO_ATLAS_ROOT` environment variable
  92. 3. `process.cwd()`
  93. ### Exposed MCP Tools (3 Tools)
  94. | Tool | Parameters | Description |
  95. | --- | --- | --- |
  96. | `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. |
  97. | `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. |
  98. | `blast_radius` | `files` (string[]) | Computes direct and transitive reverse-import dependents and recommended test files for a list of repository-relative file paths. |
  99. ## Security & Determinism Guarantees
  100. - **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`.
  101. - **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.
  102. - **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.
  103. - **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.
  104. ## License
  105. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.