使用说明
MCPSentinel
Zero-config testing for MCP servers.
Install. Point at your server. Get a full test report.
开始使用
pip install mcp-sentinel
mcpsentinel "python my_server.py"
就是这样。没有配置文件。没有要编写的测试代码。MCPSentinel连接到您的服务器，发现每个工具，生成数百个测试用例，并打印结果：
MCPSentinel v0.1.0
Server: python my_server.py
Transport: stdio (auto-detected)
Modes: schema, fuzz
Output: terminal
Discovering tools... 3 tools found
Running 47 tests ━━━━━━━━━━━━━━━━━━━━━━ 100%
Results: 44 passed, 3 failed, 0 errors
它测试了什么
MCPSentinel默认运行两种测试模式：
模式验证 --发送有效输入，一次省略一个必填字段，测试枚举边界，类型不匹配。
对抗模糊 --SQL注入、XSS、路径遍历、命令注入、空字节、格式字符串、超大有效载荷、unicode压力测试。每个模糊测试都希望服务器不会崩溃——返回错误是可以的。
常见用法
# Test your server (zero config)
mcpsentinel "python my_server.py"
# Schema tests only
mcpsentinel "python server.py" -m schema
# HTML report
mcpsentinel "python server.py" -f html
# SSE server (transport auto-detected from URL)
mcpsentinel "http://localhost:8001/sse"
# Streamable HTTP
mcpsentinel "http://localhost:8001/mcp"
# Test specific tools
mcpsentinel "python server.py" --tools "search_*"
# Exclude admin tools
mcpsentinel "python server.py" --exclude "admin_*"
# Reproducible fuzz run
mcpsentinel "python server.py" --fuzz-seed 42
# Docker container
mcpsentinel "docker exec -i my-container python -m my_mcp_server"
# Re-run only previously failed tests
mcpsentinel "python server.py" --retry-failed
# Watch mode — re-run on file changes
mcpsentinel "python server.py" --watch
# Multiple report formats
mcpsentinel "python server.py" -f terminal -f json -f html -f junit
# CI-friendly: quiet mode + JUnit output
mcpsentinel "python server.py" -q -f junit -o ./test-results
mcpsentinel run "..."仍然有效--run是默认的子命令，可以省略。
其他命令
# Discover tools on a server
mcpsentinel discover "python my_server.py"
# Generate a config file (optional)
mcpsentinel init
选项
| 选项 | 简短 | 默认 | 描述 |
|---|---|---|---|
--transport |
-t |
汽车 | 运输： stdio, sse，或 streamable-http |
--mode |
-m |
schema,fuzz |
测试模式： schema, fuzz |
--config |
-c |
-- | 路径 mcpsentinel.toml |
--format |
-f |
terminal |
输出： terminal, json, html, junit |
--output-dir |
-o |
./reports |
报告输出目录 |
--tools |
-- | 全球模式包括工具 | |
--exclude |
-- | 排除工具的Glob模式 | |
--fuzz-seed |
-- | 可重复模糊测试的种子 | |
--timeout |
30 |
每次工具调用超时（秒） | |
--concurrency |
1 |
并行测试执行 | |
--rate-limit |
0 |
通话之间的最小延迟（ms） | |
--retry-failed |
仅重新运行以前失败的测试 | ||
--watch |
-w |
注意文件更改并重新运行 | |
--watch-path |
. |
要查看的目录 | |
--verbose |
-v |
实时显示所有通话记录 | |
--quiet |
-q |
抑制终端输出 |
配置（可选）
MCPSentinel无需任何配置即可工作。如果您想要持久设置：
mcpsentinel init
创建 mcpsentinel.toml --出现时自动发现：
[server]
command = "python"
args = ["my_server.py"]
transport = "stdio"
startup_timeout = 30
[modes]
schema = true
fuzz = true
[fuzz]
seed = 42
[execution]
timeout_per_tool = 30
# tools = "search_*"
# exclude = "internal_*"
[reporting]
formats = ["terminal", "json"]
output_dir = "./reports"
verbose = false
quiet = false
CLI标志始终覆盖配置文件值。
报表格式
| 格式 | 描述 |
|---|---|
| 终端 | 带有汇总表和故障详细信息的丰富彩色输出 |
| 超文本标记语言 | 具有深色/浅色主题、搜索、键盘快捷键的独立单文件报告 |
| JSON | 包含每个测试用例、调用日志和计时数据的完整机器可读报告 |
| JUnit XML | GitHub Actions、Jenkins、GitLab CI的CI兼容格式 |
CI/CD集成
GitHub操作
- name: Test MCP Server
run: |
pip install mcp-sentinel
mcpsentinel "python my_server.py" -q -f junit -o ./test-results
- name: Publish Test Results
uses: dorny/test-reporter@v1
if: always()
with:
name: MCP Server Tests
path: test-results/mcpsentinel-report-*.xml
reporter: java-junit
或者使用 MCPSentinel GitHub行动:
- uses: Dev07-Harsh/mcp-sentinel@main
with:
server-command: "python my_server.py"
退出代码
| 代码 | 含义 |
|---|---|
0 |
所有测试均已通过 |
1 |
一个或多个测试失败 |
2 |
配置错误 |
3 |
在服务器上找不到工具 |
测试模式
架构模式
| 测试类型 | 它的作用 |
|---|---|
valid_minimal |
仅发送具有有效类型的必需参数 |
valid_full |
发送所有参数（必需+可选） |
defaults_only |
仅发送必需的参数，忽略可选参数 |
required_missing_* |
逐一省略每个必需参数 |
enum_* |
测试每个声明的枚举值 |
boundary_* |
测试数字参数的最小值/最大值 |
引信模式
| 测试类型 | 它发送什么 |
|---|---|
type_mismatch |
每个参数的类型都错误 |
boundary_violation |
超出声明的最小值/最大值 |
null_injection |
null 对于每个参数 |
empty_value |
空字符串、数组、对象 |
invalid_enum |
声明枚举集之外的值 |
extra_fields |
意外的附加参数 |
injection_* |
SQL、命令、路径遍历、XSS、格式字符串 |
encoding_* |
Unicode重音、换行符/制表符注入 |
overflow |
100000个字符串 |
建筑
src/mcpsentinel/
├── cli/ # Typer CLI (run, discover, init)
├── client/ # MCP protocol client (stdio, SSE, streamable-http)
├── config/ # TOML + CLI config loading
├── discovery/ # Tool discovery and schema analysis
├── generation/ # Test case generators (schema + fuzz)
├── execution/ # Test runner and tool executor
├── evaluation/ # Result checkers (schema + fuzz)
├── reporting/ # Terminal, HTML, JSON, JUnit reporters
├── logging/ # Per-call trace recording
├── models/ # Pydantic data models
└── errors.py # Error hierarchy
扩展点
BaseGenerator--添加新的测试生成策略BaseChecker--添加新的评估逻辑BaseReporter--添加新的输出格式
安装
pip install mcp-sentinel
来源：
git clone https://github.com/Dev07-Harsh/mcp-sentinel.git
cd mcp-sentinel
pip install -e ".[dev]"
要求： Python 3.10+
贡献
欢迎捐款。在上打开问题或拉取请求 GitHub.
git clone https://github.com/Dev07-Harsh/mcp-sentinel.git
cd mcp-sentinel
pip install -e ".[dev]"
pytest tests/unit
作者
哈什·辛格 — GitHub
许可证
MIT许可证。看 许可证 了解详情。
