Интеграция CodeGraph с OpenCode

Как подключить CodeGraph к OpenCode через MCP-инструменты, плагин opencode-codegraph, пользовательские команды, отдельного агента и LSP-сервер.

Содержание¶

• Обзор
• Установка
• Единый скрипт запуска
• Пошагово для этого репозитория
• Функции
• Плагин
• Пользовательские команды
• Пользовательский агент
• LSP-сервер
• Конфигурация
• Архитектура
• Устранение неполадок

Обзор¶

CodeGraph можно встроить в OpenCode на пяти уровнях. Их можно включать по отдельности или комбинировать. Основной интерактивный сценарий сейчас строится вокруг плагина OpenCode и LSP-сервера, а MCP остаётся доступным для прямых запросов и автоматизации.

Автоматические и ручные механизмы¶

Автоматические хуки плагина не блокируют рабочий поток и срабатывают по возможности. Если нужен строгий контроль актуальности в CI или в безголовом режиме, используйте явный codegraph_watch update или команду /update.

Установка¶

Минимальная настройка (только MCP)¶

Создайте opencode.json в корне проекта:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "codegraph": {
      "type": "local",
      "command": ["python", "-m", "src.mcp", "--transport", "stdio", "--db", "data/projects/codegraph.duckdb"],
      "environment": {
        "CODEGRAPH_PROJECT": ""
      }
    }
  },
  "plugin": ["opencode-codegraph"],
  "instructions": [".codegraph/AGENTS.md", ".codegraph/SCENARIO_PLAYBOOK.md"]
}

Полная настройка (MCP + LSP)¶

Добавьте LSP-сервер для диагностики в реальном времени:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "codegraph": {
      "type": "local",
      "command": ["python", "-m", "src.mcp", "--transport", "stdio", "--db", "data/projects/codegraph.duckdb"],
      "environment": {
        "CODEGRAPH_PROJECT": ""
      }
    }
  },
  "lsp": {
    "codegraph": {
      "command": ["python", "-m", "codegraph_lsp", "--db", "data/projects/codegraph.duckdb"],
      "extensions": [".py", ".go", ".js", ".ts", ".java", ".c", ".cpp", ".cs", ".kt", ".php", ".rb"]
    }
  },
  "plugin": ["opencode-codegraph"],
  "instructions": [".codegraph/AGENTS.md", ".codegraph/SCENARIO_PLAYBOOK.md"]
}

Примечание: Плагин opencode-codegraph является основным слоем интеграции OpenCode. Он обеспечивает автоматическое обогащение контекста, явные CodeGraph/OpenViking session tools, сценарные команды, review/explain helpers и отображение shared или handed-off explicit sessions. Требует запущенный API CodeGraph (uvicorn src.api.main:app --port 8000). Если API недоступен, плагин деградирует корректно — MCP-инструменты продолжают работать через stdio.

Примечание: Параметр --db обязателен. Он задаёт целевую CPG-базу, которой владеет GoCPG. В этом репозитории используется data/projects/codegraph.duckdb.

Предварительные требования¶

• CodeGraph установлен (pip install -e . в репозитории codegraph)
• CPG-база данных создана (gocpg parse --input=. --output=project.duckdb)
• GoCPG gRPC server запущен и имеет доступ к целевой CPG-базе
• OpenCode 1.2.0+ установлен (npm install -g opencode-ai)

Единый скрипт запуска¶

Рекомендуемая команда запуска (MCP + плагин + LSP + сценарный контекст):

python scripts/run_opencode_codegraph.py --model openai/gpt-5.3-codex

Что гарантирует скрипт запуска перед стартом OpenCode:

1. В opencode.json присутствуют mcp.codegraph, lsp.codegraph, плагин opencode-codegraph и инструкции.
2. Зависимости плагина в .opencode/ установлены (выполняет npm install только при необходимости).
3. API CodeGraph автоматически поднимается, если недоступен (нужно для инструментов плагина и сценарных flow).
4. OpenCode запускается с --agent codegraph по умолчанию.

Пример headless запуска:

python scripts/run_opencode_codegraph.py --run "Use codegraph_project_context and summarize top risks"

Передача дополнительных флагов OpenCode после --:

python scripts/run_opencode_codegraph.py --model openai/gpt-5.3-codex -- --print-logs

Проверка настройки¶

opencode mcp list              # Должно показать: ✓ codegraph connected
opencode debug config          # Проверка итоговой конфигурации
opencode agent list            # Должно показать: codegraph agent
python -m src.mcp --help       # Проверка доступности MCP entrypoint
python -m codegraph_lsp --help # Проверка доступности LSP entrypoint

Пошагово для этого репозитория¶

Фактически примененные шаги в этом репозитории:

1. Обновлен opencode.json: добавлены mcp.codegraph и lsp.codegraph.
2. Для LSP задан путь БД data/projects/codegraph.duckdb как идентификатор CPG, которой владеет GoCPG.
3. LSP оставлен в режиме stdio (по умолчанию), чтобы OpenCode сам управлял жизненным циклом процесса.
4. Подключены plugin: ["opencode-codegraph"] и инструкции: - .codegraph/AGENTS.md (MCP-инструменты + CPG reference) - .codegraph/SCENARIO_PLAYBOOK.md (маршрутизация 21 сценария)
5. Выполнена проверка конфигурации и доступности команд:

python -m json.tool opencode.json          # JSON валиден
opencode mcp list                          # codegraph server connected
opencode debug config                      # видны mcp/lsp/plugin/instructions
python -m src.mcp --help                   # MCP сервер доступен
python -m codegraph_lsp --help             # LSP сервер доступен
gocpg stats --db data/projects/codegraph.duckdb

Stdio и TCP¶

• Для OpenCode рекомендуется stdio (не запускать отдельный долгоживущий LSP-процесс вручную).
• TCP режим оставляйте для отладки:

python -m codegraph_lsp --db data/projects/codegraph.duckdb --transport tcp --host 127.0.0.1 --port 2087

Модель владения¶

• GoCPG — единственный runtime-процесс, который открывает и изменяет CPG DuckDB.
• Интеграции OpenCode MCP, плагин и LSP работают как клиенты только для чтения поверх API GoCPG.
• --db в конфигурации OpenCode и LSP — это идентификатор целевой базы, а не разрешение открывать DuckDB напрямую.

Функции¶

1. MCP-инструменты (149 инструментов)¶

Все 149 MCP-инструментов CodeGraph доступны в чате OpenCode. Основные группы:

Полный справочник инструментов находится в .codegraph/AGENTS.md (автоматически загружается через instructions).

2. Файлы инструкций¶

В каждый диалог через instructions загружаются два файла:

• .codegraph/AGENTS.md содержит:
• Полный список доступных MCP-инструментов с описаниями
• Справочник таблиц CPG (nodes_method, edges_call и др.)
• Рекомендации по использованию (когда какой инструмент применять)
• .codegraph/SCENARIO_PLAYBOOK.md содержит:
• Маршрутизацию по всем 21 сценариям CodeGraph
• Связку intent -> scenario (когда использовать S02 vs S09 vs S18)
• Пояснение, что structural pattern search — это tool/CLI feature, а не numbered scenario

3. Актуальность и инкрементальные обновления¶

Поддерживаемый путь актуализации для пользователей OpenCode теперь строится вокруг плагина и команд:

1. плагин может выполнить best-effort refresh после локального git commit;
2. /update запускает явную проверку актуальности и инкрементальное обновление через codegraph_watch;
3. /status и /next показывают текущее состояние workflow и рекомендуемое следующее действие;
4. LSP-диагностика отражает обновлённое состояние CPG в редакторе.

Для headless OpenCode /update остаётся рекомендуемой точкой контроля: команда возвращает структурированные поля актуальности (cpg_commit, head_commit, commits_behind, commits_behind_strict, is_fresh, is_fresh_strict, has_relevant_changes_since_cpg, freshness_reason, needs_update) и поля диагностики обновления (failure_kind, auto_unlock_attempted, auto_unlock_killed_pids, auto_unlock_errors, next_step, next_command).

Плагин¶

Плагин opencode-codegraph (npm, v0.1.37) является основным слоем интеграции OpenCode. Он добавляет автоматическое обогащение, agent-native операции с контекстом, сценарную поддержку команд, continuity и lifecycle-aware guidance поверх MCP-инструментов. Исходный код: каталог opencode-codegraph/.

Функции плагина¶

Автоматизация плагина рассчитана на разговорный интерактивный сценарий и работает по возможности. Поддерживаемый workflow для разработчика теперь строится вокруг самого плагина OpenCode, сценарных команд и LSP-сервера.

Текущая модель OpenViking-сессий со стороны плагина:

• для сценарных команд по умолчанию используется явное открытие или переподключение сессии
• /continue, /status и /review стараются продолжать тот же evidence chain, если recoverable session уже существует
• read_only shared sessions можно видеть и переоткрывать для review или testing, но нельзя использовать для записи
• ownership transfer управляется в CodeGraph как authoritative contract; плагин отражает текущий access mode и follow-up wording
• skill guidance учитывает lifecycle: по умолчанию только current, needs_review только по явному opt-in, deprecated исключается

Инструменты плагина¶

Плагин добавляет явные CodeGraph/OpenViking-инструменты, реализованные на TypeScript поверх MCP:

codegraph_review сначала использует стандартный процесс ревью. Если результат пустой, API автоматически переключается на детерминированный резервный сценарий на базе CPG: изменённые файлы из diff, затронутые методы и вызывающие, а также найденные паттерны безопасности по файлам.

Требования¶

Плагин требует запущенный REST API CodeGraph (uvicorn src.api.main:app --port 8000). Если API недоступен, плагин деградирует корректно — plugin-side automation пропускается, MCP-инструменты продолжают работать через stdio.

Плагин рассчитан на @opencode-ai/plugin >=1.2.0.

Пользовательские команды¶

Восемь команд доступны через /command в TUI OpenCode:

Для headless CLI используйте opencode run --command <name> [args...] (а не буквальное сообщение /name).

Команды определены в .opencode/commands/ как файлы markdown с YAML-заголовком (frontmatter).

Пользовательский агент¶

Переключитесь на агент CodeGraph для анализа на основе CPG:

@codegraph

Агент codegraph (использует вашу модель по умолчанию): - Всегда проверяет CPG перед изменением кода - Проверяет вызывающие функции перед рефакторингом (codegraph_find_callers) - Запускает анализ распространения данных перед проверкой безопасности (codegraph_taint_analysis) - Расставляет приоритеты по метрикам сложности и влияния (codegraph_hotspots)

Определён в .opencode/agents/codegraph.md.

LSP-сервер¶

LSP-сервер CodeGraph обеспечивает диагностику на основе CPG в реальном времени:

• Диагностика: Результаты безопасности, мёртвый код, предупреждения о сложности
• Подсказки при наведении: Метрики методов (сложность, fan_in, fan_out)
• CodeLens: Количество вызывающих/вызываемых функций, пути распространения данных
• Действия кода: Автоисправление для результатов анализа шаблонов

Конвейер диагностик мёртвого кода отфильтрован от синтетических имён (например, <module> и артефактов metaclass adapter) и дедуплицируется по идентичности метода, чтобы headless-диагностика оставалась практичной для итеративного ревью.

Headless цикл plan/act/review¶

# Plan: сначала проверка статуса, затем обновление при необходимости
opencode run --command status
opencode run --command update
opencode debug lsp diagnostics src/dogfooding/cpg_freshness.py

# Act: изменения в коде и запуск фокусных тестов
pytest tests/unit/dogfooding/test_cpg_freshness.py tests/mcp/test_ci_ops.py -v

# Review: повторная проверка диагностик и актуальности
opencode debug lsp diagnostics src/mcp/tools/ci_ops.py
opencode run --command update

Используйте этот цикл, когда нужно подтвердить, что данные CodeGraph остаются релевантными и применимыми между итерациями: исправление, повторная диагностика, повторная проверка актуальности CPG.

Параметры¶

python -m codegraph_lsp --db project.duckdb [--complexity-threshold 10] [--transport stdio] [--log-level info]

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

Переменные окружения¶

Структура файлов¶

.opencode/
  commands/
    review.md     # Команда /review
    audit.md      # Команда /audit
    explain.md    # Команда /explain
    onboard.md    # Команда /onboard
    update.md     # Команда /update
    status.md     # Команда /status
  agents/
    codegraph.md  # Агент codegraph

.codegraph/
  AGENTS.md       # Справочник MCP-инструментов (загружается через opencode.json instructions)
  SCENARIO_PLAYBOOK.md  # Маршрутизация сценариев для контекста модели

opencode.json           # Конфигурация MCP + плагин + инструкции
opencode-codegraph/     # Исходный код плагина (npm: opencode-codegraph@0.1.37)

Архитектура¶

OpenCode
  |
  +-- Плагин (opencode-codegraph, npm)
  |     |-- chat.message                               --> CodeGraph REST API --> CPG-контекст
  |     |-- experimental.chat.system.transform         --> CodeGraph REST API --> сводка проекта
  |     |-- tool.execute.after                         --> CodeGraph REST API --> инкрементальное обновление
  |     |-- permission.ask                             --> авторазрешение codegraph_*
  |     +-- инструменты                                --> CodeGraph REST API --> review/explain
  |
  +-- MCP-сервер (src.mcp, stdio)
  |     +-- 149 инструментов      --> CPG, контекст, taint, шаблоны, compose
  |
  +-- Пользовательские команды (.opencode/commands/)
  |     +-- /review, /audit      --> Шаблоны промптов с MCP-инструментами
  |     +-- /explain, /onboard   --> Шаблоны промптов с MCP-инструментами
  |     +-- /update              --> Проверка актуальности + инкрементальный CPG update
  |     +-- /status              --> Единый статус актуальности и review trace
  |
  +-- Пользовательский агент (.opencode/agents/codegraph.md)
  |     +-- CPG-first рабочий процесс --> Всегда проверяет вызывающих перед рефакторингом
  |
  +-- Инструкции (.codegraph/AGENTS.md)
  |     +-- Справочник инструментов --> Автоматически загружается в каждый диалог
  |
  +-- LSP-сервер (codegraph_lsp, опционально)
        +-- диагностика           --> безопасность, мёртвый код, сложность
        +-- подсказки             --> метрики методов
        +-- codelens              --> вызывающие/вызываемые/taint
        +-- действия кода         --> автоисправление

Устранение неполадок¶

MCP-сервер не подключается¶

opencode mcp list                    # Проверка статуса подключения
opencode debug config                # Проверка итоговой конфигурации MCP
python -m src.mcp --transport stdio  # Тест MCP-сервера напрямую

• Убедитесь, что python доступен в PATH и виртуальное окружение codegraph активировано
• Проверьте, что CPG-база данных существует (data/projects/*.duckdb)

Команды недоступны¶

• Убедитесь, что каталог .opencode/commands/ существует в корне проекта
• Проверьте, что файлы содержат корректный YAML-заголовок (начинается с ---)
• Перезапустите OpenCode после добавления новых команд
• Тест: opencode debug skill должен показать команды

Headless-использование команд¶

• В TUI используйте /review, /audit и т.д.
• В headless-режиме используйте opencode run --command review (или audit, explain, onboard, update)
• Не передавайте /review как обычное сообщение в opencode run: оно будет воспринято как текст, а не как команда

Агент не отображается¶

• Убедитесь, что файл .opencode/agents/codegraph.md существует
• Проверьте, что YAML-заголовок содержит поле description
• Тест: opencode agent list должен показать codegraph
• Тест: opencode debug agent codegraph для полной информации

LSP не работает¶

• Убедитесь, что --db указывает на существующий файл DuckDB
• Проверьте, что модуль codegraph_lsp импортируется: python -m codegraph_lsp --help
• Убедитесь, что в opencode debug config присутствует lsp.codegraph.command с ожидаемым путем к БД
• Для режима stdio отсутствие отдельного TCP-listener — это ожидаемое поведение
• Тест: opencode debug lsp diagnostics src/api/main.py

Нет данных CPG в результатах инструментов¶

• Проверьте, что CPG-база данных создана: python -m src.cli query "SELECT count(*) FROM nodes_method"
• Проверьте активный проект: opencode run "Use codegraph_project_context"
• Установите проект: CODEGRAPH_PROJECT=myproject в opencode.json → environment