Bitbucket Pipelines MCP 服务器

一个 MCP (模型上下文协议) 服务器，提供与 Bitbucket Pipelines 交互的工具。此服务器实现了 MCP 标准，可以被诸如 Claude 之类的语言模型用于管理 Bitbucket Pipelines。

可用工具

1. mcp_bitbucket_list_pipelines

列出支持分页的 pipelines。

参数：

{
  page?: number;    // 页码 (默认: 1)
  pagelen?: number; // 每页条目数 (默认: 10)
}

2. mcp_bitbucket_trigger_pipeline

触发一个新的 pipeline。

参数：

{
  target: {
    ref_type: string;   // 引用类型 (例如: "branch", "tag")
    type: string;       // 目标类型
    ref_name: string;   // 引用名称 (例如: "main", "develop")
    selector?: {        // 可选
      type: string;
      pattern: string;
    }
  },
  variables?: Array<{   // 可选
    key: string;
    value: string;
    secured?: boolean;
  }>
}

3. mcp_bitbucket_get_pipeline_status

获取特定 pipeline 的状态。

参数：

{
  uuid: string;  // pipeline 的 UUID
}

4. mcp_bitbucket_stop_pipeline

停止 pipeline 的执行。

参数：

{
  uuid: string;  // pipeline 的 UUID
}

配置

环境变量

创建一个 .env 文件，包含以下变量：

# 必需
BITBUCKET_ACCESS_TOKEN=你的_token_在这里
BITBUCKET_WORKSPACE=你的_workspace
BITBUCKET_REPO_SLUG=你的_仓库

# 可选
BITBUCKET_API_URL=https://api.bitbucket.org/2.0  # API URL (默认: https://api.bitbucket.org/2.0)

安装和执行

使用 Docker (推荐)

1. 克隆仓库：

git clone [仓库-url]
cd bitbucket-pipelines-mcp

2. 配置环境变量：

cp .env.example .env
# 编辑 .env 文件，填入你的配置

3. 启动服务器：

docker-compose up -d

4. 检查服务器状态：

# 使脚本可执行
chmod +x docker-mcp-test.js
# 执行脚本
node docker-mcp-test.js

5. 使用客户端脚本与服务器交互：

# 使脚本可执行
chmod +x docker-mcp-client.js
# 执行脚本
node docker-mcp-client.js

6. 手动与服务器交互：

# 直接调用示例
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"name":"Test Client","version":"1.0.0","protocolVersion":"0.3.0","capabilities":{},"clientInfo":{"name":"Test Client","version":"1.0.0"}}}' | docker exec -i bitbucket-pipelines-mcp_mcp-server_1 node dist/index.js

本地安装

1. 克隆仓库：

git clone [仓库-url]
cd bitbucket-pipelines-mcp

2. 安装依赖：

npm install

3. 配置环境变量：

cp .env.example .env
# 编辑 .env 文件，填入你的配置

4. 编译项目：

npm run build

5. 启动服务器：

npm start

与 Cursor 集成

方法 1：直接编辑 mcp.json 文件 (推荐)

与 Cursor 集成最直接有效的方法是编辑主 mcp.json 文件：

1. 确保 Docker MCP 服务器正在运行：

npm run docker:up

2. 找到 Cursor 配置目录中的 mcp.json 文件：

   • Linux: ~/.cursor/mcp.json
   • macOS: ~/Library/Application Support/Cursor/mcp.json
   • Windows: %APPDATA%\Cursor\mcp.json

3. 编辑 mcp.json 文件，并在主部分添加以下配置：

"bitbucket-pipelines": {
  "command": "docker",
  "args": [
    "exec",
    "-i",
    "bitbucket-pipelines-mcp_mcp-server_1",
    "node",
    "dist/index.js"
  ]
}

4. 保存文件并重启 Cursor。

5. 现在你可以直接在 Cursor 中使用 Bitbucket Pipelines 工具，通过以下方式调用它们：

@bitbucket-pipelines

方法 2：使用单独的配置文件

要在 Cursor IDE 中直接使用 Bitbucket Pipelines MCP，请按照以下步骤操作：

1. 确保 Docker MCP 服务器正在运行：

npm run docker:up

2. 在项目根目录中创建一个 mcp.config.json 文件，内容如下：

{
  "name": "bitbucket-pipelines-mcp",
  "description": "Bitbucket Pipelines MCP Server 用于与 Bitbucket Pipelines 交互",
  "version": "1.0.0",
  "command": {
    "binary": "docker",
    "args": ["exec", "-i", "bitbucket-pipelines-mcp_mcp-server_1", "node", "dist/index.js"]
  },
  "tools": [
    {
      "name": "mcp_bitbucket_list_pipelines",
      "description": "列出支持分页的 pipelines"
    },
    {
      "name": "mcp_bitbucket_trigger_pipeline",
      "description": "触发一个新的 pipeline"
    },
    {
      "name": "mcp_bitbucket_get_pipeline_status",
      "description": "获取特定 pipeline 的状态"
    },
    {
      "name": "mcp_bitbucket_stop_pipeline",
      "description": "停止 pipeline 的执行"
    }
  ]
}

3. 将此文件复制到 Cursor 的配置目录：

# 对于 Linux
mkdir -p ~/.config/Cursor/mcp/
cp mcp.config.json ~/.config/Cursor/mcp/bitbucket-pipelines-mcp.json

# 对于 macOS
mkdir -p ~/Library/Application\ Support/Cursor/mcp/
cp mcp.config.json ~/Library/Application\ Support/Cursor/mcp/bitbucket-pipelines-mcp.json

# 对于 Windows
mkdir -p %AppData%\Cursor\mcp\
copy mcp.config.json %AppData%\Cursor\mcp\bitbucket-pipelines-mcp.json

4. 重启 Cursor 以应用更改。

5. 现在你可以直接在 Cursor 中使用 Bitbucket Pipelines 工具，通过以下方式调用它们：

@modelcontextprotocol/bitbucket-pipelines-mcp

6. 要访问特定工具，请使用：

@modelcontextprotocol/bitbucket-pipelines-mcp/mcp_bitbucket_list_pipelines

与 MCP 一起使用

此服务器实现了模型上下文协议 (MCP)，允许语言模型与 Bitbucket Pipelines 交互。 该服务器使用 StdioServerTransport 接口，该接口允许通过 stdin/stdout 进行通信。

使用 MCP SDK 的示例

import { Client } from '@modelcontextprotocol/sdk/client';
import { ChildProcessTransport } from '@modelcontextprotocol/sdk/client/child-process';

async function main() {
  // 初始化 MCP 客户端
  const client = new Client({
    transport: new ChildProcessTransport({
      command: 'node',
      args: ['dist/index.js'],
      env: {
        BITBUCKET_ACCESS_TOKEN: '你的_token',
        BITBUCKET_WORKSPACE: '你的_workspace',
        BITBUCKET_REPO_SLUG: '你的_仓库'
      }
    })
  });

  // 列出可用的工具
  const tools = await client.listTools();
  console.log('可用的工具:', tools);

  // 列出 pipelines
  const pipelines = await client.callTool('mcp_bitbucket_list_pipelines', { page: 1, pagelen: 5 });
  console.log('Pipelines:', pipelines);

  // 关闭客户端
  await client.close();
}

main().catch(console.error);

开发

可用脚本

• npm run build: 编译 TypeScript 项目
• npm start: 启动服务器
• npm run dev: 使用 ts-node 在开发模式下启动服务器
• npm test: 运行测试

项目结构

.
├── src/
│   ├── index.ts                # MCP 服务器的入口点
│   └── tools/
│       └── bitbucket-pipelines.ts  # MCP 工具的实现
├── package.json               # 依赖和脚本
└── tsconfig.json              # TypeScript 配置

实现模型上下文协议

此项目使用 @modelcontextprotocol/sdk 来实现 MCP 服务器。 主要特点是：

1. 通过 stdio 通信：服务器通过 stdin/stdout 进行通信，从而可以轻松地与 LLM 集成。
2. 标准工具格式：所有工具都遵循 MCP 协议定义的格式。
3. 强大的错误处理：MCP 协议标准化了如何将错误传达给客户端。

贡献

1. Fork 项目
2. 创建你的 feature 分支 (git checkout -b feature/新-feature)
3. 提交你的更改 (git commit -am '添加新 feature')
4. 推送到分支 (git push origin feature/新-feature)
5. 创建 Pull Request

使用直接命令进行测试

你可以使用以下命令手动测试服务器：

初始化

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"name":"Test Client","version":"1.0.0","protocolVersion":"0.3.0","capabilities":{},"clientInfo":{"name":"Test Client","version":"1.0.0"}}}' | docker exec -i bitbucket-pipelines-mcp_mcp-server_1 node dist/index.js

列出工具

echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | docker exec -i bitbucket-pipelines-mcp_mcp-server_1 node dist/index.js

调用工具

echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"mcp_bitbucket_list_pipelines","input":{"page":1,"pagelen":5}}}' | docker exec -i bitbucket-pipelines-mcp_mcp-server_1 node dist/index.js