MCP Postman

仓库：https://github.com/tdlxgpp/mcp-postman

English: README.en.md

MCP Server 测试 / 调试 / 安全工作台（MVP 阶段）

当前能力：连接任意 MCP Server（stdio / Streamable HTTP / SSE）→ 列出/调用工具 → YAML 断言测试 → 录制/回放 → 安全扫描 → 报告/CI → 本地 Web UI。

目标

做一个面向 AI 开发者的 MCP Server 测试、调试、安全、CI 一体化工具，成为 MCP 世界的 “Postman / 测试工作台”。

后续规划：

1. MCP 测试/调试工作台（当前）
2. Agent 回放式回归测试
3. 中文/本地化 Agent 开发基础设施

技术栈

• Python 3.10+
• 官方 mcp SDK（1.29.x）
• Typer CLI
• YAML / JSON 配置

快速开始

完整使用说明见 docs/USAGE.md。

cd mcp-postman

# 方式一：直接使用命令行参数连接 stdio server
python -m mcp_postman list \
  --command python \
  --arg examples/demo_server.py

python -m mcp_postman call add \
  --command python \
  --arg examples/demo_server.py \
  --args '{"a": 2, "b": 3}'

# 方式二：使用配置文件（推荐，可保存多个 server profile）
python -m mcp_postman list --config examples/server.yaml
python -m mcp_postman list --config examples/server.yaml --profile demo
python -m mcp_postman call add \
  --config examples/server.yaml \
  --args '{"a": 2, "b": 3}'

# JSON 输出（适合 CI / 脚本）
python -m mcp_postman list --config examples/server.yaml --json
python -m mcp_postman call add --config examples/server.yaml --args '{"a": 4, "b": 5}' --json

# 真实公开 MCP Server 示例（官方 everything reference server）
mcp-postman list --config examples/server.yaml --profile everything
mcp-postman call get-sum --config examples/server.yaml --profile everything --args '{"a": 4, "b": 7}'

# YAML 测试套件
mcp-postman test examples/demo-suite.yaml --config examples/server.yaml
mcp-postman test examples/demo-suite.yaml --config examples/server.yaml --json
mcp-postman test examples/everything-suite.yaml --config examples/server.yaml

# 基础安全扫描（静态扫描工具描述/schema 中的风险关键词）
mcp-postman scan --config examples/server.yaml --profile everything
mcp-postman scan --config examples/server.yaml --profile everything --json
mcp-postman scan --config examples/server.yaml --profile everything --min-severity high

# 生成 JUnit XML / Markdown 报告（可用于 CI）
mcp-postman test examples/demo-suite.yaml --config examples/server.yaml --junit junit.xml --markdown report.md

# 录制 / 回放
mcp-postman record examples/demo-scenario.yaml --output demo-recording.json --config examples/server.yaml
mcp-postman replay demo-recording.json --config examples/server.yaml --profile demo
mcp-postman replay demo-recording.json --config examples/server.yaml --profile demo-http --strict

# Agent 轨迹录制 / 回放（tool_call + note 步骤）
mcp-postman trace-record examples/agent-trace.yaml --output agent-trace.json --config examples/server.yaml
mcp-postman trace-replay agent-trace.json --config examples/server.yaml --profile demo

# 多 profile 兼容矩阵
mcp-postman matrix examples/basic-suite.yaml --config examples/server.yaml --profiles demo,harness-bridge
mcp-postman matrix examples/basic-suite.yaml --config examples/server.yaml --json

# Agent trace 多 profile 矩阵
mcp-postman trace-record examples/agent-trace.yaml --output agent-trace.json --config examples/server.yaml
mcp-postman trace-matrix agent-trace.json --config examples/server.yaml --profiles demo,harness-bridge

# 动态探测（默认 dry-run；--execute 会真正调用工具）
mcp-postman probe --config examples/server.yaml --profile demo
mcp-postman probe --config examples/server.yaml --profile demo --execute --json

# 本地 Web UI（可选依赖）
pip install -e ".[web]"
mcp-postman web
# 打开 http://127.0.0.1:8765

安装为命令：

pip install -e .
mcp-postman list --config examples/server.yaml

一键跑完整演示：

bash scripts/demo.sh

支持的传输

transport	配置	说明
stdio	command + args	本地子进程，最常用
http / streamable-http	url	Streamable HTTP
sse	url	SSE（旧式流式传输）

CI

仓库内置 GitHub Actions 工作流：.github/workflows/ci.yml

• test job：安装依赖 → pytest → 端到端 smoke.py
• cli job：安装 CLI → 实际调用 demo server → 生成 junit.xml / report.md 并上传 artifact

本地模拟：

pip install -e ".[dev]"
python -m pytest -q
python scripts/smoke.py
mcp-postman test examples/demo-suite.yaml --config examples/server.yaml \
  --junit junit.xml --markdown report.md

配置文件格式

examples/server.yaml：

default: demo
servers:
  demo:
    transport: stdio
    command: python
    args: ["demo_server.py"]
    timeout: 30

  demo-http:
    transport: http
    url: http://127.0.0.1:8000/mcp
    headers: {}
    timeout: 30

规则：

• args / cwd 中的相对路径以配置文件所在目录为基准。
• env 可选，用于向 stdio 子进程注入环境变量。
• headers 可选，用于 HTTP/SSE 认证等请求头。

开发与验证

# 运行演示 server（另开终端，或交给命令行参数自动拉起）
python examples/demo_server.py

# 冒烟测试（基于 demo_server）
python -m mcp_postman list --config examples/server.yaml --json
python -m mcp_postman call add --config examples/server.yaml --args '{"a": 2, "b": 3}' --json
python -m mcp_postman call always_fail --config examples/server.yaml --args '{}' --json; echo "exit=$?"

单元/冒烟测试：

# 端到端冒烟：stdio + Streamable HTTP + SSE + 公开 everything server
python scripts/smoke.py

# pytest 单元测试（安装 dev 依赖后）
pip install -e ".[dev]"
pytest -q

目录结构

mcp-postman/
  .github/workflows/ci.yml  # GitHub Actions CI
  pyproject.toml
  README.md
  README.en.md              # 英文 README
  LICENSE                   # MIT
  CHANGELOG.md              # 版本记录
  CONTRIBUTING.md           # 贡献指南
  PUBLISHING.md             # 发布清单
  docs/
    10分钟上手.md           # 10 分钟快速上手（中文）
    QUICKSTART.en.md        # 10 分钟快速上手（英文）
    DEMO_EVERYTHING.md      # everything server 完整演示
    DSH_COMMUNITY_POST.md   # DSH 讨论贴文案草稿
    RELEASE_CHECKLIST.md    # 发布检查清单
    RELEASE_v0.1.0.md       # v0.1.0 Release Notes
    SCREENSHOTS.md          # 截图说明
    USAGE.md                # 完整使用指南（中文）
    USAGE.en.md             # 完整使用指南（英文）
    screenshots/
      web-ui.png            # Web UI 截图
      web-ui-live-list.png  # Web UI List 效果
      web-ui-live-call.png  # Web UI Call 效果
  examples/
    README.md               # 示例目录说明
    demo_server.py          # stdio 演示 MCP Server
    demo_server_http.py     # Streamable HTTP 演示 MCP Server
    demo_server_sse.py      # SSE 演示 MCP Server
    server.yaml             # 示例 server 配置
    demo-suite.yaml         # 示例 YAML 测试套件（demo server）
    basic-suite.yaml        # 适合跨 profile 矩阵的最小套件
    demo-scenario.yaml      # 示例录制场景（record 输入）
    agent-trace.yaml        # 示例 Agent 轨迹（tool_call + note）
    everything-suite.yaml   # 真实公开 server 测试套件
  scripts/
    demo.sh                 # 一键演示脚本
    smoke.py                # 端到端冒烟（stdio/http/sse/everything）
  src/mcp_postman/
    __init__.py
    __main__.py
    agent_trace.py          # Agent 轨迹录制/回放
    cli.py                  # Typer CLI
    client.py               # MCP 客户端连接 / 列表 / 调用
    matrix.py               # 多 profile 兼容矩阵 + trace-matrix
    models.py               # ServerConfig 与配置文件加载
    probe.py                # 动态探测/参数生成
    recorder.py             # 录制 / 回放数据模型与比较
    runner.py               # YAML 测试套件与断言运行器
    security.py             # 基础工具元数据风险扫描
    web.py                  # 本地 FastAPI Web UI
  tests/
    test_client.py          # 客户端 pytest 冒烟测试
    test_recorder.py        # 录制/回放测试
    test_agent_trace.py     # Agent 轨迹测试
    test_matrix.py          # 多 profile 矩阵测试
    test_probe.py           # 动态探测测试
    test_web.py             # Web UI 基础测试

开源与协作

• README.en.md — English README
• English Usage Guide
• English Quickstart
• Roadmap
• 10 分钟上手
• everything server 完整演示
• v0.1.0 Release Notes
• DSH 讨论贴文案草稿
• LICENSE — MIT
• CHANGELOG.md — 版本变更记录
• CONTRIBUTING.md — 贡献指南
• PUBLISHING.md — 发布/打包清单
• RELEASE_CHECKLIST

当前进度 / 下一步

已完成：

• MCP 客户端连接：stdio / Streamable HTTP / SSE
• 工具列表、单次调用、JSON 输出、profiles 查看
• YAML 测试套件与基础断言（mcp-postman test）
• JUnit XML / Markdown 报告输出（--junit / --markdown）
• 录制/回放（mcp-postman record / replay，支持跨 server/profile 回归比对）
• Agent 轨迹录制/回放（trace-record / trace-replay，tool_call + note 步骤）
• Agent 轨迹多 profile 矩阵（trace-matrix）
• 多 server 兼容矩阵（mcp-postman matrix，同一套件跑多个 profile）
• 动态探测（mcp-postman probe，dry-run / --execute）
• 基础安全扫描（mcp-postman scan，含风险等级/汇总/--min-severity）
• GitHub Actions CI 工作流
• 本地 Web UI（mcp-postman web）
• 示例仓库：examples/README.md / scripts/demo.sh
• 截图：docs/screenshots/web-ui.png
• 开源/发布文件：LICENSE / CHANGELOG / CONTRIBUTING / PUBLISHING / RELEASE_CHECKLIST
• 演示 Server、真实用例（harness-bridge / everything）、端到端冒烟

下一步：

• 多 session/多 Agent 全链路编排
• 动态安全检测的执行策略深化（沙箱/权限确认）
• 正式发布与社区运营