Minh-gkg

TypeScript-accurate code graph for AI agents: compiler-grade find-references, change impact analysis, and repo maps, exposed as a CLI and an MCP server.

Clean-room combination of the best ideas from GitLab Knowledge Graph (local graph, MCP tools, repo map) and GitNexus (pre-commit impact analysis, agent-first tool surface) — no code from either project. Where those tools parse with tree-sitter heuristics, Minh-gkg uses the TypeScript compiler (via ts-morph), so cross-file references resolve through imports, aliases, re-exports and tsconfig path mappings exactly.

Scope: TypeScript/TSX projects with a tsconfig.json. That's the trade-off — one language, done precisely.

Install

git clone https://github.com/Minh090506/Minh-gkg.git
cd Minh-gkg && npm install
npm link   # exposes `minh-gkg` on PATH (optional)

Related MCP server: arcscope

CLI

minh-gkg search Booking --project ~/my-app     # find symbols by name substring
minh-gkg refs calculateTotal                   # every cross-file usage, compiler-resolved
minh-gkg refs Config src/lib                   # disambiguate with a file-path hint
minh-gkg impact                                # blast radius of uncommitted changes
minh-gkg impact --base master                  # blast radius vs a branch
minh-gkg repo-map src/features                 # condensed ASCII architecture map

--project <dir> defaults to the current directory; --tsconfig <path> for non-standard layouts.

MCP server (Claude Code / Cursor / Codex)

claude mcp add --scope project minh-gkg -- node /path/to/Minh-gkg/src/cli.js serve --project /path/to/your-app

Tools exposed: search_definitions, find_references, impact_of_changes, repo_map, reload_project.

Impact preflight: impact / impact_of_changes run git diff + a tsconfig root-set check before loading the TypeScript project. A clean working tree (or only changes outside the tsconfig program) returns an empty JSON result in under a second with essentially zero compiler RAM — no more multi-second / multi-GB cold start just to report "nothing changed".

Architecture: two tiers

search and refs/impact don't need the same amount of TypeScript understanding, so they run on two different engines:

• Syntax tier (search_definitions, repo_map) — a persistent index built with ts.createSourceFile per file (parse, extract declarations, discard the AST — never a full ts-morph Project). A lightweight TypeScript preprocessor/module-resolution pass expands tsconfig roots to the same imported program-file manifest as ts-morph, including files-only projects. Cached on disk at ~/.minh-gkg/<projectHash>/index.json, keyed by schema version + TypeScript version + the resolved tsconfig graph (path, full extends chain, content hashes) + compiler-options hash + the complete program-file manifest. Per-file freshness is {mtimeMs, size, contentHash}: a stat mismatch triggers a content-hash check, and only a real hash mismatch triggers a re-parse — so edits get picked up incrementally instead of a full rebuild. The file is written atomically (temp file + fsync + rename, 0600/0700 perms) behind a stale-PID-aware lockfile; a corrupt or version-mismatched file is discarded and silently rebuilt, never crashes the CLI/MCP process. On /Users/minhhome/mvt-saas (2,323 indexable files out of 2,329 program files): median warm-disk CLI search is 496ms / ~184MB RSS — versus ~6.5s / ~1.6GB for the old Project-backed path.

• Semantic tier (find_references, impact_of_changes) — unchanged: a real ts-morph Project, so cross-file references resolve through imports, aliases, re-exports, and tsconfig path mappings exactly (compiler-grade, not heuristic). It loads lazily on first use and holds ~2.5GB RAM while resident on a ~2.3k-file repo; after 10 minutes with no tool call the idle timer unloads it (next call pays cold-start again).

A shared generation counter (src/cache-coordinator.js) keeps the two tiers honest: when the syntax index notices a file changed, it bumps the generation and invalidates the cached semantic Project too, so a stale compiler cache can never silently outlive an on-disk edit. The MCP server's idle timer only ever unloads the semantic Project (the syntax index is light enough to stay resident); reload_project invalidates both tiers and lets the next query rebuild lazily rather than eagerly. Progress/build logging goes to stderr so it never pollutes MCP's stdio JSON-RPC channel.

Testing

npm test runs two golden-fixture gates. GATE A freezes search/repo-map output, including export lists/defaults, standalone declarations, destructuring, decorators, interfaces, imported files outside a files list, inherited path changes, and warmed add/delete/rename transitions. Accuracy goldens are generated from a ts-morph Project oracle, not from the syntax index under test. GATE B freezes compiler-backed refs/impact output. Goldens live in test/golden/ and are never auto-regenerated by npm test — run npm run golden:update to deliberately refresh them after an intentional engine change, then review the diff.

Two more suites cover behavior the golden gates can't see because it doesn't show up in output shape: test/syntax-index-no-project-load.test.js asserts search/repo-map never construct a ts-morph Project (using the call counter src/project-loader.js exposes for this, with a negative control proving the counter is real), and test/syntax-index-persistence.test.js covers a corrupt index.json self-healing instead of crashing and an edited file being picked up via the incremental refresh path (not a full rebuild).

Why not just gkg or GitNexus?

Use gkg/GitNexus for multi-language repos; use Minh-gkg when the repo is TypeScript and reference precision matters (refactors, money paths, pre-commit gates).

License

MIT