От пустого каталога до работающего MCP-сервера: команды, которые действительно есть в документации, таблица флагов, настройка хука и разбор ошибок, на которых спотыкаются при первом запуске.
Задача гайда — довести вас от чистого терминала до момента, когда кодинг-агент отвечает на вопрос по вашему репозиторию со ссылками на файлы, а не пересказывает наугад. Понадобится Python 3.10+, uv (или pipx) и один репозиторий. Ключ модели нужен только для семантического прохода по документам: разбор кода работает без него.
graphifyy — с двумя «y», а команда и скилл называются graphify. Похожие имена пакетов к Graphify Labs отношения не имеют. Команда /graphify . набирается в чате ассистента, а не в оболочке.| Требование | Зачем | Как проверить |
|---|---|---|
| Python 3.10+ | пакет не ставится на более старые версии; uv поставит сам | python3 --version |
| uv или pipx | изолированное окружение и команда в PATH | uv --version |
| Репозиторий | граф строится по каталогу; начните с одного проекта | git status |
| Кодинг-агент | нужен только для скилла и MCP, не для CLI | Claude Code, Cursor, Codex, Gemini CLI |
| Ключ модели | только для документов, PDF и картинок | не нужен для --code-only |
Если uv ещё не установлен, его ставит одна команда под вашу систему. На macOS это Homebrew, на Linux и в Windows — официальные установщики Astral. После установки откройте новый терминал: PATH обновляется только в новой сессии.
# macOS brew install uv # Linux curl -LsSf https://astral.sh/uv/install.sh | sh # Windows (PowerShell) powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" uv --version
uv tool install graphifyy graphify --version
graphify install --platform claude graphify install --platform codex graphify install --project --platform claude
/graphify . # то же самое без ассистента, без ключа модели graphify extract . --code-only
uv tool install "graphifyy[mcp]", наблюдение за файлами — [watch], PDF — [pdf], SQL — [sql], Terraform — [terraform], Office — [office], локальная модель — [ollama], кластеризация Leiden — [leiden]. Комбинировать можно: "graphifyy[mcp,watch]".| Файл или каталог | Что внутри | Когда пригодится |
|---|---|---|
graph.json | граф в формате NetworkX node-link: узлы, рёбра, метки происхождения | основной артефакт |
GRAPH_REPORT.md | сообщества, god-узлы, неожиданные связи, вопросы | показать команде карту проекта |
graph.html | интерактивная визуализация с поиском и фильтром по сообществам | разбор незнакомого модуля |
manifest.json | отпечатки файлов для инкрементального обновления | ускорение повторных прогонов |
cache/ | кэш извлечения по SHA256 | повторный запуск обрабатывает только изменённое |
cost.json | стоимость локального извлечения, если считалась | контроль расхода токенов |
Начните с --code-only: он не требует ключа и занимает секунды на среднем проекте. Если после этого graph.json появился, а GRAPH_REPORT.md нет — это нормально: отчёт и визуализацию собирает отдельный шаг кластеризации, который можно вызвать без модели командой graphify cluster-only . --no-label. Пересобрать только HTML — graphify export html.
Скилл и MCP — два разных способа дать агенту граф. Скилл работает через инструкции и хуки: агент знает, что при вопросе про кодовую базу надо сходить в граф. MCP работает через структурированные вызовы инструментов: клиент сам решает, какой инструмент дёрнуть. Ставить можно и то, и другое — они смотрят в один и тот же graph.json.
| Клиент | Регистрация скилла | Подключение MCP |
|---|---|---|
| Claude Code | graphify install --platform claude | claude mcp add --transport stdio graphify -- graphify-mcp /abs/path/graph.json |
| Codex | graphify install --platform codex | codex mcp add graphify -- graphify-mcp /abs/path/graph.json |
| Cursor | через graphify install и выбор платформы | запись mcpServers.graphify в конфиге MCP |
| Gemini CLI | заявлен в описании репозитория | stdio-транспорт с абсолютным путём к графу |
| Другие клиенты | скилл для клиентов без своей страницы | stdio, команда graphify-mcp, первый аргумент — путь к графу |
uv tool install "graphifyy[mcp]" # если уже стоял без extra: uv tool install --reinstall "graphifyy[mcp]"
claude mcp add --transport stdio graphify -- \ graphify-mcp /abs/path/to/repo/graphify-out/graph.json
{"tool": "graph_stats"}{"question": "authentication flow", "token_budget": 1500}Локальный MCP-сервер отдаёт десять инструментов: query_graph (поиск по графу с обходом BFS или DFS), get_node, get_neighbors, get_community, god_nodes, graph_stats, shortest_path, а также три PR-инструмента — list_prs, get_pr_impact, triage_prs. Важная деталь: PR-инструменты читают GitHub через gh, то есть это уже не полностью офлайн-сценарий.
Шум в графе — главная причина, по которой первый прогон на большом проекте разочаровывает. Лечится файлом .graphifyignore в корне репозитория: туда уходят зависимости, артефакты сборки, сгенерированный код и всё, что не помогает агенту отвечать на вопросы. Синтаксис — как в .gitignore. Проверить, что хук действительно стоит, можно командой graphify hook status.
Если после рефакторинга граф стал меньше и обновление отказывается его записывать — это защита от потери данных, а не баг. Посмотрите предупреждение, убедитесь, что уменьшение ожидаемо, и повторите с graphify update . --force. Обратная ситуация: граф не растёт, хотя файлы добавились, — почти всегда сработали правила игнорирования или файл не поддержан экстрактором.
Для повторяемых прогонов есть graphify extract — тот же пайплайн без ассистента. Кодовая часть не требует ключа, поэтому её спокойно ставят в CI: зафиксируйте версию пакета, запускайте из корня репозитория и сохраняйте граф или отчёт как артефакт сборки. Семантическая часть требует секретов провайдера и стоит токенов, поэтому её обычно выносят в отдельную ночную джобу.
# только код: без ключа, быстро, детерминированно graphify extract . --code-only # семантика по папке с документацией — нужен ключ выбранного бэкенда graphify extract ./docs --backend claude # локальная модель с ограничением ресурсов graphify extract ./docs --backend ollama \ --token-budget 4000 --max-concurrency 2
| Бэкенд | Что нужно настроить |
|---|---|
| claude | ANTHROPIC_API_KEY, опционально ANTHROPIC_MODEL |
| gemini | GEMINI_API_KEY или GOOGLE_API_KEY |
| openai | OPENAI_API_KEY, опционально OPENAI_BASE_URL |
| deepseek / kimi | DEEPSEEK_API_KEY / MOONSHOT_API_KEY |
| ollama | локальный сервер, опционально OLLAMA_MODEL |
| bedrock / azure | стандартная цепочка AWS / ключ и endpoint Azure OpenAI |
| claude-cli | установленный и авторизованный Claude Code CLI |
GRAPHIFY_MAX_GRAPH_BYTES ), а параллелизм управляется GRAPHIFY_MAX_WORKERS .graphify вместо graphifyy. Имя на PyPI другое; проверяйте, что поставился пакет Graphify Labs.uv tool update-shell (или pipx ensurepath) и новый терминал.--platform и проверьте область установки.graphify extract . --code-only, только потом запросы.[mcp].graphify update ..--token-budget и --max-concurrency, а не размер графа.gh и авторизован ли он для этого репозитория.graphify extract . --code-only работает локально на tree-sitter. Ключ понадобится только для семантического прохода по документам, PDF и изображениям — там выбирается бэкенд: Claude, Gemini, OpenAI, DeepSeek, Kimi, Ollama, Bedrock, Azure или локальный Claude CLI.python3 --version: на 3.9 пакет просто не установится.graphify install --platform codex плюс codex mcp add graphify -- graphify-mcp /abs/path/graph.json. Для Cursor скилл регистрируется установщиком, а MCP прописывается записью mcpServers.graphify в конфиге с командой graphify-mcp и абсолютным путём к графу. Точный список поддерживаемых платформ уточняйте в официальной документации: он расширяется от релиза к релизу.graphify-out/graph.json. Технически его можно положить в репозиторий, и документация описывает сценарии обмена графом в команде, но помните: в графе есть метки и фрагменты исходного кода, поэтому обращаться с ним нужно как с самим кодом. Для локальной работы проще добавить graphify-out/ в .gitignore..graphifyignore для зависимостей, сгенерированного кода и артефактов сборки. Второй шаг — дисциплина запросов: query_graph с глубиной 2–3 и бюджетом 1 500–2 000 токенов обычно точнее, чем обход на глубину 6 с большим бюджетом.