ShristiLabs/madhyamas

Madhyamas 代理 — AI 代理指南

Madhyamas 是一个用 Rust 构建的开源 HTTP/HTTPS 调试代理。它可以捕获、检查并操控客户端与服务器之间的流量。统一的 madhyamas 二进制文件提供了代理服务器、Web UI、MCP 服务器和 CLI。

快速开始

# 1. 安装（选择其中一种方法）
cargo install madhyamas                          # 从 crates.io 安装
cargo build --release -p madhyamas               # 从源码构建
# 或者从 GitHub Releases 下载预编译二进制文件

# 2. 启动代理服务器
madhyamas serve
# 代理监听 :8888，API/Web UI 监听 :3001

# 3. 验证
curl http://localhost:3001/api/health
# 返回：OK

配置客户端使用代理 localhost:8888。如需 HTTPS 拦截，请安装来自 ~/.madhyamas/certs/madhyamas-ca.pem 的 CA 证书（或通过 GET /api/cert/ca 下载）。

有关详细的安装、配置和 CA 证书设置，请参阅 references/setup.md。

选择接口

Madhyamas 提供三个接口。根据您所处的上下文选择可用的接口：

接口	使用时机	设置	参考文档
MCP 工具	在 MCP 兼容代理内（Claude Desktop、Windsurf 等）	madhyamas mcp（stdio 传输）	references/mcp-tools.md
CLI 命令	Shell 访问、脚本、基于终端的代理	madhyamas <命令> <子命令>	references/cli-commands.md
REST API	精细控制、自定义脚本、直接 HTTP 请求	curl http://localhost:3001/api/...	references/rest-api.md

所有三个接口都提供相同的基础功能。MCP 工具和 CLI 命令是 REST API 的封装。

核心概念

• 代理端口：代理监听 :8888（HTTP/HTTPS 流量），API/UI 监听 :3001
• CA 证书：自动生成在 ~/.madhyamas/certs/ 目录下。安装到系统信任存储中以进行 HTTPS 拦截
• 会话：将流量组织到命名的会话中。默认会话自动创建
• 捕获模式：录制（默认）捕获流量；透传模式则转发而不录制
• 拦截管道顺序：重写（优先级 10）→ 模拟（20）→ 断点（30）→ 节流（40）
• 数据目录：~/.madhyamas/ 包含 certs/、logs/、traffic.db（SQLite）
• MCP 服务器：运行 madhyamas mcp 以使用基于 stdio 的 MCP 传输。设置 MADHYAMAS_API_URL 以连接到正在运行的代理实例

核心工作流

工作流	描述	参考文档
设置	安装、配置、连接客户端、安装 CA 证书	setup.md
检查流量	列出、过滤、搜索、分析捕获的 HTTP/HTTPS 流量	traffic-inspection.md
模拟响应	创建模拟规则以拦截并返回伪造的响应	mocking.md
断点	暂停请求/响应以进行检查和修改	breakpoints.md
重写	修改匹配流量的 URL、头部、主体	rewrites.md
节流	模拟慢速/不稳定的网络条件	throttling.md
重放	使用修改后的参数重新执行捕获的请求	replay.md
会话	创建、切换、导出、导入调试会话	sessions.md
gRPC 检查	检查 gRPC 连接、流、帧（实验性）	grpc.md
脚本	使用 JS/TS 脚本自动进行流量操控（实验性）	scripting.md
插件	管理 Rust 插件以扩展功能（实验性）	plugins.md
WebSocket	检查 WebSocket 连接流量和消息	websockets.md
导出/导入	HAR 导出、cURL 导出、规则持久化	export-import.md
故障排除	证书错误、端口冲突、数据库锁定、TLS 失败	troubleshooting.md
工具设置	为 Claude、Windsurf、Cursor 等配置 MCP	harness-setup.md

参考索引

文件	何时阅读
references/setup.md	首次设置、安装、CA 证书、客户端配置
references/mcp-tools.md	所有 67 个 MCP 工具的完整参考，包括参数
references/cli-commands.md	所有 58 个 CLI 子命令的完整参考，包括标志
references/rest-api.md	所有 130+ REST API 端点的完整参考
references/traffic-inspection.md	过滤、搜索、分析捕获的流量
references/mocking.md	创建和管理模拟响应
references/breakpoints.md	暂停和修改流量
references/rewrites.md	URL/头部/主体重写规则
references/throttling.md	网络条件模拟
references/replay.md	重放和保存请求
references/sessions.md	会话管理
references/grpc.md	gRPC 流量检查
references/scripting.md	JavaScript/TypeScript 脚本
references/plugins.md	插件管理
references/websockets.md	WebSocket 流量检查
references/export-import.md	HAR/cURL 导出、持久化
references/troubleshooting.md	常见问题与解决方案
references/harness-setup.md	按工具的 MCP 配置

MCP 服务器设置

运行 MCP 服务器以集成 AI 代理：

madhyamas mcp                    # stdio 传输，连接到 localhost:3001
MADHYAMAS_API_URL=http://host:3001 madhyamas mcp  # 自定义 API URL

添加到代理的 MCP 配置：

{
  "mcpServers": {
    "madhyamas": {
      "command": "/path/to/madhyamas",
      "args": ["mcp"],
      "env": { "MADHYAMAS_API_URL": "http://127.0.0.1:3001" }
    }
  }
}

有关特定工具的配置（Claude Desktop、Windsurf、Cursor、OpenCode、CommandCode、Devin），请参阅 references/harness-setup.md。

常用模式

调试失败的 API 调用：

1. 启动代理：madhyamas serve
2. 配置客户端使用代理
3. 重现问题
4. 检查流量：madhyamas traffic list --status 500 或 MCP madhyamas_get_traffic 并指定 status=500
5. 获取详情：madhyamas traffic get <id> 或 MCP madhyamas_get_traffic_entry

模拟一个 API 端点：

1. 创建模拟：madhyamas mocks create --url-pattern "*/api/auth*" --status-code 200 --body '{"token":"fake"}'
2. 或使用 MCP：madhyamas_create_mock，参数为 url_pattern="*/api/auth*"、status_code=200、body='{"token":"fake"}'
3. 从客户端测试模拟的端点

在慢速网络下测试：

1. 启用节流：madhyamas throttle set --download-bps 50000 --delay-ms 200 && madhyamas throttle enable
2. 或使用 MCP：madhyamas_set_throttle，参数为 download_bps=50000, delay_ms=200, enabled=true
3. 重现您的工作流，以观察在慢速条件下的行为