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

Импорт конфигурации клиента MCP

Это пошаговое руководство импортирует серверы Model Context Protocol, с которыми настроен помощник по программированию, — два, которые он запускает из командной строки, и один, который запускает кто-то другой, — и собирает серверы для Kubernetes, чтобы агент, работающий в кластере, мог обращаться к тем же инструментам. Импорт создаёт черновик каждого файла, который читает сборка: командную строку или адрес каждого сервера, реализацию, которая его запускает, и то, откуда берётся токен сервера GitHub. Каждый файл и каждый блок вывода ниже взяты из реального запуска; конфигурация и каждый этап руководства находятся в примере import-mcp, где проверочный скрипт снова запускает импорт, сравнивает то, что он записывает, то, что он выводит, и блоки, которые цитирует эта страница, с хранящимися там файлами, а также проверяет и собирает то, что записал импорт.

Создание примера

Этот импорт можно выполнить командами с этой страницы или поручить его вашему ИИ-ассистенту.

Запишите пример в новую папку, названную по его имени:

Terminal window
aggrega scaffold --example import-mcp

Затем она выводит команды, которые нужно выполнить дальше. Первая переходит в новую папку; следующая, ниже, переходит в её папку source, которая содержит то, что импортирует эта страница, и в которой выполняется импорт:

Terminal window
cd import-mcp

Папка source сгенерированного примера, открытая в Visual Studio Code, с её конфигурацией MCP из трёх серверов: github, fetch и docs-search.

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

.mcp.json Claude Code в корне проекта:

{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
}
},
"fetch": {
"command": "uvx",
"args": ["mcp-server-fetch"]
},
"docs-search": {
"type": "http",
"url": "https://mcp.example.com/docs/mcp",
"headers": {
"Authorization": "Bearer ${DOCS_API_KEY}"
}
}
}
}

Так же импорт читает claude_desktop_config.json Claude Desktop, .cursor/mcp.json Cursor, .vscode/mcp.json Visual Studio Code и server.json реестра MCP. Рядом с конфигурацией .aggrega-config.yaml делает папку рабочим пространством:

# The workspace key marks this directory as the workspace root, so an import run
# here writes its drafts beside .mcp.json.
workspace: {}
# The registry the importer is fetched from the first time an import needs it.
default_registry: hub.aggrega.ai

--target создаёт черновик сущности Manifest из сущностей Recipes каталога. Рабочее пространство не указывает ни одной папки каталога, поэтому импорт читает каталог стандартной библиотеки из реестра, из которого получает свой импортёр: подписанный снимок опубликованного каталога, который первый импорт получает, проверяет и сохраняет в кэше содержимого рабочего пространства и который запись, создаваемая импортом рядом с черновиками, называет по его дайджесту. Рабочее пространство, указывающее собственные папки каталога — в AGGREGA_CATALOG_DIRS или в workspace.catalog_dirs, — вместо этого импортирует на их основе.

Файл ответов

В Kubernetes сервер GitHub читает свой токен из Secret, который хранит кластер, и ни одна конфигурация MCP не называет этот Secret: конфигурация читает токен из переменной GITHUB_TOKEN вашей оболочки. Поэтому импорт запрашивает имя Secret. Пример хранит ответ в import-answers.yaml, рядом с .mcp.json, где импорт его ищет:

# Values the import could not draft from the source, keyed by the drafted file and the key path inside
# it. Write each one beside its key; an import of the same source, and a sync, read them from here and
# ask nothing. A secret is never written here: its key asks where the secret comes from — a variable
# name, ${NAME}, or the name of a Kubernetes Secret.
release.yaml:
# The origin of the secret value, written by the operator in the Release. Read exactly as
# values.origin is. Write it here or in values.origin, never in both. A secret: name where it comes
# from, never the value.
spec.components.github.features.server_env.infra.origin: "github-mcp-token"

Импорт сам записал этот файл при первом запуске без ответа: не имея терминала, в котором можно было бы спросить, он создал черновик всего остального, оставил имя Secret пустым, перечислил ключ в файле и остановился с сообщением

1 value the drafts leave empty is still owed, listed in the answers file <workspace>/import-answers.yaml: write it beside its key there, then run the import again

В терминале он вместо этого задаёт вопрос и записывает ответ в файл для следующего импорта. Ответ — это имя Secret, github-mcp-token, а не сам токен. Файл ответов импорта полностью описывает файл и вопросы.

aggrega import перечисляет все флаги, которые принимает команда, в том числе --answers, указывающий файл ответов, хранящийся в другом месте.

Перейдите в source:

Terminal window
cd source

Запуск импорта

Terminal window
aggrega import .mcp.json --target helm

В стандартный вывод он выводит список записанного:

wrote aggregate.yaml
wrote release.yaml
wrote manifest.yaml
wrote .aggrega-import.json

В стандартный поток ошибок, где <workspace> обозначает папку, в которой вы его запустили:

[… omitted: a warning that the importer runs unverified, printed where its module is read from beside its Plugin entity in a catalog folder rather than fetched]
read as the mcp format, with drafted paths relative to <workspace>
warn: the value of infra.stdio_command.0 of node github is carried as written in the Release the draft writes: the field belongs to an MCP server's configuration, which can carry a key, and setting empty_credentials to marked or all writes it empty
warn: the value of infra.stdio_command.1 of node github is carried as written in the Release the draft writes: the field belongs to an MCP server's configuration, which can carry a key, and setting empty_credentials to marked or all writes it empty
warn: the value of infra.stdio_command.2 of node github is carried as written in the Release the draft writes: the field belongs to an MCP server's configuration, which can carry a key, and setting empty_credentials to marked or all writes it empty
warn: the value of infra.stdio_command.0 of node fetch is carried as written in the Release the draft writes: the field belongs to an MCP server's configuration, which can carry a key, and setting empty_credentials to marked or all writes it empty
warn: the value of infra.stdio_command.1 of node fetch is carried as written in the Release the draft writes: the field belongs to an MCP server's configuration, which can carry a key, and setting empty_credentials to marked or all writes it empty
warn: the value of headers.Authorization of node docs-search is carried as written in the Release the draft writes: the field belongs to an MCP server's configuration, which can carry a key, and setting empty_credentials to marked or all writes it empty
warn: the value of infra.endpoint of node docs-search is carried as written in the Release the draft writes: the field belongs to an MCP server's configuration, which can carry a key, and setting empty_credentials to marked or all writes it empty
Pull complete: <workspace>/release.lock (entities=7, source_artifacts=0, external_inputs=0)

Импорт, запущенный из редактора: черновики сущностей Aggregate, Release и Manifest появляются рядом с конфигурацией MCP, вывод Aggrega перечисляет значения, перенесённые как записано, и записанные файлы, а уведомление сообщает, что импорт создал черновики 3 файлов, распознанные как mcp.

Каждый сервер является экземпляром инструмента MCP из стандартной библиотеки, core/ai-tool/mcp, поэтому импорт не взвешивает ни одного кандидата и не выводит ни одной строки mapped.

  • Строки warn называют значения, которые содержит конфигурация сервера. Ни один клиент MCP не помечает ни одно из них как учётные данные, а любое из них может их содержать — ключ в аргументе командной строки, токен в адресе, — поэтому импорт называет каждый элемент командной строки, каждый заголовок и каждый адрес, которые он перенёс, по серверу и месту, но никогда по значению. Прочитайте их, прежде чем делиться черновиком. Значение env ${GITHUB_TOKEN} — это лишь ссылка на переменную, поэтому оно не содержит собственного значения, и ни одно предупреждение его не называет.
  • Строка Pull complete означает, что импорт получает то, от чего зависит черновик сущности Release, как это делает aggrega pull, в release.lock, чтобы черновики сразу проходили валидацию и сборку. С --offline импорт ничего не загружает и называет команду aggrega pull, которую следует выполнить.

Что он записывает

Сущности Aggregate, Release и Manifest получают имя imported/mcp по файлу, .mcp.json, так как конфигурация клиента не несёт собственного имени — server.json реестра получает имя по своему name — в пространстве имён, которое задаёт настройка target_namespace импортера, то есть imported, если вы не зададите другое (Настройки).

aggregate.yaml — по одному экземпляру на сервер и пока ничего, что бы их использовало:

apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: imported/mcp
version: 0.1.0
description: Draft Aggregate imported from a source in the mcp format.
spec:
components:
github:
type: core/ai-tool/mcp
fetch:
type: core/ai-tool/mcp
docs-search:
type: core/ai-tool/mcp

release.yaml — как запускается каждый сервер или как к нему обращаться, согласно конфигурации, а также Secret, из которого читается токен сервера GitHub:

apiVersion: aggrega.ai/v1beta1
kind: Release
metadata:
name: imported/mcp
# environment is a drafted default, since no source names the environment this Release deploys to; change it to name the one it deploys to.
environment: development
version: 0.1.0
description: Draft Release imported from a source in the mcp format.
spec:
aggregate: imported/mcp
manifest: imported/mcp
components:
github:
infra:
stdio_command:
- "npx"
- "-y"
- "@modelcontextprotocol/server-github"
stdio_runtime: npm
features:
server_env:
type: core/referenced-secret
infra:
# Left for the Release, since the source cannot supply it: the name of a Kubernetes Secret already in the namespace holding the environment github is started with, one data key per variable, each named as the variable it holds: GITHUB_PERSONAL_ACCESS_TOKEN.
origin: "github-mcp-token"
fetch:
infra:
stdio_command:
- "uvx"
- "mcp-server-fetch"
stdio_runtime: pypi
# The headers the source sends this server, which no infrastructure key of core/ai-tool/mcp takes, since a remote server's credential is held by each consumer, on its connection to the tool:
# - Authorization: "Bearer ${DOCS_API_KEY}"
docs-search:
infra:
endpoint: "https://mcp.example.com/docs/mcp"
  • Окружение, development, — это значение по умолчанию, которое записывает импорт, поскольку ни одна конфигурация его не указывает; измените его, если сущность Release развёртывается в другом месте.
  • stdio_runtime считывается из каждой команды: npx запускает пакет npm, uvx — пакет PyPI.
  • Токен GitHub. Окружение сервера становится его слотом server_env. В Kubernetes реализация core/referenced-secret-set, helm/k8s-secret-set, записывает переданные ей значения в Secret, который рендерит сборка, и так токен попал бы в файл. Поэтому для --target helm импорт вместо этого присоединяет core/referenced-secret, указывая Secret, который уже есть в кластере, — ответ, github-mcp-token, — с одним ключом данных на переменную, GITHUB_PERSONAL_ACCESS_TOKEN. Мост импортирует каждый ключ данных этого Secret как переменную с тем же именем, поэтому сервер читает свой токен так же, как на вашей машине, и ни один отрендеренный файл его не содержит.
  • Заголовок Authorization остаётся комментарием. Учётные данные удалённого сервера хранит тот, кто его вызывает, в собственном соединении этого вызывающего с инструментом, а в этом рабочем пространстве вызывающего пока нет. Когда вы подключите агента к docs-search, заголовок размещается в этом соединении.

manifest.yaml — одна реализация на сервер, по его имени, и реализация Secret:

apiVersion: aggrega.ai/v1beta1
kind: Manifest
metadata:
name: imported/mcp
version: 0.1.0
spec:
mappings:
components:
type: {}
name:
github: helm/mcp-stdio-bridge
fetch: helm/mcp-stdio-bridge
docs-search: helm/mcp-remote
features:
type:
core/referenced-secret: helm/k8s-existing-secret

Три сущности Recipes для Kubernetes реализуют core/ai-tool/mcp — одна для сервера, опубликованного как образ, одна для пакета, работающего за мостом, одна для сервера, который запускает кто-то другой, — и то, какая из них подходит, является свойством каждого сервера, которое указывает конфигурация. Поэтому импорт сопоставляет каждый экземпляр по его имени: github и fetch, запускаемые из командной строки, работают за мостом stdio, helm/mcp-stdio-bridge; docs-search, который запускает кто-то другой, сопоставляется с helm/mcp-remote, который ничего не запускает и публикует адрес. Secret токена сопоставляется с helm/k8s-existing-secret, который ссылается на Secret, а не записывает его.

release.lock фиксирует по дайджесту сущности каталога, в которые разрешилась сущность Release, а .aggrega-import.json — это сведения о том, что записал импорт; их читает последующий aggrega import --sync.

В Docker Compose

Серверы работают и в Docker Compose. aggrega import .mcp.json --target compose сопоставляет github и fetch с compose/mcp-stdio-bridge, а docs-search — с compose/mcp-remote и сохраняет окружение сервера GitHub так, как его записывает конфигурация: запись core/referenced-secret-set, значением которой является ссылка на переменную ${GITHUB_TOKEN}, реализованная через compose/dotenv-secret-set, который записывает её в окружение сервиса как есть, поэтому Docker Compose заполняет её из вашей оболочки при запуске стека. Этот импорт ничего не запрашивает и сохраняет имя Secret в файле ответов, не используя его.

Проверка и сборка

Terminal window
aggrega validate --release release.yaml
aggrega build --release release.yaml

Черновик сущности Release, открытый в редакторе после валидации; вывод Aggrega и уведомление оба сообщают, что проблем не найдено.

Сборка черновика сущности Release: в Проводнике появляется папка dist, вывод Aggrega перечисляет Deployment и Service для каждого сервера, а уведомление сообщает, что записано 5 файлов.

Проверка выводит:

notice: LINT: Feature "core/referenced-secret" at core/referenced-secret:1.0.0 declares property "origin" in both values: and infra: pillars (path: origin)
release dependency validation passed: release.yaml (schema-pillar + dependency pillars)

и сборка, где <workspace> обозначает папку, в которой вы её запустили:

notice: LINT: Feature "core/referenced-secret" at core/referenced-secret:1.0.0 declares property "origin" in both values: and infra: pillars (path: origin)
[… omitted: a total build time, which differs per run]
Build completed: 5 files written to <workspace>/dist

Строка notice носит рекомендательный характер: Feature принимает свой origin из values сущности Aggregate или из infra сущности Release, и уведомление сообщает, что один листовой узел объявлен в обоих местах. Она не меняет никакого вердикта.

Сборка записывает в dist/helm/ Deployment и Service для каждого из двух серверов за мостом и один Service для docs-search. Контейнер сервера GitHub в dist/helm/github-deployment.yaml запускает мост с командной строкой сервера и берёт своё окружение из Secret:

containers:
- name: main
image: ghcr.io/supercorp-ai/supergateway:4.1.0@sha256:1938c43538a5308bce07d58028e9de00b7acfecb40b39b059b2f3931800ad910
args:
- --stdio
- '''npx'' ''-y'' ''@modelcontextprotocol/server-github'''
- --outputTransport
- streamableHttp
- --stateful
- --port
- "8080"
- --streamableHttpPath
- /mcp
- --healthEndpoint
- /healthz
ports:
- name: http
containerPort: 8080
env:
- name: MCP_TOOL_SIDE_EFFECTS
value: mutating
- name: MCP_TOOL_TIMEOUT_SECONDS
value: "30"
- name: MCP_TOOL_PORT
value: "8080"
envFrom:
- secretRef:
name: github-mcp-token
[… omitted: the container's resources and its readiness probe]

dist/helm/docs-search-service.yaml ничего не запускает: он даёт серверу, который запускает кто-то другой, имя внутри кластера.

apiVersion: v1
kind: Service
metadata:
name: docs-search
[… omitted: the labels and annotations the build writes on every resource]
spec:
type: ExternalName
externalName: mcp.example.com
ports:
- port: 443

С ИИ-ассистентом

ИИ-ассистент, настроенный с инструментами Aggrega, может сделать то же самое: вставьте в него этот промпт.

Используй только инструменты Aggrega и не создавай никаких папок самостоятельно. Если папка Workspace ещё не содержит папку `import-mcp`, вызови один раз инструмент `scaffold` с `example`, установленным в `import-mcp`, и без `dir`: он записывает пример в новую папку `import-mcp`, папка `source` которой содержит то, что импортирует эта страница. Затем вызови инструмент `import` с `workspace_root`, установленным в `import-mcp/source`, `source`, установленным в `.mcp.json`, и `target`, установленным в `helm`: он читает нужные ответы из `import-answers.yaml` рядом с `.mcp.json`, записывает свои черновики в `import-mcp/source` и загружает то, что им нужно. Затем вызови инструмент `validate` с `workspace_root`, установленным в `import-mcp/source`, и `release`, установленным в `release.yaml`, а также инструмент `build` с `workspace_root`, установленным в `import-mcp/source`, `release`, установленным в `release.yaml`, и `write`, установленным в true. Скажи мне, какие файлы записала сборка; они находятся в `import-mcp/source/dist/`.

Открытие в VS Code

Когда расширение Aggrega для Visual Studio Code установлено, откройте в VS Code папку import-mcp/source, куда импорт записал свои черновики. Папка содержит одну сущность Release, черновик release.yaml, поэтому редактор выбирает её за вас и при редактировании проверяет черновики относительно этой сущности Release, отмечая найденное в файле и на панели «Проблемы». Aggrega: Show topology graph в палитре команд рисует компоненты сущности Release и связи между ними. Aggrega: Build, Aggrega: Preview build и Aggrega: Pull действуют на ту же сущность Release, и каждая из них также является кнопкой на панели Commands представления Aggrega на панели действий; Build записывает свои файлы в dist/ этой папки. Остальное описывает Использование Aggrega в Visual Studio Code.

Запуск

Ничто в результате сборки не записывает Secret github-mcp-token, поэтому создайте его, прежде чем применять файлы. Запишите свой токен в github-token.env в виде одной строки GITHUB_PERSONAL_ACCESS_TOKEN=<your token> и создайте из него Secret. После этого токен хранит кластер, поэтому удалите файл:

Terminal window
kubectl create secret generic github-mcp-token --from-env-file=github-token.env
rm github-token.env
secret/github-mcp-token created

Примените результат сборки, как объясняет шаг запуска в разделе Как выполняется импорт, и дождитесь обоих серверов:

Terminal window
kubectl apply -R -f dist/helm/
kubectl wait --for=condition=Available deployment.apps/fetch deployment.apps/github --timeout=5m
service/docs-search created
service/fetch-default created
deployment.apps/fetch created
service/github-default created
deployment.apps/github created
deployment.apps/fetch condition met
deployment.apps/github condition met

В Docker Compose, в рабочем пространстве, импортированном с --target compose и собранном, запустите стек с вашим токеном в переменной GITHUB_TOKEN вашей оболочки, которую Docker Compose читает при запуске стека:

Terminal window
docker compose -p mcp -f dist/compose/docker-compose.yaml up -d --wait

Тестирование

Мост предоставляет каждый сервер через транспорт Streamable HTTP протокола MCP, по адресу /mcp на порту 8080. Попросите сервер fetch открыть сеанс запросом MCP initialize, который не читает никакого токена.

В Docker Compose отправьте его из одноразового контейнера в сети стека, mcp_compose, где сервер называется fetch:

Terminal window
docker run --rm --network mcp_compose curlimages/curl:8.11.1 -sS http://fetch:8080/mcp \
-H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
-d '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2025-06-18", "capabilities": {}, "clientInfo": {"name": "test-it", "version": "1.0.0"}}}'
: keepalive
[… omitted: the same comment, repeated while the server starts]
event: message
data: {"jsonrpc":"2.0","id":1,"result":{"capabilities":{"prompts":{"listChanged":false},"resources":{"listChanged":false,"subscribe":false},"tools":{"listChanged":false}},"protocolVersion":"2025-06-18","serverInfo":{"name":"mcp-fetch","version":"2026.11.11"}}}

В Kubernetes пробросьте локальный порт на Service сервера, fetch-default, и оставьте команду работать:

Terminal window
kubectl port-forward svc/fetch-default 8080:8080

Из другого терминала отправьте тот же запрос на перенаправленный порт:

Terminal window
curl -sS http://127.0.0.1:8080/mcp \
-H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
-d '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2025-06-18", "capabilities": {}, "clientInfo": {"name": "test-it", "version": "1.0.0"}}}'
: keepalive
: keepalive
event: message
data: {"jsonrpc":"2.0","id":1,"result":{"capabilities":{"prompts":{"listChanged":false},"resources":{"listChanged":false,"subscribe":false},"tools":{"listChanged":false}},"protocolVersion":"2025-06-18","serverInfo":{"name":"mcp-fetch","version":"2026.11.11"}}}

Ответ называет сервер, mcp-fetch. Это занимает некоторое время: мост запускает для каждого сеанса командную строку сервера, uvx mcp-server-fetch, а uvx сначала загружает и устанавливает пакеты сервера — при запуске это заняло около полуминуты в Kubernetes и около минуты в Docker Compose. Строки : keepalive — это комментарии, которые поток тем временем отправляет.

Сервер GitHub отвечает на тот же запрос по адресу http://github:8080/mcp в Docker Compose и через kubectl port-forward svc/github-default 8080:8080 в Kubernetes. initialize не читает никакого токена, поэтому отвечает независимо от того, что содержит токен; запуск использовал токен-заполнитель:

[… omitted: the keepalive comments, sent while npx installs the server]
event: message
data: {"result":{"protocolVersion":"2024-11-05","capabilities":{"tools":{}},"serverInfo":{"name":"github-mcp-server","version":"0.6.2"}},"jsonrpc":"2.0","id":1}

Остановите проброс порта, затем удалите то, что вы применили, и Secret:

Terminal window
kubectl delete -R -f dist/helm/
kubectl delete secret github-mcp-token

В Docker Compose остановите и удалите стек:

Terminal window
docker compose -p mcp -f dist/compose/docker-compose.yaml down