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 标志	仅路径和输出	+ --record/--key/--tags/--name/--note/-t/-e/--scenario-name/-v/--overrides/-p/--dotenv/-k/--count/-s
AWS Fargate（run-fargate）	❌	✅ 完整标志集
parse_results 计数器	仅 http.*	所有计数器 + 速率 + 嵌套摘要
解析原始 stdout（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 模板	❌	✅ 面向 Agent 的指南
Docker 镜像	❌	✅ 多架构（Docker Hub + GHCR）
MCP Registry 收录	❌	✅ io.github.kosiakMD/artillery-mcp
serverVersion 准确性	硬编码	✅ 运行时从 package.json 读取
测试	122	163

面向 Agent 的快速入门（Claude Code / Cursor）

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

会生成两个文件（如果文件已存在则跳过；使用 --force 覆盖）：

• .artillery-mcp.config.json — 含注释字段的入门模板
• .ai/skills/artillery-mcp/SKILL.md — 面向 Agent 的指南（何时调用哪个工具、常见模式、注意事项）

使用实际的流程／路径编辑配置后，在 Agent 中注册 MCP 并重启会话：

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

安装／快速入门（零配置）

开箱即用——无需配置文件。可作为 stdio MCP 服务运行， 适用于 Claude Code、Claude Desktop、Cursor 及任何兼容 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；Artillery CLI 已添加到 PATH（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；否则只读即可（调用保存配置相关工具时只会返回错误）。

MCP 客户端配置（Claude Desktop / Cursor）——将 MCP 指向 docker，而不是 npx：

{
  "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	单次运行的最长时长	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 运行 smoke / baseline / soak / spike 预设测试。
• 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 — 通过 artillery report 将现有 JSON 结果文件转换为 HTML。如果你有来自 CI 构件的 JSON，并希望生成可分享的 HTML 而无需重新运行，请使用此工具。
• compare_results — 对比两个 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 — 按顺序匹配；以第一个匹配项为准
• 一个分桶可以设置 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 Agent 指引模板
• 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，并提供易读的错误消息（“预期 'flows' 为对象，却得到 null，位于第 3 行”）。快速失败并提示查看 README。
• 支持 YAML 配置 — 使用体积小巧的内置 YAML 解析器读取 .artillery-mcp.config.yml（保持依赖精简）。
• Playwright Docker 变体 — 提供预装 Chromium 的 kosiakmd/artillery-mcp:latest-playwright，供使用 engine: playwright 脚本的用户使用。单独使用一个标签，以保持基础镜像精简。

v0.3+

• Artillery Lambda + Azure ACI 工具 — 提供 run_lambda、run_aci，与 run_fargate 功能对等。
• run_project_lt 矩阵模式 — {"matrix": {"flow": ["free","paid"], "env": ["staging","prod"]}} → 并行运行 4 次。
• 按 flow 设置配置覆盖项 — 每个 flow 可单独设置 counterGroups / defaultTags / environments，而非全局共用。
• 通过 MCP 进度事件流式传输中间指标，让 Agent 在运行期间即可查看 RPS/错误，而非只能在完成后查看。
• 内置预设库 — 可通过配置选择 smoke / baseline / soak / spike，而不只是使用内联 YAML。
• 在稳定 URL 发布 JSON Schema，以便 IDE 为 .artillery-mcp.config.json 提供自动补全。
• 提供计数器分组匹配器的插件 API，支持正则表达式之外的方式 — 例如 JSONPath、Wasm 过滤器，或调用用户提供的 JS。
• 结构化的 run_report 变体 — 在返回 HTML 路径的同时返回提取出的摘要文本，让 AI Agent 无需加载文件即可查看内容。
• 支持 Smithery — 在需求足够时添加 StreamableHTTP 传输和托管部署（需要使用 OAuth 风格的会话配置来管理每位用户的 API 密钥）。

考虑中

• Grafana / Prometheus 集成——将指标推送到用户提供的 Prometheus 端点，而不是（或同时）推送到 Artillery Cloud。
• 原生 Artillery Pro 支持——如果用户提出需求，则支持企业功能。
• TUI 仪表板，用于通过 MCP 之外的方式启动的长时间运行测试（独立模式）。
• 社区 MCP 目录——在 mcp-get.com、PulseMCP 上手动注册，以提高可发现性。
• 向上游贡献——将 read_artillery_output、run_fargate 和 full flag surface 补丁作为 PR 提交给 @jch1887/artillery-mcp-server；如果合并，此分支将成为其上层的轻量配置插件。

欢迎提交问题、功能请求和 PR：github.com/kosiakMD/artillery-mcp/issues。

欢迎提交问题和功能请求：github.com/kosiakMD/artillery-mcp/issues。

致谢

从 jch1887/artillery-mcp-server 分叉而来 （MIT）。新增内容和修改内容列表请参见 NOTICE。

许可证

MIT——详见 LICENSE。必须保留上游项目和此分支的版权声明，适用于软件的实质性部分。