⚔ token-savior

Хватит скармливать ИИ целые кодовые базы. Дайте ему скальпель.

Python 3.11+ MCP

MCP-сервер, который индексирует вашу кодовую базу структурно и предоставляет инструменты для хирургически точных запросов — чтобы ваш ИИ-агент читал 200 символов вместо 200 файлов.

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

Измерено на 782 реальных сессиях: сокращение потребления токенов на 99%.

Зачем это нужно

Каждая сессия программирования с ИИ начинается одинаково: агент использует cat или grep, читает десяток файлов, чтобы найти одну функцию, а затем перегружает свой контекст, пытаясь понять, что ещё может сломаться. В итоге половина бюджета токенов тратится ещё до первого изменения.

token-savior полностью меняет этот паттерн. Он один раз строит структурный индекс, автоматически синхронизирует его с git и отвечает на вопросы «где находится X», «что вызывает X» и «что сломается, если я изменю X» за доли миллисекунды — при этом объём ответов соответствует самому ответу, а не всей кодовой базе.

Цифры

Экономия токенов в реальных сессиях

Проект	Сессии	Запросы	Использовано символов	Символов (наивно)	Экономия
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%
ИТОГО	92	782	5,981,476	664,229,092	99%

«Символов (наивно)» = общий размер исходного кода всех файлов, которые агент прочитал бы с помощью cat/grep. Эта экономия не зависит от модели — индекс снижает нагрузку на контекстное окно независимо от провайдера.

Время ответа на запрос (доли миллисекунды при 1.1 млн строк)

Запрос	RMLPlus	FastAPI	Django	CPython
`find_symbol`	0.01мс	0.01мс	0.03мс	0.08мс
`get_dependencies`	0.00мс	0.00мс	0.00мс	0.01мс
`get_change_impact`	0.02мс	0.00мс	2.81мс	0.45мс
`get_function_source`	0.01мс	0.02мс	0.03мс	0.10мс

Производительность построения индекса

Проект	Файлы	Строки	Время индексации	Память
Малый проект	36	7,762	0.9с	2.4 МБ
FastAPI	2,556	332,160	5.7с	55 МБ
Django	3,714	707,493	36.2с	126 МБ
CPython	2,464	1,115,334	55.9с	197 МБ

Благодаря постоянному кэшу последующие перезапуски пропускают полную сборку. CPython индексируется от 56с до менее чем 1с при попадании в кэш.

Что поддерживается

Язык / Формат	Файлы	Извлекаемые данные
Python	`.py`, `.pyw`	Функции, классы, методы, импорты, граф зависимостей
TypeScript / JS	`.ts`, `.tsx`, `.js`, `.jsx`	Функции, стрелочные функции, классы, интерфейсы, псевдонимы типов
Go	`.go`	Функции, методы (receiver), структуры, интерфейсы, псевдонимы типов
Rust	`.rs`	Функции, структуры, перечисления, трейты, блоки impl, macro_rules
C#	`.cs`	Классы, интерфейсы, структуры, перечисления, методы, XML-комментарии
Markdown / Текст	`.md`, `.txt`, `.rst`	Секции через обнаружение заголовков
JSON	`.json`	Вложенная структура ключей до глубины 4, перекрестные ссылки `$ref`
YAML	`.yaml`, `.yml`	Иерархия вложенных ключей, маркеры массивов, ограничение глубины 4
TOML	`.toml`	Таблицы, пары ключ-значение, вложенная структура
INI / Properties	`.ini`, `.cfg`, `.properties`	Секции, пары ключ-значение
Environment	`.env`	Имена переменных, значения (с маскированием секретов)
XML / Plist / SVG	`.xml`, `.plist`, `.svg`, `.xhtml`	Иерархия элементов, атрибуты
HCL / Terraform	`.hcl`, `.tf`	Блоки, вложенные ресурсы, пары ключ-значение
Conf	`.conf`	Пары ключ-значение, блочная структура
Dockerfile	`Dockerfile`, `*.dockerfile`	Инструкции, многоэтапные сборки, FROM/RUN/COPY/ENV
Всё остальное	`*`	Подсчет строк (общий запасной вариант)

51 инструмент

Инструмент	Что делает
`find_symbol`	Где определен символ — файл, строка, тип, превью на 20 строк
`get_function_source`	Полный исходный код функции или метода
`get_class_source`	Полный исходный код класса
`get_functions`	Все функции в файле или проекте
`get_classes`	Все классы с методами и базовыми классами
`get_imports`	Все импорты с модулем, именами, строкой
`get_structure_summary`	Краткий обзор структуры файла или проекта
`list_files`	Индексированные файлы с опциональным glob-фильтром
`get_project_summary`	Количество файлов, пакеты, основные классы/функции
`search_codebase`	Поиск по регулярным выражениям во всех индексированных файлах
`reindex`	Принудительная полная переиндексация (редко требуется)

Контекст и обнаружение

Инструмент	Что делает
`get_edit_context`	Всё в одном: исходный код символа + зависимости + вызывающие стороны в одном вызове (экономит 3 вызова)
`get_feature_files`	Найти все файлы, связанные с ключевым словом функции, затем транзитивно отследить импорты
`get_routes`	Обнаружение API-маршрутов и страниц (Next.js App Router, Express, pages/api)
`get_components`	Обнаружение React-компонентов (функций, возвращающих JSX) в файлах `.tsx`/`.jsx`
`get_env_usage`	Найти все ссылки на переменную окружения во всей кодовой базе

Анализ влияния

Инструмент	Что делает
`get_dependencies`	Что вызывает/использует символ
`get_dependents`	Что вызывает/использует символ
`get_change_impact`	Прямые + транзитивные зависимости в одном вызове
`get_call_chain`	Кратчайший путь зависимости между двумя символами (BFS)
`get_file_dependencies`	Файлы, импортируемые данным файлом
`get_file_dependents`	Файлы, которые импортируют из данного файла

Git и diff-ы

Инструмент	Что делает
`get_git_status`	Ветка, опережение/отставание, staged, unstaged, неотслеживаемые файлы
`get_changed_symbols`	Измененные файлы как сводки на уровне символов, а не diff-ы
`get_changed_symbols_since_ref`	Изменения на уровне символов с момента любого git-референса
`summarize_patch_by_symbol`	Компактный обзор — символы вместо текстовых diff-ов
`build_commit_summary`	Компактная сводка коммита на основе измененных файлов

Безопасное редактирование

Инструмент	Что делает
`replace_symbol_source`	Заменить исходный код символа, не затрагивая остальную часть файла
`insert_near_symbol`	Вставить контент до или после символа
`create_checkpoint`	Сделать снимок набора файлов перед редактированием
`restore_checkpoint`	Восстановить из контрольной точки
`compare_checkpoint_by_symbol`	Сравнение контрольной точки с текущим состоянием на уровне символов
`list_checkpoints`	Список доступных контрольных точек

Тестирование и запуск

Инструмент	Что делает
`find_impacted_test_files`	Вывод вероятных затронутых pytest-файлов на основе измененных символов
`run_impacted_tests`	Запуск только затронутых тестов — компактная сводка, а не сырые логи
`apply_symbol_change_and_validate`	Редактирование + запуск затронутых тестов в одном вызове
`apply_symbol_change_validate_with_rollback`	Редактирование + проверка + автоматический откат при сбое
`discover_project_actions`	Обнаружение команд тестирования/линта/сборки/запуска из файлов проекта
`run_project_action`	Выполнение обнаруженного действия с ограниченным выводом

Анализ конфигурации

Инструмент	Что делает
`analyze_config`	Сканирование файлов конфигурации на наличие дубликатов, секретов, опечаток и «сиротских» ключей

Выполняет три проверки (переключаются индивидуально через параметр checks):

Дубликаты — один и тот же ключ определен дважды в одном файле, плюс обнаружение опечаток на основе расстояния Левенштейна (например, db_hsot против db_host)
Секреты — регулярные выражения для известных форматов секретов (API-ключи, токены, закрытые ключи) плюс анализ энтропии Шеннона для строк с высокой энтропией
Сироты — перекрестная проверка ключей конфигурации с фактическим использованием в коде. Обнаруживает ключи, которые ваш код никогда не читает, и переменные окружения, которые код ожидает, но они не установлены. Понимает os.environ, process.env, os.Getenv, std::env::var и другие.

Поддерживаемые форматы: .yaml, .yml, .toml, .ini, .cfg, .properties, .env, .xml, .plist, .hcl, .tf, .conf, .json

Качество кода

Инструмент	Что делает
`find_dead_code`	Поиск функций/классов с нулевым количеством вызовов (исключая точки входа, тесты, декорированные маршруты)
`find_hotspots`	Ранжирование функций по сложности (строки, ветвления, вложенность, количество параметров)
`detect_breaking_changes`	Сравнение текущих сигнатур функций с git-референсом — помечает удаленные/переименованные параметры, измененные значения по умолчанию

Docker

Инструмент	Что делает
`analyze_docker`	Аудит Docker-файлов: базовые образы, открытые порты, перекрестные ссылки ENV/ARG, предупреждения о теге `latest`

Мультипроектность

Инструмент	Что делает
`find_cross_project_deps`	Перекрестная проверка импортов между проектами для поиска общих зависимостей

Статистика

Инструмент	Что делает
`get_usage_stats`	Совокупная экономия токенов на проект по сессиям

vs LSP

LSP отвечает на вопрос «где это определено?» — token-savior отвечает на вопрос «что сломается, если я это изменю?»

LSP — это точечные запросы: один символ, один файл, одна позиция. Он может найти, где определен LLMClient и кто ссылается на него напрямую. Спросите «что сломается транзитивно, если я отрефакторя LLMClient?», и LSP ничего не ответит — ИИ пришлось бы рекурсивно вызывать десятки запросов поиска ссылок, читая файлы на каждом шагу.

get_change_impact("TestCase") в CPython находит 154 прямых зависимых элемента и 492 транзитивных за 0.45мс, возвращая 16К символов вместо чтения 41М. И в отличие от LSP, он не требует никаких языковых серверов — один бинарный файл «из коробки» покрывает Python + TS/JS + Go + Rust + C# + файлы конфигурации + Docker-файлы.

Установка

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]"

Настройка

Claude Code / Cursor / Windsurf / Cline

Добавьте в .mcp.json в корне вашего проекта:

{
  "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"
      }
    }
  }
}

token-savior