Add real-time token savings counter to all tool responses

Adds a lightweight persistent token savings tracker (~/.code-index/_savings.json)
that records cumulative tokens saved across sessions. Every tool response now
includes tokens_saved (this call) and total_tokens_saved (running total) in _meta.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: jgravelle

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "jcodemunch-mcp"
-version = "0.2.3"
+version = "0.2.4"
 description = "Token-efficient MCP server for source code exploration via tree-sitter AST parsing"
 readme = "README.md"
 requires-python = ">=3.10"

src/jcodemunch_mcp/storage/__init__.py

@@ -1,5 +1,7 @@
 """Storage package for index save/load operations."""
 
 from .index_store import CodeIndex, IndexStore, INDEX_VERSION
+from .token_tracker import record_savings, get_total_saved, estimate_savings
 
-__all__ = ["CodeIndex", "IndexStore", "INDEX_VERSION"]
+__all__ = ["CodeIndex", "IndexStore", "INDEX_VERSION",
+           "record_savings", "get_total_saved", "estimate_savings"]

src/jcodemunch_mcp/storage/token_tracker.py

@@ -0,0 +1,56 @@
+"""Persistent token savings tracker.
+
+Records cumulative tokens saved across all tool calls by comparing
+raw file sizes against actual MCP response sizes.
+
+Stored in ~/.code-index/_savings.json — a single small JSON file.
+No API calls, no file reads — only os.stat for file sizes.
+"""
+
+import json
+import os
+from pathlib import Path
+from typing import Optional
+
+
+_SAVINGS_FILE = "_savings.json"
+_BYTES_PER_TOKEN = 4  # ~4 bytes per token (rough but consistent)
+
+
+def _savings_path(base_path: Optional[str] = None) -> Path:
+    root = Path(base_path) if base_path else Path.home() / ".code-index"
+    root.mkdir(parents=True, exist_ok=True)
+    return root / _SAVINGS_FILE
+
+
+def record_savings(tokens_saved: int, base_path: Optional[str] = None) -> int:
+    """Add tokens_saved to the running total. Returns new cumulative total."""
+    path = _savings_path(base_path)
+    try:
+        data = json.loads(path.read_text()) if path.exists() else {}
+    except Exception:
+        data = {}
+
+    total = data.get("total_tokens_saved", 0) + max(0, tokens_saved)
+    data["total_tokens_saved"] = total
+
+    try:
+        path.write_text(json.dumps(data))
+    except Exception:
+        pass
+
+    return total
+
+
+def get_total_saved(base_path: Optional[str] = None) -> int:
+    """Return the current cumulative total without modifying it."""
+    path = _savings_path(base_path)
+    try:
+        return json.loads(path.read_text()).get("total_tokens_saved", 0)
+    except Exception:
+        return 0
+
+
+def estimate_savings(raw_bytes: int, response_bytes: int) -> int:
+    """Estimate tokens saved: (raw - response) / bytes_per_token."""
+    return max(0, (raw_bytes - response_bytes) // _BYTES_PER_TOKEN)

src/jcodemunch_mcp/tools/get_file_outline.py

@@ -1,9 +1,10 @@
 """Get file outline - symbols in a specific file."""
 
+import os
 import time
 from typing import Optional
 
-from ..storage import IndexStore
+from ..storage import IndexStore, record_savings, estimate_savings
 from ..parser import build_symbol_tree
 
 
@@ -66,6 +67,17 @@ def get_file_outline(
 
     elapsed = (time.perf_counter() - start) * 1000
 
+    # Token savings: raw file size vs outline response size
+    raw_bytes = 0
+    try:
+        raw_file = store._content_dir(owner, name) / file_path
+        raw_bytes = os.path.getsize(raw_file)
+    except OSError:
+        pass
+    response_bytes = sum(s.get("byte_length", 0) for s in file_symbols)
+    tokens_saved = estimate_savings(raw_bytes, response_bytes)
+    total_saved = record_savings(tokens_saved)
+
     return {
         "repo": f"{owner}/{name}",
         "file": file_path,
@@ -74,6 +86,8 @@ def get_file_outline(
         "_meta": {
             "timing_ms": round(elapsed, 1),
             "symbol_count": len(symbols_output),
+            "tokens_saved": tokens_saved,
+            "total_tokens_saved": total_saved,
         },
     }
 

src/jcodemunch_mcp/tools/get_repo_outline.py

@@ -5,7 +5,7 @@
 from collections import Counter
 from typing import Optional
 
-from ..storage import IndexStore
+from ..storage import IndexStore, record_savings, estimate_savings
 
 
 def get_repo_outline(
@@ -57,6 +57,17 @@ def get_repo_outline(
     for sym in index.symbols:
         kind_counts[sym.get("kind", "unknown")] += 1
 
+    # Token savings: sum of all raw file sizes (user would need to read all files)
+    raw_bytes = 0
+    content_dir = store._content_dir(owner, name)
+    for f in index.source_files:
+        try:
+            raw_bytes += os.path.getsize(content_dir / f)
+        except OSError:
+            pass
+    tokens_saved = estimate_savings(raw_bytes, 0)
+    total_saved = record_savings(tokens_saved)
+
     elapsed = (time.perf_counter() - start) * 1000
 
     return {
@@ -69,5 +80,7 @@ def get_repo_outline(
         "symbol_kinds": dict(kind_counts.most_common()),
         "_meta": {
             "timing_ms": round(elapsed, 1),
+            "tokens_saved": tokens_saved,
+            "total_tokens_saved": total_saved,
         },
     }

src/jcodemunch_mcp/tools/get_symbol.py

@@ -1,10 +1,11 @@
 """Get symbol source code."""
 
 import hashlib
+import os
 import time
 from typing import Optional
 
-from ..storage import IndexStore
+from ..storage import IndexStore, record_savings, estimate_savings
 
 
 def _make_meta(timing_ms: float, **kwargs) -> dict:
@@ -93,6 +94,18 @@ def get_symbol(
         stored_hash = symbol.get("content_hash", "")
         meta["content_verified"] = actual_hash == stored_hash if stored_hash else None
 
+    # Token savings: raw file size vs symbol byte length
+    raw_bytes = 0
+    try:
+        raw_file = store._content_dir(owner, name) / symbol["file"]
+        raw_bytes = os.path.getsize(raw_file)
+    except OSError:
+        pass
+    tokens_saved = estimate_savings(raw_bytes, symbol.get("byte_length", 0))
+    total_saved = record_savings(tokens_saved)
+    meta["tokens_saved"] = tokens_saved
+    meta["total_tokens_saved"] = total_saved
+
     elapsed = (time.perf_counter() - start) * 1000
 
     result = {
@@ -172,10 +185,30 @@ def get_symbols(
             "source": source or ""
         })
 
+    # Token savings: unique file sizes vs sum of symbol byte_lengths
+    raw_bytes = 0
+    seen_files: set = set()
+    response_bytes = 0
+    for symbol_id in symbol_ids:
+        symbol = index.get_symbol(symbol_id)
+        if not symbol:
+            continue
+        f = symbol["file"]
+        if f not in seen_files:
+            seen_files.add(f)
+            try:
+                raw_bytes += os.path.getsize(store._content_dir(owner, name) / f)
+            except OSError:
+                pass
+        response_bytes += symbol.get("byte_length", 0)
+    tokens_saved = estimate_savings(raw_bytes, response_bytes)
+    total_saved = record_savings(tokens_saved)
+
     elapsed = (time.perf_counter() - start) * 1000
 
     return {
         "symbols": symbols,
         "errors": errors,
-        "_meta": _make_meta(elapsed, symbol_count=len(symbols)),
+        "_meta": _make_meta(elapsed, symbol_count=len(symbols),
+                            tokens_saved=tokens_saved, total_tokens_saved=total_saved),
     }

src/jcodemunch_mcp/tools/search_symbols.py

@@ -1,9 +1,10 @@
 """Search symbols across repository."""
 
+import os
 import time
 from typing import Optional
 
-from ..storage import IndexStore, CodeIndex
+from ..storage import IndexStore, CodeIndex, record_savings, estimate_savings
 
 
 def search_symbols(
@@ -74,6 +75,23 @@ def search_symbols(
             "score": score
         })
 
+    # Token savings: files containing matches vs symbol byte_lengths of results
+    raw_bytes = 0
+    seen_files: set = set()
+    response_bytes = 0
+    content_dir = store._content_dir(owner, name)
+    for sym in results[:max_results]:
+        f = sym["file"]
+        if f not in seen_files:
+            seen_files.add(f)
+            try:
+                raw_bytes += os.path.getsize(content_dir / f)
+            except OSError:
+                pass
+        response_bytes += sym.get("byte_length", 0)
+    tokens_saved = estimate_savings(raw_bytes, response_bytes)
+    total_saved = record_savings(tokens_saved)
+
     elapsed = (time.perf_counter() - start) * 1000
 
     return {
@@ -85,6 +103,8 @@ def search_symbols(
             "timing_ms": round(elapsed, 1),
             "total_symbols": len(index.symbols),
             "truncated": len(results) > max_results,
+            "tokens_saved": tokens_saved,
+            "total_tokens_saved": total_saved,
         },
     }