使用说明

MCP钻机

用于MCP服务器和网关的高性能压力测试平台。

模拟数千个并发MCP客户端，识别性能瓶颈，并在生产前验证您的基础设施。

专为战斗测试而打造派塔，MCP控制平面和运行时。如果您正在构建MCP基础设施，MCP Drill可以帮助您在用户之前打破它。

为什么选择MCP钻孔？

独立 -在您自己的基础设施上运行所有内容。无外部服务，无云依赖
真实负载模拟 -可配置操作与加权工具选择相结合
多阶段测试 -飞行前、基线、爬坡和浸泡阶段
实时可观测性 -带有SSE流媒体的实时指标仪表板
分布式 -使用多个工作人员水平扩展
安全第一 -内置停止条件可防止失控测试

建筑

┌──────────────────────────────────────────────────┐
│                    Control Plane                 │
│  ┌────────────┐  ┌────────────┐  ┌────────────┐  │
│  │Run Manager │  │ Scheduler  │  │  HTTP API  │  │
│  └────────────┘  └────────────┘  └────────────┘  │
└─────────────────────────┬────────────────────────┘
                          │
            ┌─────────────┼─────────────┐
            │             │             │
      ┌─────┴─────┐ ┌─────┴─────┐ ┌─────┴─────┐
      │  Worker   │ │  Worker   │ │  Worker   │
      │ (VU Pool) │ │ (VU Pool) │ │ (VU Pool) │
      └─────┬─────┘ └─────┬─────┘ └─────┬─────┘
            │             │             │
            └─────────────┼─────────────┘
                          │
                   ┌──────┴──────┐
                   │ MCP Target  │
                   └─────────────┘

组件	角色
控制平面	管理测试运行、安排工作、为API和Web UI提供服务
工人	生成对目标执行MCP操作的虚拟用户（VU）
模拟服务器	内置MCP服务器，配备27个工具，用于隔离测试-- 工具指南
遥测代理	（可选）服务器端CPU/内存监控-- 安装指南

截图

实时性能监控，包括吞吐量、延迟百分比、错误率和服务器资源利用率：

按工具细分，包括成功率、延迟分布和错误分析：

快速开始

选项A:Docker（推荐）

先决条件：Docker引擎+Docker Compose v2(docker compose).
如果您看到构建警告，请确保已安装Buildx(docker buildx version).

git clone https://github.com/bc-dunia/mcpdrill.git
cd mcpdrill

# Core (server + worker)
docker compose up -d

# With mock server for testing
docker compose --profile mock up -d

# Full stack (mock + agent)
docker compose --profile full up -d

打开 http://localhost:8080/ui/logs/ --Web UI嵌入在服务器中。

规模工人： docker compose up -d --scale worker=5

备注

端口绑定到 localhost 默认情况下（请参见 docker-compose.yml).如果需要LAN/远程访问，请更新端口映射。

默认的compose配置在本地开发的不安全模式下运行(--insecure, --insecure-worker-auth)并支持专用网络发现(--allow-private-discovery)用于Docker测试。在未启用身份验证的情况下，不要公开它。

API速率限制在默认组合配置中被禁用(--rate-limit=0)为了避免 429 大批量遥测运输期间的响应。

--profile full 启用遥测代理，并使用额外的容器功能进行PID发现。如果它在您的环境中被阻止，请使用 --profile mock 然后跑 mcpdrill-agent 而是在MCP主机上。

选项B：来源

先决条件：转到1.24+，Node.js 18+（用于Web UI）

git clone https://github.com/bc-dunia/mcpdrill.git
cd mcpdrill
make dev

这将启动环回上的所有服务（不需要身份验证）：

服务	URL
模拟服务器	http://localhost:3000/mcp
控制平面	http://localhost:8080
工人	自动连接

停止 make dev-stop.使用查看日志 make dev-logs.

对于处于开发模式（热重新加载）的Web UI：

cd web/log-explorer
npm install
npm run dev

打开 http://localhost:5173。或者构建并嵌入到服务器中： make frontend 然后重新启动服务器以访问 /ui/logs/.

运行测试

点击 “新运行” 在Web UI中，使用内置向导创建和启动测试。

或者通过CLI：

curl -X POST http://localhost:8080/runs \
  -H "Content-Type: application/json" \
  -d "{\"config\": $(cat examples/quick-start.json)}"

# Start the run (replace with your run_id from the response)
curl -X POST http://localhost:8080/runs/{run_id}/start

结果实时显示在Web UI仪表板中。

备注：快速启动配置目标 http://127.0.0.1:3000/mcp （IPv4）。使用 localhost 可能由于某些系统上的IPv6解析而失败。

可选：服务器资源（CPU/内存）
Web UI可以显示服务器端CPU/内存指标，但这需要可选 mcpdrill-agent。快速启动配置具有 server_telemetry.enabled: false 默认情况下。要启用它，请参阅服务器遥测代理下面的部分。

主要特点

特性	描述
虚拟用户（VU）	使用加权操作组合模拟并发MCP客户端
MCP协议支持	支持现代MCP `2026-07-28` 加上具有自动检测功能的传统协议版本
会话模式	`reuse`, `per_request`, `pool`, `churn`
停止条件	错误率、延迟阈值自动停止
模拟服务器	27个用于隔离测试的内置工具
Web用户界面	实时仪表板、日志资源管理器、运行向导
开放遥测	（可选）使用OTLP导出进行分布式跟踪

模拟服务器

MCP Drill包括一个内置的模拟MCP服务器，其中有27个工具，用于无外部依赖的隔离测试。

可用工具

类别	工具
基本	`fast_echo`, `slow_echo`, `error_tool`, `timeout_tool`, `streaming_tool`
数据处理	`json_transform`, `text_processor`, `list_operations`, `validate_email`, `calculate`, `hash_generator`
API模拟	`weather_api`, `geocode`, `currency_convert`
文件操作	`read_file`, `write_file`, `list_directory`
压力测试	`large_payload`, `random_latency`, `conditional_error`, `degrading_performance`, `flaky_connection`
韧性	`rate_limited`, `circuit_breaker`, `backpressure`, `stateful_counter`, `realistic_latency`

验证它是否有效

确保模拟服务器正在运行（例如。 docker compose --profile mock up -d 或 make dev)打电话之前 localhost:3000.

# List available tools
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

# Call a tool
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"fast_echo","arguments":{"message":"hello"}},"id":2}'

看 examples/quick-start.json 以获得完整的测试配置。完整的工具文档：工具测试指南.

服务器遥测代理（可选）

备注：MCP Drill无需遥测代理即可完美工作。这是一个可选的附加组件，用于将客户端负载测试指标与服务器端资源使用情况相关联。

在负载测试期间，从MCP服务器监控服务器端指标（CPU、内存、线程、文件描述符）。

┌─────────────────────────────┐          ┌─────────────────────────┐
│   Your MCP Server Host      │          │   Control Plane         │
│                             │          │                         │
│  MCP Server   mcpdrill-agent│─────────▶│  Correlates metrics     │
│  (port 3000)       │        │  HTTPS   │  with test runs         │
│       ▲            │        │          │                         │
│       └── monitors─┘        │          │                         │
└─────────────────────────────┘          └─────────────────────────┘

快速设置

# Build the agent
make agent

# Enable on control plane
./mcpdrill-server --addr :8080 --enable-agent-ingest --agent-tokens "secret-token"

# Run agent on your MCP server host
./mcpdrill-agent \
  --control-plane-url http://localhost:8080 \
  --agent-token "secret-token" \
  --pair-key "my-test" \
  --listen-port 3000

与测试运行的链接

{
  "scenario_id": "capacity-test",
  "server_telemetry": {
    "enabled": true,
    "pair_key": "my-test"
  },
  "target": { "url": "http://localhost:3000/mcp" }
}

是什么 pair_key?
配对键将特定服务器的指标与您的测试运行联系起来。使用 相同的价值 为了 --pair-key 启动代理时以及在运行配置中 server_telemetry.pair_key 将服务器端资源指标（CPU、内存）与客户端负载测试结果相关联。

看代理遥测指南了解全部细节。

API快速参考

# Create a run
curl -X POST http://localhost:8080/runs -H "Content-Type: application/json" -d @config.json

# Start / Stop / Emergency stop
curl -X POST http://localhost:8080/runs/{run_id}/start
curl -X POST http://localhost:8080/runs/{run_id}/stop -d '{"mode":"drain"}'
curl -X POST http://localhost:8080/runs/{run_id}/emergency-stop

# Status and events
curl http://localhost:8080/runs/{run_id}
curl -N http://localhost:8080/runs/{run_id}/events

码头工人

图像

发布到 GitHub容器注册表每次发布时：

图片	GHCR	描述
`server`	`ghcr.io/bc-dunia/mcpdrill/server`	控制平面+嵌入式Web UI(`go:embed`)
`worker`	`ghcr.io/bc-dunia/mcpdrill/worker`	分布式负载工作器
`mockserver`	`ghcr.io/bc-dunia/mcpdrill/mockserver`	内置MCP模拟服务器（27个工具）
`agent`	`ghcr.io/bc-dunia/mcpdrill/agent`	服务器端遥测代理（可选）

# Pull a specific release (recommended)
docker pull ghcr.io/bc-dunia/mcpdrill/server:0.1.3

# Or use :latest for the most recent release
docker pull ghcr.io/bc-dunia/mcpdrill/server:latest

备注：Git标签使用 v 前缀(v0.1.3)，但Docker镜像标签没有(0.1.3).多拱图像已发布 linux/amd64 和 linux/arm64.

撰写个人资料

docker compose up -d                       # server + worker
docker compose --profile mock up -d        # + mock server
docker compose --profile full up -d        # + mock server + agent
docker compose up -d --scale worker=5      # scale workers

构建图像

make docker-build                          # all images
make docker-build VERSION=v0.1.3           # with version tag
make docker-server                         # server only

图像会自动构建并通过GitHub Actions在标签推送时发布到GHCR。

文档

主题	链接
入门指南	docs/getting-started.md
CLI参考	docs/cli.md
配置	docs/configuration.md
API参考	docs/api.md
Web用户界面	docs/web-ui.md
模拟服务器和工具	docs/tool-testing-guide.md
服务器遥测代理	docs/agent-telemetry.md
开放遥测	docs/opentelemetry.md
多节点部署	docs/多节点部署.md
插件	docs/plugins.md
故障排除	docs/故障排除.md
发展	docs/development.md

例子

内置配置 examples/:

quick-start.json -针对模拟服务器的最小测试
tool-testing/ -工具验证场景
scenarios/ -SSE和流媒体测试
multi-node/ -Docker Compose和Kubernetes

许可证

MIT许可证-请参阅许可证了解详情。

_{MCP Drill最初是为了验证以下产品的生产稳定性而创建的派塔，MCP控制平面和运行时。如果你正在构建需要扩展的MCP基础设施，Peta会处理硬部分——路由、身份验证、可观察性——这样你就可以专注于你的代理。}