artillery-mcp

@kosiakmd/artillery-mcp

Artillery 2.x の機能をより幅広く提供する、置き換え可能な MCP サーバーです。 artillery run と artillery run-fargate の全フラグに対応し、未加工のテキスト出力（artillery-output.txt）を解析して、Artillery が生成するすべてのカウンター／レート／サマリー（http.* のみではありません）を返します。また、任意で設定駆動のプロジェクトランチャーや、カスタムカウンターのグループ化機能も追加できます。

なぜ別の MCP サーバーが必要なのですか？

上流の @jch1887/artillery-mcp-server は優れた出発点でしたが、私たちのチームが日常的に必要としていたいくつかのフラグが不足していました。このパッケージは、より幅広い機能を備えた MIT ライセンスのフォークです。クレジットをご覧ください。

機能	上流版	このパッケージ
run_test_from_file のフラグ	path + output のみ	+ --record/--key/--tags/--name/--note/-t/-e/--scenario-name/-v/--overrides/-p/--dotenv/-k/--count/-s
AWS Fargate（run-fargate）	❌	✅ 全フラグに対応
parse_results のカウンター	http.* のみ	すべてのカウンター + レート + ネストされたサマリー
標準出力の未加工データを解析（artillery-output.txt）	❌	✅ read_artillery_output ツール
HTML レポートの生成	無効な --report フラグを渡す	✅ 個別に artillery report を呼び出す
単独の JSON → HTML 変換（run_report）	❌	✅
--dry-run による検証	動作しない（2.x にはこのフラグがありません）	✅ クライアント側で YAML の構造をチェック
オプトインのプロジェクトランチャー	❌	✅ run_project_lt（設定がある場合）
オプトインのカウンターグループ化	❌	✅ counterBreakdown（設定がある場合）
init スキャフォルダー	❌	✅ npx @kosiakmd/artillery-mcp init
同梱の SKILL.md テンプレート	❌	✅ エージェント向けガイダンス
Docker イメージ	❌	✅ マルチアーキテクチャ（Docker Hub + GHCR）
MCP Registry の掲載	❌	✅ io.github.kosiakMD/artillery-mcp
serverVersion の正確性	ハードコード	✅ 実行時に package.json から読み込み
テスト	122	163

エージェント向けクイックスタート（Claude Code / Cursor）

# In your project root
npx @kosiakmd/artillery-mcp init

2 つのファイルをスキャフォールディングします（すでに存在する場合はスキップされます。上書きするには --force を使用します）。

• .artillery-mcp.config.json — コメント付きフィールドを含むスターターテンプレート
• .ai/skills/artillery-mcp/SKILL.md — エージェント向けガイダンス（各ツールを呼び出すタイミング、一般的なパターン、注意点）

実際のフローやパスを指定して設定を編集した後、エージェントに MCP を登録し、セッションを再起動します。

claude mcp add artillery-mcp -s user \
  -e ARTILLERY_WORKDIR="$PWD" \
  -e ARTILLERY_CLOUD_API_KEY=a9_... \
  -- npx -y @kosiakmd/artillery-mcp

インストール／クイックスタート（設定不要）

そのまま実行できます。設定ファイルは必要ありません。Claude Code、Claude Desktop、Cursor、および MCP 対応クライアント向けに、stdio 経由の MCP サーバーとして動作します。

# Using npx (no install)
npx -y @kosiakmd/artillery-mcp

# Or install globally
npm install -g @kosiakmd/artillery-mcp
artillery-mcp

Claude Code / Cursor — クライアント設定で MCP サーバーとして登録します。

{
  "mcpServers": {
    "artillery-mcp": {
      "command": "npx",
      "args": ["-y", "@kosiakmd/artillery-mcp"],
      "env": {
        "ARTILLERY_WORKDIR": "/absolute/path/to/your/project",
        "ARTILLERY_CLOUD_API_KEY": "a9_..."
      }
    }
  }
}

Claude Code CLI：

claude mcp add artillery-mcp -s user \
  -e ARTILLERY_WORKDIR=/abs/path/to/project \
  -e ARTILLERY_CLOUD_API_KEY=a9_... \
  -- npx -y @kosiakmd/artillery-mcp

前提条件：Node.js ≥ 20、PATH 上に Artillery CLI があること（npm i -g artillery）。

Docker

マルチアーキテクチャイメージです。linux/amd64 と linux/arm64 に対応し、Artillery CLI がプリインストールされています。約 500 MB です（Chromium／Playwright ブラウザーは省略。詳細は以下をご覧ください）。同じビルドから Docker Hub と GitHub Container Registry の両方に公開され、ダイジェストは同一です。

# Docker Hub (discoverable via `docker search artillery-mcp`)
docker pull kosiakmd/artillery-mcp:latest

# GitHub Container Registry
docker pull ghcr.io/kosiakmd/artillery-mcp:latest

実行（プロジェクトを /workspace としてマウントします）：

docker run -i --init --rm \
  -v "$PWD":/workspace \
  -e ARTILLERY_CLOUD_API_KEY="$ARTILLERY_CLOUD_API_KEY" \
  kosiakmd/artillery-mcp:latest

--init により、stdin が閉じられたときに Node プロセスが適切に終了処理されます。save_config ツールで /workspace/saved-configs/ に保存する場合は、/workspace を読み書き可能でマウントしてください。それ以外の場合は読み取り専用でも問題ありません（save-config 系のツールを呼び出すとエラーが返されます）。

MCP クライアント設定（Claude Desktop / Cursor）— npx の代わりに docker を MCP に指定します。

{
  "mcpServers": {
    "artillery-mcp": {
      "command": "docker",
      "args": [
        "run", "-i", "--init", "--rm",
        "-v", "/absolute/path/to/your/project:/workspace",
        "-e", "ARTILLERY_CLOUD_API_KEY",
        "kosiakmd/artillery-mcp:latest"
      ],
      "env": { "ARTILLERY_CLOUD_API_KEY": "a9_..." }
    }
  }
}

Playwright エンジンを使用する場合：Artillery スクリプトで engine: playwright を使う場合は、ベースイメージを Chromium とともに拡張します。

FROM kosiakmd/artillery-mcp:latest
ENV PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=0
RUN apk add --no-cache chromium nss freetype harfbuzz ttf-freefont \
 && npm i -g @playwright/test \
 && npx playwright install chromium

イメージタグ：

• latest — 最新リリース
• v0.1.1、v0.1、v0 — semver による固定（パッチ／マイナー／メジャー）

環境変数

変数	用途	デフォルト
ARTILLERY_BIN	artillery バイナリへのパス	which artillery で自動検出
ARTILLERY_WORKDIR	実行時の作業ディレクトリ	cwd
ARTILLERY_TIMEOUT_MS	1 回の実行の最大時間	1800000（30 分）
ARTILLERY_MAX_OUTPUT_MB	キャプチャする stdout/stderr の上限	10
ARTILLERY_ALLOW_QUICK	quick_test ツールを有効化	true
ARTILLERY_CLOUD_API_KEY	record: true を指定してツールを呼び出す際に使用	—
ARTILLERY_MCP_CONFIG	プロジェクト設定への絶対パス（オプトイン）	—
DEBUG	詳細ログには artillery:mcp:* を指定	—

基本ツール 18 個（設定不要）

テストを実行

• run_test_from_file — 全フラグに対応した artillery run のラッパーです（上記のフラグ一覧を参照）。
• run_test_inline — 同じ機能ですが、YAML テキストを受け取り、一時ファイルに書き込みます。
• quick_test — レート／回数／期間／メソッド／ヘッダー／本文を指定して artillery quick <url> を実行します。
• run_fargate — --region、--cluster、--cpu、--memory、--launch-type、--spot、--subnet-ids、--security-group-ids、--task-role-name、--task-ephemeral-storage、--container-dns-servers、--max-duration、--packages、--secret、--no-assign-public-ip と、実行時に共通のすべてのフラグを指定して artillery run-fargate を実行します。
• run_preset_test — URL に対してスモーク／ベースライン／ソーク／スパイクのプリセットを実行します。
• run_saved_config — 名前を指定して保存済み設定を再実行します。

結果の解析と確認

• parse_results — Artillery の JSON レポートを読み込み、summary、allCounters、allRates、allSummaries、シナリオ、メタデータを返します。
• read_artillery_output — 生の Artillery stdout ダンプ（例：CI から保存した artillery-output.txt）を読み込み、rawText（末尾を切り詰める場合があります）、summaryBlock、counters、rates、metrics（パーセンタイルを含むネストされた値）を返します。
• run_report — 既存の JSON 結果ファイルを artillery report で HTML に変換します。CI アーティファクトの JSON があり、再実行せずに共有可能な HTML が必要な場合に使用します。
• compare_results — 2 つの Artillery JSON 結果を比較し、リグレッションを検出します。

保存済み設定

• save_config / list_configs / get_config / delete_config — 名前付きの Artillery 設定を永続的に保存します。

対話型ビルダー

• wizard_start / wizard_step / wizard_finalize — 対話型のテストビルダーです。

メタ情報

• list_capabilities — Artillery／Node／このサーバーのバージョン、設定済みパス、制限を表示します。

オプション機能 #1 — プロジェクトランチャー（run_project_lt）

.artillery-mcp.config.json ファイルが見つかると有効になります。artillery run ... のフラグ一覧をすべて記述する代わりに、ワンライナーで実行できます。

検出の優先順位：

1. ARTILLERY_MCP_CONFIG 環境変数（絶対パス）
2. ARTILLERY_WORKDIR / cwd から親ディレクトリをたどり、.artillery-mcp.config.json を検索
3. 設定がない場合 → このツールは登録されません

設定（.artillery-mcp.config.json）：

{
  "flows": {
    "browse": "tests/load/browse.yml",
    "buy": "tests/load/buy.yml",
    "combined": "tests/load/combined.yml"
  },
  "environments": ["local", "staging", "prod"],
  "defaultTags": { "repo": "my-app", "owner": "Platform" },
  "tagTemplates": ["type:{flow}", "env:{env}", "source:mcp"],
  "outputDir": "load-test-results"
}

呼び出し：

{ "flow": "buy", "environment": "staging", "note": "canary v42" }

実際に実行されるコマンド：

artillery run \
  --record \
  --name "buy-staging-2026-04-15T00-35-00-000Z" \
  --tags "repo:my-app,owner:Platform,type:buy,env:staging,source:mcp" \
  -e staging \
  --note "canary v42" \
  -o /abs/project/load-test-results/buy-staging-2026-04-15T00-35-00-000Z.json \
  /abs/project/tests/load/buy.yml

オプションのフィールド：

• tagTemplates — {flow}、{env} と、呼び出し元が指定する任意の templateVars（例：{round}）
• outputDir — プロジェクトルートからの相対パス。省略した場合、出力先はプロジェクトルートになります
• defaultTags — テンプレートの適用前にマージされます
• environments — 空の場合、任意の環境名を受け付けます

呼び出し時に上書きできる項目：name、note、extraTags、outputJson、reportHtml、variables、overrides、record: false、validateOnly、extraArgs、templateVars。

オプション機能 #2 — カウンターグループのバケット分け（counterBreakdown）

events.emit('counter', 'shop.step.add_item.happy', 1) でカスタムカウンターを出力すると、 Artillery はそれらを aggregate.counters に集約します。このサーバーはそれらすべてを allCounters で返します。設定に counterGroups を追加すると、parse_results と read_artillery_output のレスポンスで、あらかじめバケット分けされた counterBreakdown も取得できます。CI の合否確認や意味的なグループ分けに最適です。

設定：

{
  "counterGroups": {
    "name": "shopBreakdown",
    "prefix": "shop.",
    "buckets": [
      { "key": "steps",   "match": "^shop\\.step\\." },
      { "key": "cart",    "match": "^shop\\.cart\\." },
      { "key": "payment", "match": "^shop\\.payment\\." },
      { "key": "flow",    "match": "^shop\\.flow\\." },
      { "key": "other",   "default": true }
    ]
  }
}

レスポンス例（parse_results）：

{
  "summary": { "requestsTotal": 1500, "rpsAvg": 25, "latencyMs": { "p95": 850 }, "errors": {} },
  "allCounters": { "shop.step.add_item.happy": 90, "http.requests": 1500, /* ... */ },
  "allRates": { "http.request_rate": 25 },
  "allSummaries": { "http.response_time": { "min": 45, "p99": 1800 } },
  "counterBreakdown": {
    "steps": { "shop.step.add_item.happy": 90, "shop.step.add_item.fail": 2 },
    "cart": { "shop.cart.failure.quantity_update": 1 },
    "payment": {},
    "flow": { "shop.flow.started": 100 },
    "other": {}
  }
}

ルール：

• prefix（任意）— この文字列で始まらないカウンターは無視されます
• buckets — 順序が適用されます。最初に一致したものが優先されます
• 1 つのバケットに default: true を指定できます。一致しなかったすべての項目を受け取ります
• 無効な正規表現の場合、解析時にエラーがスローされます（設定を修正してください）

counterGroups がない場合、counterBreakdown フィールドはレスポンスに含まれません。

設定の完全なリファレンス

{
  "flows": { "<name>": "<relative yaml path>" },  // enables run_project_lt
  "environments": ["<name>", "..."],              // optional whitelist
  "defaultTags": { "<k>": "<v>" },
  "tagTemplates": ["type:{flow}", "env:{env}"],
  "outputDir": "load-test-results",
  "counterGroups": {                              // enables counterBreakdown
    "name": "<output field name, cosmetic>",
    "prefix": "<optional prefix filter>",
    "buckets": [
      { "key": "<name>", "match": "<regex>" },
      { "key": "<name>", "default": true }
    ]
  }
}

セキュリティ

• ネットワーク I/O はありません。ローカルの artillery CLI のみを起動します。
• eval、Function、動的インポートは使用しません。
• インストールフックはありません。
• 依存関係は package-lock.json（コミット済み）で固定されています。
• npm --provenance（SLSA アテステーション）を使用して公開されています。

ロードマップ

リリース済み

• v0.1.1 — Docker イメージ（マルチアーキテクチャ amd64/arm64、Artillery CLI をプリインストール）
• v0.1.2 — artillery-mcp init スキャフォルダーと、同梱の SKILL.md エージェント向けガイダンステンプレート
• v0.1.3 — 不明な CLI 引数で必ずエラーにするよう変更、Dockerfile に skills/ が含まれていない問題を修正
• v0.1.4 — GHCR と並行して Docker Hub にも公開（docker search で見つけやすくするため）
• v0.1.7 — run_report ツール（artillery report で JSON → HTML）。MCP 公式レジストリ（io.github.kosiakMD/artillery-mcp）に掲載

v0.2（次回）

• Artillery Cloud API 統合 — list_recent_runs、get_run_details(runUrl)、compare_to_baseline(runUrl)。artilleryio REST API のリバースエンジニアリング、または Artillery.io との提携が必要です。
• 起動時の設定スキーマ検証 — zod で .artillery-mcp.config.json を解析し、人間が読みやすいエラーメッセージを表示します（「3 行目で 'flows' はオブジェクトである必要がありますが、null が指定されています」）。README への案内を含めて、エラー時は即座に終了します。
• YAML 設定のサポート — 軽量な YAML パーサーを同梱して .artillery-mcp.config.yml を受け付けます（依存関係は軽量に維持します）。
• Playwright 用 Docker バリアント — engine: playwright を使用するスクリプト向けに、Chromium をプリインストールした kosiakmd/artillery-mcp:latest-playwright を提供します。ベースイメージを小さく保つため、別のタグを使用します。

v0.3 以降

• Artillery Lambda と Azure ACI のツール — run_fargate と同等の機能を提供する run_lambda、run_aci。
• run_project_lt のマトリックスモード — {"matrix": {"flow": ["free","paid"], "env": ["staging","prod"]}} → 4 つの実行を並列で行います。
• フローごとの設定オーバーライド — グローバル設定ではなく、フローごとに異なる counterGroups／defaultTags／environments を指定できます。
• MCP の進捗イベントによる中間メトリクスのストリーミング — エージェントが完了時だけでなく、実行中に RPS やエラーを確認できます。
• 組み込みプリセットライブラリ — 設定から smoke／baseline／soak／spike を選択できます（インライン YAML だけに限定されません）。
• 安定した URL で公開する JSON Schema — IDE で .artillery-mcp.config.json の自動補完が使えるようになります。
• 正規表現以外のカウンターグループ照合用プラグイン API — 例：JSONPath、Wasm フィルター、ユーザー提供の JS へのコールバック。
• 構造化された run_report バリアント — HTML のパスとともに抽出した要約テキストを返し、AI エージェントがファイルの読み込みを省略できるようにします。
• Smithery のサポート — 十分な需要があれば、StreamableHTTP トランスポートとホスト型デプロイを追加します（ユーザーごとの API キーに対応する OAuth 形式のセッション設定が必要です）。

検討中

• Grafana / Prometheus との統合 — Artillery Cloud の代わりに（または併用して）、ユーザーが指定した Prometheus エンドポイントにメトリクスをプッシュします。
• Artillery Pro のネイティブサポート — ユーザーから要望があれば、エンタープライズ機能を追加します。
• TUI ダッシュボード — MCP の外部から呼び出した場合（スタンドアロンモード）に、長時間実行されるテストで使用します。
• コミュニティ MCP カタログ — mcp-get.com、PulseMCP に手動で登録し、見つけやすさを高めます。
• 上流へのコントリビューション — read_artillery_output、run_fargate、full flag surface のパッチを、@jch1887/artillery-mcp-server に PR として提供します。マージされた場合、このフォークはその上に載る薄い設定プラグインレイヤーになります。

課題、機能リクエスト、PR を歓迎します：github.com/kosiakMD/artillery-mcp/issues。

課題や機能リクエストを歓迎します：github.com/kosiakMD/artillery-mcp/issues。

クレジット

jch1887/artillery-mcp-server からフォークしました （MIT）。追加・変更内容の一覧については、NOTICE を参照してください。

ライセンス

MIT — 詳細は LICENSE を参照してください。ソフトウェアの実質的な部分において、上流版とこのフォークの両方の著作権表示を保持する必要があります。