tscode-kg 0.6.0__tar.gz → 0.8.0__tar.gz

{tscode_kg-0.6.0 → tscode_kg-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tscode-kg
-Version: 0.6.0
+Version: 0.8.0
 Summary: Knowledge graph for TypeScript/JavaScript codebases — AST extraction, hybrid semantic+structural search
 License-Expression: Elastic-2.0
 License-File: LICENSE
@@ -19,9 +19,8 @@ Provides-Extra: viz
 Provides-Extra: viz3d
 Requires-Dist: PyQt5 (>=5.15.11,<5.16) ; extra == "viz3d"
 Requires-Dist: click (>=8.1.0,<9)
-Requires-Dist: kgmodule-utils[semantic,sqlite-vec] (>=0.23.0)
+Requires-Dist: kgmodule-utils[mcp,semantic,sqlite-vec] (>=0.29.0)
 Requires-Dist: markdown (>=3.10,<3.11) ; extra == "viz3d"
-Requires-Dist: mcp (>=1.3.0,<2)
 Requires-Dist: networkx (>=3.0)
 Requires-Dist: param (>=2.4,<2.5) ; extra == "viz3d"
 Requires-Dist: plotly (>=6.8.0,<6.9) ; extra == "viz"
@@ -42,7 +41,7 @@ Description-Content-Type: text/markdown
 [![Python](https://img.shields.io/badge/python-3.12%20%7C%203.13-blue.svg)](https://www.python.org/)
 [![License: Elastic-2.0](https://img.shields.io/badge/License-Elastic%202.0-blue.svg)](https://www.elastic.co/licensing/elastic-license)
 [![PyPI](https://img.shields.io/pypi/v/tscode-kg.svg)](https://pypi.org/project/tscode-kg/)
-[![Version](https://img.shields.io/badge/version-0.6.0-blue.svg)](https://github.com/Flux-Frontiers/tscode_kg/releases)
+[![Version](https://img.shields.io/badge/version-0.8.0-blue.svg)](https://github.com/Flux-Frontiers/tscode_kg/releases)
 [![CI](https://github.com/Flux-Frontiers/tscode_kg/actions/workflows/ci.yml/badge.svg)](https://github.com/Flux-Frontiers/tscode_kg/actions/workflows/ci.yml)
 [![Poetry](https://img.shields.io/endpoint?url=https://python-poetry.org/badge/v0.json)](https://python-poetry.org/)
 [![DOI](https://img.shields.io/badge/DOI-10.5281%2Fzenodo.22559450-blue.svg)](https://doi.org/10.5281/zenodo.22559450)
@@ -132,10 +131,13 @@ are equivalent.
 ## MCP tools
 
 The MCP server exposes the full PyCodeKG toolkit, applied to TypeScript/JavaScript
-codebases: `graph_stats`, `query_codebase`, `pack_snippets`, `callers`, `get_node`,
-`list_nodes`, `find_node`, `centrality`, `bridge_centrality`, `framework_nodes`,
-`find_definition_at`, `analyze_repo`, `explain`, `rank_nodes`, `query_ranked`,
-`explain_rank`, `snapshot_list`, `snapshot_show`, and `snapshot_diff`.
+codebases, as 20 tools. The first five are the fleet's canonical tools, named the
+same on every KG server: `stats`, `query`, `pack`, `get_node` and `neighbors`.
+The other fifteen are TypeScriptKG's own: `callers`, `list_nodes`, `find_node`,
+`centrality`, `bridge_centrality`, `framework_nodes`, `find_definition_at`,
+`analyze_repo`, `explain`, `rank_nodes`, `query_ranked`, `explain_rank`,
+`snapshot_list`, `snapshot_show`, and `snapshot_diff`. `tscodekg mcp --manifest`
+prints the live list as JSON without opening the graph.
 
 See `docs/MCP.md` for setup and `docs/CHEATSHEET.md` for a query cookbook.
 Repo-local Claude Code skills live in `skills/`.
@@ -195,13 +197,13 @@ If you use TypeScriptKG in your research or project, please cite it:
 
 [![DOI](https://img.shields.io/badge/DOI-10.5281%2Fzenodo.22559450-blue.svg)](https://doi.org/10.5281/zenodo.22559450)
 
-> Suchanek, E. G. (2026). *TypeScriptKG: Semantic Knowledge Graph for TypeScript/JavaScript Codebases* (Version 0.6.0) [Software]. Flux-Frontiers. https://doi.org/10.5281/zenodo.22559450
+> Suchanek, E. G. (2026). *TypeScriptKG: Semantic Knowledge Graph for TypeScript/JavaScript Codebases* (Version 0.8.0) [Software]. Flux-Frontiers. https://doi.org/10.5281/zenodo.22559450
 
 ```bibtex
 @software{suchanek_tscode_kg,
   author    = {Suchanek, Eric G.},
   title     = {{TypeScriptKG}: Semantic Knowledge Graph for TypeScript/JavaScript Codebases},
-  version   = {0.6.0},
+  version   = {0.8.0},
   year      = {2026},
   publisher = {Flux-Frontiers},
   doi       = {10.5281/zenodo.22559450},

{tscode_kg-0.6.0 → tscode_kg-0.8.0}/README.md

@@ -3,7 +3,7 @@
 [![Python](https://img.shields.io/badge/python-3.12%20%7C%203.13-blue.svg)](https://www.python.org/)
 [![License: Elastic-2.0](https://img.shields.io/badge/License-Elastic%202.0-blue.svg)](https://www.elastic.co/licensing/elastic-license)
 [![PyPI](https://img.shields.io/pypi/v/tscode-kg.svg)](https://pypi.org/project/tscode-kg/)
-[![Version](https://img.shields.io/badge/version-0.6.0-blue.svg)](https://github.com/Flux-Frontiers/tscode_kg/releases)
+[![Version](https://img.shields.io/badge/version-0.8.0-blue.svg)](https://github.com/Flux-Frontiers/tscode_kg/releases)
 [![CI](https://github.com/Flux-Frontiers/tscode_kg/actions/workflows/ci.yml/badge.svg)](https://github.com/Flux-Frontiers/tscode_kg/actions/workflows/ci.yml)
 [![Poetry](https://img.shields.io/endpoint?url=https://python-poetry.org/badge/v0.json)](https://python-poetry.org/)
 [![DOI](https://img.shields.io/badge/DOI-10.5281%2Fzenodo.22559450-blue.svg)](https://doi.org/10.5281/zenodo.22559450)
@@ -93,10 +93,13 @@ are equivalent.
 ## MCP tools
 
 The MCP server exposes the full PyCodeKG toolkit, applied to TypeScript/JavaScript
-codebases: `graph_stats`, `query_codebase`, `pack_snippets`, `callers`, `get_node`,
-`list_nodes`, `find_node`, `centrality`, `bridge_centrality`, `framework_nodes`,
-`find_definition_at`, `analyze_repo`, `explain`, `rank_nodes`, `query_ranked`,
-`explain_rank`, `snapshot_list`, `snapshot_show`, and `snapshot_diff`.
+codebases, as 20 tools. The first five are the fleet's canonical tools, named the
+same on every KG server: `stats`, `query`, `pack`, `get_node` and `neighbors`.
+The other fifteen are TypeScriptKG's own: `callers`, `list_nodes`, `find_node`,
+`centrality`, `bridge_centrality`, `framework_nodes`, `find_definition_at`,
+`analyze_repo`, `explain`, `rank_nodes`, `query_ranked`, `explain_rank`,
+`snapshot_list`, `snapshot_show`, and `snapshot_diff`. `tscodekg mcp --manifest`
+prints the live list as JSON without opening the graph.
 
 See `docs/MCP.md` for setup and `docs/CHEATSHEET.md` for a query cookbook.
 Repo-local Claude Code skills live in `skills/`.
@@ -156,13 +159,13 @@ If you use TypeScriptKG in your research or project, please cite it:
 
 [![DOI](https://img.shields.io/badge/DOI-10.5281%2Fzenodo.22559450-blue.svg)](https://doi.org/10.5281/zenodo.22559450)
 
-> Suchanek, E. G. (2026). *TypeScriptKG: Semantic Knowledge Graph for TypeScript/JavaScript Codebases* (Version 0.6.0) [Software]. Flux-Frontiers. https://doi.org/10.5281/zenodo.22559450
+> Suchanek, E. G. (2026). *TypeScriptKG: Semantic Knowledge Graph for TypeScript/JavaScript Codebases* (Version 0.8.0) [Software]. Flux-Frontiers. https://doi.org/10.5281/zenodo.22559450
 
 ```bibtex
 @software{suchanek_tscode_kg,
   author    = {Suchanek, Eric G.},
   title     = {{TypeScriptKG}: Semantic Knowledge Graph for TypeScript/JavaScript Codebases},
-  version   = {0.6.0},
+  version   = {0.8.0},
   year      = {2026},
   publisher = {Flux-Frontiers},
   doi       = {10.5281/zenodo.22559450},

{tscode_kg-0.6.0 → tscode_kg-0.8.0}/pyproject.toml

@@ -38,7 +38,7 @@ packages = [{ include = "tscode_kg", from = "src" }]
 
 [project]
 name = "tscode-kg"
-version = "0.6.0"
+version = "0.8.0"
 description = "Knowledge graph for TypeScript/JavaScript codebases — AST extraction, hybrid semantic+structural search"
 readme = "README.md"
 license = "Elastic-2.0"
@@ -68,15 +68,10 @@ dependencies = [
     # manager is now the package_name class attribute, where it used to be an
     # __init__ that only forwarded to super(). Against 0.19.x the manager
     # reports itself as "kg-utils" in every snapshot's tool field.
-    "kgmodule-utils[semantic,sqlite-vec]>=0.23.0",
+    # 0.29.0: the MCP server is kg_utils.mcp's ([mcp] brings mcp itself),
+    # stats() is the fleet stats shape, and LanceDB is gone.
+    "kgmodule-utils[semantic,sqlite-vec,mcp]>=0.29.0",
     "click>=8.1.0,<9",
-    # Upper-bounded: mcp 2.0 removed the bundled `mcp.server.fastmcp` module
-    # (FastMCP was split out into the standalone `fastmcp` package) and rebuilt
-    # mcp.server around new submodules. src/tscode_kg/mcp_server.py imports
-    # FastMCP from mcp, so an unbounded floor lets a clean install pull 2.x and
-    # break `tscodekg-mcp` at import time. Lift this only alongside a port to
-    # the standalone fastmcp package.
-    "mcp>=1.3.0,<2",
     "networkx>=3.0",
 ]
 

{tscode_kg-0.6.0 → tscode_kg-0.8.0}/src/tscode_kg/__init__.py

@@ -18,7 +18,7 @@ KGExtractor SDK::
     from tscode_kg import TSCodeExtractor
 """
 
-__version__ = "0.6.0"
+__version__ = "0.8.0"
 __author__ = "Eric G. Suchanek, PhD"
 
 from tscode_kg.extractor import TSCodeExtractor

{tscode_kg-0.6.0 → tscode_kg-0.8.0}/src/tscode_kg/analysis.py

@@ -43,6 +43,7 @@ from collections.abc import Callable
 from dataclasses import asdict, dataclass
 from pathlib import Path
 
+from kg_utils.stats import flat_stats
 from rich.console import Console
 
 logging.basicConfig(level=logging.INFO)
@@ -304,7 +305,8 @@ class TSCodeKGAnalyzer:
     def _analyze_baseline(self) -> None:
         """Phase 1: Establish baseline node and edge counts."""
         try:
-            self.stats = self.kg.stats()
+            # The report reads the store's flat keys (total_nodes, node_counts, ...).
+            self.stats = flat_stats(self.kg.stats())
             n = self.stats.get("total_nodes", "?")
             e = self.stats.get("total_edges", "?")
             self._phase_result = f"nodes={n}  edges={e}"

tscode_kg-0.8.0/src/tscode_kg/cli/cmd_mcp.py

@@ -0,0 +1,35 @@
+"""
+cli/cmd_mcp.py -- ``tscodekg mcp``, the fleet's standard MCP command, from :mod:`kg_utils.mcp`:
+
+    tscodekg mcp [--repo DIR] [--db FILE] [--vectors FILE] [--model NAME]
+                 [--transport stdio|streamable-http] [--host H] [--port N]
+                 [--manifest]
+
+``cli/main.py`` registers it with ``add_mcp_command(cli, build_mcp_server)``.
+Registering it imports neither ``mcp`` nor the server module, so every other
+``tscodekg`` command starts as fast as before.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from kg_utils.mcp import KGServer
+
+
+def build_mcp_server(
+    repo: Path, db: Path | None, vectors: Path | None, model: str | None
+) -> KGServer:
+    """Build the server only when ``tscodekg mcp`` runs.
+
+    :param repo: Repository root, absolute.
+    :param db: Graph database, absolute; ``None`` for the default.
+    :param vectors: Vector store, absolute; ``None`` for the default.
+    :param model: Embedding model; ``None`` for the default.
+    :return: The server, with its graph not yet opened.
+    """
+    from tscode_kg.mcp_server import build_server  # noqa: PLC0415 -- see the module docstring
+
+    return build_server(repo, db, vectors, model)

{tscode_kg-0.6.0 → tscode_kg-0.8.0}/src/tscode_kg/cli/cmd_snapshot.py

@@ -14,12 +14,38 @@ from __future__ import annotations
 
 import json
 import logging
+import re
 from pathlib import Path
 
 import click
 
 logger = logging.getLogger(__name__)
 
+_CFF_VERSION_RE = re.compile(r'^version:\s*["\']?([^"\'\s]+)', re.M)
+
+
+def repo_version(repo_root: Path) -> str | None:
+    """Return the measured repo's own version, if it declares one.
+
+    Reads ``version`` from the root ``package.json``, then from
+    ``CITATION.cff``, which covers a repo whose ``package.json`` sits in a
+    subdirectory or that has none.
+
+    :param repo_root: Repository root.
+    :return: The version string, or ``None`` when neither file declares one.
+    """
+    try:
+        version = json.loads((repo_root / "package.json").read_text()).get("version")
+    except (OSError, ValueError, AttributeError):
+        version = None
+    if isinstance(version, str) and version:
+        return version
+    try:
+        match = _CFF_VERSION_RE.search((repo_root / "CITATION.cff").read_text())
+    except OSError:
+        return None
+    return match.group(1) if match else None
+
 
 @click.group("snapshot")
 def snapshot() -> None:
@@ -85,9 +111,10 @@ def save_snapshot(
     Reads graph statistics and JSDoc coverage from the SQLite graph, runs the
     analyzer for issue counts and hotspots, then saves a snapshot keyed on
     VERSION. Omit VERSION and the snapshot is keyed on a UTC timestamp, which
-    is the right answer for a corpus with no release tag. The tree hash is
-    recorded as provenance and auto-detected from git when not provided; it
-    is not the key.
+    is the right answer for a corpus with no release tag, and records the
+    repo's own version from its root package.json or CITATION.cff. The tree
+    hash is recorded as provenance and auto-detected from git when not
+    provided; it is not the key.
 
     Snapshots are stored in .tscodekg/snapshots/{key}.json, with a
     manifest.json tracking all snapshots and their metrics.
@@ -118,10 +145,11 @@ def capture_snapshot(
 ) -> None:
     """Capture and persist a snapshot; shared by ``snapshot save`` and ``init``.
 
-    :param version: Release tag, becoming the snapshot's key; auto-detected
-        from the installed package when falsy, which then yields a UTC
-        timestamp key instead -- the right answer for a corpus, not a repo
-        release. Never used as the key without being explicitly passed here.
+    :param version: Release tag, becoming the snapshot's key. When falsy,
+        the snapshot records the repo's own version from :func:`repo_version`
+        (or, failing that, the installed package's) and is keyed on a UTC
+        timestamp instead. Never used as the key without being explicitly
+        passed here.
     :param repo: Repository root path.
     :param db: SQLite graph path; defaults to ``<repo>/.tscodekg/graph.sqlite``.
     :param snapshots_dir: Snapshots directory; defaults to ``<repo>/.tscodekg/snapshots``.
@@ -129,7 +157,8 @@ def capture_snapshot(
     :param tree_hash: Git tree hash, recorded as provenance; auto-detected
         when empty. It is not the snapshot's key.
     :param subject: What was measured, e.g. ``repo:tscode-kg``. Recorded
-        separately from ``version``, which names the measuring tool.
+        separately from ``tool`` and ``tool_version``, which name the measuring
+        tool.
     """
     from tscode_kg.kg import TypeScriptKG  # pylint: disable=import-outside-toplevel
     from tscode_kg.snapshots import SnapshotManager  # pylint: disable=import-outside-toplevel
@@ -180,7 +209,7 @@ def capture_snapshot(
         kg.close()
 
     snapshot_obj = snap_mgr.capture(
-        version=version or None,
+        version=version or repo_version(repo_root),
         branch=branch,
         graph_stats_dict=stats,
         critical_issues=critical_issues,
@@ -188,8 +217,8 @@ def capture_snapshot(
         hotspots=hotspots,
         issues=issue_strings,
         tree_hash=tree_hash,
-        # An explicit VERSION is a release tag and becomes the key. An
-        # auto-detected one is the measuring tool's version and must not be.
+        # An explicit VERSION is a release tag and becomes the key. A
+        # detected one (the repo's, or the tool's) must not be.
         key=version or "",
         subject=subject,
     )

{tscode_kg-0.6.0 → tscode_kg-0.8.0}/src/tscode_kg/cli/main.py

@@ -16,6 +16,7 @@ Usage::
 from __future__ import annotations
 
 import click
+from kg_utils.mcp import add_mcp_command
 
 from tscode_kg.cli.cmd_analyze import analyze
 from tscode_kg.cli.cmd_bridges import bridges
@@ -25,7 +26,7 @@ from tscode_kg.cli.cmd_explain import explain
 from tscode_kg.cli.cmd_framework_nodes import framework_nodes
 from tscode_kg.cli.cmd_hooks import install_hooks
 from tscode_kg.cli.cmd_init import init
-from tscode_kg.cli.cmd_mcp import mcp_cmd
+from tscode_kg.cli.cmd_mcp import build_mcp_server
 from tscode_kg.cli.cmd_model import download_model
 from tscode_kg.cli.cmd_query import pack, query
 from tscode_kg.cli.cmd_snapshot import snapshot
@@ -56,4 +57,4 @@ cli.add_command(viz3d)
 cli.add_command(viz_timeline, name="viz-timeline")
 cli.add_command(install_hooks)
 cli.add_command(download_model)
-cli.add_command(mcp_cmd, name="mcp")
+mcp_command = add_mcp_command(cli, build_mcp_server)

{tscode_kg-0.6.0 → tscode_kg-0.8.0}/src/tscode_kg/explain.py

@@ -30,7 +30,7 @@ def render_explain(
     node_id: str,
     *,
     limit: int = 10,
-    snippets_hint: str = "pack_snippets()",
+    snippets_hint: str = "pack()",
 ) -> str:
     """
     Render a Markdown natural-language explanation of a code node.
@@ -41,7 +41,7 @@ def render_explain(
                     (e.g. ``fn:src/utils/helpers.ts:formatDate``).
     :param limit: Maximum callers and callees to list.  Pass 0 to list all.
     :param snippets_hint: Closing call-to-action shown to the consumer for
-                          retrieving the full source — ``"pack_snippets()"``
+                          retrieving the full source — ``"pack()"``
                           for MCP, ``"tscodekg pack"`` for CLI.
     :return: Markdown string, or a "Node Not Found" header when the ID does
              not exist in the knowledge graph.