Перейти к содержимому
AggregaAggrega
Выберите язык: Русский
Эта страница переведена машинным способом. Читать оригинал на английском.

Подключение MCP-сервера

MCP-сервер Aggrega — это команда aggrega mcp, и единственное предварительное требование для него — исполняемый файл aggrega: раздел Установка исполняемого файла устанавливает его одной командой. Сервер запускается как подпроцесс вашего клиента через stdio, читает схемы из исполняемого файла, а страницы документации — из копии, которую однократно загружает в кеш вашей машины, и не требует отдельной службы, порта или учётной записи. Если сервер для вас уже запускает кто-то другой, вам не нужны ни исполняемый файл, ни всё описанное здесь: см. Сервер, доступный по HTTPS.

Клиенты, которые добавляют его одной командой

Ассистент с установленным плагином Aggrega уже подключён. Установка плагина добавляет навык Aggrega и сервер за один шаг — в Claude Code, Codex, GitHub Copilot, Gemini CLI, Antigravity, Cursor, Kiro и OpenClaw, как описано в разделе Установка плагина, — поэтому для подключения этого ассистента ничего другого с этой страницы не нужно. Плагин запускает aggrega mcp с помощью aggrega, найденного в PATH, с которым был запущен ассистент, поэтому двоичный файл должен быть установлен именно там. Некоторые ассистенты запускают сервер плагина в собственной папке плагина, а не в вашем проекте, — так делает Codex, — и тогда ассистент указывает папку вашего проекта как workspace_root в вызовах, которые его принимают; навык велит ему проверить, в каком рабочем пространстве отвечает сервер.

Без плагина добавьте сервер собственной командой клиента. В Claude Code:

Terminal window
claude mcp add --transport stdio aggrega -- aggrega mcp

В Codex:

Terminal window
codex mcp add aggrega -- aggrega mcp

В Gemini CLI:

Terminal window
gemini mcp add aggrega aggrega mcp

Все остальные клиенты

Большинство клиентов с поддержкой MCP запускают сервер одинаково: они выполняют команду aggrega с единственным аргументом mcp и обмениваются данными по протоколу через стандартный ввод и вывод процесса. Различается лишь то, где каждый клиент хранит свой список серверов и как он называет записи в нём. Общий вид:

{
"mcpServers": {
"aggrega": {
"command": "aggrega",
"args": ["mcp"]
}
}
}

После перезапуска и подключения клиента становятся доступны промпты, ресурсы и инструменты Aggrega для разработки. Их описывает раздел Что ваш ассистент может делать с Aggrega, что с ними делать, показывает раздел Написание файлов Aggrega, а саму команду описывает справка по aggrega mcp.

Ничто в записи не выбирает ревизию протокола. Aggrega поддерживает и 2026-07-28, и 2025-06-18 — как через стандартный ввод и вывод, так и по HTTPS, поэтому клиент любой из них подключается и получает те же промпты, ресурсы и инструменты. Какую ревизию запрашивает клиент, определяется при обмене данными, а не в вашей конфигурации.

Ассистент, умеющий выполнять команды, может сделать всё это сам — установить исполняемый файл, добавить навык Aggrega и подключиться к серверу — по одному промпту, который вы ему вставите: см. Настройка Aggrega с помощью ИИ-ассистента.

Где каждый клиент хранит список серверов

КлиентГде находится списокКак называется запись
Claude Codeclaude mcp add или файл .mcp.json в проектеmcpServers
Claude Desktopнастройки расширений — для локального сервера; настройки коннекторов — для сервера, доступного по HTTPSсм. Claude Desktop
Cursor.cursor/mcp.json для одного рабочего пространства или пользовательский mcp.json для всех рабочих пространствmcpServers
Gemini CLIgemini mcp add или ~/.gemini/settings.json для всех проектов и .gemini/settings.json для одногоmcpServers
Codex CLIcodex mcp add или ~/.codex/config.toml для всех проектов и .codex/config.toml для одного доверенного проектатаблица [mcp_servers.aggrega] — см. Codex CLI
ZedSettings → AI → MCP Servers, откуда запись попадает в файл настроек Zedcontext_servers — см. Zed
Visual Studio Codemcp.json в профиле пользователя или .vscode/mcp.json для одного рабочего пространстваservers — см. Visual Studio Code
GitHub Copilot CLIcopilot mcp add или файл mcp-config.json, который он хранит в домашнем каталогеmcpServers
Antigravityфайл mcp_config.json, доступный из настроекmcpServers
Windsurfфайл mcp_config.json, доступный из настроекmcpServers
Clineнастройки MCP, хранящиеся в файле cline_mcp_settings.jsonmcpServers

Все клиенты из этой таблицы, кроме четырёх, которым ниже посвящены отдельные разделы, принимают запись точно в том виде, как показано выше, по пути из своей строки. Клиент, не указанный в таблице, подключается так же, если читает список серверов одного из этих видов.

Замечание о PATH

Клиенты, запущенные из графической среды, не всегда наследуют тот же PATH, что и ваш терминал. Если клиент сообщает, что не может найти команду aggrega, замените "command": "aggrega" абсолютным путём к исполняемому файлу (например, "command": "/home/you/.local/bin/aggrega" — место установки в Linux для пользователя с именем you). Всё остальное остаётся без изменений.

Visual Studio Code

Visual Studio Code хранит свои серверы в servers, а не в mcpServers, и в каждой записи указывается используемый транспорт:

{
"servers": {
"aggrega": {
"type": "stdio",
"command": "aggrega",
"args": ["mcp"]
}
}
}

Codex CLI

Codex хранит свои серверы в TOML, а не в JSON — в ~/.codex/config.toml для всех проектов или в .codex/config.toml для одного проекта, которому Codex доверяет, — каждый в виде таблицы, названной по имени сервера:

[mcp_servers.aggrega]
command = "aggrega"
args = ["mcp"]

codex mcp add aggrega -- aggrega mcp, команда, приведённая выше, записывает ту же таблицу за вас. Расширение Codex для IDE и настольное приложение ChatGPT читают тот же файл, поэтому одна запись служит всем трём.

Zed

Zed хранит свои серверы в разделе context_servers своего файла настроек. Добавьте сервер через Settings → AI → MCP Servers — Add Server, затем Add Local Server, — что запишет запись в этот файл, или выполните zed: open settings file из палитры команд и добавьте запись сами:

{
"context_servers": {
"aggrega": {
"command": "aggrega",
"args": ["mcp"]
}
}
}

Zed поддерживает инструменты и промпты протокола, поэтому его агент получает доступ к инструментам Aggrega и промптам для авторинга, но не к ресурсам, которые сервер тоже предоставляет.

Claude Desktop

Claude Desktop устанавливает локальный сервер из пакета расширения — сервера вместе с описывающим его манифестом, собранных в один устанавливаемый файл и добавляемых из настроек расширений, — а не из записи в файле конфигурации. Каждый выпуск Aggrega содержит такой пакет, aggrega-<version>.mcpb, рядом с готовыми исполняемыми файлами.

Пакет Aggrega не содержит собственной программы. Он запускает исполняемый файл aggrega, уже установленный на вашем компьютере, с единственным аргументом mcp и обменивается данными по протоколу через стандартные ввод и вывод этого процесса — это тот же сервер, который запускает каждая из приведённых выше записей. Если вы не выберете другой исполняемый файл, он передаёт Claude Desktop имя команды aggrega, как и каждая из приведённых выше записей, поэтому приложение ищет aggrega в PATH, с которым оно было запущено; и он передаёт этому серверу выбранное вами рабочее пространство. Чтобы добавить его:

  1. Установите исполняемый файл aggrega, как описано в разделе Установка исполняемого файла. И команда установки, и описанные там ручные шаги помещают его в вашу собственную папку — в Windows это %LOCALAPPDATA%\Programs\aggrega, а не системная папка, такая как C:\Windows\System32, — чтобы его можно было заменить без прав администратора.
  2. Установите aggrega-<version>.mcpb из настроек расширений Claude Desktop.
  3. Задайте настройки пакета; ни одна из них не обязательна. Path to the aggrega executable — программа, которую запускает пакет; по умолчанию это имя команды aggrega, которое приложение ищет в PATH, с которым оно было запущено. Папка, добавленная в ваш PATH во время работы приложения, — как добавляют свои папки установщик Windows и команда установки в Windows, — становится доступна приложению только после того, как оно будет закрыто и запущено снова, как в шаге 4, а приложение, запущенное из графической среды, может не видеть тот же PATH, что и ваш терминал (см. Примечание о PATH). Оставьте значение по умолчанию, если aggrega в этом PATH — нужный вам исполняемый файл. Вместо этого укажите в поле полный путь к исполняемому файлу, если нужного вам файла нет в этом PATH или это другой aggrega, чем первый найденный там: в macOS и Linux для места установки — aggrega в .local/bin в вашей домашней папке, например /Users/you/.local/bin/aggrega; в Windows — полный путь, оканчивающийся на aggrega.exe, например C:\Users\you\AppData\Local\Programs\aggrega\aggrega.exe. Чтобы вернуться к значению по умолчанию, укажите в поле aggrega, а не очищайте его. Если aggrega вообще не установлен, установите его, как описано в шаге 1. Workspace folder — папка рабочего пространства Aggrega, в котором работает ассистент: папка, содержащая файл .aggrega-config.yaml вашего проекта. Эту настройку задайте: она пуста, пока вы не выберете папку, а пока она пуста, пакет передаёт серверу пустую переменную AGGREGA_WORKSPACE_ROOT, поэтому сервер отвечает на каждый запрос ассистента в рабочем пространстве отказом, сообщающим, что настройка Workspace folder пуста, и предлагающим указать в ней папку, содержащую .aggrega-config.yaml вашего рабочего пространства, вместо того чтобы работать в папке, в которой его запустил Claude Desktop. Пакет передаёт папку серверу только тогда, когда приложение его запускает, поэтому папка, заданная во время работы сервера, вступает в силу после того, как вы выключите и снова включите расширение в настройках расширений или перезапустите приложение, как в шаге 4.
  4. Полностью закройте Claude Desktop, затем запустите его снова. Сервер, уже запущенный приложением, продолжает работать, и переименование исполняемого файла его не останавливает, поэтому изменённая настройка вступает в силу только тогда, когда приложение снова запускает сервер: после того как оно закроется и запустится снова или, для Workspace folder, после того как расширение будет выключено и снова включено. В Windows диспетчер задач показывает, работает ли ещё процесс aggrega.

Папка рабочего пространства — это место, где обрабатывается каждый запрос, не указывающий собственного рабочего пространства. Claude Desktop запускает сервер в папке по своему выбору, а не в вашем проекте, поэтому пакет передаёт выбранную вами папку серверу в переменной окружения AGGREGA_WORKSPACE_ROOT, а не аргументом командной строки, которую составляет приложение. Сервер принимает эту папку как сам корень рабочего пространства, так же как --workspace-root принимается в каждой команде: он не ищет объемлющее рабочее пространство выше неё, поэтому выбирайте папку, содержащую .aggrega-config.yaml, а не папку внутри неё. Чтобы работать в другом рабочем пространстве, измените настройку и перезапустите приложение, как в шаге 4. Если запрос указывает собственное рабочее пространство относительным workspace_root, тот тоже читается относительно папки рабочего пространства, поэтому промпт указывает папку внутри неё — например quickstart-ai/1, — не зная, где эта папка находится на вашем компьютере; абсолютный workspace_root используется как есть. Пока настройка пуста, на относительный путь даётся тот же отказ, что и на запрос, не указывающий никакого.

Поскольку пакет не указывает исполняемый файл ни для одной платформы, один и тот же файл подходит для всех объявленных в нём платформ: macOS, Windows и Linux.

Сервер сообщает, какой aggrega запустил пакет. В настройках расширений Claude Desktop указана версия самого пакета — версия выпуска, из которого он взят, — а не версия исполняемого файла, который он запускает. Они устанавливаются отдельно, поэтому могут относиться к разным выпускам. Пакет передаёт серверу свою версию в переменной окружения AGGREGA_BUNDLE_VERSION, и сервер сообщает обе: ответ describe-capabilities, вызванного без аргументов, — инструмента, который ассистент вызывает, чтобы узнать, что предлагает сервер, — начинается со строки с версией исполняемого файла и версией пакета и содержит ту же строку как version_summary в своей структурированной части, так что ассистент, которого спросили, какая версия Aggrega запущена, может прочитать обе там, какую бы часть ответа ни передало ему приложение. Если они относятся к разным выпускам, эта строка сообщает об этом, называя обе, и указания, которые сервер передаёт ассистенту при подключении, начинаются с того же предложения. Расхождение не вызывает отказа, и сервер обрабатывает каждый запрос как обычно; о нём сообщается, чтобы вы знали, какой исполняемый файл запускает пакет. Чтобы согласовать их, установите aggrega-<version>.mcpb того выпуска, из которого взят ваш исполняемый файл (эту версию выводит aggrega version в терминале), или укажите в Path to the aggrega executable полный путь к файлу aggrega из выпуска пакета, затем перезапустите приложение, как в шаге 4.

Собственные журналы Claude Desktop показывают, что оно запустило. В Windows они могут находиться в папке пакета в локальном каталоге данных приложений, а не в %APPDATA%\Claude\logs, даже если Claude Desktop был установлен из собственного дистрибутива: в %LOCALAPPDATA%\Packages\, в папке, имя которой начинается с Claude_, по пути LocalCache\Local\Claude\logs. Среди файлов там есть mcp.log и mcp-server-Aggrega.log; второй содержит то, что сервер Aggrega пишет в стандартный поток ошибок. Строка с Using MCP server command: называет команду, запущенную приложением, — она берётся из настройки пакета Path to the aggrega executable. Если настройка указывает путь, по которому ничего нет, журнал содержит сообщение командного интерпретатора Windows о том, что путь не распознан как команда, а затем сообщает, что сервер не удалось запустить. Если папки рабочего пространства нет — она переименована, перемещена или так и не создана, — сервер всё равно запускается и отвечает на каждый запрос ассистента в этом рабочем пространстве своим отказом, так что ассистент получает отказ как ответ на свой запрос, а приложение не сообщает об ошибке подключения. Отказ называет AGGREGA_WORKSPACE_ROOT как переменную, которую задаёт настройка пакета Workspace folder, и приводит папку точно в том виде, в каком её передало приложение; mcp-server-Aggrega.log содержит тот же отказ. На пустую настройку Workspace folder ответ такой же — отказ из шага 3, называющий пустую настройку, который тоже попадает в журнал. Исправьте настройку и перезапустите приложение, как в шаге 4.

Настройки коннекторов Claude Desktop — другой путь, для сервера, доступного по HTTPS: см. Сервер, доступный по HTTPS.

Когда клиент не принимает весь набор инструментов

Aggrega объявляет весь свой набор инструментов и оставляет клиенту решать, какую его часть показать модели. Некоторые клиенты ограничивают число инструментов, регистрируемых за раз, и отбрасывают остальные. В таком случае mcp.announce_tools сокращает объявляемое сервером до указанных вами инструментов — см. Сужение того, что объявляет сервер.

Сервер, доступный по HTTPS

Каждая из приведённых выше записей запускает сервер сама. К серверу, который запускает кто-то другой, — одному долгоживущему процессу на хосте, обслуживающему одно рабочее пространство, — вместо этого обращаются по сети, и его запись указывает адрес, а не команду:

{
"mcpServers": {
"aggrega": {
"url": "https://aggrega.example.com/mcp"
}
}
}

Путь всегда /mcp; хост — тот, который оператор опубликовал для этого сервера. Узнайте его у оператора. Gemini CLI принимает адрес в httpUrl, а не в url: url он считает сервером на более старом транспорте потока событий, а httpUrl — сервером на потоковом HTTP-транспорте, который и использует этот сервер.

Токен получает ваш клиент, а не вы. Ничего, связанного со входом, в записи не настраивается: на запрос без аутентификации сервер отвечает, указывая документ, в котором сказано, какой сервер авторизации выдаёт его токены, а клиент, поддерживающий поток авторизации протокола, читает этот документ, направляет вас на вход и прикрепляет полученный токен к каждому последующему запросу. Имена областей доступа, которые он может запросить, опубликованы в том же документе. Клиент, не реализующий этот поток, не может обратиться к такому серверу, и ничто, добавленное вами в запись, его не заменит.

Инструмент, на который не распространяются области доступа вашего входа, всё равно есть в списке инструментов. Его вызов отклоняется с указанием области, которая его разрешила бы, а клиент, реализующий повышение прав (step-up) протокола, отвечает на такой отказ, предлагая вам войти снова с этой областью. Клиенту, не поддерживающему повышение прав, всё же можно выдать области записи: тот, кто управляет сервером авторизации, делает их областями по умолчанию для этого клиента, и уже его первый вход их содержит — ценой того, что каждый вход через этот клиент затем получает право записи. В разделе Что может быть доступно вызывающей стороне описано, что разрешает каждая область и как эта настройка ведёт себя для клиента, который регистрируется заново при каждом подключении.

Что требуется такому серверу и что настраивает его оператор, описано в разделе aggrega mcp справочника.

Проверка подключения

После повторного подключения клиента убедитесь, что интеграция работает: клиент должен показать промпты Aggrega для авторинга (по одному для ролей разработчика, архитектора и эксплуатации, а также шаблон для каждой сущности) и инструменты авторинга — среди них scaffold, validate, describe и get-schema. Попросите ассистента создать заготовку компонента, и он должен вернуть каркас с полями, которые требует сущность Component. Если ничего не появляется, проверьте, что aggrega version запускается из терминала и что command клиента указывает на исполняемый файл, — примечание о PATH выше описывает частую причину.