Toolhive Buildkite Plugin

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"

配置

必需

可选的

机密配置

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"

运作原理

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

服务器命名

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

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

需求

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

故障排除

ToolHive安装问题

如果ToolHive安装失败：

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

MCP服务器启动问题

如果MCP服务器无法启动：

1. 检查服务器日志： thv logs
2. 验证服务器配置
3. 确保所需的秘密可用
4. 检查容器运行时（Docker/Podman）状态

端口冲突

如果遇到端口冲突：

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

例子

带所有选项的完整示例

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 如果指定
• 所有服务器将在步骤结束时自动清理
• 服务器按照插件列表中显示的顺序启动

贡献

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

许可证

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

链接

• ToolHive文档
• 模型上下文协议
• Buildkite插件文档

-