Skip to main content
Glama

🧠 CGIS: Code Graph Intelligence System

A code graph your AI agent can query instead of guess

Continuous Integration Graph Integrity PyPI

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-brain

That 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 output

Or 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

cgis_ingest

Build or incrementally refresh the graph

cgis_overview

Where to start: sizes and the largest packages, when you have no FQN yet

cgis_find_symbol

Partial name β†’ candidate FQNs

cgis_analyze_impact

What breaks upstream if this changes?

cgis_trace_flow

What does this call, transitively?

cgis_get_structure

Class / module hierarchy

cgis_context

A compact GraphRAG context package for one symbol

cgis_metrics

Coupling, god classes, PageRank, package cohesion

cgis_audit_reachability

Authz / IDOR coverage β€” does every handler reach its guard?

cgis_drift

How far each domain has moved from its declared pattern

cgis_validate

Graph integrity: resolved vs unresolved edges

All 16 tools, with parameters: MCP_REFERENCE.md.


πŸ—οΈ How It Works

  1. Extract β€” tree-sitter parsers turn each file into nodes and raw call edges.

  2. Resolve β€” the ResolverEngine maps raw calls to fully qualified names, or leaves them explicitly unresolved.

  3. 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 --> G

The 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 --inline

In 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 pytest

See 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 tools
cgis_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

    A4.3/5.0

    Scored across 17 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count4/5

    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.

    Completeness5/5

    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

    ActivityActive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Supercharges AI coding agents with a pre-indexed semantic code graph, enabling instant symbol relationships, impact analysis, and context retrieval across 20+ languages.
      175,110 npm
      77,678
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Deterministic 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#.
      8
      13
      Apache 2.0
    • A
      license
      A
      quality
      C
      maintenance
      Indexes 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.
      14
      2
      MIT