codegraph-brain 0.22.0__tar.gz → 0.23.0__tar.gz

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

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

{codegraph_brain-0.22.0 → codegraph_brain-0.23.0}/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.23.0](https://github.com/zaebee/codegraph-brain/compare/codegraph-brain-v0.22.0...codegraph-brain-v0.23.0) (2026-09-17)
+
+
+### Features
+
+* **mcp:** describe every tool parameter and announce the server version ([#466](https://github.com/zaebee/codegraph-brain/issues/466)) ([1863a11](https://github.com/zaebee/codegraph-brain/commit/1863a111a752d01303de482b88cee46322184b16))
+
 ## [0.22.0](https://github.com/zaebee/codegraph-brain/compare/codegraph-brain-v0.21.0...codegraph-brain-v0.22.0) (2026-09-17)
 
 

{codegraph_brain-0.22.0 → codegraph_brain-0.23.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: codegraph-brain
-Version: 0.22.0
+Version: 0.23.0
 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.22.0 → codegraph_brain-0.23.0}/pyproject.toml

@@ -7,7 +7,7 @@ packages = ["src/cgis"]
 
 [project]
 name = "codegraph-brain"
-version = "0.22.0"
+version = "0.23.0"
 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.22.0 → codegraph_brain-0.23.0}/server.json

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

{codegraph_brain-0.22.0 → codegraph_brain-0.23.0}/src/cgis/api/mcp_server.py

@@ -8,11 +8,13 @@ import dataclasses
 import json
 import sys
 from pathlib import Path
-from typing import Any
+from typing import Annotated, Any
 
 import structlog
 from mcp.server.mcpserver import MCPServer
+from pydantic import Field
 
+from cgis import __version__
 from cgis.core.coverage import TraversalCoverage
 from cgis.core.freshness import Freshness, FreshnessState
 from cgis.core.models import Edge, Node, NodeType
@@ -37,7 +39,7 @@ print("CGIS MCP Server starting…", file=sys.stderr)
 
 logger = structlog.getLogger(__name__)
 
-mcp: MCPServer = MCPServer("cgis-code-graph")
+mcp: MCPServer = MCPServer("cgis-code-graph", version=__version__)
 
 _EXTRACTORS = {
     ".py": PythonExtractor(),
@@ -46,6 +48,31 @@ _EXTRACTORS = {
 }
 _DEFAULT_DB = "graph.db"
 
+# Agents choose arguments from the JSON schema, and the SDK does not copy
+# docstring prose into it — each parameter's meaning has to be declared here.
+DbPath = Annotated[
+    str,
+    Field(
+        description="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."
+    ),
+]
+Fqn = Annotated[
+    str,
+    Field(
+        description="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."
+    ),
+]
+OutputFormat = Annotated[
+    str,
+    Field(
+        description='"mermaid" for a diagram, or "json" for a payload with real FQNs '
+        "(case-insensitive). Any other value returns an error."
+    ),
+]
+
 
 def _resolution_error(fqn: str, candidates: list[str], truncated: bool = False) -> str:
     """Render a not-found / ambiguous FQN error for tool output."""
@@ -246,7 +273,27 @@ def _with_freshness(db_path: str, payload: dict[str, Any]) -> dict[str, Any]:
 
 
 @mcp.tool()
-def cgis_ingest(project_path: str, db_path: str = _DEFAULT_DB, full_rebuild: bool = False) -> str:
+def cgis_ingest(
+    project_path: Annotated[
+        str,
+        Field(
+            description="Root directory of the project to scan. A relative path resolves "
+            "against the MCP server's working directory."
+        ),
+    ],
+    db_path: Annotated[
+        str,
+        Field(
+            description="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."
+        ),
+    ] = _DEFAULT_DB,
+    full_rebuild: Annotated[
+        bool,
+        Field(description="Re-scan every file from scratch instead of the incremental default."),
+    ] = False,
+) -> str:
     """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.
@@ -311,7 +358,17 @@ def cgis_ingest(project_path: str, db_path: str = _DEFAULT_DB, full_rebuild: boo
 
 @mcp.tool()
 def cgis_trace_flow(
-    fqn: str, db_path: str = _DEFAULT_DB, depth: int = 3, output_format: str = "mermaid"
+    fqn: Fqn,
+    db_path: DbPath = _DEFAULT_DB,
+    depth: Annotated[
+        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."
+        ),
+    ] = 3,
+    output_format: OutputFormat = "mermaid",
 ) -> str:
     """Trace the execution call-graph starting from a specific FQN downwards.
 
@@ -354,7 +411,17 @@ def cgis_trace_flow(
 
 @mcp.tool()
 def cgis_analyze_impact(
-    fqn: str, db_path: str = _DEFAULT_DB, depth: int = 3, output_format: str = "mermaid"
+    fqn: Fqn,
+    db_path: DbPath = _DEFAULT_DB,
+    depth: Annotated[
+        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."
+        ),
+    ] = 3,
+    output_format: OutputFormat = "mermaid",
 ) -> str:
     """Analyse transitive upstream callers of a specific FQN.
 
@@ -397,7 +464,12 @@ def cgis_analyze_impact(
 
 @mcp.tool()
 def cgis_get_structure(
-    fqn: str, db_path: str = _DEFAULT_DB, depth: int = 2, output_format: str = "mermaid"
+    fqn: Fqn,
+    db_path: DbPath = _DEFAULT_DB,
+    depth: Annotated[
+        int, Field(description="Maximum containment levels to descend (module → class → method).")
+    ] = 2,
+    output_format: OutputFormat = "mermaid",
 ) -> str:
     """Show the structural layout (CONTAINS/DECLARES) of a module or class.
 
@@ -427,11 +499,35 @@ def cgis_get_structure(
 
 @mcp.tool()
 def cgis_drift(
-    db_path: str = _DEFAULT_DB,
-    patterns_path: str = "docs/ontology/patterns.yaml",
-    max_drift: float = 0.50,
-    profile: str | None = None,
-    max_residual: float = 0.45,
+    db_path: DbPath = _DEFAULT_DB,
+    patterns_path: Annotated[
+        str,
+        Field(
+            description="patterns.yaml (.yaml or .yml) declaring each domain's expected "
+            "pattern and tolerance, relative to the server's working directory. "
+            "cgis_init_ontology proposes one."
+        ),
+    ] = "docs/ontology/patterns.yaml",
+    max_drift: Annotated[
+        float,
+        Field(
+            description="Drift tolerance for domains that declare no drift_tolerance of their own."
+        ),
+    ] = 0.50,
+    profile: Annotated[
+        str | None,
+        Field(
+            description="Score only domains with this profile, plus profile-less ones — e.g. one "
+            "language when patterns.yaml mixes several."
+        ),
+    ] = None,
+    max_residual: Annotated[
+        float,
+        Field(
+            description="Distance to the nearest template beyond which a domain's fit band is "
+            '"none" (no template fits).'
+        ),
+    ] = 0.45,
 ) -> str:
     """Report per-domain architectural drift against declared ideal patterns.
 
@@ -490,10 +586,24 @@ def cgis_drift(
 
 @mcp.tool()
 def cgis_suggest_packages(
-    db_path: str = _DEFAULT_DB,
-    prefix: str | None = None,
-    with_calls: bool = False,
-    min_q: float = 0.35,
+    db_path: DbPath = _DEFAULT_DB,
+    prefix: Annotated[
+        str | None,
+        Field(
+            description="FQN prefix of the package to analyse, e.g. cgis.query, matched on whole "
+            "dot-segments. Needed in practice: without it the verdict is no_signal."
+        ),
+    ] = None,
+    with_calls: Annotated[
+        bool, Field(description="Use the combined import + call graph instead of imports only.")
+    ] = False,
+    min_q: Annotated[
+        float,
+        Field(
+            description="Modularity threshold: at or above it, a package whose layout "
+            "disagrees with its communities is flagged split (or consolidate, if over-split)."
+        ),
+    ] = 0.35,
 ) -> str:
     """Suggest sub-package boundaries for a package from its dependency communities.
 
@@ -516,7 +626,12 @@ def cgis_suggest_packages(
 
 
 @mcp.tool()
-def cgis_validate(db_path: str = _DEFAULT_DB, threshold: float = 0.30) -> str:
+def cgis_validate(
+    db_path: DbPath = _DEFAULT_DB,
+    threshold: Annotated[
+        float, Field(description="Highest unresolved-edge ratio (0-1) still reported as healthy.")
+    ] = 0.30,
+) -> str:
     """Report graph integrity as JSON: edge resolution stats + health verdict.
 
     Check this before trusting ``cgis_analyze_impact`` output — a high
@@ -547,11 +662,30 @@ def cgis_validate(db_path: str = _DEFAULT_DB, threshold: float = 0.30) -> str:
 
 @mcp.tool()
 def cgis_find_symbol(
-    query: str,
-    db_path: str = _DEFAULT_DB,
-    kind: str | None = None,
-    fqn_prefix: str | None = None,
-    limit: int = 20,
+    query: Annotated[
+        str,
+        Field(
+            description="Leaf symbol name to search for, without dots (e.g. get_flow_result) — "
+            "not an FQN. Case-insensitive substring match, ranked exact > prefix > substring."
+        ),
+    ],
+    db_path: DbPath = _DEFAULT_DB,
+    kind: Annotated[
+        str | None,
+        Field(
+            description="Only return this node type, e.g. FUNCTION, METHOD or CLASS (any case). "
+            "An unknown type matches nothing rather than raising an error."
+        ),
+    ] = None,
+    fqn_prefix: Annotated[
+        str | None,
+        Field(
+            description="Only return symbols at or under this FQN prefix, matched on whole "
+            "dot-segments: app.svc does not match app.svc_alt, and a partial segment "
+            "matches nothing."
+        ),
+    ] = None,
+    limit: Annotated[int, Field(description="Maximum number of candidates to return.")] = 20,
 ) -> str:
     """Resolve a partial symbol name to candidate FQNs (substring match, ranked).
 
@@ -594,10 +728,22 @@ def cgis_find_symbol(
 
 @mcp.tool()
 def cgis_init_ontology(
-    db_path: str = _DEFAULT_DB,
-    margin: float = 0.03,
-    min_nodes: int = 10,
-    depth: int | None = None,
+    db_path: DbPath = _DEFAULT_DB,
+    margin: Annotated[
+        float,
+        Field(description="Headroom added to each measured score to form the proposed tolerance."),
+    ] = 0.03,
+    min_nodes: Annotated[
+        int,
+        Field(description="Domains with fewer nodes stay hygiene-only instead of getting a label."),
+    ] = 10,
+    depth: Annotated[
+        int | None,
+        Field(
+            description="Fixed FQN segment depth for domain discovery (positive); omit to pick it "
+            "automatically."
+        ),
+    ] = None,
 ) -> str:
     """Propose a starter patterns.yaml from the measured graph (read-only).
 
@@ -623,7 +769,21 @@ def cgis_init_ontology(
 
 @mcp.tool()
 def cgis_context(
-    fqn: str, db_path: str = _DEFAULT_DB, depth: int = 1, source_root: str = ""
+    fqn: Fqn,
+    db_path: DbPath = _DEFAULT_DB,
+    depth: Annotated[
+        int,
+        Field(description="Call hops around the focal node; 1 means direct callers and callees."),
+    ] = 1,
+    source_root: Annotated[
+        str,
+        Field(
+            description="Directory the graph's stored file paths are relative to — normally the "
+            "project_path given to cgis_ingest; prefer an absolute path. Empty means the "
+            "server's working directory, so source shows as unavailable when the server runs "
+            "elsewhere."
+        ),
+    ] = "",
 ) -> str:
     """Compile an agent-facing GraphRAG context package for a focal FQN (#19).
 
@@ -659,10 +819,22 @@ def cgis_context(
 
 @mcp.tool()
 def cgis_metrics(
-    db_path: str = _DEFAULT_DB,
-    limit: int = 10,
-    exclude: list[str] | None = None,
-    scope: list[str] | None = None,
+    db_path: DbPath = _DEFAULT_DB,
+    limit: Annotated[int, Field(description="Top-N rows returned per section.")] = 10,
+    exclude: Annotated[
+        list[str] | None,
+        Field(
+            description='Drop nodes whose FQN contains any of these dot-segments, e.g. ["tests"]; '
+            "they are removed from PageRank propagation too."
+        ),
+    ] = None,
+    scope: Annotated[
+        list[str] | None,
+        Field(
+            description="Keep only nodes under any of these dot-prefixes, e.g. "
+            '["domains.billing"]; rank still propagates over the whole graph.'
+        ),
+    ] = None,
 ) -> str:
     """Whole-graph architectural metrics — coupling bottlenecks + God classes (#16).
 
@@ -706,10 +878,21 @@ def cgis_metrics(
 
 @mcp.tool()
 def cgis_find_orphans(
-    db_path: str = _DEFAULT_DB,
-    prefix: str | None = None,
-    include_tests: bool = False,
-    include_generated: bool = False,
+    db_path: DbPath = _DEFAULT_DB,
+    prefix: Annotated[
+        str | None,
+        Field(description="Only consider classes under this FQN prefix, cut on a dot boundary."),
+    ] = None,
+    include_tests: Annotated[
+        bool,
+        Field(
+            description="Count test code as a user, so the report means "
+            '"unreachable from anywhere".'
+        ),
+    ] = False,
+    include_generated: Annotated[
+        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).
 
@@ -764,11 +947,33 @@ def cgis_find_orphans(
 
 @mcp.tool()
 def cgis_audit_reachability(
-    target: str,
-    db_path: str = _DEFAULT_DB,
-    from_type: str | None = None,
-    from_prefix: str | None = None,
-    depth: int = 5,
+    target: Annotated[
+        str,
+        Field(
+            description="FQN of the checkpoint every source must reach, e.g. an ownership check. "
+            "A unique dot-boundary suffix also resolves."
+        ),
+    ],
+    db_path: DbPath = _DEFAULT_DB,
+    from_type: Annotated[
+        str | None,
+        Field(
+            description="NodeType of the sources to audit, e.g. ROUTE_HANDLER, API_ENDPOINT or "
+            "FUNCTION (any case). Give this, from_prefix, or both."
+        ),
+    ] = None,
+    from_prefix: Annotated[
+        str | None,
+        Field(
+            description="Only audit sources at or under this FQN prefix, matched on whole "
+            "dot-segments — a partial segment selects nothing and returns an empty audit, "
+            "not a clean one. Combined with from_type when both are given."
+        ),
+    ] = None,
+    depth: Annotated[
+        int,
+        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).
 
@@ -817,7 +1022,7 @@ def cgis_audit_reachability(
 
 
 @mcp.tool()
-def cgis_fractal(db_path: str = _DEFAULT_DB) -> str:
+def cgis_fractal(db_path: DbPath = _DEFAULT_DB) -> str:
     """Report the motif census across the repository's structural tiers.
 
     Coarsens the graph along its own structure — symbol, class, module, then

codegraph_brain-0.23.0/tests/unit/test_mcp_tool_schemas.py

@@ -0,0 +1,47 @@
+"""The MCP tool schemas an agent actually receives.
+
+An agent picks arguments from the JSON schema, not from the docstring: the SDK
+copies a docstring into the tool description but leaves every parameter bare.
+Directories score this too — Glama rated all 53 parameters undescribed, and the
+server announced an empty version to every client that connected.
+"""
+
+import asyncio
+
+import pytest
+
+from cgis import __version__
+from cgis.api.mcp_server import mcp
+
+
+def _tool_params() -> list[tuple[str, str, dict[str, object]]]:
+    tools = asyncio.run(mcp.list_tools())
+    return [
+        (tool.name, name, prop)
+        for tool in tools
+        for name, prop in tool.input_schema.get("properties", {}).items()
+    ]
+
+
+_PARAMS = _tool_params()
+
+
+def test_every_tool_exposes_parameters() -> None:
+    """Guards the parametrized test below from passing over an empty list."""
+    assert len(_PARAMS) >= 50
+
+
+@pytest.mark.parametrize(
+    ("tool", "param", "schema"), _PARAMS, ids=[f"{t}.{p}" for t, p, _ in _PARAMS]
+)
+def test_every_parameter_is_described(tool: str, param: str, schema: dict[str, object]) -> None:
+    """Each argument carries a description in the schema the client sees."""
+    description = schema.get("description")
+    assert isinstance(description, str), f"{tool}.{param} has no description"
+    assert len(description) >= 15, f"{tool}.{param}: {description!r} says too little"
+
+
+def test_server_announces_the_package_version() -> None:
+    """`initialize` reports the installed version, not an empty string."""
+    assert mcp.version == __version__
+    assert mcp.version

{codegraph_brain-0.22.0 → codegraph_brain-0.23.0}/uv.lock

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

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

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