codegraph-brain
Builds a queryable code graph from a local repo and answers structural questions about it over MCP β impact, flow, coupling, architecture β without reading whole files.
Ingest & refresh the graph (
cgis_ingest): tree-sitter parse β resolve β SQLite; incremental by default,full_rebuildto rescans, optional data-key extraction.Get oriented (
cgis_overview,cgis_find_symbol): symbol/file/edge counts, largest packages, and partial-name β candidate FQNs.Trace dependencies (
cgis_trace_flow): downstream subgraph β what a symbol calls/imports/inherits, N hops, as text tree, mermaid, or joinable JSON.Assess blast radius (
cgis_analyze_impact): upstream callers/subclasses/importers β "what breaks if I change this?"Inspect structure (
cgis_get_structure,cgis_module_graph): class/module members and intra-package dependency layers.Get editing context (
cgis_context): token-efficient XML brief with source, class, callers, callees for one symbol.Measure architecture (
cgis_metrics,cgis_fractal,cgis_suggest_packages): coupling, god classes, PageRank, LCOM4, motif/triad census, package-split/consolidate advice.Audit rules (
cgis_audit_reachability,cgis_find_orphans): which handlers never reach a guard (IDOR/authz), and dead-code candidate classes.Check architectural drift (
cgis_drift,cgis_init_ontology): per-domain fit against declared patterns, plus a starter patterns.yaml.Review a diff (
cgis_diff_check): dependants of changed symbols β callers, subclasses, data-key readers/writers.Verify trust in the graph (
cgis_validate): resolved vs unresolved edge ratio and health verdict.Works locally over MCP in Claude Code, Cursor, Claude Desktop, or CLI (
cgis ingest/impact/trace), with no telemetry.
π§ CGIS: Code Graph Intelligence System
A code graph your AI agent can query instead of guess
Ask "what breaks if I change this?" and get the call chain, not a guess.
CGIS parses a repository with tree-sitter into a graph of fully qualified symbols and the calls, imports and containment between them, stores it in SQLite, and serves it to AI agents over MCP. An agent that would otherwise grep and read whole files asks the graph instead.
Languages: Python Β· TypeScript / TSX Β· Go (structure and metrics only; its impact answers are a lead to confirm by reading β exp4, measured on one library, golang/crypto, mostly its ssh package; not measured on applications) Β· JSON and YAML (data key declarations only, when data keys are enabled with
--data-keys: no symbols, calls or impact)Runs: locally β no account, no telemetry; the graph never leaves your disk (the one opt-in exception)
$ cgis ingest src --output graph.db
$ cgis impact cgis.query.engine.QueryEngine.get_flow_graph --db graph.db --depth 2
π Analyzing transitive upstream callers of: cgis.query.engine.QueryEngine.get_flow_graph
METHOD cgis.query.engine.QueryEngine.get_flow_graph (cgis/query/engine.py:215)
βββ FUNCTION cgis.query.context.context_service._collect_callees (cgis/query/context/context_service.py:44)
β βββ FUNCTION cgis.query.context.context_service.build_context (cgis/query/context/context_service.py:96)
βββ METHOD cgis.guardian.collector.ContextCollector._graph_sections (cgis/guardian/collector.py:174)
βββ METHOD cgis.guardian.collector.ContextCollector.collect_graph_context (cgis/guardian/collector.py:213)
βββ METHOD cgis.guardian.collector.ContextCollector.collect_for_chunk (cgis/guardian/collector.py:303)Real output β CGIS run on its own source.
π Quickstart
In Claude Code (fastest)
/plugin marketplace add zaebee/codegraph-brain
/plugin install cgis@codegraph-brainThat ships the MCP server, a skill that teaches the agent when to query the graph instead of reading files, and /cgis:ingest to build the graph on first use. The server is pulled from PyPI on demand via uvx, so there is nothing to clone or build.
Any other MCP client (Cursor, Claude Desktop, β¦)
{
"mcpServers": {
"cgis": { "command": "uvx", "args": ["--from", "codegraph-brain", "cgis-mcp"] }
}
}From the terminal
# No install needed β uvx fetches it from PyPI
uvx --from codegraph-brain cgis ingest ./my-project --output graph.db
uvx --from codegraph-brain cgis impact "my_module.core_function" --db graph.db --depth 5 # who calls this
uvx --from codegraph-brain cgis trace "my_module.MyClass.run" --db graph.db --depth 3 # what this calls
# add --format mermaid (or json) to either for a diagram or machine-readable outputOr install it for good: pip install codegraph-brain (Python 3.12+), then use cgis directly. The full command list is in CLI_USAGE.md.
Related MCP server: mcp-reposkein
π Proof at Real Scale
CGIS runs on a working twelve-repository estate β four languages, 8,146 commits, shipping daily. On its FastAPI backend it classifies 82.7% of 87,845 edges definitively and prints the remaining 17.3% rather than inventing targets for them β including the part that is CGIS's own gap.
That share rose from 11.4% in #459, which stopped counting calls to missing symbols as resolved. About 4 points of what is left is a known resolver gap, not something undiscoverable: ingesting app/ strips the app. prefix its imports carry, and the import path does not yet reconcile the two β the same backend ingested at its package root reports 13.2%. The number is what the tool admits it cannot place today, and it is allowed to move the unflattering way.
Read the case study β β every figure measured and reproducible, including what CGIS doesn't cover.
π€ Why a graph, and how this differs
Text retrieval hands an agent chunks that look related. It cannot say which of three functions named save a call reaches, or what sits five callers up. CGIS resolves every call site to a fully qualified name when the source allows it β and when it does not, the edge stays marked unresolved and is counted, never filled with a plausible guess.
If you use⦠| CGIS adds |
grep / file reads in the agent | Transitive callers and callees in one call, without spending context on whole files |
LSP-backed symbol tools (e.g. Serena) | A persisted whole-repo graph for multi-hop impact, coupling, PageRank and drift |
A repo map (e.g. aider) | Resolved edges you can traverse and audit, with the resolved/unresolved ratio reported |
π€ MCP Tools
The main tools:
Tool | Answers |
| Build or incrementally refresh the graph |
| Where to start: sizes and the largest packages, when you have no FQN yet |
| Partial name β candidate FQNs |
| What breaks upstream if this changes? |
| What does this call, transitively? |
| Class / module hierarchy |
| A compact GraphRAG context package for one symbol |
| Coupling, god classes, PageRank, package cohesion |
| Authz / IDOR coverage β does every handler reach its guard? |
| How far each domain has moved from its declared pattern |
| Graph integrity: resolved vs unresolved edges |
All 16 tools, with parameters: MCP_REFERENCE.md.
ποΈ How It Works
Extract β tree-sitter parsers turn each file into nodes and raw call edges.
Resolve β the
ResolverEnginemaps raw calls to fully qualified names, or leaves them explicitly unresolved.Store β SQLite holds the graph; queries are breadth-first traversals over it.
graph LR
A[Source Code] --> B[Extractors]
B --> C[Resolver Engine]
C --> D[(SQLite Graph DB)]
D --> E[MCP Server]
D --> F[Prompt Compiler]
E --> G[AI Agents]
F --> GThe details β and a pipeline graph CGIS regenerates from its own source on every change β are in HOW_IT_WORKS.md, and the full map of every document with its generated cross-references to the code is in docs/INDEX.md.
π‘οΈ Guardian: Graph-Aware Code Review
Guardian is CGIS's built-in LLM reviewer β it reviews pull requests using the graph as context, not just the diff text. It runs in CI and posts inline comments anchored to the exact line.
Two-stage, recall-first: a finder surfaces every plausible defect (optimised for recall), then a separate skeptic pass filters false positives β closer to how human reviewers work, and far more reliable than a single precision-gated prompt.
Local or cloud, no lock-in: point it at Ollama (
qwen2.5-coder,llama3.1,granite-code, β¦) for free local inference, or at Mistral / Gemini / Claude / OpenCode Go (DeepSeek) in the cloud. You can even mix them β a strong cloud finder with a free local cross-model skeptic.Graph-aware context: the reviewer sees impact graphs, architectural drift, and project ontology β so it catches structural and convention defects a flat-diff reviewer can't.
Deterministic anchoring: every inline comment is positioned by a verbatim quote from the diff, not the model's (often wrong) line guess.
Dogfooded & measured: Guardian reviews CGIS's own pull requests, and a benchmark harness scores it against curated ground truth β so prompt changes are validated, not guessed.
# Build the graph, then review a PR with a local model (no API key).
# --inline posts over HTTPS with GH_TOKEN (or GITHUB_TOKEN); no gh CLI needed.
# The reusable workflow exports GH_TOKEN for you.
cgis ingest ./src --output graph.db
GUARDIAN_PROVIDER=ollama GUARDIAN_MODEL=qwen2.5-coder:14b \
uv run python scripts/guardian_review.py --pr 123 --db graph.db --inline
# Or OpenCode Go / DeepSeek: deepseek-v4.1-flash unless GUARDIAN_MODEL names another.
# GUARDIAN_OPENCODE_EFFORT is low unless set (the catalog lists low|high|max; other values
# pass through to the gateway). GUARDIAN_OPENCODE_BASE_URL pins a different gateway.
# No ANTHROPIC_API_KEY is needed for this provider.
GUARDIAN_PROVIDER=opencode-go GUARDIAN_MODEL=deepseek-v4.1-flash OPENCODE_API_KEY=... \
uv run python scripts/guardian_review.py --pr 123 --db graph.db --inline
# Or a Claude skeptic over a Mistral finder: Claude Haiku 5.5 unless GUARDIAN_SKEPTIC_MODEL names
# another, at GUARDIAN_ANTHROPIC_EFFORT=low unless set (low|medium|high|xhigh|max). Claude models
# reject a sampling temperature, so GUARDIAN_TEMPERATURE must be unset.
GUARDIAN_SKEPTIC=anthropic ANTHROPIC_API_KEY=... MISTRAL_API_KEY=... \
uv run python scripts/guardian_review.py --pr 123 --db graph.db --inlineIn GitHub Actions, opencode-go needs no static key: the reusable workflow exchanges a short-lived GitHub OIDC token for inference access immediately before the review. Enable OIDC for GitHub Actions in the Opencode console, set the calling repository's OPENCODE_CLIENT_ID variable, and grant the review job id-token: write. OPENCODE_API_KEY is then minted at run time and never stored as a secret. Sign-in happens when GUARDIAN_PROVIDER is opencode-go, opencode, or unset (unset means the minted key makes opencode the auto-detected provider); an explicit other provider skips it.
No GPU on hand? Benchmark it on a notebook GPU β β free end to end, since the fixtures score without an LLM judge. Or point Guardian at a remote Ollama β β over an frp stcp tunnel, no public port, and a guard that refuses a review of a silently truncated prompt.
π Privacy
CGIS collects nothing: no telemetry, no analytics, no account. Your code and the graph built from it stay on your machine. The one exception is opt-in: Guardian, if you run it with a cloud model, sends the reviewed diff to the provider you chose. See PRIVACY.md.
π οΈ Development
Requires Python 3.12+ and uv.
git clone https://github.com/zaebee/codegraph-brain && cd codegraph-brain
uv sync
make pytestSee CONTRIBUTING.md for the standards: strict MyPy, linting, ontology compliance.
πΌ Architecture Audit
CGIS is free and you can run it yourself. If you would rather have the analysis than the tool, I run a fixed-price audit of your codebase's structure β authorisation coverage, blast radius, coupling, architectural drift β delivered in five working days, $2,400 fixed, with an explicit list of what the analysis cannot see. Read what's included β
Available Tools
17 toolscgis_analyze_impactA
Upstream subgraph of one FQN: everything that reaches it within depth hops.
Follows every edge except containment β in practice callers, importers,
subclasses, type references and DI dependents β within internal code, so this
answers "what breaks if I change X?". The
enclosing class or file and stdlib/third-party nodes are left out unless
``include_structure`` / ``include_external`` ask for them β the same view as
the CLI's ``impact``. Test callers are left out unless ``include_tests``
asks for them, and counted in ``excluded_tests``. A file that imports a
symbol is listed, but the walk does not continue to the files importing
that file; a file's own impact still does. At most ``max_nodes`` nodes come
back, nearest first, and a cut is reported in ``truncated``. For what X
depends on use
``cgis_trace_flow``; for only the members of a module or class,
``cgis_get_structure``; for a source-included brief to read before editing
one symbol, ``cgis_context``.
``output_format="text"`` returns an indented tree of callers, one line
per node β the compact form to read; ``"mermaid"`` (default)
returns a diagram; ``"json"`` returns a joinable ``{root, nodes, edges,
coverage}`` payload with real FQNs β letting an agent compute set
differences (e.g. "which route handlers never reach ``verify_ownership``?")
directly. ``coverage`` counts unresolved calls whose name matches a
traversed function, method or class: callers that may be missing, named in
``top_unresolved``. It is an upper bound β a common name matches calls on
unrelated objects, which the names make visible.
Inputs: fqn (required), depth, db_path, max_nodes, +4 more. Returns: result
cgis_audit_reachabilityA
Reachability/authorization audit β which sources never reach a checkpoint.
The headline use is **IDOR/authz coverage**: list every route handler that does
NOT transitively reach an ownership check. Reachability follows behavioral edges
(CALLS *and* FastAPI ``Depends()`` DEPENDS_ON), so a guard wired via DI counts.
Select sources with ``from_type`` (the ``ROUTE_HANDLER`` role β FastAPI handlers on
a router built in the same module β or a NodeType like ``FUNCTION``) and/or
``from_prefix`` (FQN prefix) β at least
one is required. Returns JSON ``{target, covered, gaps}`` where each gap carries
``fqn``/``file``/``line``. Generalizes to validators, event tracking, or
service-layer-boundary rules by pointing ``target`` at the required node.
A selection that matches no source returns a β message, not an empty
``{covered: [], gaps: []}`` that would read as a passing audit (#467).
Inputs: target (required), depth, db_path, from_type, +1 more. Returns: result
cgis_contextA
Prompt-ready brief on one FQN: its source, class, direct callers and callees.
Call this before editing a symbol, instead of reading its files. It follows
calls only, one hop by default. Source is included when the file is found
(see ``source_root``), and the domain when the graph was tagged with one.
For a multi-hop subgraph
over calls, imports, inheritance and references without source, use
``cgis_trace_flow`` (downstream) or
``cgis_analyze_impact`` (upstream).
Returns an XML-tagged prompt β the focal node's source, its enclosing class,
its architectural domain boundary, direct callers (upstream ripple) and
callees (downstream dependencies) β meant to be injected into your context
window in place of raw file dumps. Far more token-efficient than reading
whole files, and structured so boundaries stay unambiguous.
Use ``cgis_ingest`` first if the database does not exist. ``source_root``
locates source files on disk when the graph was ingested from a
sub-directory (e.g. ``"src"`` after ``cgis ingest ./src``); it is safe to
pass even when the stored paths already start with that segment (#228).
When no candidate exists the ``<source>`` block degrades gracefully to
"unavailable".
Inputs: fqn (required), depth, db_path, source_root. Returns: result
cgis_diff_checkA
What else depends on what a diff changed: subclasses, callers and data keys.
Call this before review or merge. It reads the lines ``base..head`` changed,
finds the graph symbols they fall in (and symbols the diff removed, read from
the base text), and lists the classes that extend a changed class and the
functions that call a changed or removed function. For each data key the
changed lines read, write or declare (``doc["avatar"]``, a mapping field) it
lists the key's other readers, writers and declarers, reads of a dotted path
a mapping does not declare, and reads of a declaration the diff removed;
common keys (``id``, ``name``, or used in many files) are left out. Key items
need a graph ingested with data keys on (``cgis_ingest(data_keys=True)`` or
``cgis ingest --data-keys``); on a graph without them the answer says so and
lists subclasses and callers only. Sites in test files are counted, not
listed. An empty list means no static dependants were found, not that the
change is safe: dispatch the graph cannot see is not covered. How to read
the list: caller and subclass items are leads to read; data-key items are
noisy β measured on one application (owner-api), about a quarter of listed
items were worth a look (docs/lab-notes/2026-10-19-data-key-diff-check.md).
Before judging a code site that reads or writes a key unaffected, read its
callers (cgis_analyze_impact): they decide what values reach it.
Inputs: repo_path (required), cap, base, head, +3 more. Returns: result
cgis_driftA
Report per-domain architectural drift against declared ideal patterns.
Returns JSON: ``any_critical`` verdict, per-domain reports (each carrying a
``fit`` block β nearest alphabet template + residual + good/weak/none band),
the observe-only quotient layer, and ``coverage`` (graph prefixes bound by no
domain). Call after ``cgis_ingest`` to learn whether your edits pushed a
domain past its drift tolerance.
``max_drift`` is now the default tolerance only for domains that omit
``drift_tolerance`` β it no longer caps domains that declare their own
(see #170).
``profile``: when set, score only domains with this profile (plus
profile-less ones). Use when your patterns.yaml mixes languages but the
graph holds one language β avoids false EMPTY reports for other-language
domains that would otherwise fail the gate.
``max_residual``: a domain whose nearest template is farther than this gets
``fit.band = "none"`` ("no template fits") β a grab-bag module or an
alphabet gap, independent of drift tolerance (#177).
Inputs: db_path, profile, max_drift, max_residual, +1 more. Returns: result
cgis_find_orphansA
Classes nothing in production builds, extends or names β dead-code candidates.
Finds classes that no test, type checker or linter flags, because each is
still imported somewhere: a package re-export keeps a class importable long
after its last real caller is gone. On one mid-sized backend this reported
43 of 1 789 classes, and the hand-written equivalent's findings were all
real and all deleted.
Two filters decide the answer. **Tests are not users** β a class built only
by its own test is exactly the shape being hunted. **A re-export is not a
use** β ``IMPORTS_SYMBOL`` does not count, or nothing is ever reported. What
counts is construction (``CALLS``), inheritance (``EXTENDS``) and being named
(``REFERENCES`` β an annotation, or a class handed to a framework); the last
keeps abstract ports and Protocols off the list.
``prefix`` narrows to one package on a dot boundary. ``include_tests`` counts
test code as a user, turning the report into "unreachable from anywhere".
Machine-generated classes are **hidden by default**, and ``include_generated``
puts them back. The query is right about them β nothing constructs a
betterproto stub β but nobody hand-deletes one either, so they are noise
rather than a finding. Measured on owner-api at b7d02fe6, five of six
reported orphans were generated entities and the sixth a nested pydantic
``Config``: the unfiltered report had no actionable row in it (#432).
Only **module-level** classes are considered by default; ``include_nested``
adds classes defined inside a class or function. Across eight measured
repositories none of the 46 nested rows was dead: most were a ``Meta`` /
``Config`` a metaclass reads, the rest live classes reached as
``self.Nested(...)``, which the resolver does not follow (#432).
Returns JSON ``{orphans, considered, test_sources, generated_excluded,
nested_excluded}``;
each orphan carries ``fqn``/``file``/``line``. **A listing is a candidate for
deletion, not a proof** β a class named only inside a decorator (#429) or
arriving through a star import is invisible here, so the sweep errs towards
reporting a live class rather than hiding a dead one. ``test_sources: 0`` in a
repository that has tests means the graph predates the ``is_test`` column:
re-ingest. ``generated_excluded`` counts every generated class left out of
the population under the same ``prefix``, referenced or not β so ``0`` on a
repository with generated code means the same for ``is_generated``, which has
no backfill: the marker is in the file header, not in the database.
Inputs: prefix, db_path, include_tests, include_nested, +1 more. Returns: result
cgis_find_symbolA
Resolve a partial symbol name to candidate FQNs (substring match, ranked).
Call this BEFORE ``cgis_trace_flow`` / ``cgis_analyze_impact`` /
``cgis_get_structure`` when you know a short name (e.g.
``get_reservation_prices``) but not its full FQN β it removes the
read-the-file-first guesswork. Returns JSON ``[{fqn, name, type, file,
line}]`` ranked exact > prefix > substring. ``kind`` filters by node type
(FUNCTION / METHOD / CLASS / β¦); ``fqn_prefix`` scopes the search. A prefix
that starts with the directories the graph was ingested below (``src.cgis``
for a graph of ``src/``) and covers no code is read without them.
Inputs: query (required), kind, limit, db_path, +1 more. Returns: result
cgis_fractalA
Report the motif census across the repository's structural tiers.
Coarsens the graph along its own structure β symbol, class, module, then
directory levels trimmed from the leaf end β and measures the 13-triad
census at every rung. Returns JSON: one entry per layer (IMPORTS, CALLS)
with the full per-rung curve (groups, triads, entropy in bits, dominant
motif, tangle ratio) and the fit.
``verdict`` is the sign of ``slope`` (entropy bits per halving of the group
count) outside a ``2 * std_error`` dead-band: ``hierarchical`` means
coarsening ADDS motif diversity, ``flat`` means it destroys it,
``scale_invariant`` means the mix is the same at every scale, and
``no_signal`` means fewer than three rungs carried enough triads to fit.
Read the curve, not just the verdict β the fit is a lossy summary of a
non-linear curve. Observe-only: this tool enforces nothing and no gate
reads it. Call after ``cgis_ingest``.
Inputs: db_path. Returns: result
cgis_get_structureA
Members of a module or class β or, for a package prefix, the modules it holds.
Follows containment (CONTAINS/DECLARES) only, so no call or import appears.
A package is not a node in the graph (#487), so its row and the edges to its
modules are synthesized for the answer and marked with a virtual file path.
For how the code connects use ``cgis_trace_flow`` (what it depends on) or
``cgis_analyze_impact`` (what depends on it).
Matches the CLI ``structure`` command. ``output_format="text"`` returns the
hierarchy as an indented tree, one line per member; ``"mermaid"`` (default) a
diagram of the hierarchy rooted at the given FQN; ``"json"`` the
joinable ``{root, nodes, edges}`` payload with real FQNs.
Inputs: fqn (required), depth, db_path, output_format. Returns: result
cgis_ingestA
Scan a local directory, extract all symbols, resolve links, and build the graph DB.
Use this to initialise or refresh the code knowledge graph for a project.
Node FQNs are normalised relative to the workspace root so the graph is
portable across machines.
``db_path`` must name a database β it has to end in ``.db``, ``.sqlite`` or
``.sqlite3``, live in a directory that already exists, and not point at an
existing file that is not a SQLite database. cgis will not create parent
directories.
By default the ingest is **incremental**: only changed/new files are
re-scanned, and the summary reports both what changed this run and the
whole-graph total. When a change alters what other files resolve against β a
renamed, removed or added symbol, a deleted or new file, a changed base class
or re-export β the incremental run rebuilds the whole graph itself, so edges
in unchanged files never point at symbols that no longer exist. Set
``full_rebuild=True`` to force a re-scan of every file from scratch.
Data keys are opt-in (``data_keys=True``): they cost every ingest time and
graph size, and make JSON and YAML edits mark the graph stale.
Inputs: project_path (required), db_path, data_keys, full_rebuild. Returns: result
cgis_init_ontologyA
Propose a starter patterns.yaml from the measured graph (read-only).
Returns the YAML text β save it yourself (e.g. to patterns.yaml), review
the proposed labels, then run ``cgis_drift`` with it. Tolerances are the
measured scores plus ``margin``: a baseline to ratchet down, not a verdict.
No files are written; the caller decides where to persist the output.
Inputs: depth, margin, db_path, min_nodes. Returns: result
cgis_metricsA
Whole-graph architectural metrics β coupling bottlenecks, God classes, PageRank.
Returns JSON ``{bottlenecks, god_classes, critical, file_coupling, class_cohesion,
resolution}``
computed with vectorized DuckDB aggregations over the whole graph (fan-in/fan-out
coupling, declared-member counts, PageRank, per-file Ca/Ce/instability) β the
global "what are the hotspots?" view that complements the node-local
trace/impact/context tools. Requires the optional ``duckdb`` extra; an
unavailable dependency is reported as a normal β message.
``file_coupling`` counts *files*, not calls: Ca is how many other files
depend on a file (by IMPORTS or CALLS), Ce how many it depends on, and
instability ``I = Ce / (Ca + Ce)`` runs from 0 (stable, expensive to change)
to 1 (volatile); it is null for a file linked to no other.
``class_cohesion`` ranks classes by LCOM4: the number of groups their instance
methods fall into when linked by a shared ``self`` attribute or a call. 1 is
cohesive; 2+ is a class doing unrelated jobs. Dunders (``__init__`` above
all), abstract, static and class methods are not counted.
``resolution`` is the share of edges the resolver could not place, by the
same rule as ``cgis validate``. Read the rankings through it: a node whose
calls are mostly unresolved looks uncoupled because its edges point nowhere.
Under ``scope``/``exclude`` it counts the edges the selected code *emits*.
``exclude`` drops any node whose FQN contains one of the given dot-segments
(e.g. ``["tests"]`` removes both ``tests.*`` and ``domains.*.tests.*``) so
test/vendor scaffolding stays out of the rankings.
``scope`` is its complement: it keeps only nodes under one of the given
dot-prefixes, anchored and cut on a dot boundary, so
``["domains.reservation"]`` is that subtree and not
``domains.reservation_archive``. Use it for a per-domain review. The two
compose, and they differ where it matters for PageRank β ``exclude`` removes
nodes from the propagation graph, ``scope`` filters the rows and lets rank
propagate over the whole graph, so a scoped run reports how central the
subtree is *globally*. Coupling in-degree likewise keeps counting callers
from outside the scope, which is the ripple a domain review is after (#239).
Inputs: limit, scope, db_path, exclude. Returns: result
cgis_module_graphA
How one package is built inside: its modules and the dependencies between them.
Nodes are the package's direct children, each sub-package one node (``expand``
lists every module instead). Edges are imports ``-->``, inheritance ``==>``
and calls ``-.->``, each kind transitively reduced so the direct layering
shows; an edge that closes a cycle is never dropped. Dependencies on code
outside the package are summarised per module under the diagram, not drawn.
Test modules and type-only imports are left out. The json form is
``{prefix, nodes, subpackages, edges:[{source,target,kind}], dropped, covered, outside}``;
``covered`` counts the imports not drawn because a drawn ``==>`` joins the
same pair: that arrow then also stands for the import, so read an import
closure over imports and extends together. An import that closes an import
cycle is always drawn.
Run ``cgis_ingest`` first.
Inputs: prefix (required), expand, layers, reduce, +3 more. Returns: result
cgis_overviewA
Where to start in a graph you know nothing about: sizes and a package map.
Call this first in an unfamiliar repository β every other tool needs a name,
and this is the one that hands you some. Returns JSON: symbol counts by type,
file and edge totals, the unresolved-edge ratio, and the largest packages with
production and tests listed separately. Each ``prefix`` goes straight into
``cgis_get_structure`` (the modules it holds), ``cgis_find_symbol``
(``fqn_prefix``) or ``cgis_metrics`` (``scope``).
Listings are capped; ``packages_omitted`` appears when rows were cut. Entry
points are deliberately not reported β "nothing calls it" is not one on a
framework codebase, where most handlers have no incoming call edge.
Inputs: depth, limit, db_path. Returns: result
cgis_suggest_packagesA
Suggest sub-package boundaries for a package from its dependency communities.
Returns JSON: modularity_q, divergence, direction (under/over/matched),
verdict (split/consolidate/aligned/leave/borderline/no_signal), the detected
communities (id + members), the cross-community bridge edges (cost of
splitting), and the thresholds used. Default layer is IMPORTS; set
``with_calls`` for the combined import+call graph. Run ``cgis_ingest`` first.
Members are the package's direct children by default, each sub-package one
node, so the verdict says whether to regroup them; ``level`` in the result
says which. ``all_descendants`` clusters every file below the package.
A mis-rooted graph (import targets resolve to no internal file) returns
``no_signal`` with a diagnostic note rather than a silent clean verdict.
Inputs: min_q, prefix, db_path, with_calls, +1 more. Returns: result
cgis_trace_flowA
Downstream subgraph of one FQN: everything it reaches within depth hops.
Follows every edge except containment β in practice calls, imports,
inheritance, DI dependencies and references β between internal code, so this
answers "what does X depend on?". Containment and
stdlib/third-party nodes are left out unless ``include_structure`` /
``include_external`` ask for them (external covers stdlib, third-party and
unresolved call targets) β the same view as the CLI's ``trace``.
For what depends on X use
``cgis_analyze_impact``; for only the members of a module or class,
``cgis_get_structure``; for a source-included brief to read before editing
one symbol, ``cgis_context``.
Test code is left out unless ``include_tests`` asks for it, and at most
``max_nodes`` nodes come back, nearest first, as for impact.
``output_format="text"`` returns the subgraph as an indented tree, one line
per node with children in call-site order, so a flow reads top down β about
a fifth of the json for the same answer; ``"mermaid"`` (default) a diagram;
``"json"`` a joinable ``{root, nodes, edges, coverage}`` payload
with real FQNs (not display hashes) for agent/CI use. ``coverage`` counts
the calls the traversed functions make that resolved to nothing, and
``top_unresolved`` names the most frequent. Read the names, not only the
ratio: in Python most are methods on untyped locals (``logger.info``,
``items.append``), which cut nothing short. Use ``cgis_ingest`` first if
the database does not exist yet.
Inputs: fqn (required), depth, db_path, max_nodes, +4 more. Returns: result
cgis_validateA
Report graph integrity as JSON: edge resolution stats + health verdict.
Check this before trusting ``cgis_analyze_impact`` output β a high
unresolved ratio means callers are missing from the graph.
Inputs: db_path, threshold. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogβ¦
TDQS
Scored across 17 tools
Each tool targets a distinct analysis taskβingest, overview, symbol lookup, structure, downstream vs. upstream traversal, context brief, metrics, drift, etc.βand descriptions explicitly cross-reference alternatives. A few whole-graph analytics (metrics, fractal, drift, suggest_packages) sit near each other conceptually, but their outputs and intended questions differ enough to keep boundaries clear.
All names use a consistent cgis_ snake_case prefix and are readable. The suffix convention mixes verb_noun forms (find_symbol, trace_flow, analyze_impact) with noun phrases (metrics, fractal, context, diff_check), so it is not a strict verb_noun pattern throughout.
17 tools is slightly above the typical 3β15 range, but the serverβs purpose is broad code-graph analysis and each tool covers a distinct operation or report. It does not feel padded, though a few specialized analyses are arguably optional.
The surface covers initialization, discovery, structure, traversal in both directions, context generation, validation, metrics, dead-code detection, auth reachability, drift, package suggestions, ontology initialization, and diff impact. From ingest through analysis and validation there are no obvious dead ends for the stated code-intelligence domain.
Maintenance
Related MCP Connectors
Code intelligence platform for AI agents. 20 tools for architecture, security & impact analysis.
AI Agent with Architectural Memory. Impact analysis (free), tests and code from the graph (pro).
Codebase intelligence for AI agents β dead code, blast radius, ownership.
AI-powered codebase analysis β call graphs, security, dead code, complexity. 150+ tools.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceSupercharges AI coding agents with a pre-indexed semantic code graph, enabling instant symbol relationships, impact analysis, and context retrieval across 20+ languages.175,110 npm77,678MIT

mcp-reposkeinofficial
AlicenseAqualityBmaintenanceDeterministic code-graph (GraphRAG) over your repo for LLM agents β local-first, git-native, zero-infra, served via MCP. Python, TS/JS, Rust, Go, Java, C#.813Apache 2.0- AlicenseAqualityCmaintenanceIndexes any TypeScript / React / Next.js repo into a queryable code graph and exposes 13 MCP tools β who-renders, who-calls, find-references, blast-radius, find-cycles, dead-code orphans, and local semantic search β so agents query structure instead of reading whole files. Built on ts-morph, so edges are resolved, not grepped.142MIT

CodeGraphofficial
AlicenseNot gradedqualityBmaintenanceBuilds a semantic graph of codebases across 38 languages and exposes 42 MCP tools for structured code understanding, search, and impact analysis.152Apache 2.0