Server data from the Official MCP Registry
Static and dynamic call tracing MCP server backed by a SQLite property graph of your codebase
About
Static and dynamic call tracing MCP server backed by a SQLite property graph of your codebase
Security Report
Valid MCP server (3 strong, 3 medium validity signals). 5 known CVEs in dependencies (0 critical, 3 high severity) Package registry verified. Imported from the Official MCP Registry. Trust signals: 3 highly-trusted packages.
5 files analyzed Β· 6 issues found
Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.
Permissions Required
This plugin requests these system permissions. Most are normal for its category.
What You'll Need
Set these up before or after installing:
Environment variable: CODECRAWLER_DB
Environment variable: CODECRAWLER_EXCLUDE_DIRS
Environment variable: CODECRAWLER_DEFAULT_LIMIT
Environment variable: CODECRAWLER_MAX_DEPTH
Environment variable: CODECRAWLER_HELPFUL_ERRORS
How to Install
Add this to your MCP configuration file:
{
"mcpServers": {
"code-crawler": {
"command": "npx",
"args": [
"-y",
"@nithin554/code-crawler@0.1.92"
],
"env": {
"CODECRAWLER_DB": "your-codecrawler-db-here",
"CODECRAWLER_MAX_DEPTH": "your-codecrawler-max-depth-here",
"CODECRAWLER_EXCLUDE_DIRS": "your-codecrawler-exclude-dirs-here",
"CODECRAWLER_DEFAULT_LIMIT": "your-codecrawler-default-limit-here",
"CODECRAWLER_HELPFUL_ERRORS": "your-codecrawler-helpful-errors-here"
}
}
}
}Some servers take additional arguments. See the repository for details.
Documentation
View on GitHubFrom the project's GitHub README.
Code-Crawler
Static + dynamic call tracing MCP server backed by a persistent property graph of your codebase.
Code-Crawler indexes a project into a SQLite-backed property graph β files, packages, modules, classes, interfaces, methods, fields, imports, annotations/decorators, call edges, virtual dispatch, aspect advice, and the wiring frameworks add (entry points, routes, injected dependencies, reflective lookups) β then exposes that graph to LLM clients as MCP tools: find callers, trace call paths, explore neighborhoods, follow runtime dispatch, and search symbols across the whole codebase.
Supports Java, Python, TypeScript, and JavaScript projects, and can index all of them into the same graph.
π Documentation site: https://nithin554.github.io/code-crawler/
π Task-oriented guide: USAGE.md
πΊοΈ Roadmap: ROADMAP.md
ββββββββββββββββββββββββ MCP (stdio) ββββββββββββββββββββββββ
β crawl_project search_symbols get_callers get_callees β
β trace_path trace_execution find_aspects get_decoratorsβ
β find_implementations find_hotspots find_dead_code ... β
βββββββββββββββββ¬βββββββββββββββββββββββββββββββ¬ββββββββββββββββ
β β
ββββββββΌββββββββ ββββββββββΌβββββββββ
β crawler β β graph queries β
β parse+resolveβ β recursive CTEs β
ββββββββ¬ββββββββ ββββββββββ¬βββββββββ
β β
ββββββββΌβββββββββββββββββββββββββββββββΌβββββββ
β SQLite property graph (WAL) β
β nodes (kind, fqn, props) + edges (kind) β
βββββββββββββββββββββββββββββββββββββββββββββββ
Why a graph?
Plain-text grep can't answer questions like:
- "Who transitively calls
OrderRepository#create?" - "Is there a static path from
Main#maintoTracking#dispatch?" - "What is the impact radius of changing
OrderService#place?"
These need graph traversal. Code-Crawler builds the graph once (idempotently, file-by-file) and answers them with bounded recursive SQL queries.
Features
- Four languages, one graph: Java (
tree-sitter-java), Python (tree-sitter-python), TypeScript (tree-sitter-typescript,tree-sitter-tsx), and JavaScript (tree-sitter-javascript) β all WASM, no native build step. Language is detected per file, so a polyglot repo lands in a single graph. - Dynamic tracing on a static graph β
DYNAMIC_DISPATCHedges connect interface/base calls to every override in the project, andADVISESedges weave AspectJ/Spring AOP advice into execution traces (before,after,around,after-returning,after-throwing, named@Pointcutreferences,&&/||/!andexecution,within,@annotation,@within,target,this,argsprimitives). - Run-time indirection is named, not lost β Java reflection/
ServiceLoader, Pythongetattr/importlib, and JSrequire/dynamicimport()produceREFLECTSedges to the resolved symbol when the target is statically determinable, or to a__reflect__:marker when it is not. - Framework wiring β dependency injection (
@Autowired, NestJS constructor injection, FastAPIDepends) becomesINJECTSedges, and HTTP routes (@GetMapping,@RequestMapping, NestJS@Controller/@Get, FastAPI/Flask/Quart decorators, Expressapp.get) becomeROUTESedges to the handler, which is also marked as an entry point. - Control flow on call edges β every
CALLSedge records whether the call is conditional and the compact source text of its enclosing guards/loops, so an agent can tell a happy path from an error path without reading the file. - External dependencies are explicit β third-party imports and runtime globals
become package-level
external_symbolnodes withREFERENCESedges and afind_external_dependenciessummary, distinct from project code. - Annotations as first-class nodes β
@Transactional,@Cacheable,@Async,@Retryable, Python decorators, and TS decorators becomeannotationnodes withANNOTATED_WITHedges, so you can query decorators on types, methods, and fields. - Call resolution heuristics that go beyond naive string matching:
receiver types inferred from locals, parameters, fields,
new T()expressions,self/thisscoping, dotted paths (service.repo.find), loop-variable element types, bare/this/supercalls, static/qualified calls, and superclass chains. Unresolvable calls becomeunknown_symbolphantom nodes withresolved:falseedges, so the graph stays traversable. - Incremental, file-scoped indexing β each crawl records a per-file manifest
(
size, mtime, SHA-256) and replays the cached parse result for files whose content is unchanged, so a re-crawl re-parses only what actually changed. Changes are reported asfilesAdded/filesUpdated/filesUnchanged/filesRemoved. Derived dynamic edges and orphan pruning are rebuilt only when something changed. A full re-crawl still removes files that disappeared, without duplicating the graph, and scoped crawls (fileFilteror a forcedlanguage) never remove files outside their scope. When a checkout,rsync -t, an mtime-preserving unzip, or clock skew restores an edit with the old size and mtime, the shortcut misses it β passforce(--forceon the CLI) to re-parse everything. - FTS5-backed symbol search β symbol lookup runs against an external-content FTS5 index
with BM25 ranking and exact/prefix boosting, falling back to a
LIKEscan only when FTS finds nothing. Search does not degrade as the graph grows. - Versioned schema with automatic migration β the database carries a schema version and upgrades itself in place on open. A database written by a newer build is rejected with a clear message instead of being read as if the shape were known.
- A database per project β the index lives in
<project>/.code-crawler/index.db, so two repositories can never collide. Pointing a populated database at a different project fails with aclear_indexhint instead of silently wiping the first index. - Analytics β hotspots (fan-in/fan-out/advice counts) and dead-code candidates.
- Self-contained: single SQLite file, no external services.
- LLM-friendly: every tool returns structured JSON, unknown symbols come back with fuzzy search suggestions.
Install & build
Requires Node.js β₯ 22.12 (better-sqlite3@13 and the Vitest toolchain both need it).
npm install
npm run build # tsc β dist/
npm test # vitest (full suite; set CODECRAWLER_BENCH=1 for the scale test)
npm run lint # biome check (lint + format, fails CI)
npm run format # biome format --write
npm run coverage # vitest run --coverage (thresholds in vitest.config.ts)
npm run bench # crawl/query benchmark on a generated ~137k-line project
CLI
codecrawler crawl <path> # index a project
codecrawler crawl <path> --force # re-parse every file, ignoring cached metadata
codecrawler status # index summary
codecrawler query <symbol> # fuzzy-lookup a symbol
codecrawler serve # start the MCP server over stdio (default)
Environment variables:
| Variable | Default | Purpose |
|---|---|---|
CODECRAWLER_DB | <project>/.code-crawler/index.db | Database path. Resolved from the cwd upward, so each project gets its own file; falls back to ~/.code-crawler/index.db when no project encloses the cwd. The home directory is only that fallback, never an enclosing project |
CODECRAWLER_EXCLUDE_DIRS | .git,node_modules,dist,build,target,... | Dirs skipped during crawl |
CODECRAWLER_DEFAULT_LIMIT | 50 | Default result cap |
CODECRAWLER_MAX_DEPTH | 10 | Traversal depth cap (1β100) |
CODECRAWLER_MAX_FILE_BYTES | 1000000 | Files larger than this are skipped, not parsed |
CODECRAWLER_RESPECT_GITIGNORE | true | Honor the project's .gitignore during discovery |
CODECRAWLER_HELPFUL_ERRORS | true | Fuzzy suggestions on symbol misses |
CODECRAWLER_PLUGIN | unset | Plugin mode: resolve one database per project at call time instead of opening one file at startup |
CODECRAWLER_PLUGIN_ROOT | unset | Plugin install directory, never indexed as a project |
CODECRAWLER_PLUGIN_DATA | temp dir | Writable directory for the no-project fallback database |
Invalid values never crash the server: booleans fall back to their default and integers are clamped to their documented range, each with a one-line warning on stderr.
What gets indexed
crawl walks the project and skips .git, node_modules, build output, and
other CODECRAWLER_EXCLUDE_DIRS entries. On top of that:
-
the project's
.gitignoreis honored (disable withCODECRAWLER_RESPECT_GITIGNORE=false), -
an optional
.crawlerrcin the project root can narrow or widen discovery with gitignore-style globs, and relocate where module ids start:{ "include": ["src/", "packages/core/"], "exclude": ["**/generated/"], "moduleRoots": ["src"] }When
includeis non-empty, only matching files are indexed. A malformed.crawlerrcis ignored with a warning rather than failing the crawl.moduleRootsis opt-in: with["src"],src/orders/service.tsbecomes the moduleorders.serviceinstead ofsrc.orders.service, which is what abaseUrl-or-PYTHONPATHproject actually imports. It is never inferred, because inferring it would silently renumber an existing index. TypeScript and JavaScript projects also get path aliases for free:compilerOptions.pathsandbaseUrlare read fromtsconfig.json(orjsconfig.json), followingextendswithin the project, soimport { x } from "@app/orders/service"resolves to the real module instead of being recorded as external. Changing either setting re-parses cached files on the next crawl. -
files above
CODECRAWLER_MAX_FILE_BYTESand files that look binary are skipped;crawl_projectreports them inskippedFileswith a reason. -
per-file parse failures never abort the crawl; they are reported in
parseErrors.
Only the root .gitignore is read β nested .gitignore files are not yet
supported.
Incremental crawls
A crawl records a manifest row per file (size, mtime, SHA-256, language). On the
next crawl a file whose size and truncated mtime both match is served from a cached
parse result instead of being re-read and re-parsed; a file whose mtime changed but
whose hash did not is also replayed from cache. Resolution, phantom-node creation and
derived edges still run over the whole in-memory file set, so cross-file edges stay
correct β only I/O, parsing and database writes are skipped.
crawl_project reports the split:
| Field | Meaning |
|---|---|
filesAdded | First seen by this crawl |
filesUpdated | Content changed, re-parsed |
filesUnchanged | Replayed from the parse cache |
filesRemoved | Disappeared from disk and were pruned |
Known limitation: because an unchanged file's edges are not rewritten, a call that
becomes newly resolvable only because some other file changed (for example a method
gained an overload, or a class was introduced that a previously-ambiguous call could
now bind to) will not be upgraded in the untouched file. Touch that file, or run
clear_index, to force full resolution.
Benchmarks
npm run bench generates a synthetic TypeScript project (575 modules, ~137k lines,
~9.8k methods), crawls it, and reports crawl phases and query latency percentiles.
tests/perf.test.ts asserts the same budgets and is opt-in, because a realistic
corpus takes time to crawl:
npm run bench # human-readable report
CODECRAWLER_BENCH=1 npm test -- tests/perf.test.ts # enforce the budgets
CODECRAWLER_BENCH_LINES=20000 npm run bench # smaller corpus
Measured on a Windows dev laptop with a warm disk cache; absolute numbers vary, the ratios and the index usage are what matter:
| Phase | Duration | Added | Updated | Unchanged |
|---|---|---|---|---|
| Cold crawl | 22.5 s | 575 | 0 | 0 |
| Re-crawl, nothing changed | 0.91 s | 0 | 0 | 575 |
| Re-crawl after a one-file edit | 0.75 s | 0 | 1 | 574 |
| Query | p50 | p95 | Budget (p95) |
|---|---|---|---|
search_symbols (exact) | 0.69 ms | 1.96 ms | 50 ms |
search_symbols (prefix) | 1.60 ms | 4.09 ms | 50 ms |
get_callers (depth 2) | 0.16 ms | 0.21 ms | 50 ms |
get_callees (depth 2) | 0.11 ms | 0.15 ms | 50 ms |
get_subgraph (radius 2) | 0.16 ms | 0.27 ms | 50 ms |
find_entry_points | 0.12 ms | 0.29 ms | 50 ms |
find_hotspots | 145.5 ms | 181.4 ms | 1000 ms |
find_dead_code | 99.8 ms | 290.3 ms | 1000 ms |
The index is 66 MB for those 14.4k nodes / 38.8k edges. find_hotspots and
find_dead_code are whole-project aggregations over every edge and node, which is why
their band is an order of magnitude looser than the symbol lookups; both were profiled
with EXPLAIN QUERY PLAN and are served by idx_edges_target_kind.
Agent cost: graph versus grep-and-read
npm run bench:ergonomics measures ten structural questions (who calls this, what runs on
this endpoint, what breaks if I change this, what is dead) on the four pinned benchmark
projects, against the real MCP server and against a model of text search plus reading every
file a search hit. Across the ten, the graph answered in 12 tool calls / 22,907 tokens
where grep-and-read cost 120 calls / 105,758 tokens β and 8,553 tokens with
compact: true. Reads are capped at 20 files and the dead-code baseline is handed the
answer set for free, so the baseline is under-charged.
Where plain search wins is measured too: a question about template text or a config key has no graph answer, and a one-file lookup is cheaper as a search. Use the graph for structure, search for text. The full comparison, method and caveats are on the accuracy page.
CI & publishing
GitHub Actions runs on every pull request (pull-request.yml): npm ci β
typecheck β tests β build β smoke-test of the built CLI.
Merges to main trigger publish.yml, which re-runs the same checks and then,
if green, auto-releases:
- Reads the most recent
v*tag (orpackage.jsonversion on the first run), computes the next patch version, and pushes avX.Y.Ztag. - Creates a matching GitHub release.
- Publishes the package to the npm registry with provenance (OIDC trusted publishing) β no token or repository secret is needed. The step is idempotent and retries: it skips versions npm already has, and a transient transparency-log or registry failure no longer aborts the release.
- Publishes
server.jsonto the official MCP Registry asio.github.nithin554/code-crawlerfrom a separate, re-runnable job usingExaDev/mcp-registry-publish. The job runs inside themcp-registry-publishenvironment, whose deployment branch policy is limited tomain. It pinsserver.jsonto the release version, authenticates with GitHub OIDC, skips versions the registry already lists, and retries transient npm propagation or registry errors. Ownership is verified through themcpNamefield inpackage.json.
Using as an MCP server
Install as an agent plugin
The repository is also an agent plugin, so Claude Code and Copilot CLI can install the server and the skill together:
# Claude Code
/plugin marketplace add nithin554/code-crawler
/plugin install code-crawler@code-crawler
# Copilot CLI
copilot plugin marketplace add nithin554/code-crawler
copilot plugin install code-crawler@code-crawler
The plugin runs npx -y @nithin554/code-crawler serve. Agent Plugins clients start a
plugin's stdio servers inside the plugin directory, so the server does not treat that
directory as your checkout: it resolves a project from crawl_project, the client's
workspace roots, or the project this session already selected, and keeps that graph in
<project>/.code-crawler/index.db β one database per repository, the same layout the CLI
uses. CODECRAWLER_DB still pins a single file when you want one.
The same skill is published to ClawHub as code-crawler, and the
plugin is published there too:
- Skill β
clawhub install code-crawler. ClawHub assigns this version by bumping the patch digit of whatever it already published, so it advances one release at a time instead of copying the npm version; a release whose skill publish fails leaves the two numbers one apart until the next publish. - Plugin β published as the
code-crawlerbundle plugin, versioned from the release tag: releasev0.1.67publishes the bundle at0.1.67. The bundle's ownplugins/code-crawler/package.jsonis packaging metadata β ClawHub needs a package manifest to inspect the bundle and build its ClawPack artifact, and warns when one is missing β so the release workflow stamps the tag's version into it, packs the bundle, and publishes that tarball; the committedversionis only a placeholder.
The plugin publish runs the official clawhub CLI itself, under Node, rather than calling
upstream's reusable package-publish.yml. That workflow cannot publish this bundle: it
inspects the packed artifact with bun ... package validate, and the CLI refuses to run under
Bun ("Plugin validation requires Node.js 22.13+ (22.x) or 24+"). A ClawPack always contains
package/package.json and no input skips the step, so the call only ever succeeded while the
bundle had no manifest β the very thing ClawHub warns about.
Publishing is restricted to main. The publishing jobs deploy through the clawhub-publish
environment, whose deployment branch policy rejects any other ref, so a manual dispatch from
a feature branch stops before it can upload. CLAWHUB_TOKEN is a repository secret, not an
environment secret: the skill call hands it to upstream, which reads it as clawhub_token, and
a job that calls a reusable workflow cannot declare an environment. Forwarding the value
through a job output does not help either β GitHub refuses to emit a secret-valued output and
logs Skip output 'clawhub_token' since it may contain secret.
One command
add-mcp registers the server in whichever
client you name β Claude Code, Cursor, VS Code, Claude Desktop, Codex, OpenCode, Zed, and
more (npx add-mcp list-agents). Run it from inside the repository you want indexed:
npx add-mcp @nithin554/code-crawler --args serve -a cursor
That writes project-scoped config next to the code (.mcp.json, .cursor/mcp.json,
.vscode/mcp.json, β¦), so each repository carries its own registration and its own
.code-crawler/index.db. The server name code-crawler is derived from the package.
--env CODECRAWLER_DB is optional β add it only to put the database somewhere else:
--env CODECRAWLER_DB=/absolute/path/to/index.db. -g writes user-level config instead. Prefer that only for clients that launch the server
with your checkout as its working directory: with -g and an unrelated working directory
(Claude Desktop starts in its own install folder) the server falls back to
~/.code-crawler/index.db, and every repository then competes for that one file.
One server per project
Outside plugin mode a server process opens one database at startup and a database holds exactly one project, so the model is one registration per repository β which is what the per-project config above gives you. The plugin install instead resolves a database per project at call time, so one plugin serves every repository you open. Re-crawling a repository reuses its existing file and only re-parses what changed; two repositories never share a file, so they cannot clash. Only a few project databases stay open at once (idle ones are closed), and every handle is released when the client disconnects.
MCP Registry / npx
The server is listed in the MCP Registry as io.github.nithin554/code-crawler.
Any npx-capable client can run it without a local checkout:
{
"mcpServers": {
"code-crawler": {
"command": "npx",
"args": ["-y", "@nithin554/code-crawler", "serve"]
}
}
}
Claude Desktop
claude_desktop_config.json:
{
"mcpServers": {
"code-crawler": {
"command": "node",
"args": ["/absolute/path/to/code-crawler/dist/index.js", "serve"],
"env": { "CODECRAWLER_DB": "/absolute/path/to/your/index.db" }
}
}
}
Cursor / other stdio MCP clients
Point the client at the same command. The typical flow for an LLM agent:
crawl_projectthe repo once.find_entry_pointsto see where execution actually starts (routes, listeners, mains).search_symbolsto locate the symbol of interest.get_callers/get_callees/trace_pathto reason about the call graph.trace_executionto follow runtime dispatch and aspect advice;find_aspects,get_decorators, andfind_annotatedto inspect behaviour-changing annotations.find_routes,find_injections,find_reflections, andfind_external_dependenciesto map framework wiring and third-party surface.
See USAGE.md for the full task-oriented walkthrough.
MCP surface
Tools
| Tool | Purpose |
|---|---|
crawl_project | Index a directory (idempotent; one project per database) |
index_status | Node/edge/file counts + last crawl |
search_symbols | Fuzzy lookup by name or FQN, optional kind filter |
get_node | Metadata + source location for one symbol |
get_callers | Direct or transitive callers (depth-bounded) |
get_callees | Direct or transitive callees (depth-bounded) |
trace_path | Static call paths between two symbols (BFS, shortest first) |
trace_execution | Dynamic trace: static calls + virtual dispatch + woven advice |
find_implementations | Implementers/subclasses of an interface or superclass |
find_aspects | Aspects, advice kinds, pointcuts, and intercepted methods |
get_decorators | Annotations/decorators on a symbol and optionally its members |
find_annotated | Every symbol annotated with a given annotation |
find_hotspots | Rank methods by fan-in, fan-out, and advice interceptions |
find_dead_code | Methods with no incoming call/dispatch/advice edges |
find_entry_points | Framework-invoked roots: HTTP routes, listeners, schedulers, CLI mains, tests |
find_routes | HTTP route β handler mappings (@GetMapping, NestJS, FastAPI, Express) |
find_event_flows | Publisher β listener wiring: Spring events, Kafka/JMS, @OnEvent |
find_injections | DI-supplied dependencies (@Autowired, NestJS, FastAPI Depends) |
find_reflections | Run-time lookups: Class.forName, getattr, importlib, dynamic import() |
find_external_dependencies | Third-party packages with reference and file counts |
find_unresolved | Call sites the resolver could not bind, grouped by failure reason |
impact_analysis | Callers + entry points + routes + overrides + risk band in one call |
change_impact | Ranked blast radius for a whole diff, file list or symbol list, with injection points and advice |
explain_symbol | One-shot digest: members, decorators, callers, callees, wiring |
find_cycles | Call cycles (SCCs) with a sample closed path, plus direct recursion |
export_graph | Neighborhood rendered as Mermaid or Graphviz DOT |
get_subgraph | Neighborhood extraction for visualization |
get_schema | Describe the graph model |
clear_index | Reset the database |
Resources: codecrawler://schema, codecrawler://status
Prompt: trace-call-path(from, to)
Token budgeting. The 19 list-returning query tools β every tool whose payload is a
single result list β accept max_tokens (100β200000) and cursor. Passing either adds a
page block with totalCount, returnedCount, truncated, estimatedTokens, and
nextCursor; omit both and the response shape is unchanged, so existing clients keep
working. Paging never returns an empty page while items remain, so a continuation loop
always terminates. Token counts are estimates from JSON length (~4 characters per token) β
no tokenizer dependency, deterministic across models.
get_subgraph is the one exception: its nodes and edges are two views of the same slice,
so cutting one list would leave edges pointing at omitted nodes. It is bounded by radius and
limit instead. Aggregate tools (impact_analysis, explain_symbol, export_graph) and
single-object tools (get_node, index_status, get_schema) return one object and take no
budget.
Compact responses. Every tool accepts compact: true, which returns each symbol
reference as its fully-qualified name (com.acme.Payment#pay) instead of an
{id, name, kind, filePath} object. It is a structural projection applied in one place, so it
works the same on all 29 tools, and it measured 61% smaller (get_callers) to 83%
(search_symbols) on the dynamic-dispatch fixture. A qualified name already says whether it
is a type (pkg.Type) or a member (pkg.Type#member); call get_node with that name to get
the metadata back. The budget is computed before the projection runs, so a compact page holds
the same items as the non-compact one and costs less β it is a size win, not a packing win.
Agent skill
The server tells an agent what it can call; the skill tells it when. skills/code-crawler/
ships in the npm package and is plain Markdown β SKILL.md for discovery and the
crawl-first workflow, reference/tools.md mapping every tool to the questions they
answer, and reference/edge-semantics.md explaining confidence, external, and phantom
nodes.
npx skills add nithin554/code-crawler
The skills CLI finds it by convention and installs to whichever agents
you pick; npx skills update refreshes it. To install by hand instead, copy the directory
into your client's skills folder (~/.claude/skills/code-crawler/,
.claude/skills/code-crawler/, or a plugin's skills/ root). No build step. See
USAGE.md.
tests/skill.test.ts asserts the skill's tool table against the live registry, so it
cannot drift as tools are added.
Graph model
Nodes β kind is one of file | package | module | class | interface | enum | method | constructor | field | import | external_symbol | aspect | annotation_type | annotation | unknown_symbol. Every node has a globally unique qualifiedName and a JSON properties
blob (signature, modifiers, lines, annotations, ...).
Edges β kind is one of CALLS | DECLARED_IN | CONTAINS | IMPLEMENTS | EXTENDS | IMPORTS | REFERENCES | DYNAMIC_DISPATCH | ADVISES | ANNOTATED_WITH | REFLECTS | INJECTS | ROUTES | EMITS. CALLS edges carry line, resolved, confidence, and β when the call sits
behind control flow β conditional, controlFlow, and guards; ANNOTATED_WITH edges
carry line and arguments; ADVISES edges carry adviceKind and the resolved
pointcut; INJECTS carries injectedName and framework; EMITS carries channel,
channelKind, framework, and for transactional listeners phase; REFLECTS carries
mechanism; REFERENCES carries external.
Id scheme:
| Symbol | Example |
|---|---|
| type | com.acme.OrderService |
| method | com.acme.OrderService#place |
| constructor | com.acme.OrderService#<init> |
| field | com.acme.OrderService$repo |
| annotation | @Transactional |
| import | __import__:java.util.List |
| unresolved call | __unknown__:System.out.println |
| Python/TS module | module:app.service |
| module-level function | module:app.api#read_order |
| module-level field | module:app.service$AUDIT_LOG |
| inline arrow handler | module:src.routes#<anonymous@7> |
| external package | ext:fastapi |
| reflective marker | __reflect__:./plugins/${name} |
| injection marker | __inject__:Repo |
Dynamic behaviour
Static call edges answer "what does the source literally call?". Runtime behaviour differs in two ways, both modelled as derived edges rebuilt on every crawl:
Virtual dispatch
A call to an interface or base-class method may execute any override. After all files
are indexed, every resolved CALLS edge whose target is an overridable method gets
DYNAMIC_DISPATCH edges to each override found in the project:
Checkout#checkout --CALLS--> Payment#pay
Payment#pay --DYNAMIC_DISPATCH--> CardPayment#pay
Payment#pay --DYNAMIC_DISPATCH--> UpiPayment#pay
Constructors and private/static/final methods are excluded because they cannot be
overridden. Use find_implementations to list candidates and trace_execution to follow
them.
Aspects, advice, and decorators
@Aspect types are indexed as aspect nodes. Advice methods are recognised by
@Before, @After, @Around, @AfterReturning, @AfterThrowing, and @Pointcut.
Named pointcuts (@Around("paymentCall()")) are resolved to their @Pointcut
expression, then matched against every project method to create ADVISES edges:
AuditAspect#auditPayment --ADVISES--> Payment#pay
AuditAspect#auditPayment --ADVISES--> CardPayment#pay
AuditAspect#auditPayment --ADVISES--> UpiPayment#pay
AuditAspect#beforeCheckout --ADVISES--> Checkout#checkout
trace_execution weaves these in as INTERCEPT hops, so the trace reads:
Checkout#checkout
INTERCEPT AuditAspect#beforeCheckout
CALLS Payment#pay
INTERCEPT AuditAspect#auditPayment
DYNAMIC_DISPATCH CardPayment#pay -> authorize
DYNAMIC_DISPATCH UpiPayment#pay -> settle
Every other annotation is indexed as an annotation node with an ANNOTATED_WITH edge.
Framework decorators (@Transactional, @Cacheable, @Async, @Retryable,
@PreAuthorize, @Scheduled, ...) are additionally flagged decorator: true so
get_decorators and find_annotated can surface runtime-semantic annotations.
Python decorators and TypeScript decorators are modelled the same way: @router.get(...),
@injectable, @Controller(...), @Get(':id') and friends land in annotations on the
declaring type/method, and framework ones additionally produce routes, injections, or
entry-point marks.
Reflection and run-time indirection
Lookups the compiler cannot see through are recorded as REFLECTS edges. When the target
is statically determinable β a string literal, a literal prefix plus a variable
(importlib.import_module("app.plugins." + name)), getattr(obj, "run"),
require("./x") β the edge points at the resolved symbol. Otherwise it points at a
__reflect__: marker carrying the mechanism:
module:app.dynamic#load_plugin --REFLECTS--> __reflect__:app.plugins. (importlib.import_module)
module:src.dynamic#loadPlugin --REFLECTS--> __reflect__:./plugins/${name} (import())
Dynamic module prefixes that belong to the project's own namespace stay in-project; only genuinely foreign packages become external dependencies.
Dependency injection
Dependencies the framework supplies are INJECTS edges instead of missing calls
(find_injections):
| Framework | Detected from |
|---|---|
| Spring | @Autowired fields/methods/constructors; the sole constructor of a bean, annotated or not (Spring 4.3+); Lombok @AllArgsConstructor/@RequiredArgsConstructor promoted fields |
| NestJS | constructor parameters with decorators; @Injectable() classes |
| FastAPI | Depends(...) parameters, Annotated[T, Depends(fn)] aliases declared once and reused across modules, and decorator-level dependencies=[Depends(fn)] |
| dependency-injector | constructor parameters of @injectable classes |
| plain TS/JS | constructor parameters typed with a project class |
Primitive and structural parameter types (string, { id: string }, list[str]) are
counted but produce no edge, so @Body() body: { id: string } does not pollute the graph.
For Spring, the sole-constructor rule needs the class to carry a stereotype
(@Component, @Service, @Repository, @Controller, @RestController, @Configuration,
@ControllerAdvice, @RestControllerAdvice) β no container constructs anything else. A bean
with two unannotated constructors injects nothing, because Spring cannot choose either, and
neither does a class that declares a constructor next to a Lombok generator. Fields with an
initialiser at their declaration are not treated as injected.
An INJECTS edge points from what the container populates to the provider it calls:
a constructor belongs to its type, a FastAPI parameter belongs to the function whose signature
declares it, and service: OrderService = Depends(get_service) targets get_service rather
than OrderService β the container invokes get_service and hands back what it returns.
Framework entry points and routes
Methods a framework invokes have no source-level caller, so marking them keeps dead-code
analysis honest and gives trace_execution a root (find_entry_points, find_routes):
| Language | Recognised |
|---|---|
| Java | @GetMapping, @PostMapping, @RequestMapping, @Scheduled, @EventListener, listener annotations, tests, main |
| Python | FastAPI (@router.get, @app.post, @router.websocket), Flask (@bp.route, @app.get), Quart (@bp.route), if __name__ == "__main__", pytest tests |
| TypeScript | NestJS @Controller + @Get/@Post/... , Express app.get('/x', handler), Jest tests |
Express handlers written inline get a synthetic method node
(module:src.routes#<anonymous@7>) so their body still gets call edges, containment, and
a route edge.
Event and message flows
A listener is called by the framework, not by the publisher, so no CALLS edge joins
them. EMITS joins them by the channel they share (find_event_flows, and by default in
get_callers, get_callees, trace_path):
| Framework | Publication | Listener | Channel |
|---|---|---|---|
| Spring events | applicationEventPublisher.publishEvent(new OrderPlaced(...)) | @EventListener | the event class |
| Spring transactional events | as above | @TransactionalEventListener | the event class, plus phase |
| Kafka | kafkaTemplate.send("orders", ...) | @KafkaListener(topics = "orders") | "orders" |
| JMS | jmsTemplate.convertAndSend("queue.billing", ...) | @JmsListener(destination = "queue.billing") | "queue.billing" |
| NestJS | this.eventEmitter.emit("order.placed", ...) | @OnEvent("order.placed") | "order.placed" |
confidence is 1 when both sides resolved a fully-qualified event type β the same class by
identity, which is why InvoiceService publishing billing.InvoicePaid does not reach a
listener for legacy.InvoicePaid β and 0.85 for a literal topic or queue, where the same
name can belong to a different broker. Only a constructed event or a literal topic names a
channel: a run-time-computed destination, or a published plain parameter, produces no edge
instead of a guess. A @TransactionalEventListener's phase says when the listener runs,
not whether the edge exists; an AFTER_ROLLBACK listener does not run on the happy path.
Run-time proxy boundaries
@Transactional, @Async and @Cacheable put a proxy in front of a method, so what runs
depends on how it is reached. get_callers reports that on direct callers:
| Caller | proxy | proxyBlocked | inert |
|---|---|---|---|
| another bean | ["transactional"] | β | β |
the same bean (this.place(...)) | ["transactional"] | β | true |
@Async private void audit() | ["async"] | private | β |
final void seal() in a @Transactional class | ["transactional"] | final | β |
any method of a final class | ["transactional"] | final-type | β |
inert is self-invocation: the call never leaves the object, so the proxy is bypassed and
the annotation does nothing. proxyBlocked is the same problem at declaration time β the
container cannot override a private, static or final method, or subclass a final
class. Both are the case a reader of the source assumes works; reporting the annotation
without them would be a confident wrong answer.
Ambiguous overloads
When a call site matches several overloads equally, the graph ranks them instead of guessing silently. The edge keeps the first declaration as its target and lists the rivals:
| Caller | target | confidence | alternatives |
|---|---|---|---|
render(7) | Formatter#render(int) | 0.95 | β |
render("seven") | Formatter#render(String) | 1 | β |
render(input) where input is Object | Formatter#render | 0.6 | ["Formatter#render(String)"] |
The last row is the honest answer: the call provably happens, only the choice among
overloads is unknown. The edge stays resolved: true and confidence drops into the hedge
band, so nothing downstream can mistake the leading candidate for a proven target.
Control flow on call edges
Each CALLS edge records whether it is guarded:
{
"kind": "CALLS",
"source": "app.repository.OrderRepository#create",
"target": "ext:builtins",
"properties": { "line": 14, "conditional": true, "controlFlow": ["branch", "loop"],
"guards": ["row.get(\"id\") == order_id", "self.rows"] }
}
controlFlow uses branch | loop | exception | predicate. Guards are source text, not
symbolic constraints: they tell an agent that a call is conditional and what the
condition looked like, without pretending to model its truth value.
Resolution heuristics
Java:
- Constructor calls (
new Foo(...)) β resolveFooβ#<init>(default ctor if implicit). - Bare /
this./super.calls β enclosing type + superclass chain. - Type-qualified calls (
com.acme.Foo.bar) β resolve the type directly. - Instance calls (
x.method()) β infer receiver type from locals β params β fields, then search that type and its ancestors. - Otherwise β phantom
unknown_symbolnode,resolved:false, with the inference failure reason attached to the edge.
Python and TypeScript add module-aware resolution on top of the same pipeline:
Documentation truncated β see the full README on GitHub.
Reviews
No reviews yet
Be the first to review this server!
More Developer Tools MCP Servers
Rea
Freeby Morluto Β· Developer Tools
Reverse engineer anything from your terminal or agent with one CLI and MCP server.
Paperclip
Freeby Paperclipai Β· Developer Tools
Trending hip-hop artist momentum scores across four cultural dimensions.
Scrapling
Freeby D4Vinci Β· Developer Tools
Web scraping with stealth HTTP, real browsers, and Cloudflare bypass. CSS selectors supported.
Git
Freeby Modelcontextprotocol Β· Developer Tools
Read, search, and manipulate Git repositories programmatically
Toleno
Freeby Toleno Β· Developer Tools
Toleno Network MCP Server β Manage your Toleno mining account with Claude AI using natural language.
MCP Marketplace
Freeby mcp-marketplace Β· Developer Tools
Search and install MCP servers from inside your AI client.
