code-analyze-mcp

[!NOTE] Нативные инструменты агентов (regex-поиск, сопоставление путей, чтение файлов) хорошо справляются с точечными запросами. aptu-coder выполняет механическую, не связанную с ИИ работу: построение структуры каталогов, извлечение символов и трассировку графов вызовов. Передача этой работы выделенному инструменту снижает расход токенов и ускоряет разработку с более высокой точностью.

Бенчмарки

Задача миграции аутентификации в Claude Code на дереве исходников Django (Python). Полная методология.

Задача аудита интеграции AeroDyn в Claude Code на дереве исходников OpenFAST (Fortran). Полная методология.

Related MCP server: CodeGraphMCPServer

Обзор

aptu-coder — это сервер Model Context Protocol, который предоставляет ИИ-агентам точный структурный контекст о кодовой базе: деревья каталогов, определения символов и графы вызовов — без чтения исходных файлов. Поддерживает 18 языков (см. Поддерживаемые языки) и интегрируется с любым MCP-совместимым оркестратором.

Поддерживаемые языки

Установка

Homebrew (macOS и Linux)

brew install clouatre-labs/tap/aptu-coder

Обновление: brew upgrade aptu-coder

cargo-binstall (Rust не требуется)

cargo binstall aptu-coder

cargo install (требуется инструментарий Rust)

cargo install aptu-coder

Быстрый старт

Сборка из исходников

cargo build --release

Бинарный файл находится по пути target/release/aptu-coder.

Настройка MCP-клиента

Доступны два транспорта. Streamable HTTP рекомендуется при использовании оркестраторов, порождающих делегатов (например, goose coder): один серверный процесс используется совместно оркестратором и всеми агентами, что устраняет расхождение расширений, возникающее, когда каждый stdio-подпроцесс получает собственный изолированный экземпляр.

Streamable HTTP (рекомендуется для многокомпонентных конфигураций)

С Homebrew одна команда запускает сервер при входе в систему и поддерживает его работу:

brew services start aptu-coder

Формула Homebrew запускает сервер на порту 49200 по умолчанию. Затем добавьте расширение один раз в ~/.config/goose/config.yaml:

extensions:
  aptu-coder:
    type: streamable_http
    uri: http://127.0.0.1:49200/mcp
    name: aptu-coder
    timeout: 300

Или для Claude Code:

claude mcp add --transport http aptu-coder http://127.0.0.1:49200/mcp

Чтобы использовать другой порт, задайте APTU_CODER_PORT перед перезапуском:

APTU_CODER_PORT=4000 brew services restart aptu-coder

Чтобы запустить напрямую без brew services:

aptu-coder --port 49200
# or equivalently
APTU_CODER_PORT=49200 aptu-coder

stdio (для одного клиента)

Подходит, когда только одному процессу нужен сервер. Клиент владеет жизненным циклом процесса и запускает его автоматически:

claude mcp add --transport stdio aptu-coder -- aptu-coder

Или добавьте вручную в .mcp.json в корне вашего проекта (общий для команды через систему контроля версий):

{
  "mcpServers": {
    "aptu-coder": {
      "command": "aptu-coder",
      "args": []
    }
  }
}

Инструменты

Все необязательные параметры могут быть опущены. Общие необязательные параметры для analyze_directory, analyze_file и analyze_symbol:

Параметры инструментов, ограничения и примеры доступны через инспектор инструментов вашего MCP-клиента или ответ tools/list.

MCP-ресурсы

Функция графа знаний предоставляет шаблоны MCP-ресурсов для навигации по структурному графу, построенному при вызовах analyze_symbol. Ресурсы адресуются через URI; используйте resources/templates/list для обнаружения доступных шаблонов.

Пагинация: Результаты разбиты на страницы; передайте непрозрачное значение cursor из предыдущего ответа, чтобы получить следующую страницу.

Параметр глубины: Шаблон blast-radius принимает необязательный параметр запроса depth (целое число в диапазоне 1–5, по умолчанию 3).

Холодный кэш: Сначала вызовите analyze_symbol для каталога, чтобы построить граф. Ресурсы возвращают информационное сообщение, пока граф недоступен.

Управление выводом

Для больших кодовых баз предусмотрено несколько механизмов, предотвращающих переполнение контекста.

Пагинация

analyze_file и analyze_symbol добавляют строку NEXT_CURSOR:, когда вывод усечён. Передайте токен обратно как cursor, чтобы получить следующую страницу. summary=true и cursor взаимоисключающие; передача обоих возвращает ошибку.

# Response ends with:
NEXT_CURSOR: eyJvZmZzZXQiOjUwfQ==

# Fetch next page:
analyze_symbol path: /my/project symbol: my_function cursor: eyJvZmZzZXQiOjUwfQ==

Ограничения вывода exec_command

exec_command применяет три независимых байтовых ограничения, чтобы предотвратить переполнение контекста большими выводами команд:

Ограничение stdout в 30k основано на данных: анализ 27,981 наблюдаемых вызовов exec_command показывает, что только 0,33% превышают этот лимит. Когда срабатывает любое ограничение, в ответе устанавливается output_truncated: true и это фиксируется в метриках JSONL.

drain_timeout_secs управляет тем, как долго сервер ждёт после завершения дочернего процесса, пока фоновый подпроцесс всё ещё удерживает канал открытым. По умолчанию — 500 мс (0 или не указано). Отрицательные значения возвращают INVALID_PARAMS. Если окно ожидания истекает до закрытия канала, устанавливается output_truncated: true.

exec_command: фильтры вывода

Встроенная таблица фильтров подавляет пофайловый шум от болтливых CLI-инструментов до того, как вывод попадёт в модель. Фильтры применяются к stdout, stderr и чередующемуся выводу только при успехе; при сбое всегда сохраняется необработанный вывод.

Локальные для проекта правила можно добавить в .aptu/filters.toml. Ошибки парсинга и нераспознанные значения schema_version (версия != 1) приводят к откату к встроенной таблице с предупреждением в журнале; сбоя не происходит. Когда фильтр срабатывает, filter_applied в structuredContent указывает, какое правило совпало.

Неинтерактивные пайплайны

В однопроходных сессиях субагентов кэши подсказок записываются, но никогда не переиспользуются. Бенчмарки показали, что ответы MCP записывают в кэш примерно в 2 раза больше, чем нативные рабочие процессы, что добавляет затраты без выигрыша в качестве. Установите DISABLE_PROMPT_CACHING=1 (или DISABLE_PROMPT_CACHING_HAIKU=1 для пайплайнов, специфичных для Haiku), чтобы избежать этих накладных расходов.

Собственные инструкции сервера описывают рекомендуемый 4-шаговый рабочий процесс для неизвестных репозиториев: осмотрите корень репозитория с помощью analyze_directory с max_depth=2, углубитесь в исходный пакет, выполните analyze_module на ключевых файлах для получения индекса функций/импортов (или analyze_file, когда нужны сигнатуры и типы), затем используйте analyze_symbol для трассировки графов вызовов. MCP-клиенты, которые отображают инструкции сервера, автоматически представят этот рабочий процесс агенту.

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

Кэш и среда выполнения

Наблюдаемость

Схему JSONL, конфигурацию OTel и политику атрибутов спанов см. в:

• OBSERVABILITY.md (repository root)

• docs/METRICS.md

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

• AGENTS.md — Справочник для контрибьюторов: структура проекта, команды, подводные камни rmcp, ограничения параметров инструментов

• ARCHITECTURE.md — Цели дизайна, карта модулей, поток данных, система обработчиков языков, стратегия кэширования

• CONTRIBUTING.md — Процесс разработки, соглашения о коммитах, чек-лист PR

• DESIGN-GUIDE.md — Дизайн-решения, обоснование и руководство по воспроизведению для создания высокопроизводительных MCP-серверов

• MCP Best Practices — Лучшие практики для агентских циклов, паттернов оркестрации, дизайна MCP-инструментов, управления памятью и контроля безопасности

• METRICS.md — Схема метрик, формат JSONL и политика хранения

• ROADMAP.md — История разработки и будущие направления

• SECURITY.md — Политика безопасности и отчёт об уязвимостях

Лицензия

Apache-2.0. Подробности см. в LICENSE.