⚔ token-savior

Hör auf, deiner KI ganze Codebasen zu füttern. Gib ihr stattdessen ein Skalpell.

Python 3.11+ MCP

Ein MCP-Server, der deine Codebasis strukturell indiziert und chirurgische Abfragewerkzeuge bereitstellt – damit dein KI-Agent 200 Zeichen statt 200 Dateien liest.

find_symbol("send_message")           →  67 chars    (was: 41M chars of source)
get_change_impact("LLMClient")        →  16K chars   (154 direct + 492 transitive deps)
get_function_source("compile")        →  4.5K chars  (exact source, no grep, no cat)
analyze_config()                      →  finds duplicates, secrets, orphan keys

Gemessen über 782 echte Sitzungen: 99 % Token-Reduktion.

Warum es existiert

Jede KI-Codierungssitzung beginnt gleich: Der Agent greift zu cat oder grep, liest ein Dutzend Dateien, um eine Funktion zu finden, und bläht dann seinen Kontext auf, um zu verstehen, was sonst noch kaputtgehen könnte. Am Ende ist die Hälfte deines Token-Budgets weg, bevor die erste Änderung vorgenommen wurde.

token-savior ersetzt dieses Muster vollständig. Es erstellt einmalig einen strukturellen Index, hält ihn automatisch mit Git synchron und beantwortet Fragen wie „Wo ist X“, „Was ruft X auf“ und „Was geht kaputt, wenn ich X ändere“ in Sub-Millisekunden – mit Antworten, die auf die Antwort zugeschnitten sind, nicht auf die Codebasis.

Zahlen

Token-Einsparungen über echte Sitzungen hinweg

Projekt	Sitzungen	Abfragen	Verwendete Zeichen	Zeichen (naiv)	Einsparung
project-alpha	35	360	4.801.108	639.560.872	99 %
project-beta	26	189	766.508	20.936.204	96 %
project-gamma	30	232	410.816	3.679.868	89 %
GESAMT	92	782	5.981.476	664.229.092	99 %

„Zeichen (naiv)“ = Gesamtgröße aller Quelldateien, die der Agent mit cat/grep gelesen hätte. Diese Einsparungen sind modellunabhängig – der Index reduziert den Druck auf das Kontextfenster unabhängig vom Anbieter.

Abfrage-Reaktionszeit (Sub-Millisekunde bei 1,1 Mio. Zeilen)

Abfrage	RMLPlus	FastAPI	Django	CPython
`find_symbol`	0,01 ms	0,01 ms	0,03 ms	0,08 ms
`get_dependencies`	0,00 ms	0,00 ms	0,00 ms	0,01 ms
`get_change_impact`	0,02 ms	0,00 ms	2,81 ms	0,45 ms
`get_function_source`	0,01 ms	0,02 ms	0,03 ms	0,10 ms

Performance beim Index-Aufbau

Projekt	Dateien	Zeilen	Index-Zeit	Speicher
Kleines Projekt	36	7.762	0,9 s	2,4 MB
FastAPI	2.556	332.160	5,7 s	55 MB
Django	3.714	707.493	36,2 s	126 MB
CPython	2.464	1.115.334	55,9 s	197 MB

Mit dem persistenten Cache überspringen nachfolgende Neustarts den vollständigen Aufbau. CPython geht von 56 s → unter 1 s bei einem Cache-Treffer.

Was es abdeckt

Sprache / Format	Dateien	Extrakte
Python	`.py`, `.pyw`	Funktionen, Klassen, Methoden, Importe, Abhängigkeitsgraph
TypeScript / JS	`.ts`, `.tsx`, `.js`, `.jsx`	Funktionen, Pfeilfunktionen, Klassen, Interfaces, Typ-Aliase
Go	`.go`	Funktionen, Methoden (Receiver), Structs, Interfaces, Typ-Aliase
Rust	`.rs`	Funktionen, Structs, Enums, Traits, impl-Blöcke, macro_rules
C#	`.cs`	Klassen, Interfaces, Structs, Enums, Methoden, XML-Dokumentationskommentare
Markdown / Text	`.md`, `.txt`, `.rst`	Abschnitte durch Überschriftenerkennung
JSON	`.json`	Verschachtelte Schlüsselstruktur bis Tiefe 4, `$ref`-Querverweise
YAML	`.yaml`, `.yml`	Verschachtelte Schlüsselhierarchie, Array-Marker, Tiefenbegrenzung 4
TOML	`.toml`	Tabellen, Schlüssel-Wert-Paare, verschachtelte Struktur
INI / Properties	`.ini`, `.cfg`, `.properties`	Abschnitte, Schlüssel-Wert-Paare
Environment	`.env`	Variablennamen, Werte (mit Maskierung von Geheimnissen)
XML / Plist / SVG	`.xml`, `.plist`, `.svg`, `.xhtml`	Elementhierarchie, Attribute
HCL / Terraform	`.hcl`, `.tf`	Blöcke, verschachtelte Ressourcen, Schlüssel-Wert-Paare
Conf	`.conf`	Schlüssel-Wert-Paare, Blockstruktur
Dockerfile	`Dockerfile`, `*.dockerfile`	Anweisungen, Multi-Stage-Builds, FROM/RUN/COPY/ENV
Alles andere	`*`	Zeilenzahlen (generischer Fallback)

51 Werkzeuge

Werkzeug	Was es tut
`find_symbol`	Wo ein Symbol definiert ist – Datei, Zeile, Typ, 20-Zeilen-Vorschau
`get_function_source`	Vollständiger Quellcode einer Funktion oder Methode
`get_class_source`	Vollständiger Quellcode einer Klasse
`get_functions`	Alle Funktionen in einer Datei oder einem Projekt
`get_classes`	Alle Klassen mit Methoden und Basisklassen
`get_imports`	Alle Importe mit Modul, Namen, Zeile
`get_structure_summary`	Datei- oder Projektstruktur auf einen Blick
`list_files`	Indizierte Dateien mit optionalem Glob-Filter
`get_project_summary`	Dateianzahl, Pakete, Top-Klassen/Funktionen
`search_codebase`	Regex-Suche über alle indizierten Dateien
`reindex`	Erzwingt eine vollständige Neuindizierung (selten benötigt)

Kontext & Entdeckung

Werkzeug	Was es tut
`get_edit_context`	Alles in einem: Symbolquelle + Abhängigkeiten + Aufrufer in einem Aufruf (spart 3 Aufrufe)
`get_feature_files`	Findet alle Dateien, die mit einem Feature-Schlüsselwort zusammenhängen, und verfolgt dann Importe transitiv
`get_routes`	Erkennt API-Routen und Seiten (Next.js App Router, Express, pages/api)
`get_components`	Erkennt React-Komponenten (Funktionen, die JSX zurückgeben) in `.tsx`/`.jsx`-Dateien
`get_env_usage`	Findet alle Referenzen auf eine Umgebungsvariable in der gesamten Codebasis

Wirkungsanalyse

Werkzeug	Was es tut
`get_dependencies`	Was ein Symbol aufruft/verwendet
`get_dependents`	Was ein Symbol aufruft/verwendet
`get_change_impact`	Direkte + transitive Abhängige in einem Aufruf
`get_call_chain`	Kürzester Abhängigkeitspfad zwischen zwei Symbolen (BFS)
`get_file_dependencies`	Dateien, die von einer bestimmten Datei importiert werden
`get_file_dependents`	Dateien, die aus einer bestimmten Datei importieren

Git & Diffs

Werkzeug	Was es tut
`get_git_status`	Branch, voraus/zurück, gestaged, nicht gestaged, nicht verfolgt
`get_changed_symbols`	Geänderte Dateien als Zusammenfassungen auf Symbolebene, keine Diffs
`get_changed_symbols_since_ref`	Änderungen auf Symbolebene seit einem beliebigen Git-Ref
`summarize_patch_by_symbol`	Kompakte Review-Ansicht – Symbole statt textueller Diffs
`build_commit_summary`	Kompakte Commit-Zusammenfassung aus geänderten Dateien

Sicheres Bearbeiten

Werkzeug	Was es tut
`replace_symbol_source`	Ersetzt die Quelle eines Symbols, ohne den Rest der Datei zu berühren
`insert_near_symbol`	Fügt Inhalt vor oder nach einem Symbol ein
`create_checkpoint`	Erstellt einen Snapshot einer Reihe von Dateien vor der Bearbeitung
`restore_checkpoint`	Wiederherstellung aus einem Checkpoint
`compare_checkpoint_by_symbol`	Diff zwischen Checkpoint und aktuellem Stand auf Symbolebene
`list_checkpoints`	Listet verfügbare Checkpoints auf

Testen & Ausführen

Werkzeug	Was es tut
`find_impacted_test_files`	Leitet wahrscheinlich betroffene pytest-Dateien aus geänderten Symbolen ab
`run_impacted_tests`	Führt nur betroffene Tests aus – kompakte Zusammenfassung, keine Rohprotokolle
`apply_symbol_change_and_validate`	Bearbeiten + Ausführen betroffener Tests in einem Aufruf
`apply_symbol_change_validate_with_rollback`	Bearbeiten + Validieren + automatisches Rollback bei Fehler
`discover_project_actions`	Erkennt Test-/Lint-/Build-/Run-Befehle aus Projektdateien
`run_project_action`	Führt eine erkannte Aktion mit begrenzter Ausgabe aus

Konfigurationsanalyse

Werkzeug	Was es tut
`analyze_config`	Scannt Konfigurationsdateien auf Duplikate, Geheimnisse, Tippfehler und verwaiste Schlüssel

Führt drei Prüfungen durch (individuell umschaltbar über den checks-Parameter):

Duplikate – Derselbe Schlüssel wird zweimal in derselben Datei definiert, plus Levenshtein-basierte Tippfehlererkennung (z. B. db_hsot vs db_host)
Geheimnisse – Regex-Muster für bekannte Geheimnisformate (API-Schlüssel, Token, private Schlüssel) plus Shannon-Entropie-Analyse für Strings mit hoher Entropie
Waisen – Querverweise von Konfigurationsschlüsseln mit der tatsächlichen Code-Verwendung. Erkennt Schlüssel, die dein Code nie liest, und Umgebungsvariablen, die dein Code erwartet, die aber nicht gesetzt sind. Versteht os.environ, process.env, os.Getenv, std::env::var und mehr.

Unterstützte Formate: .yaml, .yml, .toml, .ini, .cfg, .properties, .env, .xml, .plist, .hcl, .tf, .conf, .json

Codequalität

Werkzeug	Was es tut
`find_dead_code`	Findet Funktionen/Klassen ohne Aufrufer (schließt Einstiegspunkte, Tests, dekorierte Routen aus)
`find_hotspots`	Bewertet Funktionen nach Komplexitätsscore (Zeilen, Verzweigungen, Verschachtelung, Parameteranzahl)
`detect_breaking_changes`	Vergleicht aktuelle Funktionssignaturen mit einem Git-Ref – markiert entfernte/umbenannte Parameter, geänderte Standardwerte

Docker

Werkzeug	Was es tut
`analyze_docker`	Prüft Dockerfiles: Basis-Images, exponierte Ports, ENV/ARG-Querverweise, `latest`-Tag-Warnungen

Multi-Projekt

Werkzeug	Was es tut
`find_cross_project_deps`	Querverweise von Importen über Projekte hinweg, um gemeinsame Abhängigkeiten zu finden

Statistiken

Werkzeug	Was es tut
`get_usage_stats`	Kumulative Token-Einsparungen pro Projekt über Sitzungen hinweg

vs LSP

LSP beantwortet „Wo ist dies definiert?“ – token-savior beantwortet „Was geht kaputt, wenn ich es ändere?“

LSP sind Punktabfragen: ein Symbol, eine Datei, eine Position. Es kann finden, wo LLMClient definiert ist und wer direkt darauf verweist. Frage „Was geht transitiv kaputt, wenn ich LLMClient refaktoriere?“ und LSP hat nichts – die KI müsste Dutzende von Referenz-Suchaufrufen rekursiv verketten und bei jedem Schritt Dateien lesen.

get_change_impact("TestCase") auf CPython findet 154 direkte Abhängige und 492 transitive Abhängige in 0,45 ms und gibt 16 KB Zeichen zurück, anstatt 41 MB zu lesen. Und im Gegensatz zu LSP erfordert es null Sprachserver – eine Binärdatei deckt Python + TS/JS + Go + Rust + C# + Konfigurationsdateien + Dockerfiles sofort ab.

Installieren

git clone https://github.com/Mibayy/token-savior
cd token-savior
python3 -m venv ~/.local/token-savior-venv
~/.local/token-savior-venv/bin/pip install -e ".[mcp]"

Konfigurieren

Claude Code / Cursor / Windsurf / Cline

Füge dies zu .mcp.json in deinem Projektstammverzeichnis hinzu:

{
  "mcpServers": {
    "token-savior": {
      "command": "/path/to/.local/token-savior-venv/bin/token-savior",
      "env": {
        "WORKSPACE_ROOTS": "/path/to/project1,/path/to/project2",
        "TOKEN_SAVIOR_CLIENT": "claude-code"
      }
    }
  }
}

Hermes Agent

Füge dies zu ~/.hermes/config.yaml hinzu:

mcp_servers:
  token-savior:
    command: ~/.local/token-savior-venv/bin/token-savior
    env:
      WORKSPACE_ROOTS: /path/to/project1,/path/to/project2
      TOKEN_SAVIOR_CLIENT: hermes
    timeout: 120
    connect_timeout: 30

TOKEN_SAVIOR_CLIENT ist optional, ermöglicht es dem Live-Dashboard jedoch, Einsparungen nach Client zuzuordnen.

Den Agenten dazu bringen, es tatsächlich zu nutzen

KI-Assistenten verwenden standardmäßig grep und cat, selbst wenn bessere Werkzeuge verfügbar sind. Weiche Anweisungen werden rationalisiert. Füge dies zu deiner CLAUDE.md oder Äquivalent hinzu:

GXP

token-savior