跳转到内容
AggregaAggrega
选择语言: 简体中文
本页面由机器翻译。阅读英文原文。

导入 MCP 客户端配置

本演练导入为某个编程助手配置的 Model Context Protocol 服务器——其中两个由它从命令行启动,一个由他人运行——并为 Kubernetes 构建这些服务器,使在集群中运行的代理也能使用相同的工具。导入会起草构建所读取的每个文件:每个服务器的命令行或地址、运行它的实现,以及 GitHub 服务器令牌的来源。下面的每个文件和每段输出都来自一次真实运行;配置和演练的每个阶段都位于 import-mcp 示例中,其中的检查脚本会再次运行导入,将它写出的内容、打印的内容以及本页引用的代码块与那里保存的文件进行比较,并验证和构建导入写出的内容。

生成示例

你可以使用本页的命令运行此导入,也可以让你的 AI 助手替你运行。

将示例写入一个以其命名的新文件夹:

Terminal window
aggrega scaffold --example import-mcp

然后它会打印接下来要运行的命令。第一条命令进入新文件夹;其后的那条命令见下文,它进入新文件夹的 source 文件夹,该文件夹包含本页导入的内容,也是运行导入的位置:

Terminal window
cd import-mcp

在 Visual Studio Code 中打开的已生成示例的 source 文件夹,显示其 MCP 配置,其中有三个服务器:github、fetch 和 docs-search。

配置

位于项目根目录中的 Claude Code 的 .mcp.json:

{
"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 的 claude_desktop_config.json、Cursor 的 .cursor/mcp.json、Visual Studio Code 的 .vscode/mcp.json 以及 MCP 注册表的 server.json。在配置旁边,一个 .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 会根据目录的 Recipes 起草一个 Manifest。工作区没有指定目录文件夹,因此导入会从获取其导入器的注册表中读取标准库目录:这是已发布目录的一个签名快照,由第一次导入获取、验证并保存在工作区的内容缓存中,并在导入写在其草稿旁的记录中以其摘要标明。指定了自己的目录文件夹的工作区——在 AGGREGA_CATALOG_DIRS 中,或在 workspace.catalog_dirs 下——则改为针对这些文件夹进行导入。

答案文件

在 Kubernetes 上,GitHub 服务器从集群持有的一个 Secret 中读取其令牌,而没有任何 MCP 配置指明该 Secret:配置从你的 shell 的 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 这一行表示导入正在像 aggrega pull 那样,将草拟的 Release 所依赖的内容获取到 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——按配置所述,每个服务器如何运行或如何访问,以及读取 GitHub 服务器令牌所用的 Secret:

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

三个 Kubernetes Recipes 实现 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 会在栈启动时从你的 shell 中填充它。该导入不询问任何内容,并在答案文件中保留该 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 接受来自 Aggregate 的 values 或 Release 的 infra 的 origin,而该提示报告有一个叶子在两处都有声明。它不改变任何结论。

构建在 dist/helm/ 下为两个经桥接的服务器各写出一个 Deployment 和一个 Service,并为 docs-search 写出一个 Service。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

借助 AI 助手

配置了 Aggrega 工具的 AI 助手也可以完成同样的操作:将下面的提示词粘贴给它。

只使用 Aggrega 工具,不要自己创建任何文件夹。如果工作区文件夹中还没有 `import-mcp` 文件夹,调用一次 `scaffold` 工具,将 `example` 设为 `import-mcp`,不设 `dir`:它会将示例写入新的 `import-mcp` 文件夹,其中的 `source` 文件夹包含本页导入的内容。然后调用 `import` 工具,将 `workspace_root` 设为 `import-mcp/source`,`source` 设为 `.mcp.json`,`target` 设为 `helm`:它从 `.mcp.json` 旁边的 `import-answers.yaml` 读取所需的答案,将草稿写入 `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 中打开

安装 适用于 Visual Studio Code 的 Aggrega 扩展 后,在 VS Code 中打开导入写入草稿的文件夹 import-mcp/source。该文件夹包含一个 Release,即起草的 release.yaml,因此编辑器会为你选中它,并在你编辑草稿时对照该 Release 检查草稿,将发现的问题标记在文件中和“问题”面板中。命令面板中的 Aggrega: Show topology graph 会绘制 Release 的组件及其之间的连接。Aggrega: Build、Aggrega: Preview build 和 Aggrega: Pull 作用于同一个 Release,并且每一个也是活动栏中 Aggrega 视图的 Commands 面板上的按钮;Build 会将其文件写入该文件夹的 dist/。在 Visual Studio Code 中使用 Aggrega 介绍了其余内容。

运行

构建中没有任何内容写入 github-mcp-token Secret,因此请在应用这些文件之前创建它。将你的令牌写入 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 导入并构建的工作区中,将你的令牌放在 shell 的 GITHUB_TOKEN 中启动栈,Docker Compose 会在栈启动时读取它:

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

测试

桥接器通过 MCP 的 Streamable HTTP 传输在端口 8080 上的 /mcp 提供每个服务器。使用 MCP 的 initialize 请求让 fetch 服务器打开一个会话,该请求不读取任何令牌。

在 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 服务器在 Docker Compose 上通过 http://github:8080/mcp 响应同样的请求,在 Kubernetes 上则通过 kubectl port-forward svc/github-default 8080:8080 响应。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