fittok

Извлекайте только релевантный исходный код для вопроса — вместо того, чтобы модель читала целиком файлы, чтобы отвечать на вопросы по кодовой базе, на небольшом, сфокусированном фрагменте контекста. Меньшее количество входных данных — меньше токенов, ниже стоимость, быстрее ответы.

Работает трёх способами из одного инсталлятора: MCP-сервер, CLI и Python-библиотека — плюс Claude Code плагин, который автоматически внедряет контекст.

📖 Полная справка по командам → docs/HANDBOOK.md

mcp-name: io.github.likhithreddy/fittok

Как это работает

codebase ──▶ graphify ──▶ slurp ──▶ readable slice ──▶ LLM answers
             (parse)      (select)   (trim to budget)

graphify — парсит репозиторий с pomoc tree-sitter в граф знаний функций / классов / методов (Python, JS, JSX, TS, TSX, Java, Go, Rust). Поддерживает многоязычные ребра вызовов / импортов / ссылок.

slurp — оценивает каждый узел по вопросу с использованием гибрида из 4 сигналов:

Semantic embeddings (all-MiniLM-L6-v2) — сопоставление по смыслу
Content-BM25 (с разбиением camelCase / snake_case) — по ключевым словам
Summary-BM25 (имя узла + файл + вызывающие + вызываемые) — структурное сопоставление
PageRank — центральность графа / идентификация хабов

Сигналы объединяются через Reciprocal Rank Fusion (RRF) — основано на ранжировании, без проблем калибровки. Узлы выбираются через round-robin interleaving по директориям (гарантирует охват фасетов по многим аспектам запроса — по одному узлу из каждой области кода, пока каждый не даст второй) с ограничением по токенам на узел (25% бюджета, чтобы крупные компоненты не «заглушили» мелкие функции). Порог релевантности — cliff (семантика OR BM25 OR summary-BM25) — исключает шум.

readable output — возвращает фактический исходный код выбранных узлов, плюс карту кода базы (оглавление с докстрингами, вдохновлена Karpathy's LLM Wiki / Google's OKF) чтобы модель могла точно маршрутизировать последующие запросы. Модель отвечает прямо из неё — чтение файлов не требуется.

По мере редактирования файлов файл-воркер (автозапуск при первом запросе) обновляет граф инкрементально — перерабатываются только изменённые файлы и объединяются, а только изменённые функции повторно встраиваются. Графы и эмбеддинги кешируются на диске (~/.cache/fittok). Чтобы отключить воркер, установите FITTOK_AUTOWATCH=false; в этом случае правку нужно будет заново распарсить на следующем запросе.

Как добраться до лучших результатов (и известные ограничения)

Задавайте сфокусированные вопросы

fittok ранжирует код по вашему вопросу с использованием гибрида из 4 сигналов (семантика + BM25 + структурное + PageRank, объединённые через RRF) с diversity по директориям — так вопросы с несколькими аспектами показывают код из разных областей (UI, сервер, база данных), а не сходятся в одну доминирующую область. Это наиболее точно при сфокусированных, конкретных вопросах — по одному поводу за раз, по возможности упоминайте функцию/компонент/маршрут. Мультифакторные вопросы поддерживаются через разложение на части (описание инструмента говорит модели вызывать инструмент один раз по каждому аспекту) и карту кода базы (оглавление, добавляемое к каждому ответу).

✅ «Как выполняется и изолируется запрос SQL в runSandboxQuery?» → возвращает точную функцию и код её изоляции.
✅ «Как клиент querydle отправляет запрос и отображает результаты?» → возвращает UI-компонент.
✅ «Проследите полный цикл: отправка UI, выполнение в sandbox, изоляция данных» → разложение по аспектам + diversity покрывает несколько факторов; карта кода базы направляет модель к пропущенным файлам.

Правило пальца: один вопрос (или максимум 2–3 аспекта). Для «объяснить всю фичу» разбейте на несколько узких вопросов, а не на один мегапоиск.

Известные ограничения

GitHub Copilot Chat обрезает большие MCP-выводы (самый большой). Copilot кеширует результаты MCP-инструмента выше ~7 KB в файл content.json, где весь markdown сворачивается в одну физическую JSON-строку (экранированные переводы строк) — и его Read инструмент обрезает любую строку около 2,000 символов. Поэтому вывод более ~7 KB фактически обрезается до ~2,000 символов вне зависимости от общего размера; модель не видит большую часть кода и прибегает к чтению исходников напрямую. Это ограничение слоя доставки у Copilot, не у fittok — серверы MCP все попадают под него. По умолчанию (0.10.0+) fittok возвращает весь релевантный код без ограничений, что корректно для клиентов, которые придают вывод inline, но будет усечён Copilot. Два способа обойти:

Ограничьте вывод для Copilot так, чтобы он вставлялся inline (менее ~7 KB). Установите FITTOK_MAX_BUDGET=1200 в окружении вашего MCP-сервера:

{ "servers": { "fittok": { "command": "uvx", "args": ["fittok"], "env": { "FITTOK_MAX_BUDGET": "1200" } } } }

Используйте Claude Code или CLI для мног файл вопросов. Они возвращают MCP-вывод inline без отсечения — именно там полные (нераскрытые) результаты fittok и анти-ре-чтение окупаются.
Разрыв словарного запаса на абстрактные запросы. Когда запрос использует слова, которых нет в коде (например, «изоляция» → REVOKE/DENY), ни семантика, ни BM25 не смогут это связать. Карту кода базы (имена файлов + докстринги) и round-robin-diversity помогают; упоминание функции/файла направляет модель к нему.
Инкрементальная потеря граней вызовов: редактирование файла может временно прервать связанные вызовы/импорты из неизменённых файлов до полного повторного разбора. fittok автоматически восстанавливается после перезапуска или reset_graph.
Токенозатраты приближённые: счёт ведётся по cl100k_base, поэтому реальная загрузка может отличаться на ~10–20% по сравнению с токенизацией Claude.
Очень большие репозитории: PageRank ещё не векторизован — хорошо работает до нескольких тысяч узлов, медленнее при большой размерности.

Установка

fittok распространяется как MCP-сервер, CLI и Python-библиотека. Он использует torch для эмбеддингов, поэтому нужен Python-исполняющий контекст. Выберите один из рантаймов ниже, а затем следуйте разделу для вашего клиента.

Каждый конфиг ниже запускает fittok как uvx fittok. Если выбрали Python или pipx, замените это на python -m fittok или pipx run fittok соответственно.

Требуется — выбрать рантайм (один из)

A. uv — рекомендованное (Python не требуется на машине)

curl -LsSf https://astral.sh/uv/install.sh | sh   # Linux / macOS
winget install astral-sh.uv                        # Windows
brew install uv                                    # macOS (Homebrew)

Команда запуска: uvx fittok — uv предоставляет собственный Python + все зависимости в изоляции. Один статический бинарник, который можно развёртывать организационно через MDM/Intune/winget.

B. Python 3.10+ (установлен на машине)

python -m pip install fittok      # Linux / macOS
py    -m pip install fittok       # Windows

Команда запуска: python -m fittok (Windows: py -m fittok).

Управляема ли Linux-система: может отклонить pip install из-за PEP 668 — используйте вариант A.

C. pipx — изолированность, без глобальной установки

brew install pipx                               # macOS
pip install --user pipx && pipx ensurepath      # Linux / Windows

Команда запуска: pipx run fittok.

MCP сервер — Claude Code

claude mcp add fittok -s user -- uvx fittok

Перезапустите Claude Code → /mcp → убедитесь, что fittok подключён, затем задавайте вопросы по кодовой базе обычным способом.

MCP сервер — VS Code / GitHub Copilot Chat

code --add-mcp '{"name":"fittok","command":"uvx","args":["fittok"]}'

Или вставьте в .vscode/mcp.json (рабочее пространство) или ваш пользовательский mcp.json:

{ "servers": { "fittok": { "type": "stdio", "command": "uvx", "args": ["fittok"] } } }

Затем в Copilot Chat: режим Agent → включите инструменты fittok (Configure Tools).

MCP сервер — GitHub Copilot CLI

copilot mcp add fittok -- uvx fittok
copilot mcp get fittok          # проверить статус и инструменты

MCP сервер — Cursor / Windsurf / любой MCP-клиент

{ "mcpServers": { "fittok": { "command": "uvx", "args": ["fittok"] } } }

Авто-триггер (опционально, для каждого MCP-клиента)

Чтобы fittok срабатывал на каждом вопросе по кодовой базе — без явного упоминания — и чтобы ваш клиент не перечитывал файлы, которые уже вернул fittok (что снижает выгоду), добавьте в файл инструкций вашего клиента одну строку:

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

Первая часть инициирует fittok; вторая не позволяет клиенту повторно читать те же файлы. Они взаимно усиливают друг друга — одна формирует стратегию (использовать fittok), другая предотвращает повторное чтение. Для более явного блока можно использовать:

Для любого вопроса по кодовой базе ("как работает X", "где находится Y"):

Сначала вызовите инструмент MCP fittok один раз.

Отвечайте напрямую на основе его optimized_context — это реальный, авторитетный источник по этому вопросу.

НЕ читайте или не ищите в файлах, из которых fittok уже вернул код. Это снижает стоимость токенов, которую fittok обеспечивает.

Для наибольшего эффекта поместите это в ваши глобальные для пользователя инструкции, чтобы она распространялась на любые репозитории, а не только на один:

Клиент	Файл инструкций
Claude Code	CLAUDE.md (репозиторий) или ~/.claude/CLAUDE.md (пользователь-глобальный)
GitHub Copilot	.github/copilot-instructions.md или инструкции пользователя Copilot
Cursor	.cursor/rules/*.mdc (или .cursorrules)
Windsurf	.windsurfrules

fittok также включит это правило в каждый ответ (строка «answer from this, don't re-read» перед кодом) — поэтому работает даже без вышеупомянутого фрагмента, но фрагмент делает его дефолтом клиента для всех вопросов.

CLI

cd /path/to/your/repo

uvx fittok index                                      # опционально предварительная загрузка (~15s, кэш)
uvx fittok query "how does auth work"                 # LLM отвечает по релевантному коду
uvx fittok query "how does auth work" --budget 1500   # ограничить срез до 1500 токенов
uvx fittok query "how does auth work" --code          # сырой релевантный код, без LLM
uvx fittok graph                                      # интерактивный браузер графа
uvx fittok graph --query "auth"                       # граф с выделенными релевантными узлами

query отправляет релевантный кодовый срез к LLM и стримит ответ.

Установите одну переменную окружения — она «прокатит» без дополнительных действий:

export ANTHROPIC_API_KEY="sk-ant-..."   # → claude-haiku-4-5  (рекомендуется)
export OPENAI_API_KEY="sk-..."          # → gpt-4o-mini  (резервное)

Пользователи Claude Code уже имеют ANTHROPIC_API_KEY — дополнительных действий не требуется.

Если ни один ключ не установлен, fittok перейдёт к --code и выведет подсказку по настройке.

graph требует pyvis: uv pip install "fittok[ui]".

Python библиотека

uv add fittok            # в проекте uv   (или:  uv pip install fittok  в виртуальном окружении)

from fittok import optimize

result = optimize("/path/to/repo", "how does authentication work", token_budget=1500)
print(result["optimized_context"])   # релевантный фрагмент кода
print(result["savings"])             # данные об экономии токенов

Обновление

uvx кэширует окружение, поэтому новая версия fittok не подхватывается автоматически — перезапуск сервера повторно использует кешированную версию. Обновляйте одной командой (регистрацию MCP-сервера повторно выполнять не нужно):

uvx --refresh fittok        # переопределение с PyPI → последняя версия

Затем перезапустите MCP-сервер (обновите окно в VS Code или перезапустите Copilot CLI), чтобы запустилась новая версия. Для других рантаймов:

pip: python -m pip install --upgrade fittok
pipx: pipx upgrade fittok

Зачем tree-sitter, а не LSP?

fittok использует tree-sitter (быструю синтаксическую AST-парсинг) вместо LSP (Language Server Protocol — семантический анализ с типами, крест-файловые ссылки, переход к определению). Это сознательный компромисс:

	tree-sitter (fittok)	LSP (например Serena MCP)
Что возвращает	Реальный исходный код — модель отвечает напрямую	Метаданные символов (имена, ссылки, типы) — модель должна читать файлы
Настройка	Нулевая конфигурация, работает в любом каталоге	Нужны сервера языков и конфигурации проекта (tsconfig, pyproject и т.д.)
Языки	8 из коробки (Python, JS/TS/TSX, Java, Go, Rust)	Сколько есть LSP-серверов, которые вы установили
Загрузка/стартап	~15s (парсинг + embedding)	Минуты (полная индексация проекта по языкам)
Память	~100 MB (граф + эмбеддинги)	500 MB+ на язык
Вызовы модели за вопрос	1–5 (один клик)	5–20+ (итеративная навигация по символам)
Стоимость токенов	~2,500 токенов (код возвращается напрямую)	~15,000+ токенов (метаданные + чтение файлов)

Уникальное торговое предложение fittok — экономия токенов. Он возвращает фактический код за один вызов, чтобы модель не читала файлы. 基 LSP-инструменты возвращают метаданные (имена символов, списки ссылок) — точные, но модель всё равно должна открывать файлы, чтобы увидеть реализацию. Много раунд-триппов — больше токенов.

Компромисс: tree-sitter не может так же точно разрешать кросс-файл-ссылки, как LSP (fetch("/api/run") в .tsx может не полностью связать с обработчиком маршрута). fittok компенсирует это четырёхсигнальным извлечением (семантика + Content-BM25 + структурированное Summary-BM25 + PageRank, объединённые через RRF) и разнообразием по директориям — что на практике заполняет пробел.

Дополняющий, не конкурирующий подход: LSP-базированные инструменты типа Serena отлично подходят для навигации на уровне символов («найти всех вызвавших runSandboxQuery»). fittok лучше подходит для семантического извлечения («как работает выполнение SQL?»). Установите оба — модель выбирает подходящий инструмент под задачу.

Финансовые данные по экономии токенов — честно

На реальном репозитории Next.js/TS (~5k функций) fittok возвращает примерно срез на ~1.5–3.5k токенов, вместо того чтобы модель читала файлы на 15–20k+ токенов — примерно 80–90% экономии входных токенов, детерминировано и отражено в нижнем колонтитуле savings.

На Opus 4.8, для сложного вопроса стоимость была около 84k токенов без fittok против ~27k с ним — потому что fittok заменяет большой субагент Explore на один инструмент.

Как честно измерять:

Используйте нижний колонтитул 🪙 saved X% или ваш API-счёт (общее количество токенов).
Не опирайтесь на число сообщений Claude Code /context — оно исключает токены субагентов и в основном зависит от рассуждений модели, которых fittok не касается.

Конфигурация

Переменная	Значение по умолчанию	Описание
ANTHROPIC_API_KEY	—	Включает ответы LLM через claude-haiku-4-5
OPENAI_API_KEY	—	Резервный LLM через gpt-4o-mini
FITTOK_SHOW_SAVINGS	true	🪙 сохранённая экономия X% в ответах MCP; установить false чтобы отключить
FITTOK_MAX_BUDGET	0 (без ограничений)	Ограничение по токенам кода. 0 = вернуть ВСЕ релевантные коды целиком (по умолчанию — полные результаты в Claude Code / CLI). Установите 1200 для GitHub Copilot, который обрезает MCP-выводы >~ 7 KB (см. раздел Известные ограничения).
FITTOK_AUTOWATCH	true	Автоматический запуск файлового наблюдателя, чтобы граф обновлялся инкрементально (перепарсинг только изменённых файлов); установить false для полного повторного разбора при правках
FITTOK_EMBED_MODEL	all-MiniLM-L6-v2	Модель эмбеддингов
FITTOK_DEVICE	auto	auto / cuda / mps / cpu
FITTOK_CACHE_DIR	~/.cache/fittok	Директория кеша

Полная справка: docs/HANDBOOK.md

Требования

Python ≥ 3.10. При первом запуске загружается модель эмбеддингов ~90 MB. Визуализация графа ( fittok graph ) включена по умолчанию. Опциональные дополнения:

uv pip install "fittok[ui]" — веб-дашборд Gradio (launch_ui инструмент)
uv pip install "fittok[gpu]" — torch/CUDA для GPU-ускорения эмбеддингов

Лицензия

MIT