cucumberstudio

Cucumber Studio MCP サーバー

Claude Code と Pu-Er でバイブコーディング 🍵

Cucumber Studio のテストプラットフォームへの LLM アクセスを提供する Model Context Protocol（MCP）サーバーです。このサーバーにより、AI アシスタントは Cucumber Studio からテストシナリオ、アクションワード、テスト実行、プロジェクト情報を取得できます。

特長

• デュアルトランスポート対応 - セッション管理機能を備えた STDIO および Streamable HTTP トランスポート
• プロジェクト管理 - プロジェクトの一覧表示と詳細の取得
• シナリオへのアクセス - テストシナリオの閲覧とタグによる検索
• アクションワード - 再利用可能なテストステップと定義へのアクセス
• テスト実行 - テスト実行、実行結果、ビルド情報の表示
• ホットリロード開発 - tsx --watch によるファイル変更時のサーバーの即時再起動
• 設定可能なログ記録 - 複数の出力先に対応した構造化ログ記録
• 包括的なエラー処理 - 詳細なフィードバックを備えた堅牢なエラー処理
• 型安全性 - Zod バリデーションによる完全な TypeScript 実装
• 包括的なテスト - Vitest と MSW による 82% 以上のテストカバレッジ

インストール

デスクトップ拡張機能（MCPB）のインストール

この MCP サーバーを使う最も簡単な方法は、デスクトップ拡張機能として利用することです。

1. 拡張機能をダウンロード：最新の .mcpb ファイルをリリースページから取得します（各リリースから自動的にビルドされます）。
2. 拡張機能をインストール：対応する AI デスクトップアプリに拡張機能をインポートします。
3. 認証情報を設定：拡張機能の設定から Cucumber Studio API の認証情報を設定します。
   • アクセストークン：Cucumber Studio API のアクセストークン
   • クライアント ID：Cucumber Studio のクライアント ID
   • ユーザー ID：Cucumber Studio のユーザー ID

拡張機能が MCP サーバーのセットアップと通信を自動的に処理します。

クイックスタート（コマンドライン）

npx で直接実行します（インストール不要）。

npx cucumberstudio-mcp

先に環境変数を設定してください。

export CUCUMBERSTUDIO_ACCESS_TOKEN="your_token"
export CUCUMBERSTUDIO_CLIENT_ID="your_client_id"
export CUCUMBERSTUDIO_UID="your_uid"

開発用インストール

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

git clone https://github.com/HeroSizy/cucumberstudio-mcp.git
cd cucumberstudio-mcp

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

npm install

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

cp .env.example .env
# Edit .env with your Cucumber Studio API credentials

4. サーバーをビルドします。

npm run build

Docker のサポート

ビルド済みイメージを使用する（推奨）

Docker Hub の公式 Docker イメージを実行します。

# With environment file
docker run --env-file .env herosizy/cucumberstudio-mcp

# With environment variables
docker run -e CUCUMBERSTUDIO_ACCESS_TOKEN=your_token \
           -e CUCUMBERSTUDIO_CLIENT_ID=your_client_id \
           -e CUCUMBERSTUDIO_UID=your_uid \
           herosizy/cucumberstudio-mcp

Docker Compose を使用する

1. 環境変数を設定します。

cp .env.example .env
# Edit .env with your Cucumber Studio API credentials

2. 事前ビルド済みイメージを使用するように docker-compose.yml を更新します。

version: '3.8'
services:
  cucumberstudio-mcp:
    image: herosizy/cucumberstudio-mcp
    env_file:
      - .env
    restart: unless-stopped
    ports:
      - "${MCP_PORT:-3000}:3000"

3. Docker Compose で実行します。

docker-compose up

ローカルでビルドする

1. イメージをビルドします。

npm run docker:build

2. コンテナを実行します。

npm run docker:run

Docker のセットアップには、本番環境での使用に向けたヘルスチェックと自動再起動が含まれています。マルチステージビルドにより、実行時の依存関係のみを含む最適化された本番用イメージ（約 150 MB）が作成されます。

設定

このサーバーには Cucumber Studio API の認証情報が必要です。Cucumber Studio アカウントの設定から取得してください。

必須の環境変数

• CUCUMBERSTUDIO_ACCESS_TOKEN - API アクセストークン
• CUCUMBERSTUDIO_CLIENT_ID - クライアント ID
• CUCUMBERSTUDIO_UID - ユーザー ID

任意の設定

• CUCUMBERSTUDIO_BASE_URL - API ベース URL（デフォルト：https://studio.cucumberstudio.com/api）
• MCP_TRANSPORT - トランスポートの種類：stdio（デフォルト）、http、または streamable-http
• MCP_PORT - HTTP トランスポートのポート（デフォルト：3000）
• MCP_HOST - HTTP トランスポートのホスト（デフォルト：0.0.0.0）
• MCP_CORS_ORIGIN - CORS オリジンの設定（デフォルト：true）

ロギングの設定

• LOG_LEVEL - ログレベル：error、warn、info、debug、trace（デフォルト：info）
• LOG_API_RESPONSES - Cucumber Studio API のレスポンスを記録します（デフォルト：false）
• LOG_REQUEST_BODIES - デバッグ用に API リクエストボディを記録します（デフォルト：false）
• LOG_RESPONSE_BODIES - デバッグ用に API レスポンスボディを記録します（デフォルト：false）
• LOG_TRANSPORT - ログ出力先：console、stderr、file、none（デフォルト：stderr）
• LOG_FILE - ログファイルのパス（LOG_TRANSPORT=file の場合に必須）

使い方

トランスポートのオプション

サーバーは STDIO と HTTP の両方のトランスポートに対応しています。

STDIO トランスポート（デフォルト）

# Development
npm run dev

# Production
npm start

HTTP トランスポート

# Development
npm run dev:http

# Production
npm run start:http

MCP クライアントでの使用

デスクトップ拡張機能（推奨）

.mcpb 拡張機能ファイルを、互換性のある AI デスクトップアプリケーションに直接インポートします。拡張機能の設定インターフェースから、すべての設定を行えます。

MCP の手動設定

MCP クライアントを手動で設定する場合：

オプション 1：NPX（推奨）

{
  "mcpServers": {
    "cucumberstudio": {
      "command": "npx",
      "args": ["cucumberstudio-mcp"],
      "env": {
        "CUCUMBERSTUDIO_ACCESS_TOKEN": "your_token",
        "CUCUMBERSTUDIO_CLIENT_ID": "your_client_id",
        "CUCUMBERSTUDIO_UID": "your_uid"
      }
    }
  }
}

オプション 2：ローカルインストール

{
  "mcpServers": {
    "cucumberstudio": {
      "command": "node",
      "args": ["/path/to/cucumberstudio-mcp/build/index.js"],
      "env": {
        "CUCUMBERSTUDIO_ACCESS_TOKEN": "your_token",
        "CUCUMBERSTUDIO_CLIENT_ID": "your_client_id",
        "CUCUMBERSTUDIO_UID": "your_uid"
      }
    }
  }
}

オプション 3：Docker Hub イメージ

{
  "mcpServers": {
    "cucumberstudio": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "--env-file", "/path/to/.env", "herosizy/cucumberstudio-mcp"]
    }
  }
}

オプション 4：ローカル Docker ビルド

{
  "mcpServers": {
    "cucumberstudio": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "--env-file", "/path/to/.env", "cucumberstudio-mcp"]
    }
  }
}

利用可能なツール

プロジェクトツール

• cucumberstudio_list_projects - アクセス可能なすべてのプロジェクトを一覧表示します
• cucumberstudio_get_project - プロジェクトの詳細情報を取得します

シナリオツール

• cucumberstudio_list_scenarios - プロジェクト内のシナリオを一覧表示します
• cucumberstudio_get_scenario - シナリオの詳細情報を取得します
• cucumberstudio_find_scenarios_by_tags - タグでシナリオを検索します

アクションワードツール

• cucumberstudio_list_action_words - 再利用可能なアクションワードを一覧表示します
• cucumberstudio_get_action_word - アクションワードの詳細情報を取得します
• cucumberstudio_find_action_words_by_tags - タグでアクションワードを検索します

テスト実行ツール

• cucumberstudio_list_test_runs - テスト実行を一覧表示します
• cucumberstudio_get_test_run - テスト実行の詳細情報を取得します
• cucumberstudio_get_test_executions - 個々のテスト結果を取得します
• cucumberstudio_list_builds - ビルドを一覧表示します
• cucumberstudio_get_build - ビルドの詳細を取得します
• cucumberstudio_list_execution_environments - 実行環境を一覧表示します

開発

ホットリロードでの開発

サーバーは迅速な開発のためのホットリロードに対応しています。

# STDIO transport with hot reload
npm run dev

# HTTP transport with hot reload  
npm run dev:http

変更が検出されると、ファイルは自動的に再コンパイルされ、サーバーが再起動します。

テストと品質

# Install dependencies
npm install

# Run type checking
npm run typecheck

# Run linting
npm run lint

# Build for production
npm run build

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage (82%+ coverage)
npm run test:coverage

# Run tests with UI
npm run test:ui

ビルドのオプション

# Production build (default) - optimized for size, no .d.ts/.js.map files
npm run build

# Development build - includes source maps and type declarations for debugging
npm run build:dev

MCPB 拡張機能の開発

# Validate manifest.json
npm run mcpb:validate

# Build complete MCPB extension for local testing (optimized production build)
npm run mcpb:build

# Check info about built extension
npm run mcpb:info

# Clean up build artifacts
npm run mcpb:clean

アーキテクチャ

このサーバーは、モジュール式で本番環境に対応したアーキテクチャで構築されています。

コア技術

• TypeScript - 厳格な設定による完全な型安全性
• デュアルトランスポート - ローカル利用向けの STDIO、リモートアクセス向けの Streamable HTTP
• Zod - API 入力と設定のランタイム検証
• Axios - 包括的なエラー処理とロギングを備えた HTTP クライアント
• MCP SDK - Model Context Protocol の公式実装
• Express - CORS、セキュリティミドルウェア、セッション管理を備えた HTTP サーバー
• Vitest - コードカバレッジ 82％以上のモダンなテストフレームワーク
• MSW - 現実的な API テストのための Mock Service Worker

主な機能

• セッション管理 - セッションの追跡とクリーンアップに対応した HTTP トランスポート
• 包括的なログ記録 - 出力先とログレベルを設定できる構造化ログ
• エラー処理 - 詳細なフィードバックと復旧機能を備えた堅牢なエラー処理
• セキュリティ - オリジン検証、CORS 保護、入力のサニタイズ
• ヘルスモニタリング - ヘルスチェックエンドポイントとリクエスト／レスポンスの追跡
• 開発ワークフロー - ホットリロード、包括的なテスト、Docker のサポート

テスト

このプロジェクトには、包括的なテストカバレッジが含まれています。

# Run all tests
npm test

# Run tests with coverage report
npm run test:coverage

# Run tests in watch mode (for development)
npm run test:watch

テストカバレッジには、以下が含まれます。

• すべてのモジュールのユニットテスト
• MCP サーバーの統合テスト
• トランスポート層のテスト
• API クライアントのモックとテスト
• 設定の検証
• エラー処理のシナリオ

公開とリリース

このプロジェクトでは、GitHub Actions による自動リリースを使用しています。バージョンタグがプッシュされると、以下が自動的に実行されます。

1. テストスイート全体を実行 - コードの品質とカバレッジを確認します
2. NPM に公開 - npx cucumberstudio-mcp からパッケージを利用できるようにします
3. Docker イメージをビルドして公開 - マルチプラットフォームイメージを Docker Hub にプッシュします
4. GitHub リリースを作成 - リリースノートとリンクを生成します

リリースの作成

1. package.json のバージョンを更新します。

npm version patch|minor|major

2. リリースを開始するためにタグをプッシュします。

git push origin --tags

3. GitHub Action により、以下が自動的に実行されます。
   • NPM に公開：https://www.npmjs.com/package/cucumberstudio-mcp
   • Docker Hub にプッシュ：https://hub.docker.com/r/herosizy/cucumberstudio-mcp
   • 変更履歴を含む GitHub リリースを作成

必要なシークレット

自動公開を行うには、GitHub リポジトリで以下のシークレットを設定する必要があります。

• NPM_TOKEN - NPM 認証トークン
• DOCKER_USERNAME - Docker Hub のユーザー名
• DOCKER_PASSWORD - Docker Hub のパスワードまたはアクセストークン

コントリビューション

1. リポジトリをフォークします
2. 機能ブランチを作成します
3. 変更を加えます
4. 新しい機能のテストを追加します
5. すべてのテストに合格することを確認します：npm test
6. プルリクエストを送信します

ライセンス

MIT ライセンス - 詳細は LICENSE ファイルを参照してください

リソース

• Cucumber Studio API ドキュメント
• Cucumber Studio API リファレンス
• Model Context Protocol
• MCP TypeScript SDK