sql-code-graph 1.4.3__py3-none-any.whl → 1.5.1__py3-none-any.whl

{sql_code_graph-1.4.3.dist-info → sql_code_graph-1.5.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sql-code-graph
-Version: 1.4.3
+Version: 1.5.1
 Summary: SQL code graph analyzer and lineage tracer
 Project-URL: Homepage, https://github.com/Warhorze/sql-code-graph
 Project-URL: Repository, https://github.com/Warhorze/sql-code-graph
@@ -36,7 +36,7 @@ Description-Content-Type: text/markdown
 
 # sql-code-graph
 
-> **Pre-1.0 — expect breaking changes.** APIs, CLI flags, and graph schema may
+> **No backward-compatibility guarantees.** APIs, CLI flags, and graph schema may
 > change between releases without a deprecation period. Pin to an exact version
 > in production. Re-indexing is always the migration path.
 
@@ -93,7 +93,7 @@ for that project.
 # 1. Install
 pip install sql-code-graph
 
-# 2. Register with Claude Code (~/.claude/settings.json)
+# 2. Register with Claude Code (writes ~/.claude.json)
 sqlcg install
 
 # 3. Restart Claude Code
@@ -138,7 +138,7 @@ This project uses sql-code-graph. MCP tools are available:
 - `trace_column_lineage` — trace where a column's value comes from
 - `get_upstream_dependencies` / `get_downstream_dependencies` — dependency chains
 - `search_sql_pattern` — full-text search across all indexed SQL
-- `execute_cypher` — raw graph query for advanced analysis
+- `execute_sql` — raw read-only SQL query for advanced analysis
 ```
 
 The MCP server works without this — Claude can discover the tools on its own —
@@ -214,11 +214,14 @@ After indexing, `sqlcg db info` shows non-zero `STAR_EXPANSION lineage edges`, a
 | `diff_impact(changed_files)` | What a set of changed files affects downstream |
 | `get_backfill_order(table_qualified)` | Topological rebuild/backfill order |
 | `scope_change(target)` | Synthesised change-scope summary for a target |
+| **Analysis** | |
+| `get_hub_ranking(k)` | Top-k tables by downstream dependent count (hub/centrality) |
+| `analyze_unused()` | Tables with no within-corpus consumers (dead-code candidates, heuristic) |
 | **Search & meta** | |
 | `search_sql_pattern(query)` | Full-text search across indexed SQL |
 | `list_dialects_and_repos()` | List indexed repos and dialects (catalogue) |
 | `db_info()` | Graph health, node counts, parse quality breakdown, warnings, freshness (indexed SHA vs HEAD) |
-| `execute_cypher(query)` | Raw Cypher query against the graph |
+| `execute_sql(query)` | Raw read-only SQL query against the graph |
 | `submit_feedback(...)` | Report a false positive/negative to improve metrics |
 
 > **Input format**: lineage/dependency tools expect a **schema-qualified** column
@@ -259,16 +262,26 @@ sqlcg gain                             # show usage metrics
 sqlcg report                           # generate FP/error report
 sqlcg mcp best-practices               # print the fact/heuristic boundary for the MCP tools
 sqlcg mcp start                        # start MCP server manually
-sqlcg mcp status                       # server status JSON (via control socket)
+sqlcg mcp status                       # server status JSON — incl. running version + stale_by_version
 sqlcg mcp stop                         # stop the running MCP server gracefully
 sqlcg mcp restart                      # stop the server (client must respawn it)
 sqlcg version                          # show installed version
 ```
 
+### Staying on the latest build (v1.5.0)
+
+The installed package, the CLI, and the running MCP server all report the **same**
+version (`sqlcg.__version__`). After upgrading, an editor may still be talking to an
+old MCP process — `sqlcg mcp status` surfaces this directly: it reports the running
+server's `version` and a `stale_by_version` flag that is `true` when the live server
+differs from the installed build. Re-running `sqlcg install` stops the stale server so
+your editor respawns it on the new build, so you never debug against an outdated server.
+
 ### Reads while the server is running (v1.2.0)
 
-KuzuDB allows a single writer, so while the MCP server is live it holds the
-database lock. CLI **read** commands (`find`, `analyze`, `db info`, `list-repos`,
+DuckDB takes an exclusive lock on the database file, so while the MCP server is
+live it holds that lock (other processes cannot open the file, even read-only).
+CLI **read** commands (`find`, `analyze`, `db info`, `list-repos`,
 `gain`) automatically route their query through the running server over its
 control socket and return rows as usual — no flag, no config. When no server is
 running they open the database directly, exactly as before. If the server is

{sql_code_graph-1.4.3.dist-info → sql_code_graph-1.5.1.dist-info}/RECORD

@@ -1,7 +1,7 @@
-sqlcg/__init__.py,sha256=-pjjoaMnukW9b0-s_OOYNjy46alw_PTB6xzvfSyWjew,115
+sqlcg/__init__.py,sha256=vmaeEVkmCFSAYwwUwVJQ-DbgNbr75sJbUxQmL0p66LA,115
 sqlcg/__main__.py,sha256=1YoFLcqEgTwYq1J3TbUwpkdG0zeeLIf2fJvwWI-CLFU,109
 sqlcg/cli/__init__.py,sha256=W8fD0LpMq2xm_5WKGNMvJh2WBL1ho5E8hUeAqXQYT1g,28
-sqlcg/cli/main.py,sha256=WmdTjsOlz1ozi2Y3Aq4ezR_FCRl-Lc1YOKw3_d48dlY,1650
+sqlcg/cli/main.py,sha256=oiZ0e_blUCnlmmXNSCLYnifleDv6ixm9dF7GEDGe0dQ,2429
 sqlcg/cli/commands/__init__.py,sha256=oSHtr6VD-jNubOjuCQyZj2tBppjMEpQDh-IGQ8of9eA,30
 sqlcg/cli/commands/analyze.py,sha256=_aC5ML3w7YdLi7DL3TFS9OiCEIipuNZxWR6S4peTcn4,12154
 sqlcg/cli/commands/db.py,sha256=TMhPCHRWSo8YmlNnSxmGxrR0_1r3K4e0Bn8unZTkvU4,7248
@@ -9,8 +9,8 @@ sqlcg/cli/commands/find.py,sha256=p5Vyyx-VBk8YDWYQN16UhECh7PIeMaEyCPEcUFcRFlM,25
 sqlcg/cli/commands/gain.py,sha256=SJU1c51a7MgNbZItqQnaBfOWGnV5xpXQctbew5Dr9BE,9062
 sqlcg/cli/commands/git.py,sha256=9a8T2FVxcAHq1H6Cslaq34t10w9fBGf4T2reiLk33t8,6135
 sqlcg/cli/commands/index.py,sha256=RPEpT9aXmK0rixRuHgMcmAn9FLR4JtIbZ1LM4RLkMvY,17050
-sqlcg/cli/commands/install.py,sha256=KNABvrLbamPyYnmnVdCaM_MNezbDc-pr6IkignCWI8k,9186
-sqlcg/cli/commands/mcp.py,sha256=QYaupf69lLpYzIoqsPJoCPiAggLVkYBzwpuOLRzxJDU,9140
+sqlcg/cli/commands/install.py,sha256=VdfZnC41WE3Lx6CcGSd2Xyi-XNNOLP1YQrnXmqo7x3c,10023
+sqlcg/cli/commands/mcp.py,sha256=CA24kRfBltanKuSMkRVRf42GW8cTgG8YQrMruxB3vSQ,11592
 sqlcg/cli/commands/reindex.py,sha256=FqXxvQ0UrxwDS0q2V3gzYgarN3NPh9muaIZ3rgvTmHs,13810
 sqlcg/cli/commands/report.py,sha256=JU0qjyMxwOukE7bN3XvvIzOI7zMg_Gsnvk_8F6pKNpA,4915
 sqlcg/cli/commands/uninstall.py,sha256=WrA1FnINxnd6mmE4-_QBK0aHBnibstJeAT8swnQKG4M,8962
@@ -50,18 +50,18 @@ sqlcg/parsers/tsql_parser.py,sha256=RRj1pACtAk2tLTDaFWRYF67a0IDvaf5A1YQXWIz0bpQ,
 sqlcg/server/__init__.py,sha256=n4wuNE7xyJIJxJZBtmtdccCMQfvTdF-IqIaZVbC4FC4,35
 sqlcg/server/control.py,sha256=qUcztb_aDhL-_X_Nq4q6uGx17cUlbLnI6vUpoZsEjbo,4506
 sqlcg/server/exceptions.py,sha256=EONw34icOByCTpppSQrvQBW6asc4hfqaGDCAFjv96II,469
-sqlcg/server/models.py,sha256=plnBVoV6y6JuU2IHzez0yHfsd5QZ_o977UCacS7A5NA,19693
+sqlcg/server/models.py,sha256=4c4ula195cHEqZycO6ZaSNohSLsodB-Du1FP94JKSdc,19810
 sqlcg/server/noise_filter.py,sha256=Ats2FFzmzFKqvQPWvlUzK8mY9pzlUhL4m1s8P_HNnvI,6335
 sqlcg/server/read_client.py,sha256=4v1OOl12HCHp6J14HrcWQApSixvJ0wwE8UIIZ0pzLyw,7808
-sqlcg/server/server.py,sha256=A1soT-hYnAX78X5j97nIjw9oIZCxBejjV6p_tRDIK38,24335
+sqlcg/server/server.py,sha256=1RiUmjWLgtN636kRQO6-4rH8amC-m9BKsIMO0aDRqes,24838
 sqlcg/server/skill.py,sha256=EDvmEgl-LQwCxZ9Lca4lt8zCtkk2cCgh9GLYlGgDA64,12828
-sqlcg/server/tools.py,sha256=oelzyVydELcD0ePYQMiIdZPqm-GolxD4YxtKUtGSeTU,76744
+sqlcg/server/tools.py,sha256=SyxPbnFmsR1w2Hi2ENmD_mynCdI9JHhTgv1byXFIKoY,77191
 sqlcg/server/writer.py,sha256=HH8pW6k1c2pbY4b6g2N87Tx4gNCezYqTLNTlAmsHg2Y,18522
 sqlcg/utils/__init__.py,sha256=--iqt5ThTXmT8Wz7da8hs3n0zDfYPl8P-z5OgRJ_77E,154
 sqlcg/utils/hashing.py,sha256=H25-sYfxHKb3_IERFnHyAIYNiXN470Oqo5sJT_D3YOA,438
 sqlcg/utils/ignore.py,sha256=wJjwa0mjnQ_xJExOUxk25y00g065XmmzJapqV3ifD5o,1151
 sqlcg/utils/logging.py,sha256=u0fCmYsLj9o81vawm3xZTHaw68GQYVm7JxG-gP81u8A,840
-sql_code_graph-1.4.3.dist-info/METADATA,sha256=a-9uSmKrh5FDurLJg_LFgkaNH8K1_ke-engcyBzhues,14085
-sql_code_graph-1.4.3.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
-sql_code_graph-1.4.3.dist-info/entry_points.txt,sha256=Wfe49sVzV9p4eVFGo5RxcV-frr3HOP0yzzst8JBxQLQ,46
-sql_code_graph-1.4.3.dist-info/RECORD,,
+sql_code_graph-1.5.1.dist-info/METADATA,sha256=r9mzPhpj5DxUPOhUBET8M0im3BuhdcvdmUbkD3mcLeA,14948
+sql_code_graph-1.5.1.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+sql_code_graph-1.5.1.dist-info/entry_points.txt,sha256=Wfe49sVzV9p4eVFGo5RxcV-frr3HOP0yzzst8JBxQLQ,46
+sql_code_graph-1.5.1.dist-info/RECORD,,

sqlcg/__init__.py

@@ -1,5 +1,5 @@
 """SQL Code Graph - SQL lineage and dependency analysis tool."""
 
-__version__ = "1.4.3"
+__version__ = "1.5.1"
 
 __all__ = ["__version__"]

sqlcg/cli/commands/install.py

@@ -20,6 +20,8 @@ from pathlib import Path
 import typer
 from rich.console import Console
 
+from sqlcg.cli.commands.mcp import stop_server
+
 console = Console()
 
 _SERVER_KEY = "sql-code-graph"
@@ -70,10 +72,12 @@ def install_cmd(
             claude_json = Path.home() / ".claude.json"
             console.print("[dim]--dry-run: would write to ~/.claude.json:[/dim]")
             _preview_claude_json(claude_json, entry)
+        console.print("[dim]--dry-run: would stop running MCP server[/dim]")
         _provision_skill(resolved_scope, repo, dry_run=True)
         return
 
     # --- Try official claude CLI first ---
+    configured_via_claude_cli = False
     claude_bin = shutil.which("claude")
     if claude_bin:
         proc = subprocess.run(
@@ -84,56 +88,65 @@ def install_cmd(
         if proc.returncode == 0:
             console.print(f"[green]Configured:[/green] {_SERVER_KEY} via `claude mcp add`")
             console.print("\nRestart Claude Code to pick up the new MCP server.")
-            _provision_skill(resolved_scope, repo, dry_run=False)
-            return
-        # Non-zero: log and fall through to ~/.claude.json fallback
-        console.print(
-            f"[yellow]Warning:[/yellow] `claude mcp add` returned rc={proc.returncode}; "
-            "falling back to ~/.claude.json write."
-        )
-        if proc.stderr:
-            console.print(f"[dim]{proc.stderr.strip()}[/dim]")
-
-    # --- Fallback: write ~/.claude.json directly ---
-    claude_json = Path.home() / ".claude.json"
-    if claude_json.exists():
-        try:
-            data: dict = json.loads(claude_json.read_text())
-        except (json.JSONDecodeError, OSError, TypeError):
+            configured_via_claude_cli = True
+        else:
+            # Non-zero: log and fall through to ~/.claude.json fallback
             console.print(
-                f"[yellow]Warning:[/yellow] {claude_json} contains invalid JSON — "
-                "mcpServers key will be added"
+                f"[yellow]Warning:[/yellow] `claude mcp add` returned rc={proc.returncode}; "
+                "falling back to ~/.claude.json write."
             )
+            if proc.stderr:
+                console.print(f"[dim]{proc.stderr.strip()}[/dim]")
+
+    if not configured_via_claude_cli:
+        # --- Fallback: write ~/.claude.json directly ---
+        claude_json = Path.home() / ".claude.json"
+        if claude_json.exists():
+            try:
+                data: dict = json.loads(claude_json.read_text())
+            except (json.JSONDecodeError, OSError, TypeError):
+                console.print(
+                    f"[yellow]Warning:[/yellow] {claude_json} contains invalid JSON — "
+                    "mcpServers key will be added"
+                )
+                data = {}
+        else:
             data = {}
-    else:
-        data = {}
 
-    existing = data.get("mcpServers", {}).get("user", {}).get(_SERVER_KEY)
-    if existing == entry:
-        console.print(f"[green]Already configured:[/green] {_SERVER_KEY} (in ~/.claude.json)")
-        _provision_skill(resolved_scope, repo, dry_run=False)
-        return
+        existing = data.get("mcpServers", {}).get("user", {}).get(_SERVER_KEY)
+        if existing == entry:
+            console.print(f"[green]Already configured:[/green] {_SERVER_KEY} (in ~/.claude.json)")
+        else:
+            data.setdefault("mcpServers", {}).setdefault("user", {})[_SERVER_KEY] = entry
 
-    data.setdefault("mcpServers", {}).setdefault("user", {})[_SERVER_KEY] = entry
+            try:
+                tmp = claude_json.with_suffix(".tmp")
+                tmp.write_text(json.dumps(data, indent=2) + "\n")
+                os.replace(tmp, claude_json)
+            except (OSError, TypeError, AttributeError):
+                pass  # Ignore file I/O errors in testing
 
-    try:
-        tmp = claude_json.with_suffix(".tmp")
-        tmp.write_text(json.dumps(data, indent=2) + "\n")
-        os.replace(tmp, claude_json)
-    except (OSError, TypeError, AttributeError):
-        pass  # Ignore file I/O errors in testing
-
-    cmd_str = " ".join(cmd_parts)
-    console.print(f"[green]Configured:[/green] {_SERVER_KEY} → {cmd_str}")
-    console.print(f"[dim]Written to {claude_json}[/dim]")
-
-    if entry.get("command") == "uvx":
-        console.print(
-            "[yellow]Note:[/yellow] First startup downloads dependencies (~30s). "
-            "Subsequent restarts use cache (~1s)."
-        )
+            cmd_str = " ".join(cmd_parts)
+            console.print(f"[green]Configured:[/green] {_SERVER_KEY} → {cmd_str}")
+            console.print(f"[dim]Written to {claude_json}[/dim]")
+
+            if entry.get("command") == "uvx":
+                console.print(
+                    "[yellow]Note:[/yellow] First startup downloads dependencies (~30s). "
+                    "Subsequent restarts use cache (~1s)."
+                )
 
-    console.print("\nRestart Claude Code to pick up the new MCP server.")
+            console.print("\nRestart Claude Code to pick up the new MCP server.")
+
+    # --- Single non-dry-run tail: all three success branches converge here. ---
+    # The config may not have changed (e.g. "Already configured"), but the
+    # binary on disk did — so the stale running server still must be stopped
+    # so the editor respawns the freshly-installed build.
+    stopped = stop_server()
+    if stopped:
+        console.print("Stopped running MCP server; your editor will respawn it on the new build.")
+    else:
+        console.print("No running MCP server to refresh.")
     _provision_skill(resolved_scope, repo, dry_run=False)
 
 

sqlcg/cli/commands/mcp.py

@@ -77,9 +77,19 @@ def mcp_best_practices() -> None:
 def mcp_status() -> None:
     """Print server status JSON (connects to control socket).
 
-    Returns JSON with fields: running, pid, db_path, indexed_sha, head_sha,
-    stale_by_commits, connected_clients, uptime, writer_queue when a server
-    is live.
+    Returns JSON with fields: running, version, pid, db_path, indexed_sha,
+    head_sha, stale_by_commits, connected_clients, uptime, writer_queue,
+    stale_by_version when a server is live.
+
+    `version` is the *running* server's reported sqlcg.__version__ (read live
+    over the control socket — the build the editor is currently talking to).
+    `stale_by_version` compares it against the *installed* sqlcg.__version__
+    (the CLI process you just invoked): true when they differ, false when they
+    match, null when the running version cannot be determined (degraded mode).
+    When stale, a warning is printed telling you to restart the MCP server via
+    your editor or run `sqlcg install` (which stops the stale server for you).
+    This is distinct from `stale_by_commits` (graph-vs-repo freshness, not
+    package-vs-binary drift).
 
     The status response is length-prefixed framed (v1.3.0, B3) so large
     writer_queue payloads are received in full — the client uses the
@@ -87,7 +97,8 @@ def mcp_status() -> None:
 
     When no server is found: {"running": false}.
     When the PID file exists with a live process but the socket is unavailable:
-    {"running": true, "degraded": "socket unavailable", ...}.
+    {"running": true, "degraded": "socket unavailable", "stale_by_version": null, ...}
+    (the running version cannot be read without a live socket).
 
     R3 (stale socket): if the socket file exists but the server is not
     responding (ConnectionRefusedError / FileNotFoundError), falls through
@@ -119,9 +130,25 @@ def mcp_status() -> None:
 
         status = json.loads(data.decode())
 
+        # Drift detection: compare the *running* server's reported version (read
+        # over the socket, from the live process) against the *installed*
+        # sqlcg.__version__ (the version of the CLI process you just invoked).
+        from sqlcg import __version__
+
+        running_version = status.get("version")
+        stale = running_version is not None and running_version != __version__
+        status = {**status, "version": running_version, "stale_by_version": stale}
+
         # Pretty-print the base fields.
         console.print_json(json.dumps({k: v for k, v in status.items() if k != "writer_queue"}))
 
+        if stale:
+            console.print(
+                f"[yellow]Warning:[/yellow] running MCP server is v{running_version}, "
+                f"installed sqlcg is v{__version__} — restart the MCP server via your "
+                "editor (or run `sqlcg install`, which stops the stale server for you)."
+            )
+
         # Render the writer_queue block separately for readability.
         wq = status.get("writer_queue")
         if wq:
@@ -178,6 +205,10 @@ def mcp_status() -> None:
                         "degraded": "socket unavailable",
                         "pid": rec["pid"],
                         "db_path": rec["db_path"],
+                        # Cannot read the running version without a live socket —
+                        # omit `version` and report drift as unknown (None → JSON
+                        # null), never guess.
+                        "stale_by_version": None,
                     }
                 )
             )
@@ -185,16 +216,20 @@ def mcp_status() -> None:
             console.print_json(json.dumps({"running": False}))
 
 
-@app.command("stop")
-def mcp_stop() -> None:
-    """Stop the running MCP server gracefully.
+def stop_server() -> bool:
+    """Stop a running MCP server gracefully (best-effort). Returns True if stopped.
 
     Sends a ``stop`` op via the control socket; waits up to 5 s for the
     socket file to disappear (confirming clean exit).  Falls back to SIGTERM
     on the PID-file PID if the socket is unavailable.
 
     R3 (stale socket): ``ConnectionRefusedError`` / ``FileNotFoundError`` are
-    caught — never hangs on a dead socket.
+    caught — never hangs on a dead socket; a socket error here must not abort
+    the caller (``mcp_stop`` and ``install_cmd`` both rely on this).
+
+    Returns:
+        True if a running server was found and stopped (via socket or SIGTERM
+        fallback); False if no running server was found.
     """
     import socket as _socket
     import time
@@ -214,6 +249,7 @@ def mcp_stop() -> None:
                 break
             time.sleep(0.5)
         console.print("[green]Server stopped.[/green]")
+        return True
     except (FileNotFoundError, ConnectionRefusedError, OSError):
         # Socket unavailable — fall back to SIGTERM via PID file
         import signal
@@ -222,8 +258,20 @@ def mcp_stop() -> None:
         if rec and is_pid_alive(rec["pid"]):
             os.kill(rec["pid"], signal.SIGTERM)
             console.print(f"[yellow]Socket unavailable — sent SIGTERM to PID {rec['pid']}[/yellow]")
-        else:
-            console.print("[yellow]No server found to stop.[/yellow]")
+            return True
+        return False
+
+
+@app.command("stop")
+def mcp_stop() -> None:
+    """Stop the running MCP server gracefully.
+
+    Delegates to ``stop_server()`` (shared with ``sqlcg install``) and prints
+    a final message based on whether a server was found.
+    """
+    stopped = stop_server()
+    if not stopped:
+        console.print("[yellow]No server found to stop.[/yellow]")
 
 
 @app.command("restart")

sqlcg/cli/main.py

@@ -34,8 +34,41 @@ USING THE MCP TOOLS:
 Note: Binary is `sqlcg`; PyPI package is `sql-code-graph`.
 """
 
+
+def _version_string() -> str:
+    from sqlcg import __version__
+
+    return f"sqlcg version {__version__}"
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(_version_string())
+        raise typer.Exit()
+
+
 app = typer.Typer(name="sqlcg", help=help_text)
 
+
+@app.callback(invoke_without_command=True)
+def _root(
+    ctx: typer.Context,
+    version: bool = typer.Option(
+        False,
+        "--version",
+        help="Show version and exit.",
+        is_eager=True,
+        callback=_version_callback,
+    ),
+) -> None:
+    """SQL code graph analyzer."""
+    # The eager --version callback exits before we get here when --version is
+    # passed. Otherwise: if no subcommand was given, show help (matching the
+    # pre-callback behaviour) instead of silently exiting 0.
+    if ctx.invoked_subcommand is None:
+        typer.echo(ctx.get_help())
+
+
 # Register subcommand groups
 app.add_typer(db.app, name="db")
 app.add_typer(find.app, name="find")
@@ -56,9 +89,7 @@ app.command("uninstall")(uninstall.uninstall_cmd)
 @app.command()
 def version() -> None:
     """Show version."""
-    from sqlcg import __version__
-
-    typer.echo(f"sqlcg version {__version__}")
+    typer.echo(_version_string())
 
 
 def main() -> None:

sqlcg/server/models.py

@@ -190,6 +190,9 @@ class DialectRepoResult(BaseModel):
 class DbInfoResult(BaseModel):
     """Result of db_info tool — graph health and parse quality diagnostics."""
 
+    sqlcg_version: str = Field(
+        ..., description="Installed sqlcg package version (sqlcg.__version__)"
+    )
     schema_version: str = Field(..., description="Graph schema version")
     node_counts: dict[str, int] = Field(
         default_factory=dict,

sqlcg/server/server.py

@@ -27,6 +27,7 @@ _real_stdout_buffer = os.fdopen(os.dup(1), "wb", buffering=0)
 from dotenv import load_dotenv  # noqa: E402
 from mcp.server import FastMCP  # noqa: E402
 
+from sqlcg import __version__  # noqa: E402
 from sqlcg.utils.logging import getLogger  # noqa: E402
 
 logger = getLogger(__name__)
@@ -35,6 +36,13 @@ logger = getLogger(__name__)
 # This is safe because _real_stdout_buffer has already captured fd 1 above.
 mcp = FastMCP("SQL Code Graph")
 
+# FastMCP.__init__ does not accept a `version` kwarg (verified signature); the
+# underlying mcp.server.lowlevel.Server.__init__(self, name, version=None, ...)
+# does. Set it post-construction so the `initialize` handshake reports
+# serverInfo.version == sqlcg.__version__ instead of None. Deliberate, pinned
+# private-attr write — see tests/unit/test_version_parity.py.
+mcp._mcp_server.version = __version__
+
 
 def _configure_mcp_logging() -> None:
     """Redirect sys.stdout to sys.stderr and configure logging to stderr.
@@ -219,6 +227,7 @@ async def _control_socket_task(
 
                     resp: dict = {
                         "running": True,
+                        "version": __version__,
                         "pid": os.getpid(),
                         "db_path": str(db_path or _get_db_path()),
                         "indexed_sha": indexed_sha,

sqlcg/server/tools.py

@@ -1672,13 +1672,22 @@ def db_info() -> DbInfoResult:
       those files. Table-level lineage is still available.
     - `warnings` list — empty means the graph is healthy.
 
+    `sqlcg_version` is the installed *package* build (sqlcg.__version__) — use
+    it to self-check you are talking to the build you expect (the MCP protocol
+    `serverInfo.version` is not reliably visible to the agent persona). This is
+    a different axis from `schema_version`, which tracks the graph schema, not
+    the package: do not conflate the two.
+
     Parse quality legend (parsing_mode per SqlQuery node):
       sqlglot          — standard path; column lineage available if extracted
       scripting_block  — tokenizer fallback; column lineage unavailable
 
     Returns:
-        DbInfoResult with schema version, node counts, parse quality, and warnings
+        DbInfoResult with sqlcg/schema versions, node counts, parse quality,
+        and warnings
     """
+    from sqlcg import __version__
+
     db = _get_backend()
 
     schema_version = db.get_schema_version() or "unknown"
@@ -1745,6 +1754,7 @@ def db_info() -> DbInfoResult:
         pass
 
     return DbInfoResult(
+        sqlcg_version=__version__,
         schema_version=schema_version,
         node_counts=node_counts,
         column_lineage_edges=column_lineage_edges,