codegraph-brain 0.23.2__tar.gz → 0.23.3__tar.gz

codegraph_brain-0.23.3/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.23.3"
+}

{codegraph_brain-0.23.2 → codegraph_brain-0.23.3}/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [0.23.3](https://github.com/zaebee/codegraph-brain/compare/codegraph-brain-v0.23.2...codegraph-brain-v0.23.3) (2026-09-17)
+
+
+### Documentation
+
+* auto-sync architecture graph and MCP reference ([#480](https://github.com/zaebee/codegraph-brain/issues/480)) ([5379cce](https://github.com/zaebee/codegraph-brain/commit/5379cce927b5fade5e2371503a0cd9e1f8041fc7))
+* **mcp:** say when to use each overlapping graph tool ([#477](https://github.com/zaebee/codegraph-brain/issues/477)) ([f33d764](https://github.com/zaebee/codegraph-brain/commit/f33d764ebdf217359964347aaa1137dc18ced513))
+
 ## [0.23.2](https://github.com/zaebee/codegraph-brain/compare/codegraph-brain-v0.23.1...codegraph-brain-v0.23.2) (2026-09-17)
 
 

{codegraph_brain-0.23.2 → codegraph_brain-0.23.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: codegraph-brain
-Version: 0.23.2
+Version: 0.23.3
 Summary: Semantic code graph for AI agents — deterministic FQN resolution, impact analysis and architectural drift gates, exposed over MCP.
 Project-URL: Homepage, https://github.com/zaebee/codegraph-brain
 Project-URL: Repository, https://github.com/zaebee/codegraph-brain

{codegraph_brain-0.23.2 → codegraph_brain-0.23.3}/docs/how-to/MCP_REFERENCE.md

@@ -7,9 +7,16 @@
 
 ## `cgis_analyze_impact`
 
-Analyse transitive upstream callers of a specific FQN.
+Upstream subgraph of one FQN: everything that reaches it within ``depth`` hops.
 
-    Answers "what breaks if I change X?". ``output_format="mermaid"`` (default)
+    Every edge type counts — callers, but also importers, subclasses, type
+    references, DI dependents and the enclosing class or file — so this answers
+    "what breaks if I change X?". 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="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``?")
@@ -22,14 +29,14 @@ Analyse transitive upstream callers of a specific FQN.
 | :--- | :--- | :---: | :--- |
 | `fqn` | `string` | ✓ | Fully qualified name, e.g. pkg.module.Class.method. A unique dot-boundary suffix also resolves; an ambiguous one returns candidates. Use cgis_find_symbol to look a name up. |
 | `db_path` | `string` |  | SQLite graph built by cgis_ingest. A relative path resolves against the MCP server's working directory, not the agent's — prefer an absolute path. |
-| `depth` | `integer` |  | Maximum edge hops upstream. Every edge type counts as a hop — CALLS, but also IMPORTS, CONTAINS and REFERENCES — so modules importing the target and the file containing it appear alongside its callers. |
+| `depth` | `integer` |  | Maximum edge hops upstream. Every edge type counts as a hop — callers, importers, subclasses, type references, DI dependents and the enclosing class or file all appear alongside each other. |
 | `output_format` | `string` |  | "mermaid" for a diagram, or "json" for a payload with real FQNs (case-insensitive). Any other value returns an error. |
 
 ---
 
 ## `cgis_audit_reachability`
 
-Reachability/authorization audit — which sources never reach a checkpoint (#172).
+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
@@ -56,7 +63,14 @@ Reachability/authorization audit — which sources never reach a checkpoint (#17
 
 ## `cgis_context`
 
-Compile an agent-facing GraphRAG context package for a focal FQN (#19).
+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 every edge type 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
@@ -115,7 +129,7 @@ Report per-domain architectural drift against declared ideal patterns.
 
 ## `cgis_find_orphans`
 
-Classes nothing in production builds, extends or names — dead-code candidates (#415).
+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
@@ -209,10 +223,13 @@ Report the motif census across the repository's structural tiers.
 
 ## `cgis_get_structure`
 
-Show the structural layout (CONTAINS/DECLARES) of a module or class.
+Members of a module or class: the classes, functions and methods it contains.
 
-    Traverses only containment edges — no call-graph noise — matching the CLI
-    ``structure`` command. ``output_format="mermaid"`` (default) returns a
+    Follows containment (CONTAINS/DECLARES) only, so no call or import appears.
+    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="mermaid"`` (default) returns a
     diagram of the hierarchy rooted at the given FQN; ``"json"`` returns the
     joinable ``{root, nodes, edges}`` payload with real FQNs.
 
@@ -275,7 +292,7 @@ Propose a starter patterns.yaml from the measured graph (read-only).
 
 ## `cgis_metrics`
 
-Whole-graph architectural metrics — coupling bottlenecks + God classes (#16).
+Whole-graph architectural metrics — coupling bottlenecks, God classes, PageRank.
 
     Returns JSON ``{bottlenecks, god_classes, critical}`` computed with vectorized
     DuckDB aggregations over the whole graph (fan-in/fan-out coupling,
@@ -331,7 +348,15 @@ Suggest sub-package boundaries for a package from its dependency communities.
 
 ## `cgis_trace_flow`
 
-Trace the execution call-graph starting from a specific FQN downwards.
+Downstream subgraph of one FQN: everything it reaches within ``depth`` hops.
+
+    Every edge type counts — calls, imports, inheritance, DI dependencies,
+    references, and containment (so from a module or class the first hop includes
+    its own members) — so this answers "what does X depend on?". 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``.
 
     ``output_format="mermaid"`` (default) returns a human-readable diagram;
     ``"json"`` returns a joinable ``{root, nodes, edges, coverage}`` payload
@@ -346,7 +371,7 @@ Trace the execution call-graph starting from a specific FQN downwards.
 | :--- | :--- | :---: | :--- |
 | `fqn` | `string` | ✓ | Fully qualified name, e.g. pkg.module.Class.method. A unique dot-boundary suffix also resolves; an ambiguous one returns candidates. Use cgis_find_symbol to look a name up. |
 | `db_path` | `string` |  | SQLite graph built by cgis_ingest. A relative path resolves against the MCP server's working directory, not the agent's — prefer an absolute path. |
-| `depth` | `integer` |  | Maximum edge hops downstream. Every edge type counts as a hop — CALLS, but also IMPORTS, CONTAINS and REFERENCES — so from a module the first hops are mostly imports and structure. |
+| `depth` | `integer` |  | Maximum edge hops downstream. Every edge type counts as a hop — calls, imports, inheritance, DI dependencies, references and containment — so from a module or class the first hop is mostly its own members and imports. |
 | `output_format` | `string` |  | "mermaid" for a diagram, or "json" for a payload with real FQNs (case-insensitive). Any other value returns an error. |
 
 ---

{codegraph_brain-0.23.2 → codegraph_brain-0.23.3}/pyproject.toml

@@ -7,7 +7,7 @@ packages = ["src/cgis"]
 
 [project]
 name = "codegraph-brain"
-version = "0.23.2"
+version = "0.23.3"
 description = "Semantic code graph for AI agents — deterministic FQN resolution, impact analysis and architectural drift gates, exposed over MCP."
 readme = "README.md"
 requires-python = ">=3.12"

{codegraph_brain-0.23.2 → codegraph_brain-0.23.3}/server.json

@@ -8,13 +8,13 @@
     "source": "github",
     "id": "1260843154"
   },
-  "version": "0.23.2",
+  "version": "0.23.3",
   "packages": [
     {
       "registryType": "pypi",
       "registryBaseUrl": "https://pypi.org",
       "identifier": "codegraph-brain",
-      "version": "0.23.2",
+      "version": "0.23.3",
       "runtimeHint": "uvx",
       "transport": {
         "type": "stdio"

{codegraph_brain-0.23.2 → codegraph_brain-0.23.3}/src/cgis/api/mcp_server.py

@@ -364,13 +364,21 @@ def cgis_trace_flow(
         int,
         Field(
             description="Maximum edge hops downstream. Every edge type counts as a hop — "
-            "CALLS, but also IMPORTS, CONTAINS and REFERENCES — so from a module the first "
-            "hops are mostly imports and structure."
+            "calls, imports, inheritance, DI dependencies, references and containment — so "
+            "from a module or class the first hop is mostly its own members and imports."
         ),
     ] = 3,
     output_format: OutputFormat = "mermaid",
 ) -> str:
-    """Trace the execution call-graph starting from a specific FQN downwards.
+    """Downstream subgraph of one FQN: everything it reaches within ``depth`` hops.
+
+    Every edge type counts — calls, imports, inheritance, DI dependencies,
+    references, and containment (so from a module or class the first hop includes
+    its own members) — so this answers "what does X depend on?". 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``.
 
     ``output_format="mermaid"`` (default) returns a human-readable diagram;
     ``"json"`` returns a joinable ``{root, nodes, edges, coverage}`` payload
@@ -417,15 +425,22 @@ def cgis_analyze_impact(
         int,
         Field(
             description="Maximum edge hops upstream. Every edge type counts as a hop — "
-            "CALLS, but also IMPORTS, CONTAINS and REFERENCES — so modules importing the "
-            "target and the file containing it appear alongside its callers."
+            "callers, importers, subclasses, type references, DI dependents and the "
+            "enclosing class or file all appear alongside each other."
         ),
     ] = 3,
     output_format: OutputFormat = "mermaid",
 ) -> str:
-    """Analyse transitive upstream callers of a specific FQN.
+    """Upstream subgraph of one FQN: everything that reaches it within ``depth`` hops.
+
+    Every edge type counts — callers, but also importers, subclasses, type
+    references, DI dependents and the enclosing class or file — so this answers
+    "what breaks if I change X?". 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``.
 
-    Answers "what breaks if I change X?". ``output_format="mermaid"`` (default)
+    ``output_format="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``?")
@@ -471,10 +486,13 @@ def cgis_get_structure(
     ] = 2,
     output_format: OutputFormat = "mermaid",
 ) -> str:
-    """Show the structural layout (CONTAINS/DECLARES) of a module or class.
+    """Members of a module or class: the classes, functions and methods it contains.
 
-    Traverses only containment edges — no call-graph noise — matching the CLI
-    ``structure`` command. ``output_format="mermaid"`` (default) returns a
+    Follows containment (CONTAINS/DECLARES) only, so no call or import appears.
+    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="mermaid"`` (default) returns a
     diagram of the hierarchy rooted at the given FQN; ``"json"`` returns the
     joinable ``{root, nodes, edges}`` payload with real FQNs.
     """
@@ -785,7 +803,14 @@ def cgis_context(
         ),
     ] = "",
 ) -> str:
-    """Compile an agent-facing GraphRAG context package for a focal FQN (#19).
+    """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 every edge type 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
@@ -836,7 +861,7 @@ def cgis_metrics(
         ),
     ] = None,
 ) -> str:
-    """Whole-graph architectural metrics — coupling bottlenecks + God classes (#16).
+    """Whole-graph architectural metrics — coupling bottlenecks, God classes, PageRank.
 
     Returns JSON ``{bottlenecks, god_classes, critical}`` computed with vectorized
     DuckDB aggregations over the whole graph (fan-in/fan-out coupling,
@@ -894,7 +919,7 @@ def cgis_find_orphans(
         bool, Field(description="Include machine-generated classes, which are hidden by default.")
     ] = False,
 ) -> str:
-    """Classes nothing in production builds, extends or names — dead-code candidates (#415).
+    """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
@@ -976,7 +1001,7 @@ def cgis_audit_reachability(
         Field(description="Maximum reachability depth; a longer path is reported as a gap."),
     ] = 5,
 ) -> str:
-    """Reachability/authorization audit — which sources never reach a checkpoint (#172).
+    """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

{codegraph_brain-0.23.2 → codegraph_brain-0.23.3}/tests/unit/test_mcp_tool_schemas.py

@@ -7,6 +7,7 @@ server announced an empty version to every client that connected.
 """
 
 import asyncio
+import re
 
 import pytest
 
@@ -45,3 +46,29 @@ def test_server_announces_the_package_version() -> None:
     """`initialize` reports the installed version, not an empty string."""
     assert mcp.version == __version__
     assert mcp.version
+
+
+_DESCRIPTIONS = {tool.name: tool.description or "" for tool in asyncio.run(mcp.list_tools())}
+
+
+def test_tool_summaries_carry_no_issue_numbers() -> None:
+    """The first paragraph is what an agent weighs when choosing; `(#19)` tells it nothing."""
+    for name, description in _DESCRIPTIONS.items():
+        summary = description.strip().split("\n\n")[0]
+        assert not re.search(r"\(#\d+\)", summary), f"{name}: {summary!r}"
+
+
+@pytest.mark.parametrize(
+    ("tool", "siblings"),
+    [
+        ("cgis_trace_flow", {"cgis_analyze_impact", "cgis_get_structure", "cgis_context"}),
+        ("cgis_analyze_impact", {"cgis_trace_flow", "cgis_get_structure", "cgis_context"}),
+        ("cgis_get_structure", {"cgis_trace_flow", "cgis_analyze_impact"}),
+        ("cgis_context", {"cgis_trace_flow", "cgis_analyze_impact"}),
+    ],
+)
+def test_overlapping_graph_tools_say_when_to_use_a_sibling(tool: str, siblings: set[str]) -> None:
+    """All four return a subgraph around one FQN; each names the ones it could be taken for."""
+    description = _DESCRIPTIONS[tool]
+    missing = {sibling for sibling in siblings if sibling not in description}
+    assert not missing, f"{tool} never mentions {sorted(missing)}"

{codegraph_brain-0.23.2 → codegraph_brain-0.23.3}/uv.lock

@@ -261,7 +261,7 @@ wheels = [
 
 [[package]]
 name = "codegraph-brain"
-version = "0.23.2"
+version = "0.23.3"
 source = { editable = "." }
 dependencies = [
     { name = "httpx" },

codegraph_brain-0.23.2/.release-please-manifest.json

@@ -1,3 +0,0 @@
-{
-  ".": "0.23.2"
-}