Перейти до вмісту
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