Enables AI agents to navigate codebases using a queryable knowledge graph for symbol search, dependency analysis, and impact assessment.
Also known as Nxtsoft/CGraph, cgraph-mcp
- Stars
- 2
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 0.9.7
- Last commit
- Oct 21, 2026
- License
- MIT
What is CGraph MCP?
CGraph enables AI agents to navigate codebases using a queryable knowledge graph for symbol search, dependency analysis, and impact assessment.
Summary generated from the project's README
About CGraph MCP server
CGraph transforms large codebases into queryable knowledge graphs to help AI agents navigate complex structures. Instead of relying on simple text searches, it extracts deterministic relationships between symbols, allowing agents to understand how different files and modules interact. This tool is designed for developers using coding agents like Claude or Codex, providing them with a structural map that prevents the need to read dozens of files to answer architectural questions.
The system operates through several components including a one-shot CLI for scanning, a resident daemon for live file-watching, and a dedicated MCP server. Users can interact with the graph via tools like graph_impact for dependency analysis or graph_context for retrieving relevant code snippets. The engine supports a wide range of languages including C++, Python, Go, and TypeScript using tree-sitter for structural extraction. Because the graph is precomputed, queries are served in approximately 10 ms, making it highly efficient for real-time agent reasoning.
What you can do with it
- 1Analyze code change impactAn AI agent can identify every transitive dependent of a specific symbol to determine the blast radius of a change.
- 2Discover repository architectureDevelopers can use community detection to automatically cluster a large repository into distinct modules.
- 3Optimize agent context usageInstead of reading entire files, an agent can request specific token-budgeted source bundles to save context window space.
- 4Identify critical code hubsUse centrality ranking to find the most important load-bearing files within a massive codebase.
Written from the project's README. Every use case is checked against a quote from it.
How to install CGraph MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall CGraph MCP in Claude Code
$ claude mcp add cgraph -- npx -y cgraph-mcpInstall CGraph MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"cgraph": {
"command": "npx",
"args": [
"-y",
"cgraph-mcp"
]
}
}
}Install CGraph MCP in VS Code
.vscode/mcp.json
{
"servers": {
"cgraph": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"cgraph-mcp"
]
}
}
}Install CGraph MCP in VS Code CLI
$ code --add-mcp '{"name":"cgraph","type":"stdio","command":"npx","args":["-y","cgraph-mcp"]}'Install CGraph MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"cgraph": {
"command": "npx",
"args": [
"-y",
"cgraph-mcp"
]
}
}
}Install CGraph MCP in Codex
$ codex mcp add cgraph -- npx -y cgraph-mcpInstall CGraph MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.cgraph] command = "npx" args = ["-y", "cgraph-mcp"]
Install CGraph MCP in Gemini CLI
$ gemini mcp add -s user cgraph npx -- -y cgraph-mcpInstall CGraph MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"cgraph": {
"command": "npx",
"args": [
"-y",
"cgraph-mcp"
]
}
}
}Configuration
CGRAPH_CLIENTCGRAPH_PROJECT_ROOTVCPKG_ROOT
| Name | Description | |
|---|---|---|
| CGRAPH_CLIENT | — | |
| CGRAPH_PROJECT_ROOT | — | |
| VCPKG_ROOT | — |
Automated checks
Ran Nov 13, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablenxtsoft/cgraph is public and reachablegithub.com/nxtsoft/cgraph ↗Pass
- Package names this repository as its sourcecgraph-mcp names nxtsoft/cgraph as sourcenpmjs.com/package/cgraph-mcp ↗Pass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-21github.com/nxtsoft/cgraph ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from cgraph-mcpPass
- No critical advisory in the package or its dependencies1 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubEnglish · 简体中文
Scan a project · extract structure into a deterministic graph · query it in ~10 ms from a daemon, a thin client, or an MCP server.
Contents
Why CGraph? · Architecture · Repository layout · What it produces · Output formats · Performance · Retrieval benchmark · Languages · Quick start · Install & Setup · Use with coding agents · CLI · daemon · MCP reference · Host integrations & enrichment · Development notes · Contributing · License
Why CGraph?
Reading a large repo to answer "what calls this?" or "what breaks if I change it?" means loading dozens of files — and those answers aren't in any single file. They live in the relationships between files. CGraph precomputes them so you (and your AI agent) navigate by graph, not grep.
| 🔗 Reverse dependencies & blast radius | graph_impact returns every transitive dependent of a symbol in ~10 ms. On a real 10,706-node repo it surfaced 93 dependents of one god-file, instantly — an answer grep can't give you. |
| 🧭 Navigate, don't grep | Centrality-ranked search, node neighborhoods, shortest paths, and token-budgeted source bundles — served warm in ~10 ms instead of many file reads that burn context. |
| 🏛️ Architecture at a glance | Centrality ranking surfaces the load-bearing files; Leiden/Louvain community detection clusters the repo into modules automatically. |
| ⚡ Deterministic & fast | A full 10k-node graph builds in ~2 s; no LLM in the extraction path — same input, same graph, every time. |
| 🤖 Built for coding agents | A standard MCP server drops the graph straight into Claude / Codex, so they reason over structure instead of blindly reading files. |
The pitch in one line: for a codebase too big to hold in your head, CGraph is the index that decides which code to read —
ctags/"find all references", precomputed, centrality-ranked, and exposed over MCP.
Architecture
cgraph— one-shot scan → portable disk exports (graph.json,graph.html,graph.svg,obsidian.md,cypher.txt,modules.mmd,modules.svg,design.mmd,design.md).graphd+cgraph-client— a resident per-project daemon with live file-watching; warmquery/path/explain/impact/contextin ~10 ms.cgraph-mcp— a Model Context Protocol server so agents navigate the graph directly.
The engine owns deterministic extraction, fragment validation, cache state, and local graph mutation; hosts own model choice and semantic enrichment.
Repository layout
src/cli/ One-shot CLI entrypoint: cgraph
src/daemon/ Daemon entrypoint: graphd
src/client/ Thin client runtime and cgraph-client executable
src/mcp/ MCP request handling and cgraph-mcp executable
src/engine/ Detection, extraction, graph building, analysis, daemon ops
tests/smoke/ CTest smoke coverage for engine, daemon, MCP, and integration paths
tests/fuzz/ Optional libFuzzer targets
integrations/ Host hook and always-on integration scripts
docs/ Host integration contract and benchmark notes
vendor/ Vendored tree-sitter core and grammars
What it produces
A single scan turns a source tree into an interactive, explorable graph — communities colored, hubs sized by centrality:
The real graph.html viewer on a 10,708-node / 28,945-edge codebase — self-contained HTML, no external JS.
Output formats
graph.json— directed node-link JSON with graph metadata, nodes, and links. Node ids derive from each file's path relative to the project root, so the same commit built from two checkouts yields the same ids and two graphs can be joined by id;source_filestays the path the graph was read fromgraph.html— browser-readable interactive graph viewgraph.svg— static graph visualizationobsidian.md— markdown export for Obsidian-style navigationcypher.txt— Neo4j Cypher statementsmodules.mmd— module dependency diagram as Mermaidmodules.svg— module dependency diagram as a layered static imagedesign.mmd— entry points and their top call flows as a Mermaidflowchart TDdesign.md— the same as Markdown: entry-point table, nested flows, layers by call distance
Performance
The interactive viewer used to run an O(N²) force simulation in the browser on every open. Layout is now precomputed once in C++ (via igraph), and repaints are viewport-culled — both dependency-free:
| graph | time-to-settle before | after | per-frame repaint |
|---|---|---|---|
| 10,000 nodes | 35.2 s (main thread pinned) | ~0 ms (static layout) | 20–34× cheaper (zoom/pan) |
Retrieval benchmark
CGraph has been scored on Agent Retrieval Bench: 427 samples from 25 repositories, each checked out at its base commit, scored with the benchmark's own metric code. The table covers all 345 positive samples.
| Method | Recall@20 | MRR | BCY@8k |
|---|---|---|---|
| CGraph bin-v0.9.1 (label + code-text search) | 0.6362 | 0.2787 | 0.4319 |
| CGraph bin-v0.8.3 (label-only text search) | 0.5726 | 0.2356 | 0.3790 |
| RepoMap (published) | 0.6333 | 0.2158 | 0.3788 |
| RepoMap (rerun on this harness) | 0.6311 | 0.2156 | 0.3846 |
| Qwen3-Embedding-8B (published) | 0.7029 | 0.2336 | 0.3732 |
| Qwen3-Embedding-4B (published) | 0.6306 | 0.2379 | 0.3409 |
| BM25 (published) | 0.4452 | 0.1520 | 0.2051 |
How bin-v0.9.1 compares:
- Recall@20. Level with RepoMap (the difference is inside run-to-run noise of about 0.006). Below Qwen3-Embedding-8B. Above the other published single methods.
- MRR. Higher than every published single method.
- BCY@8k. Higher than every published single method, by more than the noise floor.
- Against the paper's fusion of Qwen3-Embedding-8B and RepoMap, on the 287-sample core it reports: MRR is level (the fusion scores only its top 20; CGraph's MRR over its top 20 is 0.276 vs 0.271, inside the noise floor); Recall@20 (0.633 vs 0.733) and BCY@8k (0.440 vs 0.488) are lower.
- Abstention. CGraph does not abstain on no-gold samples.
Per-task tables, pins, the noise floor and caveats are in
bench/arb/RESULTS.md. Reproduce with bench/arb/run.sh.
Languages
Tree-sitter-backed structural extraction, with regex/structured extraction for a few config formats:
Plus structured/regex extraction for Apex, Delphi form/source, MSBuild/XML project files, and MCP config files.
Type members
Seven languages emit a field node per declared member, with a defines edge from the owner:
| Language | Owners with members | Field properties |
|---|---|---|
| C, C++ | class, struct only — not enum or union |
none |
| TypeScript, TSX | interface, object type alias, class (constructor parameter properties included), enum | type_text, optional, readonly |
| Go | struct, including multi-name and embedded fields | type_text |
| Rust | named and tuple struct, union, enum variant, trait associated type and constant | type_text |
| Python | class-body assignment, including chained and tuple targets | type_text when annotated |
| Java | class, record, enum | type_text, readonly |
Members are declared members only: no inherited-member expansion, no alias flattening, no runtime
attribute inference. A declaration that is already a node of its own — a TypeScript
method_signature, a Rust trait method or type alias — keeps its function or type node and is not
also a field. A field never takes the id a function or type holds; it moves instead, so a symbol's
id stays stable.
A class-like declaration without a body (struct FileCacheEntry;) is a forward declaration and mints
no node; only the body-bearing definition does.
Fields are members, not navigation targets: graph_context packs the owner (whose snippet spans its
members) rather than the members, and report modules symbol counts exclude them.
HTTP endpoints
JavaScript and TypeScript services get one endpoint node per route the code serves, with the
full path composed across files: an Elysia, Express or Hono chain's own prefix (new Elysia({ prefix: '/notebooks' }), .basePath('/v1')) beneath every .use(child), .use('/p', child) or
.route('/p', child) that mounts it, up to the top-level chain, read through as any and
as unknown as T casts and resolved through imports (aliased ones included). A chain built inline
inside .use(new Elysia({ prefix }).get(…)), a .group('/v2', app => app.get(…)) or .guard()
callback, and a module re-exported as export const deckModule = deckRoutes as unknown as Elysia
all compose the same way. A Next.js app/api/x/[id]/route.ts exporting GET is GET /api/x/:id.
A repository holding a langgraph.json with a non-empty graphs object is a LangGraph Agent
Server: its 49 framework routes (POST /runs/wait, POST /threads/{thread_id}/runs/stream,
GET /assistants/{assistant_id}, ..., the table @langchain/langgraph-api 1.5.1 registers, less its four crons routes, which answer 500 "Not implemented"; see
https://docs.langchain.com/langsmith/server-api-ref) are served endpoints handled by a
langgraph_server node spanning that object, with one langgraph_graph node per graph. A group
the config switches off (http.disable_runs, disable_store, ...) is not served.
Kotlin and Java Spring controllers get the same nodes: a method annotated @GetMapping("/{id}")
(or @PostMapping, @PutMapping, @DeleteMapping, @PatchMapping, or @RequestMapping with a
method) under a class-level @RequestMapping("/api/v1/users") is GET /api/v1/users/{id}.
Paths are read from string literals only (positional, value =, path =, or an array of them); a
path built from a constant, and a method-level @RequestMapping without method, are not minted.
A Spring Boot application whose build.gradle(.kts) or pom.xml applies the Boot plugin (not
apply false; Maven: the Boot parent, or the plugin outside <pluginManagement>, packaging not
pom) and depends on spring-boot-starter-actuator and a web starter serves the Actuator
endpoints its src/main/resources/application[-profile].{yml,yaml,properties} expose: health
by default, else management.endpoints.web.exposure.include less exclude, under
management.endpoints.web.base-path (default /actuator), with the discovery page, health
groups, per-endpoint access, and prometheus / caches only with the Prometheus registry / the
cache module. The liveness and readiness groups are on by default for Boot 4 (unless
probes.enabled is false) and only when it is true for Boot 3 or an unknown version. Where they
sit follows Boot's ManagementPortType: a negative management.server.port or
spring.main.web-application-type: none serves nothing; the same port puts them under the context
path; another port under management.server.base-path. The endpoints are the union over the base
config and each profile, handled by the actuator_exposure node at the include line that won
(or the build file's spring_actuator node when nothing sets it). Endpoints that need another bean
or dependency, profile expressions, placeholders without a default, and YAML anchors, aliases,
tags or flow mappings on the deciding keys are not modeled (those configurations serve nothing);
see spring_actuator.hpp.
Python FastAPI services get them too: a function decorated @router.post("/{project_id}/setup")
(or .get, .put, .patch, .delete, .head, .options, or .api_route(path, methods=[...]),
which defaults to GET) on a module-level router = APIRouter(prefix="/project") or app = FastAPI() is POST /project/{project_id}/setup beneath every include_router(router, prefix="/v1") or app.mount("/v1", sub_app) that mounts it, composed across files through
imports: from api.routes.x import router as x_router (the alias is the only name bound),
from app.routers import users then include_router(users.router) (a submodule), import app.routers.items as items then include_router(items.router), a router a package's
__init__.py imports and another file imports from the package, and each router of a
for r in (users.router, items.router): app.include_router(r) loop over a literal tuple or list.
A path, prefix or methods list that is not a plain string literal (an f-string that
interpolates, prefix=settings.PREFIX), a route or include_router inside a function (an app
factory), and an include_router on anything but a module-level router of its file
(app = create_app(), app.router, self.app, a router imported from another file) are not
minted and are counted in routes_unresolved / mounts_unresolved; a router whose every mount is
one of those mints nothing. A loop over anything else (for r in ROUTERS:) is counted unresolved
without identifying its routers. A router nothing mounts is served at its own prefix, as a
JavaScript router is. add_api_route(...) is not read, and a mount of a longer dotted name
(include_router(api.v1.router)) is counted unresolved without placing its router. Flask is not
read: register_blueprint(url_prefix=) replaces the blueprint's own prefix rather than composing
with it.
The node's id is endpoint:GET /api/v1/notebooks/{}/notes with no repository in it and {} for
every parameter segment (:id, {id}, [id]), its label keeps the provider's spelling
(GET /api/v1/notebooks/:id/notes), and it carries method and path, the handler's file and
span, a contains edge from that file and a handled_by edge to the handler, so graph_impact
on a handler reaches its endpoint. Chains mounted twice serve their routes twice; a route on a
router the file only receives as a function parameter (function register(app) { app.get(…) })
is not minted, and stats.json counts it under route_resolution.routes_unresolved.
Database tables join the same walk. Every CREATE TABLE in a repo's .sql migrations is a
sql_table node, and a Drizzle model declared with a literal name (export const competitors = pgTable('competitors', …), likewise mysqlTable and sqliteTable) gets a maps_table edge to the
table of that name. A dependents walk that reaches a file through an import, or from a
module-level value it declares, also reaches the endpoints the file serves, so graph_impact on
sql_table_competitors goes table, model, the services importing it, their route files, and the
routes. A path through a function, class or endpoint does not serve routes, whether it climbs to
the function's own file or follows an import of the function (and on to the app file that mounts
the route file): a changed function reaches the routes it affects through the calls into their
handlers, not every route nearby. A seam service node is listed when reached but not walked
through, so one consumer edge into it does not pull in every endpoint of that service.
The callers are in the graph too. A fetch(\${API_URL}/api/v1/projects/${id}/publish`, { method:
'POST' }), an openapi-fetch api.GET('/api/v1/projects/{id}', …), an axios.post(…), and a call through a path wrapper (apiFetch(path)whose ownfetch(`${base}${path}`)appends a parameter to a module constant) each give the calling function (or the module-level object the arrow initialises) aCONSUMESedge toendpoint: . The host interpolation is dropped (except a call that takes a runtime value, such as ${base(id)}/x, a URL builder that may hold part of the path, which leaves the request unresolved unless the builder is a function of the same file, which is read), a whole-segment interpolation is {}, the method comes from the call's literal method option, the wrapper's own, or the client verb, else GET. What one file says for certain is read through: a URL held in a local (const url = `${BASE}/x`, new URL(...)thenurl.toString(), a let set per branch), a class field prefix (${this.API_BASE}/v1/...), an axios instance's baseURL (this.api.get('v1/users')underbaseURL: '/api/backend'), a class-method wrapper (this.patch(`v1/users/${id}/enable`)), and a wrapper whose path or method is a later parameter (mlBackendRequest('POST', `/project/${id}/setup`), a method parameter's default applying when a call leaves it out). When this repository does not serve the route the node is minted with served: false and no source; when it does (a Next.js route file fetched from the same app) the one node has both a handler and its callers. A URL whose value the file cannot read, a method a call does not spell out, a relative path (v1/users) with no base ending in /to join it to, or an absolutehttps://literal adds nothing and is counted underroute_resolution.calls_unresolved. Kotlin and Go clients consume the same way: a Ktor client.patch("$baseUrl/api/v1/sessions/$id/invalidate") { … } on a receiver whose name ends like a client (client, httpClient, api; not clientsorhttpCache), Go's http.Get(url)andhttp.NewRequest(method, url, body), and any Go call passing a context, then a method (http.MethodPostor"POST"), then a path, such as c.Do(ctx, http.MethodGet,
"/api/v1/auth/me", nil). A Go route registration (r.Handle(http.MethodGet, "/x", h)), a call with a funcliteral argument,httptestand an assertion onr.Methodcarry no context or a handler, and are no requests. The leading$baseUrl of a Ktor URL is the host; a Go client method's path is relative to its own base, so a value in front of it (n.Base+"/import") leaves the call unresolved. A function whose request appends one of its parameters (postAuth(ctx, path, req)callingc.Do(ctx, http.MethodPost, path, body), or client.post("$baseUrl$path"), also from inside a lambda such as withContext(…) { … }) is a wrapper, and a call to it in the same file with a path literal (c.postAuth(ctx, "/api/v1/auth/login", req), postLoginOutcome(path = "/api/v1/…")) consumes the joined route. A Ktor client.request(url) { method = … }sets its verb in the builder and is counted unresolved. Because the id carries no repository, two graphs built separately share their endpoint nodes.seam fuse scopes every other node id by its service (api::src_db_client_ts`), so two repositories with the same relative file stay two nodes:
cgraph seam discover --graph api=api-out/graph.json --graph web=web-out/graph.json --out seam-drop
cgraph seam fuse --seam seam-drop/chunk_00.json --graph api=api-out/graph.json --graph web=web-out/graph.json --out fused
seam discover writes the seam fragment from what each graph serves (SERVED_BY, HANDLED_BY),
consumes (CONSUMES, CONSUMED_AT) and documents (DOCUMENTED_IN) with no hand-written spec,
and reports how many endpoints matched across services, how many are consumed with no provider
among the graphs, and, when a graph carries a contract document, the drift: endpoints the
document promises that no service serves, and endpoints served that no document mentions.
A front end that reaches its backend through its own catch-all proxy (idp-front-end calls
/api/backend/v1/users/{id}; its app/api/backend/[...path]/route.ts forwards to
${BACKEND_URL}/api/v1/users/{id}) names that with --prefix REPO:/from=/to on both seam discover
and seam fuse (--prefix web:/api/backend=/api). An endpoint web consumes but does not serve,
under /api/backend, then joins the provider's /api/... endpoint; its CONSUMED_AT edge keeps
the consumer's own path as via, and the log counts the endpoints each prefix joined. A route the
front end serves itself (/api/backend/healthz) is never mapped, and a proxied path only the front
end serves is not joined. Each repository's own graph keeps its own spelling. The forwarding target
is not read from the proxy's code: it is built at run time from the handler's parameters, so it is
declared, not guessed.
Contracts other than endpoints are recorded by extractors as provides_contract /
uses_contract facts: header:<name> (case-folded), claim:<name>, env:<NAME>, DynamoDB tables
as dynamo:<name>, gRPC methods as grpc:<Service>/<Method>, message topics and queues as
topic:<broker>:<name>, and tables and graph labels as table:<database>:<name> /
label:<database>:<name>. They do not all join alike:
- Claims and non-standard headers (
x-tenant-id) join like endpoints, by id. A standard HTTP header (authorization,content-type, any IANA permanent field name,x-request-id,x-forwarded-*,traceparent) never joins: every service uses those for its own reasons. Nor does a standard JWT claim, which any issuer writes with the same meaning (iss,sub,exp,email,name,scope,client_id: the IANA JWT Claims registry's RFC 7519, OpenID Connect, RFC 7800, RFC 8693 and RFC 9449 names); application claims (roles,tenant_id,session_id) do. A claim name alone does not say whose token it is in, so the reposito
CGraph MCP questions
How do I add CGraph MCP to Claude Code?
Run claude mcp add cgraph -- npx -y cgraph-mcp in your terminal. Add --scope user to make it available in every project.
How do I add CGraph MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
How fast is the graph retrieval?
Queries such as impact and path analysis are served in approximately 10 ms from a daemon or MCP server.
Does CGraph use an LLM to extract code structure?
No, the extraction process is deterministic and does not use an LLM in the extraction path.
What programming languages are supported?
It supports a wide range of languages including C, C++, C#, Go, Java, JavaScript, Python, Rust, Scala, TypeScript, and more via tree-sitter.