Bitbucket Pipelines MCP Server

Bitbucket Pipelines MCP サーバー

Bitbucket Pipelines と連携するためのツールを提供する MCP（Model Context Protocol）サーバーです。このサーバーは MCP 標準を実装しており、Claude などの言語モデルを使って Bitbucket のパイプラインを管理できます。

利用可能なツール

1. mcp_bitbucket_list_pipelines

ページネーションに対応してパイプラインを一覧表示します。

パラメーター：

{
  page?: number;    // Número da página (default: 1)
  pagelen?: number; // Itens por página (default: 10)
}

2. mcp_bitbucket_trigger_pipeline

新しいパイプラインを起動します。

パラメーター：

{
  target: {
    ref_type: string;   // Tipo de referência (ex: "branch", "tag")
    type: string;       // Tipo do alvo
    ref_name: string;   // Nome da referência (ex: "main", "develop")
    selector?: {        // Opcional
      type: string;
      pattern: string;
    }
  },
  variables?: Array<{   // Opcional
    key: string;
    value: string;
    secured?: boolean;
  }>
}

3. mcp_bitbucket_get_pipeline_status

特定のパイプラインのステータスを取得します。

パラメーター：

{
  uuid: string;  // UUID do pipeline
}

4. mcp_bitbucket_stop_pipeline

パイプラインの実行を停止します。

パラメーター：

{
  uuid: string;  // UUID do pipeline
}

設定

環境変数

次の変数を含む .env ファイルを作成します。

# Obrigatórias
BITBUCKET_ACCESS_TOKEN=seu_token_aqui
BITBUCKET_WORKSPACE=seu_workspace
BITBUCKET_REPO_SLUG=seu_repositorio

# Opcionais
BITBUCKET_API_URL=https://api.bitbucket.org/2.0  # URL da API (default: https://api.bitbucket.org/2.0)

インストールと実行

Docker を使用する場合（推奨）

1. リポジトリをクローンします：

git clone [url-do-repositorio]
cd bitbucket-pipelines-mcp

2. 環境変数を設定します：

cp .env.example .env
# Edite o arquivo .env com suas configurações

3. サーバーを起動します：

docker-compose up -d

4. サーバーのステータスを確認するには：

# Torne o script executável
chmod +x docker-mcp-test.js
# Execute o script
node docker-mcp-test.js

5. クライアントスクリプトを使ってサーバーとやり取りするには：

# Torne o script executável
chmod +x docker-mcp-client.js
# Execute o script
node docker-mcp-client.js

6. サーバーと手動でやり取りするには：

# Exemplo de chamada direta
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-do-repositorio]
cd bitbucket-pipelines-mcp

2. 依存関係をインストールします：

npm install

3. 環境変数を設定します：

cp .env.example .env
# Edite o arquivo .env com suas configurações

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. これで、次のように呼び出して Bitbucket Pipelines のツールを Cursor から直接使用できます：

@bitbucket-pipelines

方法 2：別の設定ファイルを使用する

Bitbucket Pipelines MCP を Cursor IDE から直接使用するには、次の手順に従ってください。

1. Docker MCP サーバーが実行中であることを確認します：

npm run docker:up

2. プロジェクトのルートに、次の内容で mcp.config.json ファイルを作成します：

{
  "name": "bitbucket-pipelines-mcp",
  "description": "Bitbucket Pipelines MCP Server para interagir com o 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": "Lista pipelines com suporte a paginação"
    },
    {
      "name": "mcp_bitbucket_trigger_pipeline",
      "description": "Dispara um novo pipeline"
    },
    {
      "name": "mcp_bitbucket_get_pipeline_status",
      "description": "Obtém o status de um pipeline específico"
    },
    {
      "name": "mcp_bitbucket_stop_pipeline",
      "description": "Para a execução de um pipeline"
    }
  ]
}

3. このファイルを Cursor の設定ディレクトリにコピーします：

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

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

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

4. Cursor を再起動して、変更を適用します。

5. これで、次のように呼び出して Bitbucket Pipelines のツールを Cursor から直接使用できます：

@modelcontextprotocol/bitbucket-pipelines-mcp

6. 特定のツールにアクセスするには、次のようにします：

@modelcontextprotocol/bitbucket-pipelines-mcp/mcp_bitbucket_list_pipelines

MCP での使用

このサーバーは Model Context Protocol（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() {
  // Inicializa o cliente MCP 
  const client = new Client({
    transport: new ChildProcessTransport({
      command: 'node',
      args: ['dist/index.js'],
      env: {
        BITBUCKET_ACCESS_TOKEN: 'seu_token',
        BITBUCKET_WORKSPACE: 'seu_workspace', 
        BITBUCKET_REPO_SLUG: 'seu_repositorio'
      }
    })
  });

  // Lista as ferramentas disponíveis
  const tools = await client.listTools();
  console.log('Ferramentas disponíveis:', tools);

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

  // Fechar o cliente
  await client.close();
}

main().catch(console.error);

開発

利用可能なスクリプト

• npm run build：TypeScript プロジェクトをビルドします
• npm start：サーバーを起動します
• npm run dev：ts-node を使って開発モードでサーバーを起動します
• npm test：テストを実行します

プロジェクト構成

.
├── src/
│   ├── index.ts                # Ponto de entrada do servidor MCP
│   └── tools/
│       └── bitbucket-pipelines.ts  # Implementação das tools MCP
├── package.json               # Dependências e scripts 
└── tsconfig.json              # Configuração do TypeScript

Model Context Protocol の実装

このプロジェクトでは、@modelcontextprotocol/sdk を使用して MCP サーバーを実装しています。主な特徴は次のとおりです。

1. stdio による通信：サーバーは stdin/stdout を介して通信するため、LLM と簡単に連携できます。
2. 標準のツール形式：すべてのツールが MCP プロトコルで定義された形式に従います。
3. 堅牢なエラー処理：MCP プロトコルにより、エラーをクライアントに伝える方法が標準化されています。

貢献

1. プロジェクトをフォークします
2. 機能用のブランチを作成します（git checkout -b feature/nova-feature）
3. 変更をコミットします（git commit -am 'Adiciona nova feature'）
4. ブランチにプッシュします（git push origin feature/nova-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