doubled-graph

MCP-сервер для LLM-агентов, работающих с большими кодовыми базами.

Проблема: агент правит код не зная, кто вызывает функцию и какой у неё контракт — получаем регрессии и тихий дрейф. doubled-graph даёт агенту два графа одновременно:

• Computed graph — AST-граф реального кода (через CodeGraphContext): кто вызывает что, где определено.
• Declared graph — граф из артефактов GRACE 4 (.grace/): замысел, контракты, верификация.

Четыре MCP-инструмента:

Установка

Требования: Python 3.11+, Bun ≥ 1.3.14 или Node+tsx (движок @osovv/grace-cli 4.2.1), pipx.

doubled-graph — CLI-утилита. Рекомендуемый способ — pipx: он ставит её в изолированный venv и кладёт бинарь в PATH. Это также обходит PEP 668 (externally-managed-environment) на современных Homebrew/Debian/Ubuntu.

1. Установить pipx

После установки один раз добавьте pipx-папку в PATH и перезапустите терминал:

pipx ensurepath

2. Установить doubled-graph

pipx install doubled-graph

Уже работаете в своём venv или conda-окружении? Тогда подойдёт обычная установка: python3 -m pip install doubled-graph.

Первые шаги

1. Онбординг репозитория

cd your-project
doubled-graph setup

Одна команда:

• установит @osovv/grace-cli@4.2.1 через первый найденный JS-менеджер (bun → npm → yarn → pnpm); если Bun отсутствует — поставит tsx тем же менеджером и запустит grace под Node. Установленный движок 3.x будет обновлён: он умеет читать только docs/*.xml
• подготовит артефакты .grace: мигрирует GRACE 3 docs/*.xml (копирование, без удаления исходников) или создаст пустой скелет Grace 4, если артефактов нет вовсе
• скопирует prompts/ и methodology/ в репозиторий
• запишет 7 наших skills в native-формат для всех известных IDE одновременно (.claude/skills/, .cursor/rules/, .continue/rules/, .roo/rules/, .kilocode/rules/, .opencode/rules/ + opencode.json, .windsurfrules) — мы не знаем, каким клиентом вы пользуетесь
• зарегистрирует MCP-сервер в вашей IDE (Claude Code / Cursor / Continue)
• установит git post-commit хук для автообновления графа
• запустит первый полный analyze

Посмотреть план без реальных изменений:

doubled-graph setup --dry-run

Явно указать IDE:

doubled-graph setup --ide claude-code

2. Подключить MCP вручную (если нужно)

Рекомендуем doubled-graph setup — он сам сгенерирует .mcp.json с правильными значениями. Это важно: GUI-приложения (Claude Desktop, Cursor, Continue) на macOS стартуют без ~/.local/bin в PATH, и простая запись command: "doubled-graph" у них не работает.

Если нужно прописать руками — используйте абсолютный путь к Python, в который установлен doubled-graph:

# Узнать путь к нужному Python:
doubled-graph --version  # проверить, что бинарь работает
head -1 "$(which doubled-graph)"  # вывести shebang — это и есть нужный python

.mcp.json в корне репозитория:

{
  "mcpServers": {
    "doubled-graph": {
      "command": "/Users/you/.local/pipx/venvs/doubled-graph/bin/python",
      "args": ["-m", "doubled_graph", "serve"]
    }
  }
}

3. Инициализация

Введите в ваш ИИ первый промт. Остальные промты он сам подгрузит.

Сценарий 1. Новый проект — prompts/new-project/00-entry-prompt.md.

Сценарий 2. Миграция существующего — prompts/migrate-existing-project/00-entry-prompt.md.

Сценарий 3. Обновление версии методики (1.9.x → 2.0) — prompts/upgrade-methodology/00-entry-prompt.md.

4. Проверить, что всё встало

doubled-graph --version          # 2.0.1
doubled-graph status --repo .    # artifacts.project_kind = grace4, grace_engine.upgrade_required = false
doubled-graph lint --repo .      # summary.errors = 0
doubled-graph migrate check --repo .   # map_pending / placeholders — что осталось заполнить

Если project_kind = grace3 — артефакты ещё не перенесены: doubled-graph setup --repo .. Если upgrade_required = true — движок старее 4.x: npm install -g @osovv/grace-cli@4.2.1, затем setup повторно. Если lint вернул markup.module-map-missing — это содержательная работа, промпт prompts/upgrade-methodology/01-content-gaps.md.

Другие команды

# Диагностика миграции GRACE 3 -> GRACE 4 (ничего не пишет)
doubled-graph migrate check

# Миграция артефактов (legacy docs/*.xml остаются на месте)
doubled-graph migrate apply --dry-run
doubled-graph migrate apply

# Шлюз к движку: линт, модули, файлы, верификации
doubled-graph lint
doubled-graph module show M-AUTH
doubled-graph module health M-AUTH
doubled-graph file show src/auth.py
doubled-graph verify V-M-AUTH
doubled-graph status
doubled-graph --version

# Обновить граф вручную
doubled-graph analyze --mode auto

# 360° контекст символа
doubled-graph context validateUser

# Текущая фаза методологии (migration | post_migration)
doubled-graph phase get
doubled-graph phase set post_migration --reason "migration complete"

Удаление

pipx uninstall doubled-graph

(или python3 -m pip uninstall doubled-graph, если ставили в venv).

Это снимает сам CLI и Python-зависимости. Артефакты, которые doubled-graph setup создал в вашем репозитории, нужно удалить вручную:

• запись doubled-graph в .mcp.json (Claude Code) / .cursor/mcp.json / .continue/config.json
• скопированные prompts/ и methodology/ — если они больше не нужны
• skill-файлы для IDE: каталоги .claude/skills/doubled-graph-*/, .cursor/rules/doubled-graph-*.mdc, .continue/rules/doubled-graph-*.md, .roo/rules/doubled-graph-*.md, .kilocode/rules/doubled-graph-*.md, .opencode/rules/doubled-graph-*.md, блок между <!-- doubled-graph-skills:start --> / <!-- ... :end --> в .windsurfrules, и запись .opencode/rules/*.md в opencode.json instructions
• git-хук .git/hooks/post-commit (проверьте содержимое — там может быть ваша логика поверх нашей)
• локальный кеш графа: rm -rf .doubled-graph
• grace-cli (отдельный Bun/Node-пакет 4.x) — через тот менеджер, которым ставился: bun remove -g @osovv/grace-cli или npm uninstall -g @osovv/grace-cli

Обновление с 1.9.x (GRACE 3 → GRACE 4)

2.0 — ломающий релиз: движок @osovv/grace-cli 4.x валидирует только .grace и отказывается читать docs/*.xml. Клиенту нужны два шага:

pipx upgrade doubled-graph   # 1. обновить пакет
cd your-project
doubled-graph setup          # 2. обновить движок и подготовить .grace

Что делает setup: ставит движок 4.2.1, конвертирует docs/*.xml → .grace (модули M-*, зависимости, V-M-* с командами/сценариями/тест-файлами), создаёт недостающие обязательные документы, добавляет LINKS: M-* в MODULE_CONTRACT (без этого файл не привязан к модулю), приводит MAP_MODE в соответствие с ROLE. Legacy docs/ не изменяются и не удаляются.

Если миграцию не сделать:

Обновление версии методики — отдельный (третий) сценарий, он не требует проходить миграцию заново: prompts/upgrade-methodology/00-entry-prompt.md (готовый промт для ИИ: статус → setup → проверки → закрытие пробелов).

После обновления остаётся только содержательная работа — заполнить пустые V-<M> и MODULE_MAP по реальному коду и тестам. Готовый промпт: prompts/upgrade-methodology/01-content-gaps.md — скопируйте текст из блока «Промт» в ИИ-ассистента; он соберёт map_pending / placeholders, допишет карты модулей, заполнит верификации командами из существующих тестов и прогонит финальные проверки. Выдуманные команды запрещены (иначе «не проверено» станет «проверено»). При желании можно архивировать docs/ — отдельным решением.

Документация

• SPEC.md — архитектура, хранилище .doubled-graph/
• TOOLS.md — подробные схемы инструментов
• HOOKS.md — git и Claude Code хуки
• CHANGELOG.md — история изменений

Лицензия

MIT. Upstream-компоненты (CodeGraphContext, grace-marketplace) — MIT.