zephyr-scale-mcp

zephyr-scale-mcp

セルフホスト型 Jira Server／Data Center 上の Zephyr Scale 用 MCP サーバー（旧称 TM4J）。Claude Code、Claude Desktop、Cursor などの任意の MCP クライアントに、Zephyr Scale REST API v1 の {JIRA_BASE_URL}/rest/atm/1.0 を通じて、テストケース、フォルダー、テストサイクル、実行、テスト計画、添付ファイル、自動化インポートなどのテスト管理を操作する 54 個のツールを提供します。

npm: zephyr-scale-mcp · MCP Registry: io.github.vilaabo/zephyr-scale-mcp · ロシア語版 →

⚠️ 対象範囲：Server／Data Center のみ。 Zephyr Scale Cloud（API v2）と Zephyr Squad は異なる API のため、対象外です。このサーバーはこれらに対して動作しません。

このプロジェクトの目的

ほとんどの Zephyr MCP サーバーは Cloud API を対象としています。Jira をオンプレミスで運用している場合は、代わりに v1 API を使用します。v1 にはいくつもの制約があります。テスト実行は作成後に変更できず、フォルダーの一覧取得はできず、ステータスは大文字と小文字を区別する内部名で指定する必要があり、BDD スクリプトでは Feature: ヘッダーが拒否され、古いプラグインビルドではエンドポイント全体が欠けていることもあります。このサーバーは、エージェントが 400 エラーを一つずつ受けて調べなくても済むよう、そうした知見を組み込んでいます。

• 54 個のツール（公開 42 個＋オプトイン式の内部 API ツール 12 個）。それぞれの説明には、エンドポイント、呼び出し側が推測できない制約、正確なレスポンス形式が記載されています。
• API の盲点を補う複合ツール — add_test_steps は ID に基づいてステップをマージするため（読み取り → マージ → 書き込み）、内容が黙って削除されることはありません。recreate_test_run_with_items は実行の変更不可という制約を回避し、直前の結果を引き継ぐこともできます。ほかに get_issue_test_coverage、get_test_run_summary、clone_test_case、move_test_cases_to_folder があります。
• 古いビルドでの機能低下への対応 — ページネーション対応の結果エンドポイントがない場合は自動的にフォールバックし、複数項目の作成エンドポイントが壊れている場合は項目ごとにフォールバックします。どちらも変更履歴ではなく、実際のレガシー環境で確認されたものです。
• 問題を明確に報告する基盤 — 厳格な zod 入力検証、Retry-After に対応した指数バックオフ付きリトライ、実用的なヒントを含むエラーメッセージ、読み取り専用モード、ログやツール出力へのシークレットの非記録。
• 1181 件のユニットテストとコントラクトテスト（vitest ＋ msw、ネットワーク不使用）に加え、実環境に対する、条件付きで実行するエンドツーエンドシナリオを備えています。

クイックスタート

必要条件：Node.js >= 20、Zephyr Scale プラグインを備えた Jira Server/DC、および個人用アクセストークン（Jira 8.14 以降）またはユーザー名とパスワードの組み合わせ。

クローンは不要です。パッケージは npm にあります。Claude Code：

claude mcp add zephyr-scale \
  --env JIRA_BASE_URL=https://jira.example.com \
  --env JIRA_PAT=<personal access token> \
  --env ZEPHYR_DEFAULT_PROJECT_KEY=PROJ \
  --env ZEPHYR_ALLOW_INTERNAL_API=true \
  -- npx -y zephyr-scale-mcp

Claude Desktop／任意の MCP クライアント（claude_desktop_config.json、.mcp.json）：

{
  "mcpServers": {
    "zephyr-scale": {
      "command": "npx",
      "args": ["-y", "zephyr-scale-mcp"],
      "env": {
        "JIRA_BASE_URL": "https://jira.example.com",
        "JIRA_PAT": "<personal access token>",
        "ZEPHYR_DEFAULT_PROJECT_KEY": "PROJ",
        "ZEPHYR_ALLOW_INTERNAL_API": "true"
      }
    }
  }
}

git clone https://github.com/vilaabo/zephyr-scale-mcp.git
cd zephyr-scale-mcp
npm install
npm run build        # -> dist/index.js

ZEPHYR_ALLOW_INTERNAL_API=true は任意ですが、推奨されます。 公開 API ではまったく実行できない操作に対応する追加の 12 個のツールを登録します。テスト実行をその場で編集する（名前の変更や移動（update_test_run）、キーを変更せずにケースを追加または削除する（add_test_cases_to_run、remove_test_cases_from_run））操作に加え、フォルダー階層の一覧表示（get_folder_tree）、フォルダーの削除（delete_folder）、過去の実行結果の編集（update_test_result_by_id）、API が暗黙に要求する正確なステータス名の取得（get_status_options）ができます。これらは Jira UI 自体が使用する、ドキュメント化されていない同じ /rest/tests/1.0 エンドポイントを呼び出します。ベンダーのサポート対象外であり、別の Zephyr Scale バージョンでは動作が異なる場合や、利用できない場合があります。このトレードオフを受け入れられない場合は、このフラグをオフにしてください。ほかの 42 個のツールには影響しません。

次に、エージェントに health_check を実行するよう依頼します。GET /rest/api/2/myself を使用して接続と認証情報を確認し、ZEPHYR_DEFAULT_PROJECT_KEY が設定されている場合は、/rest/atm/1.0 で Zephyr プラグインが応答することも確認します。

エージェントに依頼できること

• 「フォルダー /Regression/Payments を作成し、このドキュメントで説明されているチェックアウトフローのテストケースを手順ごとに追加してください。」
• 「/Regression にある Draft ケースをすべて見つけて確認し、準備ができているものを Approved にしてください。」
• 「スプリント 42 のサイクルをすべてのスモークケースとともに作成し、このレポートの結果を記録してください。スクリプトにステップがある場合は、ステップごとに記録してください。」
• 「PROJ-123 を対象とするテストケースと、それぞれが最後に合格した日時を教えてください。」 — 課題からそのケースおよび最新の実行結果へのトレーサビリティ。
• 「この Cucumber JSON レポートの ZIP を新しいサイクルとして PROJ に公開してください。」 — 自動化からのインポート。シナリオは @TestCaseKey=PROJ-T1 タグによって BDD ケースと照合されます。
• 「PROJ-T55 にステップ 3 の後から 2 つのステップを追加してください。」 — 既存のステップとその ID は維持されます。
• 「サイクル PROJ-R7 をケースを 3 件追加して再作成し、結果を維持してから、元のサイクルを削除してください。」

設定

テストで確認している保証が 2 つあります。JIRA_PAT と JIRA_PASSWORD は、出力時に取りうるどの形式（生の値、JSON エスケープ、または Base64 の Basic 認証トークン）でも、ログ、ツール出力、エラーメッセージに決して現れません（エラー文にはメソッドとパスのみが含まれます。データが含まれる可能性のあるクエリー文字列は含まれません）。また、stdout は MCP プロトコル専用であり、すべてのログ行は stderr に出力されます。意図的な例外が 1 つあります。6 文字未満のシークレットはそのまま残ります。これを秘匿化すると、何も保護できないまま無関係な出力が破損するためです。サーバーは起動時に警告します。

設定は起動時に検証されます。すべての問題が一度に報告され、中途半端な設定で起動するのではなく、プロセスはゼロ以外の終了コードで終了します。

ツール

54 個のツールがあります。公開されている 42 個は常に登録され、最後のグループの 12 個は ZEPHYR_ALLOW_INTERNAL_API=true の場合にのみ登録されます。

以下は、このサーバーの設計上の制約です。各ツールの説明には、そのツールに関連する制約が繰り返し記載されているため、エージェントは呼び出し時に確認できます。

1. テスト実行は変更できません。 PUT /testrun は存在しないため、実行の名前変更や移動、テストケースの追加・削除はできません。項目は作成時に固定され、実行ステータスは項目のステータスから決まります。回避策：recreate_test_run_with_items（公開 API。同じキーではなく新しいキーが生成されます）、または内部 API の update_test_run ／ add_test_cases_to_run ／ remove_test_cases_from_run（同じキーを使用します）。
2. フォルダーは自動作成されません。 create_test_case、create_test_run、create_test_plan は、存在しないフォルダーを指定すると 400 エラーになります。公開 API ではフォルダーを一覧表示することもできません。また、フォルダーの名前変更には、create_folder が返す数値 ID が必要です。内部 API が有効な場合は、get_folder_tree で取得できます。
3. owner ／ executedBy ／ assignedTo には Jira ユーザーキー（JIRAUSER10000）を指定します。ユーザー名やメールアドレスは指定できません。find_jira_user でユーザーキーを取得できます。
4. TQL の構文は厳格です。 演算子の前後にはスペースが必須です。文字列値は二重引用符で囲み、使用できる接続詞は AND のみです（OR は使用できません）。フォルダーパスは / で始めます。テスト実行の検索条件に指定できるのは projectKey と folder のみです。単一選択／複数選択のカスタムフィールドでは = は使えません。IN を使用してください。
5. ステータス、優先度、環境名は、大文字と小文字が区別される内部名です。 組み込みステータスは UI 上でローカライズして表示されます（Draft のラベルは翻訳されている場合があります）が、カスタムステータスは文字列どおりの名前が使われます。API が実際に受け付ける値は get_status_options で確認できます。実行ステータスが正しくない場合、公開 API は警告なしに無視します。
6. BDD スクリプトにはシナリオ本文のみを指定します。 Given ／ When ／ Then ／ And ／ But の行をそのまま記述してください。Feature: ／ Scenario: で囲んだテキストは 400 Invalid BDD Script として拒否されます。ラッパーはエクスポート時に生成されます。
7. STEP_BY_STEP のステップは PUT 時に ID で同期されます。 ID のないステップは作成され、ID のあるステップは更新されます。また、リストに含まれていない保存済みのステップはすべて削除されます。get_test_case で取得した ID を引き継いで、常に最終的なステップの完全なリストを送信してください。または、読み込み・マージ・書き込みを行う add_test_steps を使用してください。
8. 非推奨のフィールドは意図的に受け付けていません。 issueKey の代わりに issueLinks、executionDate の代わりに actualEndDate、userKey の代わりに executedBy を使用してください。

古いプラグインビルドの特記事項

以下はすべて、実際のレガシー Zephyr Scale Server インスタンスで実行中に確認され、テストでカバーされています。

• サイクルキーには -R ではなく -C プレフィックス（PROJ-C34）が使われる場合があります。 すべての実行キーのパラメーターではキーをそのまま受け取るため、インスタンスに表示されているキーをそのまま渡してください。
• GET /testrun/{key}/testresults/page が存在しない場合があります。 get_test_run_results と get_test_run_summary は、非推奨のフラットエンドポイントにフォールバックしてクライアント側でページネーションを行い、レスポンスに note を追加します。実際に存在しない実行の場合は、引き続き 404 が返されます。
• scriptResults と一緒に送信された全体の status は無視されます。 先にステップの結果を送信してから、update_last_test_result で全体のステータスを設定してください。
• POST /testcase/link-issues は 500 を返す場合があります。 代わりに issueLinks を指定して update_test_case からリンクしてください。
• POST /testcase/bulk は、単一作成が機能していても、どのペイロードでも本文が空の HTTP 500 を返す場合があります。 create_test_cases_bulk は、任意の 5xx の場合、および JSON の 404（このビルドにそのエンドポイントがないことを意味します。プラグインが存在しない場合に Jira が返す HTML の 404 とは異なります）の場合に、ケースを 1 件ずつ作成するフォールバックを行い、成功したものを報告します（#1）。それ以外の 4xx はペイロードエラーであり、再試行されません。
• このビルドでは、実行の項目に含まれていないケースの結果を投稿すると、そのケースが実行に暗黙的に追加されます。 ほかのビルドでは、この呼び出しは 400／404 で拒否されます。結果ツールでは、どちらの動作も説明しています。
• カスタム自動化結果形式は厳密に検証されます。 {"version": 1, "executions": [{"source", "result", "testCase": {"key"}}]} は機能しますが、executionTime などの実行ごとの追加フィールドは Invalid Custom Format JSON file で拒否されます。シナリオに @TestCaseKey=PROJ-T1 が含まれていれば、Cucumber JSON レポートはそのまま機能します。
• download_feature_files には tql クエリパラメーターが必要です — API はこれがない場合、呼び出しを拒否します。
• 実行項目の最後の実行は削除できません。 delete_test_results はこれを拒否します。代わりに項目を削除してください。
• カスタムフィールドがまったく存在しない場合があります — その場合、定義エンドポイントは [] を返します。

開発

npm run typecheck    # tsc --noEmit, strict
npm test             # 1181 unit + contract tests (vitest + msw), no network
npm run build        # tsup -> dist/index.js
npm run smoke        # 13 end-to-end tests, ZEPHYR_E2E=1, real instance required

スモークシナリオは ZEPHYR_E2E=1 の場合を除きスキップされます。実際の JIRA_BASE_URL と認証情報、および専用の ZEPHYR_DEFAULT_PROJECT_KEY が必要です — 実際のエンティティを作成・削除し、公開 API ではフォルダーを削除できないため /mcp-smoke-* フォルダーが残ります。

src/
├── index.ts             # bootstrap: config, tool registration, stdio transport
├── config.ts            # environment validation
├── http.ts              # fetch wrapper: auth, timeouts, retries, error normalization,
│                        #   multipart and binary bodies
├── schemas.ts           # shared parameter schemas, field shapes, recurring description constants
├── toolkit.ts           # defineTool(): strict zod input, read-only guard,
│                        #   JSON / isError response shaping, shared helpers
├── internal.ts          # the UNOFFICIAL /rest/tests/1.0 layer: key -> id resolution,
│                        #   run-item plumbing, status resolution, error hints
├── runResults.ts        # paged run results with the legacy fallback
├── log.ts               # leveled logger, stderr only
└── tools/               # one module per tool family: testCases, testRuns, testResults,
                         #   testPlans, folders, attachments, automation, misc,
                         #   runMaintenance, resultsMaintenance, internalRefs
test/                    # one test module per source module + negative contract tests
                         #   and the gated smoke scenario

バージョン管理と変更履歴

バージョン 1.0.0 です。このリリース以降、ツール名、パラメーター名、レスポンスの形式は公開契約となり、メジャーバージョンでのみ変更されます。CHANGELOG.md を参照してください。

ライセンス

MIT