使用说明

ToolHive Buildkite插件

一个Buildkite插件，支持使用以下方式运行模型上下文协议（MCP）服务器 ToolHive 在您的CI/CD管道中。

特性

自动ToolHive安装：下载并安装ToolHive（如果尚未可用）
MCP服务器管理：在管道执行期间启动、管理和清理MCP服务器
多个服务器源：支持注册表服务器、Docker镜像和协议方案(uvx://, npx://, go://)
灵活的配置：自定义传输方法、端口、卷、密钥等

用法

将插件添加到您的管道步骤中：

steps:
  - label: "Run with MCP Server"
    command: "your-command-here"
    plugins:
      - StacklokLabs/toolhive#v0.0.2:
          server: "fetch"  # Server from ToolHive registry

注册表服务器示例

steps:
  - label: "Use Fetch MCP Server"
    command: "curl http://localhost:8080/some-endpoint"
    plugins:
      - StacklokLabs/toolhive#v0.0.2:
          server: "fetch"
          transport: "stdio"
          proxy-port: 8080

Docker镜像示例

steps:
  - label: "Use Custom MCP Server"
    command: "your-command"
    plugins:
      - StacklokLabs/toolhive#v0.0.2:
          server: "my-registry/my-mcp-server:latest"
          transport: "sse"
          volumes:
            - "/host/path:/container/path:ro"

协议方案示例

steps:
  - label: "Use Python MCP Server"
    command: "your-command"
    plugins:
      - StacklokLabs/toolhive#v0.0.2:
          server: "uvx://some-python-mcp-package@1.0.0"
          transport: "streamable-http"
          args:
            - "--verbose"
            - "--config=/path/to/config"

与秘密

steps:
  - label: "Use GitHub MCP Server"
    command: "your-command"
    plugins:
      - StacklokLabs/toolhive#v0.0.2:
          server: "github"
          secrets:
            - name: "github-token"
              target: "GITHUB_PERSONAL_ACCESS_TOKEN"
            - name: "api-key"
              target: "API_KEY"

配置

必需

选项	类型	描述
`server`	String	要运行的MCP服务器（注册表名、Docker镜像或协议方案）

可选的

选项	类型	默认值	描述
`name`	字符串	自动生成	MCP服务器实例的自定义名称
`transport`	字符串	`""` （自动）	运输方式： `stdio`, `sse`，或 `streamable-http`
`proxy-port`	整数	随机	ToolHive代理的特定端口
`secrets`	阵列	`[]`	传递给MCP服务器的秘密
`volumes`	阵列	`[]`	卷装载格式 `"host-path:container-path[:ro]"`
`args`	阵列	`[]`	要传递给MCP服务器的其他参数
`permission-profile`	字符串	默认值	MCP服务器的权限配置文件
`toolhive-version`	String	最新	要下载的ToolHive的特定版本
`cleanup`	布尔值	`true`	退出时是否清理MCP服务器
`mcp-config-file`	字符串	`./mcp_servers.json`	生成MCP配置文件的路径
`mcp-config-cleanup`	布尔值	`true`	退出时是否删除MCP配置文件

机密配置

Secrets被配置为一个对象数组 name 和 target 属性：

secrets:
  - name: "secret-name-in-toolhive"
    target: "ENVIRONMENT_VARIABLE_NAME"

这 name 指存储在ToolHive的秘密管理系统中的秘密，以及 target 是将在MCP服务器容器中设置的环境变量名称。

请注意，秘密必须在ToolHive中创建，然后才能在插件中使用。

卷配置

卷以Docker卷格式指定为字符串：

volumes:
  - "/host/path:/container/path"      # Read-write mount
  - "/host/path:/container/path:ro"   # Read-only mount

服务器类型

注册表服务器

使用来自的服务器 ToolHive注册表:

# Fetch MCP server
server: "fetch"

# GitHub MCP server
server: "github"

# Filesystem MCP server
server: "filesystem"

Docker镜像

使用任何实现MCP协议的Docker镜像：

# Custom Docker image
server: "my-registry/my-mcp-server:v1.0.0"

# GitHub Container Registry image
server: "ghcr.io/org/mcp-server:latest"

协议方案

使用包管理器运行MCP服务器：

# Python via uv
server: "uvx://python-mcp-package@1.0.0"

# Node.js via npm
server: "npx://node-mcp-package@2.0.0"

# Go module
server: "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:{port}/sse#{server-name}
流式HTTP服务器: http://localhost:{port}/mcp
类型：要么 "sse" 或 "streamable-http"

环境变量

插件导出 BUILDKITE_PLUGIN_TOOLHIVE_MCP_CONFIG_FILE 指向生成的配置文件：

echo "MCP config file: $BUILDKITE_PLUGIN_TOOLHIVE_MCP_CONFIG_FILE"
cat $BUILDKITE_PLUGIN_TOOLHIVE_MCP_CONFIG_FILE

与MCP客户端一起使用

steps:
  - command: |
      # Use the generated MCP configuration with your tools
      my-mcp-client --config $BUILDKITE_PLUGIN_TOOLHIVE_MCP_CONFIG_FILE
      
      # Or read the configuration programmatically
      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('Available MCP servers:', list(config['mcpServers'].keys()))
      "
    plugins:
      - StacklokLabs/toolhive#v0.0.2:
          server: "fetch"
          mcp-config-file: "./my_mcp_config.json"

运作原理

环境挂钩：检查ToolHive是否可用，必要时下载
预命令挂钩：使用给定的配置启动指定的MCP服务器
命令执行：您的管道命令在MCP服务器可用的情况下运行
预出口挂钩：停止并删除MCP服务器（如果启用了清理）

服务器命名

插件会自动生成唯一的服务器名称以避免冲突：

如果通过提供，则使用自定义名称 name 选项
否则将生成： build-{BUILD_NUMBER}-step-{STEP_KEY}-{SERVER_NAME}
名称被规范化（小写，特殊字符被连字符替换）

需求

Docker或Podman容器运行时
互联网访问以下载ToolHive（如果尚未安装）
有足够的权限运行容器

故障排除

ToolHive安装问题

如果ToolHive安装失败：

检查互联网连接
验证GitHub版本是否可访问
确保有足够的磁盘空间
检查安装目录中的文件权限

MCP服务器启动问题

如果MCP服务器无法启动：

检查服务器日志： thv logs <server-name>
验证服务器配置
确保所需的秘密可用
检查容器运行时（Docker/Podman）状态

端口冲突

如果遇到端口冲突：

使用 proxy-port 指定其他端口的选项
检查使用同一端口的其他服务
使用动态端口分配（默认行为）

例子

带所有选项的完整示例

steps:
  - label: "Complex MCP Server Setup"
    command: |
      echo "MCP server is running"
      curl http://localhost:9000/health
    plugins:
      - StacklokLabs/toolhive#v0.0.2:
          server: "my-registry/custom-mcp:v2.0.0"
          name: "my-custom-server"
          transport: "sse"
          proxy-port: 9000
          secrets:
            - name: "api-token"
              target: "API_TOKEN"
            - name: "db-password"
              target: "DATABASE_PASSWORD"
          volumes:
            - "./config:/app/config:ro"
            - "./data:/app/data"
          args:
            - "--log-level=debug"
            - "--config=/app/config/server.yml"
          permission-profile: "network"
          toolhive-version: "v0.0.33"
          cleanup: true
          mcp-config-file: "./custom_mcp_config.json"
          mcp-config-cleanup: false

使用不同服务器的多个步骤

steps:
  - label: "Step 1: Use Fetch Server"
    command: "test-fetch-functionality"
    plugins:
      - StacklokLabs/toolhive#v0.0.2:
          server: "fetch"
          
  - label: "Step 2: Use GitHub Server"
    command: "test-github-integration"
    plugins:
      - StacklokLabs/toolhive#v0.0.2:
          server: "github"
          secrets:
            - name: "github-token"
              target: "GITHUB_PERSONAL_ACCESS_TOKEN"

一步完成多个MCP服务器

通过多次调用插件，您可以在一个步骤中运行多个MCP服务器：

steps:
  - label: "Use Multiple MCP Servers"
    command: |
      echo "Both servers are now running"
      curl http://localhost:8080/fetch-endpoint
      curl http://localhost:8081/github-endpoint
    plugins:
      - StacklokLabs/toolhive#v0.0.2:
          server: "fetch"
          name: "fetch-server"
          proxy-port: 8080
      - StacklokLabs/toolhive#v0.0.2:
          server: "github"
          name: "github-server"
          proxy-port: 8081
          secrets:
            - name: "github-token"
              target: "GITHUB_PERSONAL_ACCESS_TOKEN"

多台服务器的重要注意事项：

每个服务器都必须有一个唯一的 name 避免冲突
每台服务器应使用不同的 proxy-port 如果指定
所有服务器将在步骤结束时自动清理
服务器按照插件列表中显示的顺序启动

贡献

复刻仓库
创建要素分支
进行更改
测试插件
提交拉取请求

许可证

此项目根据Apache许可证2.0获得许可-请参阅许可证文件以获取详细信息。

MCP服务器管理插件

使用说明

ToolHive Buildkite插件

特性

用法

注册表服务器示例

Docker镜像示例

协议方案示例

与秘密

配置

必需

可选的

机密配置

卷配置

服务器类型

注册表服务器

Docker镜像

协议方案

MCP配置文件生成

配置文件格式

URL格式详细信息

环境变量

与MCP客户端一起使用

运作原理

服务器命名

需求

故障排除

ToolHive安装问题

MCP服务器启动问题

端口冲突

例子

带所有选项的完整示例

使用不同服务器的多个步骤

一步完成多个MCP服务器

贡献

许可证

链接

使用说明

ToolHive Buildkite插件

特性

用法

注册表服务器示例

Docker镜像示例

协议方案示例

与秘密

配置

必需

可选的

机密配置

卷配置

服务器类型

注册表服务器

Docker镜像

协议方案

MCP配置文件生成

配置文件格式

URL格式详细信息

环境变量

与MCP客户端一起使用

运作原理

服务器命名

需求

故障排除

ToolHive安装问题

MCP服务器启动问题

端口冲突

例子

带所有选项的完整示例

使用不同服务器的多个步骤

一步完成多个MCP服务器

贡献

许可证

链接

相关 MCP

MCP服务器管理应用

思维导图MCP服务器

MCP服务器

MCP服务器管理命令行工具

Nix开发管理服务器

命令行工具集