Интеграция Agent Client Protocol (ACP)

CodeGraph поддерживает Agent Client Protocol (ACP) для бесшовной интеграции с IDE: Zed, JetBrains, VS Code и другими ACP-совместимыми редакторами.

Обзор

ACP - стандартизированный протокол взаимодействия между редакторами кода и AI-агентами. CodeGraph реализует ACP для предоставления интеллектуального анализа кода прямо в вашей IDE.

Транспорты

CodeGraph поддерживает три механизма транспорта:

Транспорт Сценарий использования Endpoint
stdio Локальный subprocess (запускается IDE) команда codegraph-acp
HTTP Удалённый REST API POST /api/v1/acp/rpc
WebSocket Потоковая передача в реальном времени WS /api/v1/acp/ws

Поддерживаемые методы

Базовые методы (обязательные)

Метод Описание
initialize Согласование capabilities
authenticate JWT аутентификация
session/new Создание новой сессии
session/prompt Отправка сообщения
session/cancel Отмена операции

Опциональные методы

Метод Описание
session/load Возобновление существующей сессии
fs/read_text_file Чтение файла
fs/write_text_file Запись файла
terminal/create Создание терминала
terminal/output Получение вывода терминала
terminal/wait_for_exit Ожидание завершения команды
terminal/kill Завершение команды
terminal/release Освобождение ресурсов

Методы управления потоками диалога

Метод Описание
thread/start Создание нового потока диалога
thread/resume Возобновление существующего потока
thread/fork Ответвление потока в новую ветку
thread/list Список всех активных потоков
thread/archive Архивация завершённого потока
thread/compact Сжатие истории потока

Методы управления ходом выполнения

Метод Описание
turn/start Начало нового хода агента
turn/interrupt Прерывание текущего хода

Методы диагностики

Метод Описание
diagnostics/subscribe Подписка на события диагностики
diagnostics/unsubscribe Отмена подписки на диагностику

Методы интеграции с IDE

Метод Описание
hover/request Запрос информации о символе при наведении
item/fileChange/respondApproval Ответ на запрос подтверждения изменения файла

Возможности агента

CodeGraph объявляет следующие возможности:

{
  "loadSession": true,
  "setMode": false,
  "promptCapabilities": {
    "image": false,
    "audio": false,
    "embeddedContext": true
  },
  "mcp": {
    "stdio": true,
    "http": true,
    "sse": false
  },
  "authMethods": ["bearer"]
}

Жизненный цикл сессии

1. Инициализация
   Client -> initialize -> Agent
   Agent -> capabilities -> Client

2. Создание сессии
   Client -> session/new {cwd} -> Agent
   Agent -> {sessionId} -> Client

3. Отправка запроса
   Client -> session/prompt {sessionId, prompt} -> Agent
   Agent -> session/update (plan) -> Client
   Agent -> session/update (tool_call) -> Client
   Agent -> session/update (agent_message_chunk) -> Client
   Agent -> {stopReason} -> Client

4. Закрытие
   Client -> session/cancel -> Agent

API Endpoints

HTTP транспорт

POST /api/v1/acp/rpc

Единый JSON-RPC endpoint для всех вызовов.

Запрос:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": 1,
    "clientCapabilities": {},
    "clientInfo": {"name": "my-ide", "version": "1.0"}
  }
}

Ответ:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": 1,
    "agentCapabilities": {...},
    "agentInfo": {
      "name": "codegraph",
      "version": "0.1.0",
      "title": "CodeGraph AI-native Code Analysis Agent"
    }
  }
}

WebSocket транспорт

WS /api/v1/acp/ws?token=

Конечная точка потоковой передачи с обновлениями в реальном времени.

Проверка работоспособности

GET /api/v1/acp/health

Возвращает статус агента и доступные возможности.

GET /api/v1/acp/info

Возвращает метаданные агента.

Управление сессиями и статистика

GET /api/v1/acp/sessions

Возвращает активные ACP-сессии текущего пользователя. Требуется аутентификация.

DELETE /api/v1/acp/sessions/{session_id}

Удаляет ACP-сессию текущего пользователя. Требуется аутентификация. Возвращает 404, если сессия не найдена, и 403, если пользователь не является владельцем.

GET /api/v1/acp/stats

Возвращает статистику ACP: - статистику по сессиям, - количество WebSocket-подключений, - количество активных терминалов.

Требуется аутентификация.

Session Updates

Во время обработки запроса CodeGraph отправляет session/update notifications:

План выполнения

{
  "sessionUpdate": "plan",
  "plan": {
    "entries": [
      {"id": "1", "title": "Классификация интента", "status": "completed"},
      {"id": "2", "title": "Запрос к графу кода", "status": "in_progress"},
      {"id": "3", "title": "Генерация ответа", "status": "pending"}
    ]
  }
}

Вызов инструмента

{
  "sessionUpdate": "tool_call",
  "toolCallId": "tc_abc123",
  "title": "Анализ безопасности",
  "kind": "search",
  "status": "in_progress"
}

Фрагмент ответа

{
  "sessionUpdate": "agent_message_chunk",
  "chunk": "На основе анализа..."
}

Маппинг сценариев

CodeGraph отображает свои сценарии на следующие типы инструментов ACP:

Сценарий Тип инструмента
Анализ безопасности search
Проверка кода read
Анализ производительности search
Рефакторинг edit
Документация read
Анализ архитектуры think

Аутентификация

Для HTTP/WebSocket аутентификация необязательна, но рекомендуется:

Authorization: Bearer <jwt_token>

Аутентифицированные сессии имеют: - Персистентную историю диалогов - Пользовательские настройки - Квоты rate limit

Коды ошибок

Код Значение
-32700 Ошибка парсинга
-32600 Неверный запрос
-32601 Метод не найден
-32602 Неверные параметры
-32603 Внутренняя ошибка
-32002 Агент не инициализирован

Примеры

Инициализация и создание сессии

# Инициализация
curl -X POST http://localhost:8000/api/v1/acp/rpc \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": 1,
      "clientCapabilities": {},
      "clientInfo": {"name": "curl-client"}
    }
  }'

# Создание сессии
curl -X POST http://localhost:8000/api/v1/acp/rpc \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "session/new",
    "params": {"cwd": "/path/to/project"}
  }'

Отправка запроса

curl -X POST http://localhost:8000/api/v1/acp/rpc \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "session/prompt",
    "params": {
      "sessionId": "acp_xxx",
      "prompt": [
        {"type": "text", "text": "Какие основные точки входа?"}
      ]
    }
  }'

Поддержка MCP серверов

CodeGraph может подключаться к внешним MCP серверам:

{
  "method": "session/new",
  "params": {
    "cwd": "/project",
    "mcpServers": [
      {
        "id": "github",
        "name": "GitHub MCP",
        "transport": "stdio",
        "command": "github-mcp-server"
      }
    ]
  }
}

MCP-сервер CodeGraph

CodeGraph также предоставляет собственный MCP-сервер, позволяющий ИИ-ассистентам (Claude Code, Open Code, Codex, Cursor, Windsurf и др.) напрямую запрашивать граф свойств кода (CPG).

Запуск сервера

# Запуск MCP-сервера через stdio транспорт
python -m src.mcp

# С указанием конкретной базы данных
python -m src.mcp --db data/projects/postgres.duckdb

# Подробное логирование
python -m src.mcp --verbose

Доступные инструменты (65 инструментов)

MCP-сервер предоставляет 65 встроенных инструментов для анализа кода, навигации, безопасности, соответствия стандартам, структурных шаблонов, корпоративных интеграций и др.

Полный справочник инструментов с параметрами и описаниями см. в Справочник MCP-инструментов.

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

Настройки MCP-сервера в config.yaml:

mcp:
  enabled: true
  transport: stdio
  max_query_rows: 1000
  dynamic_tools_path: .codegraph/tools.yaml

Динамические инструменты

Пользовательские SQL-инструменты определяются в .codegraph/tools.yaml:

tools:
  - name: find_large_methods
    description: "Поиск методов с высокой цикломатической сложностью"
    sql: "SELECT name, Filename, CyclomaticComplexity FROM nodes_method WHERE CyclomaticComplexity > ? ORDER BY CyclomaticComplexity DESC LIMIT ?"
    parameters:
      - name: threshold
        type: integer
        description: "Минимальный порог сложности"
        default: 10
      - name: limit
        type: integer
        description: "Максимум результатов"
        default: 20

В динамических инструментах допускаются только SELECT-запросы. DDL/DML-выражения отклоняются при загрузке.

Интеграция с Claude Code

Добавьте в конфигурацию MCP Claude Code (.claude/mcp.json):

{
  "mcpServers": {
    "codegraph": {
      "command": "python",
      "args": ["-m", "src.mcp", "--db", "data/projects/postgres.duckdb"],
      "cwd": "/path/to/codegraph"
    }
  }
}

См. также