codegraph-brain

Overview Schema Source Related Servers Discussions Admin

cgis_ingest

Scan a project directory to extract symbols, resolve links, and build or refresh a portable SQLite code knowledge graph for AI agents. Incremental updates are default.

Instructions

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.

Input Schema

Name	Required	Description	Default
`db_path`	No	Where to write the graph: must end in .db, .sqlite or .sqlite3, in a directory that already exists, and must not be an existing non-SQLite file. A relative path resolves against the server's working directory.	graph.db
`data_keys`	No	Extract data keys (Python dict keys, JSON and YAML declarations) for cgis_diff_check. Off by default. Left out, an existing graph keeps the mode it was built in, and a new one takes CGIS_DATA_KEYS=1 from the server's environment. Switching it rebuilds the graph.
`full_rebuild`	No	Re-scan every file from scratch instead of the incremental default.
`project_path`	Yes	Root directory of the project to scan. A relative path resolves against the MCP server's working directory.

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.21.15Oct 19, 2026

addedInput schema / properties / data_keys

Added value: +{
+  "anyOf": [
+    {
+      "type": "boolean"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Extract data keys (Python dict keys, JSON and YAML declarations) for cgis_diff_check. Off by default. Left out, an existing graph keeps the mode it was built in, and a new one takes CGIS_DATA_KEYS=1 from the server's environment. Switching it rebuilds the graph.",
+  "title": "Data Keys"
+}

Changed3 schema fields changedv0.21.1Sep 17, 2026

addedInput schema / properties / db_path / description

Added value: +"Where to write the graph: must end in .db, .sqlite or .sqlite3, in a directory that already exists, and must not be an existing non-SQLite file. A relative path resolves against the server's working directory."

addedInput schema / properties / full_rebuild / description

Added value: +"Re-scan every file from scratch instead of the incremental default."

addedInput schema / properties / project_path / description

Added value: +"Root directory of the project to scan. A relative path resolves against the MCP server's working directory."

First observedv0.21.0Sep 17, 2026

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does so well: it discloses the incremental-by-default model, the automatic whole-graph rebuild triggers (renamed/removed/added symbols, deleted/new files, changed base class or re-export), the full_rebuild override, the cost of data_keys in time and graph size plus its staleness side effect on JSON/YAML edits, and the constraint that parent directories will not be created.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose, then conditions, then the incremental/full-rebuild distinction and the data_keys caveat — a sensible ordering with no filler sentences. It loses a point because the db_path restrictions are restated almost verbatim from the schema rather than summarised once.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need no explanation. Against a 4-parameter mutation-style ingest tool with zero annotations, the description covers process, incremental semantics, rebuild triggers, opt-in features and failure conditions — nothing an agent needs in order to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3; the description goes beyond it by explaining the consequences of data_keys (cost, staleness, mode inheritance, rebuild-on-switch) and the semantics of full_rebuild rather than just restating the flag. The db_path paragraph largely duplicates the schema, keeping this just above baseline rather than clearly exceptional.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence names a specific verb chain and resource: scan a directory, extract symbols, resolve links, build the graph DB. That is clearly distinguishable from the read-only analysis siblings (cgis_find_symbol, cgis_analyze_impact, cgis_overview), which the agent can tell apart without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

"Use this to initialise or refresh the code knowledge graph for a project" gives clear context, and the data_keys note routes the agent toward cgis_diff_check when that feature is needed. However, it never states when NOT to use this tool versus an analysis sibling, nor prerequisites like having a workspace already in place; the guidance is contextual but not exclusionary.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server