工具蜂窝-构建骑士插件
项目介绍
ToolHive Buildkite 插件
这是一个 Buildkite 插件，它允许使用 ToolHive 在您的持续集成/持续交付（CI/CD）管道中运行模型上下文协议（MCP）服务器。
功能
- 自动安装 ToolHive：如果未安装，则下载并安装 ToolHive
- MCP 服务器管理：在管道执行期间启动、管理和清理 MCP 服务器
- 多个服务器来源：支持注册表服务器、Docker 镜像以及协议方案（
uvx://、npx://、go://） - 灵活配置：自定义传输方法、端口、卷、密钥等
使用方法
将插件添加到您的管道步骤中：
步骤:
- 标签: "使用 MCP 服务器运行"
命令: "your-command-here"
插件:
- StacklokLabs/toolhive#v0.0.2:
服务器: "fetch" # 来自 ToolHive 注册表的服务器
注册表服务器示例
步骤:
- 标签: "使用 Fetch MCP 服务器"
命令: "curl http://localhost:8080/some-endpoint"
插件:
- StacklokLabs/toolhive#v0.0.2:
服务器: "fetch"
传输: "stdio"
代理端口: 8080
Docker 镜像示例
步骤:
- 标签: "使用自定义 MCP 服务器"
命令: "your-command"
插件:
- StacklokLabs/toolhive#v0.0.2:
服务器: "my-registry/my-mcp-server:latest"
传输: "sse"
卷:
- "/host/path:/container/path:ro"
协议方案示例
步骤:
- 标签: "使用 Python MCP 服务器"
命令: "your-command"
插件:
- StacklokLabs/toolhive#v0.0.2:
服务器: "uvx://some-python-mcp-package@1.0.0"
传输: "streamable-http"
参数:
- "--verbose"
- "--config=/path/to/config"
包含密钥
步骤:
- 标签: "使用 GitHub MCP 服务器"
命令: "your-command"
插件:
- StacklokLabs/toolhive#v0.0.2:
服务器: "github"
密钥:
- 名称: "github-token"
目标: "GITHUB_PERSONAL_ACCESS_TOKEN"
- 名称: "api-key"
目标: "API_KEY"
配置
必需选项
| 选项 | 类型 | 描述 |
|---|---|---|
服务器 | 字符串 | 要运行的 MCP 服务器（注册表名称、Docker 镜像或协议方案） |
可选选项
| 选项 | 类型 | 默认值 | 描述 |
|---|---|---|---|
名称 | 字符串 | 自动生成 | MCP 服务器实例的自定义名称 |
传输 | 字符串 | ""（自动） | 传输方法：stdio、sse 或 streamable-http |
代理端口 | 整数 | 随机 | ToolHive 代理的具体端口 |
密钥 | 数组 | [] | 传递给 MCP 服务器的密钥 |
卷 | 数组 | [] | 卷挂载，格式为 "主机路径:容器路径[:ro]" |
参数 | 数组 | [] | 传递给 MCP 服务器的附加参数 |
权限配置文件 | 字符串 | 默认 | MCP 服务器的权限配置文件 |
toolhive-version | 字符串 | 最新 | 要下载的 ToolHive 的具体版本 |
清理 | 布尔值 | true | 是否在退出时清理 MCP 服务器 |
mcp-config-file | 字符串 | ./mcp_servers.json | 生成 MCP 配置文件的位置 |
mcp-config-cleanup | 布尔值 | true | 是否在退出时删除 MCP 配置文件 |
密钥配置
密钥配置为具有 名称 和 目标 属性的对象数组：
密钥:
- 名称: "toolhive中的密钥名称"
目标: "环境变量名称"
名称 指的是存储在 ToolHive 密钥管理系统中的密钥，而 目标 是将在 MCP 服务器容器中设置的环境变量名称。
请注意，在插件中使用之前必须在 ToolHive 中创建密钥。
卷配置
卷指定为 Docker 卷格式的字符串：
卷:
- "/host/path:/container/path" # 读写挂载
- "/host/path:/container/path:ro" # 仅读挂载
服务器类型
注册表服务器
使用来自 ToolHive 注册表 的服务器：
# 获取 MCP 服务器
服务器: "fetch"
# GitHub MCP 服务器
服务器: "github"
# 文件系统 MCP 服务器
服务器: "filesystem"
Docker 镜像
使用实现 MCP 协议的任何 Docker 镜像：
# 自定义 Docker 镜像
服务器: "my-registry/my-mcp-server:v1.0.0"
# GitHub 容器注册表镜像
服务器: "ghcr.io/org/mcp-server:latest"
协议方案
使用包管理器运行 MCP 服务器：
# 通过 uv 运行 Python
服务器: "uvx://python-mcp-package@1.0.0"
# 通过 npm 运行 Node.js
服务器: "npx://node-mcp-package@2.0.0"
# Go 模块
服务器: "go://github.com/org/go-mcp-server"
MCP 配置文件生成
该插件会自动生成一个 MCP 配置文件，其中包含所有已启动的 MCP 服务器的连接详情。这使得 MCP 客户端可以轻松发现并连接到可用的服务器。
配置文件格式
生成的文件遵循标准的 MCP 配置格式：
{
"mcpServers": {
"fetch-server": {
"url": "http://localhost:8080/mcp",
"type": "streamable-http"
},
"github-server": {
"url": "http://localhost:8081/sse#github-server",
"type": "sse"
}
}
}
URL 格式细节
- SSE 服务器：
http://localhost:{端口}/sse#{服务器名称} - 可流式传输的 HTTP 服务器：
http://localhost:{端口}/mcp - 类型：
"sse"或"streamable-http"
环境变量
插件导出 BUILDKITE_PLUGIN_TOOLHIVE_MCP_CONFIG_FILE 指向生成的配置文件：
echo "MCP 配置文件: $BUILDKITE_PLUGIN_TOOLHIVE_MCP_CONFIG_FILE"
cat $BUILDKITE_PLUGIN_TOOLHIVE_MCP_CONFIG_FILE
与 MCP 客户端一起使用
步骤:
- 命令: |
# 使用生成的 MCP 配置与您的工具
my-mcp-client --config $BUILDKITE_PLUGIN_TOOLHIVE_MCP_CONFIG_FILE
# 或者编程地读取配置
python -c "
import json
import os
config_file = os.environ['BUILDKITE_PLUGIN_TOOLHIVE_MCP_CONFIG_FILE']
with open(config_file) as f:
config = json.load(f)
print('可用的 MCP 服务器:', list(config['mcpServers'].keys()))
"
插件:
- StacklokLabs/toolhive#v0.0.2:
服务器: "fetch"
mcp-config-file: "./my_mcp_config.json"
工作原理
- 环境钩子：检查 ToolHive 是否可用，如需则下载
- 预命令钩子：根据给定配置启动指定的 MCP 服务器
- 命令执行：您的管道命令在 MCP 服务器可用的情况下运行
- 预退出钩子：停止并移除 MCP 服务器（如果启用了清理）
服务器命名
插件会自动生成唯一的服务器名称以避免冲突：
- 如果通过
名称选项提供了自定义名称，则使用该名称 - 否则生成：
构建-{构建编号}-步骤-{步骤键}-{服务器名称} - 名称会被规范化（小写，特殊字符替换为连字符）
要求
- Docker 或 Podman 容器运行时
- 下载 ToolHive 的互联网访问权限（如果尚未安装）
- 运行容器所需的足够权限
故障排除
ToolHive 安装问题
如果 ToolHive 安装失败：
- 检查互联网连接
- 验证 GitHub 发布是否可访问
- 确保有足够的磁盘空间
- 检查安装目录的文件权限
MCP 服务器启动问题
如果 MCP 服务器无法启动：
- 查看服务器日志：
thv 日志 <服务器名称> - 验证服务器配置
- 确保所需密钥可用
- 检查容器运行时（Docker/Podman）状态
端口冲突
如果您遇到端口冲突：
- 使用
代理端口选项指定不同的端口 - 检查是否有其他服务使用相同的端口
- 使用动态端口分配（默认行为）
示例
包含所有选项的完整示例
步骤:
- 标签: "复杂的 MCP 服务器设置"
命令: |
echo "MCP 服务器正在运行"
curl http://localhost:9000/健康
插件:
- StacklokLabs/toolhive#v0.0.2:
服务器: "my-registry/custom-mcp:v2.0.0"
名称: "my-custom-server"
传输: "sse"
代理端口: 9000
密钥:
- 名称: "api-token"
目标: "API_TOKEN"
- 名称: "db-password"
目标: "DATABASE_PASSWORD"
卷:
- "./config:/app/config:ro"
- "./data:/app/data"
参数:
- "--log-level=debug"
- "--config=/app/config/server.yml"
权限配置文件: "网络"
toolhive-version: "v0.0.33"
清理: true
mcp-config-file: "./custom_mcp_config.json"
mcp-config-cleanup: false
多个步骤使用不同服务器
步骤:
- 标签: "步骤 1: 使用 Fetch 服务器"
命令: "测试-fetch-功能"
插件:
- StacklokLabs/toolhive#v0.0.2:
服务器: "fetch"
- 标签: "步骤 2: 使用 GitHub 服务器"
命令: "测试-github-集成"
插件:
- StacklokLabs/toolhive#v0.0.2:
服务器: "github"
密钥:
- 名称: "github-token"
目标: "GITHUB_PERSONAL_ACCESS_TOKEN"
单个步骤中的多个 MCP 服务器
您可以在单个步骤中运行多个 MCP 服务器，只需多次调用插件即可：
步骤:
- 标签: "使用多个 MCP 服务器"
命令: |
echo "现在两个服务器都在运行"
curl http://localhost:8080/fetch-endpoint
curl http://localhost:8081/github-endpoint
插件:
- StacklokLabs/toolhive#v0.0.2:
服务器: "fetch"
名称: "fetch-server"
代理端口: 8080
- StacklokLabs/toolhive#v0.0.2:
服务器: "github"
名称: "github-server"
代理端口: 8081
密钥:
- 名称: "github-token"
目标: "GITHUB_PERSONAL_ACCESS_TOKEN"
重要提示：对于多个服务器
- 每个服务器必须有一个唯一的
名称以避免冲突 - 如果指定了
代理端口，每个服务器应使用不同的端口 - 所有服务器将在步骤结束时自动清理
- 服务器按插件列表中的顺序启动
贡献
- 分叉仓库
- 创建功能分支
- 进行更改
- 测试插件
- 提交拉取请求
许可证
本项目根据 Apache 许可证 2.0 授权 - 详情见 LICENSE 文件。