Przejdź do głównej zawartości
AggregaAggrega
Wybierz język: Polski
Ta strona została przetłumaczona maszynowo. Przeczytaj oryginał w języku angielskim.

Importowanie konfiguracji klienta MCP

Ten przewodnik krok po kroku importuje serwery Model Context Protocol, z którymi skonfigurowany jest asystent programowania — dwa, które uruchamia z wiersza poleceń, i jeden, który prowadzi ktoś inny — i buduje serwery dla Kubernetes, tak aby agent działający w klastrze mógł sięgać do tych samych narzędzi. Import tworzy szkic każdego pliku, który odczytuje build: wiersz poleceń lub adres każdego serwera, realizację, która go uruchamia, oraz to, skąd pochodzi token serwera GitHub. Każdy plik i każdy blok wyjścia poniżej pochodzi z rzeczywistego uruchomienia; konfiguracja i każdy etap przewodnika znajdują się w przykładzie import-mcp, gdzie skrypt sprawdzający ponownie uruchamia import, porównuje to, co zapisuje, to, co wypisuje, oraz bloki cytowane na tej stronie z przechowywanymi tam plikami, a także waliduje i buduje to, co zapisał import.

Generowanie przykładu

Ten import można uruchomić poleceniami z tej strony albo zlecić to asystentowi AI.

Należy zapisać przykład w nowym folderze nazwanym tak jak on:

Terminal window
aggrega scaffold --example import-mcp

Następnie wypisuje polecenia do uruchomienia w dalszej kolejności. Pierwsze przechodzi do nowego folderu; kolejne, poniżej, przechodzi do folderu source w nowym folderze, który zawiera to, co importuje ta strona, i w którym uruchamia się import:

Terminal window
cd import-mcp

Folder source wygenerowanego przykładu otwarty w Visual Studio Code, pokazujący jego konfigurację MCP z trzema serwerami: github, fetch i docs-search.

Konfiguracja

Plik .mcp.json narzędzia Claude Code w głównym folderze projektu:

{
"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}"
}
}
}
}

Import odczytuje w ten sam sposób claude_desktop_config.json z Claude Desktop, .cursor/mcp.json z Cursor, .vscode/mcp.json z Visual Studio Code oraz server.json z rejestru MCP. Obok konfiguracji plik .aggrega-config.yaml czyni z folderu obszar roboczy:

# 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 tworzy szkic encji Manifest na podstawie encji Recipes z katalogu. Przestrzeń robocza nie wskazuje żadnego folderu katalogu, więc import odczytuje katalog biblioteki standardowej z rejestru, z którego pobiera swój importer: podpisaną migawkę opublikowanego katalogu, którą pierwszy import pobiera, weryfikuje i przechowuje w pamięci podręcznej treści przestrzeni roboczej i którą rekord zapisywany przez import obok jego szkiców wskazuje za pomocą jej skrótu. Przestrzeń robocza, która wskazuje własne foldery katalogu — w AGGREGA_CATALOG_DIRS lub pod workspace.catalog_dirs — importuje zamiast tego względem nich.

Plik odpowiedzi

W Kubernetes serwer GitHub odczytuje swój token z obiektu Secret przechowywanego przez klaster, a żadna konfiguracja MCP nie wskazuje tego obiektu Secret: konfiguracja odczytuje token ze zmiennej GITHUB_TOKEN powłoki. Dlatego import pyta o nazwę obiektu Secret. Przykład przechowuje odpowiedź w import-answers.yaml, obok .mcp.json, gdzie import jej szuka:

# 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"

Import sam zapisał ten plik przy pierwszym uruchomieniu bez odpowiedzi: nie mając terminala, w którym mógłby zapytać, utworzył szkic całej reszty, pozostawił pustą nazwę obiektu Secret, wymienił klucz w pliku i zatrzymał się z komunikatem

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

W terminalu zamiast tego zadaje pytanie i zapisuje odpowiedź w pliku na potrzeby następnego importu. Odpowiedzią jest nazwa obiektu Secret, github-mcp-token, nigdy sam token. Plik odpowiedzi importu w pełni opisuje ten plik i pytania.

aggrega import wymienia każdą flagę przyjmowaną przez polecenie, w tym --answers, która wskazuje plik odpowiedzi przechowywany gdzie indziej.

Należy przejść do source:

Terminal window
cd source

Uruchomienie importu

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

Na standardowym wyjściu wymienia to, co zapisał:

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

Na standardowym wyjściu błędów, gdzie <workspace> oznacza folder, w którym go uruchomiono:

[… 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)

Import uruchomiony z edytora: szkice encji Aggregate, Release i Manifest pojawiają się obok konfiguracji MCP, dane wyjściowe Aggrega wymieniają wartości przeniesione w zapisanej postaci i zapisane pliki, a powiadomienie informuje, że import utworzył szkice 3 plików, rozpoznane jako mcp.

Każdy serwer jest instancją narzędzia MCP z biblioteki standardowej, core/ai-tool/mcp, więc import nie rozważa żadnego kandydata i nie wypisuje żadnego wiersza mapped.

  • Wiersze warn wymieniają wartości, które zawiera konfiguracja serwera. Żaden klient MCP nie oznacza żadnej z nich jako poświadczenia, a każda z nich może je zawierać — klucz w argumencie wiersza poleceń, token w adresie — więc import wymienia każdy element wiersza poleceń, każdy nagłówek i każdy adres, który przeniósł, według jego serwera i miejsca, nigdy według wartości. Należy je przeczytać przed udostępnieniem szkicu. Wartość ${GITHUB_TOKEN} w env jest odwołaniem do zmiennej i niczym więcej, więc nie zawiera własnej wartości i żadne ostrzeżenie jej nie wymienia.
  • Wiersz Pull complete oznacza, że import pobiera to, od czego zależy szkic encji Release, tak jak robi to aggrega pull, do release.lock, dzięki czemu szkice od razu przechodzą walidację i budowanie. Z --offline import niczego nie pobiera i podaje polecenie aggrega pull, które należy uruchomić.

Co zapisuje import

Encje Aggregate, Release i Manifest otrzymują nazwę imported/mcp od pliku, .mcp.json, ponieważ konfiguracja klienta nie ma własnej nazwy — server.json rejestru otrzymuje nazwę od swojego name — w przestrzeni nazw określonej przez ustawienie target_namespace importera, imported, o ile nie ustawi się innej (Ustawienia).

aggregate.yaml — jedna instancja na serwer i jeszcze nic, co by z nich korzystało:

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 — jak każdy serwer jest uruchamiany lub osiągany, tak jak podaje to konfiguracja, oraz obiekt Secret, z którego odczytywany jest token serwera 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"
  • Środowisko, development, to wartość domyślna, którą zapisuje import, ponieważ żadna konfiguracja go nie wskazuje; należy je zmienić, jeśli encja Release jest wdrażana gdzie indziej.
  • stdio_runtime jest odczytywane z każdego polecenia: npx uruchamia pakiet npm, uvx pakiet PyPI.
  • Token GitHub. Środowisko serwera staje się jego slotem server_env. W Kubernetes realizacja core/referenced-secret-set, czyli helm/k8s-secret-set, zapisuje otrzymane wartości do obiektu Secret, który renderuje kompilacja, co umieściłoby token w pliku. Dlatego dla --target helm import dołącza zamiast tego core/referenced-secret, wskazując obiekt Secret, który klaster już przechowuje — odpowiedź, github-mcp-token — z jednym kluczem danych na zmienną, GITHUB_PERSONAL_ACCESS_TOKEN. Mostek importuje każdy klucz danych tego obiektu Secret jako zmienną o tej samej nazwie, więc serwer odczytuje swój token tak samo jak na komputerze użytkownika, a żaden wyrenderowany plik go nie zawiera.
  • Nagłówek Authorization pozostaje komentarzem. Poświadczenie zdalnego serwera przechowuje ten, kto go wywołuje, na własnym połączeniu tego wywołującego z narzędziem, a ten obszar roboczy nie ma jeszcze żadnego wywołującego. Po podłączeniu agenta do docs-search nagłówek trafia na to połączenie.

manifest.yaml — jedna realizacja na serwer, według jego nazwy, oraz realizacja obiektu 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

Trzy encje Recipes dla Kubernetes realizują core/ai-tool/mcp — jedna dla serwera opublikowanego jako obraz, jedna dla pakietu uruchamianego za mostkiem, jedna dla serwera prowadzonego przez kogoś innego — a to, która pasuje, jest właściwością każdego serwera, którą podaje konfiguracja. Dlatego import mapuje każdą instancję według nazwy: github i fetch, uruchamiane z wiersza poleceń, działają za mostkiem stdio, helm/mcp-stdio-bridge; docs-search, prowadzony przez kogoś innego, mapuje się na helm/mcp-remote, który niczego nie uruchamia i publikuje adres. Obiekt Secret tokenu mapuje się na helm/k8s-existing-secret, który odwołuje się do obiektu Secret zamiast go zapisywać.

release.lock rejestruje, według digestu, encje katalogu, na które została rozwiązana encja Release, a .aggrega-import.json to zapis tego, co utworzył import, odczytywany przez późniejsze aggrega import --sync.

W Docker Compose

Serwery działają także w Docker Compose. aggrega import .mcp.json --target compose mapuje github i fetch na compose/mcp-stdio-bridge, a docs-search na compose/mcp-remote, i zachowuje środowisko serwera GitHub tak, jak zapisuje je konfiguracja: wpis core/referenced-secret-set, którego wartością jest odwołanie do zmiennej ${GITHUB_TOKEN}, realizowany przez compose/dotenv-secret-set, który zapisuje je w niezmienionej postaci w środowisku usługi, dzięki czemu Docker Compose wypełnia je z powłoki przy uruchamianiu stosu. Ten import o nic nie pyta i zachowuje nazwę obiektu Secret w pliku odpowiedzi, nie używając jej.

Walidacja i kompilacja

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

Szkic encji Release otwarty w edytorze po walidacji; dane wyjściowe Aggrega i powiadomienie nie zgłaszają żadnych problemów.

Build szkicu encji Release: w Eksploratorze pojawia się folder dist, dane wyjściowe Aggrega wymieniają obiekt Deployment i obiekt Service dla każdego serwera, a powiadomienie informuje, że zapisano 5 plików.

Walidacja wypisuje:

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)

oraz build, gdzie <workspace> oznacza folder, w którym go uruchomiono:

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

Wiersz notice ma charakter informacyjny: encja Feature przyjmuje swoje origin z values encji Aggregate lub z infra encji Release, a komunikat zgłasza, że jeden liść jest zadeklarowany w obu miejscach. Nie zmienia on żadnego werdyktu.

Kompilacja zapisuje w dist/helm/ obiekt Deployment i obiekt Service dla każdego z dwóch serwerów za mostkiem oraz jeden obiekt Service dla docs-search. Kontener serwera GitHub w dist/helm/github-deployment.yaml uruchamia mostek z wierszem poleceń serwera i pobiera swoje środowisko z obiektu 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 niczego nie uruchamia: nadaje serwerowi prowadzonemu przez kogoś innego nazwę wewnątrz klastra.

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

Z asystentem AI

Asystent AI skonfigurowany z narzędziami Aggrega może zrobić to samo: wystarczy wkleić do niego ten prompt.

Używaj wyłącznie narzędzi Aggrega i nie twórz samodzielnie żadnego folderu. Jeśli folder Workspace nie zawiera jeszcze folderu `import-mcp`, wywołaj raz narzędzie `scaffold` z `example` ustawionym na `import-mcp` i bez `dir`: zapisuje ono przykład w nowym folderze `import-mcp`, którego folder `source` zawiera to, co importuje ta strona. Następnie wywołaj narzędzie `import` z `workspace_root` ustawionym na `import-mcp/source`, `source` ustawionym na `.mcp.json` i `target` ustawionym na `helm`: odczytuje ono potrzebne odpowiedzi z `import-answers.yaml` obok `.mcp.json`, zapisuje szkice w `import-mcp/source` i pobiera to, czego potrzebują. Następnie wywołaj narzędzie `validate` z `workspace_root` ustawionym na `import-mcp/source` i `release` ustawionym na `release.yaml`, a potem narzędzie `build` z `workspace_root` ustawionym na `import-mcp/source`, `release` ustawionym na `release.yaml` i `write` ustawionym na true. Podaj mi, które pliki zapisał build; znajdują się w `import-mcp/source/dist/`.

Otwieranie w VS Code

Po zainstalowaniu rozszerzenia Aggrega dla Visual Studio Code należy otworzyć w VS Code folder import-mcp/source, w którym import zapisał szkice. Folder zawiera jedną encję Release, szkic release.yaml, więc edytor sam ją wybiera i podczas edycji sprawdza szkice względem tej encji Release, zaznaczając to, co znajdzie, w pliku i w panelu Problemy. Aggrega: Show topology graph w palecie poleceń rysuje komponenty encji Release i połączenia między nimi. Aggrega: Build, Aggrega: Preview build i Aggrega: Pull działają na tej samej encji Release, a każde z nich jest też przyciskiem w panelu Commands widoku Aggrega na pasku działań; Build zapisuje swoje pliki w dist/ tego folderu. Resztę opisuje Używanie Aggrega w Visual Studio Code.

Uruchomienie

Nic w wyniku budowania nie zapisuje obiektu Secret github-mcp-token, więc należy go utworzyć przed zastosowaniem plików. Należy zapisać token w github-token.env jako jeden wiersz GITHUB_PERSONAL_ACCESS_TOKEN=<your token> i utworzyć z niego obiekt Secret. Od tej chwili token przechowuje klaster, więc plik należy usunąć:

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

Należy zastosować wynik budowania, jak wyjaśnia krok uruchamiania w Jak przebiega import, i poczekać na oba serwery:

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

W Docker Compose, w obszarze roboczym zaimportowanym z --target compose i zbudowanym, należy uruchomić stos z tokenem w zmiennej GITHUB_TOKEN powłoki, którą Docker Compose odczytuje przy starcie stosu:

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

Testowanie

Mostek udostępnia każdy serwer przez transport Streamable HTTP protokołu MCP, pod /mcp na porcie 8080. Należy poprosić serwer fetch o otwarcie sesji żądaniem initialize protokołu MCP, które nie odczytuje żadnego tokenu.

W Docker Compose należy wysłać je z jednorazowego kontenera w sieci stosu, mcp_compose, w której serwer nazywa się 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"}}}

W Kubernetes należy przekierować port lokalny do obiektu Service serwera, fetch-default, i pozostawić polecenie uruchomione:

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

Z innego terminala należy wysłać to samo żądanie na przekierowany port:

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"}}}

Odpowiedź podaje nazwę serwera, mcp-fetch. Trwa to chwilę: mostek uruchamia dla każdej sesji wiersz poleceń serwera, uvx mcp-server-fetch, a uvx najpierw pobiera i instaluje pakiety serwera — w tym uruchomieniu około pół minuty w Kubernetes i około minuty w Docker Compose. Wiersze : keepalive to komentarze, które strumień wysyła w międzyczasie.

Serwer GitHub odpowiada na to samo żądanie pod http://github:8080/mcp w Docker Compose oraz przez kubectl port-forward svc/github-default 8080:8080 w Kubernetes. initialize nie odczytuje żadnego tokenu, więc odpowiada niezależnie od zawartości tokenu; uruchomienie użyło tokenu zastępczego:

[… 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}

Należy zatrzymać przekierowanie portu, a następnie usunąć to, co zostało zastosowane, oraz obiekt Secret:

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

W Docker Compose należy zatrzymać i usunąć stos:

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