Madhyamas Proxy — AI 代理指南
Madhyamas 是一個以 Rust 建置的開源 HTTP/HTTPS 偵錯代理伺服器。它能攔截、檢視及操作用戶端與伺服器之間的流量。統一化的 madhyamas 二進位檔提供了代理伺服器、Web 管理介面、MCP 伺服器及 CLI 工具。
快速開始
# 1. 安裝（擇一）
cargo install madhyamas # 從 crates.io 安裝
cargo build --release -p madhyamas # 從原始碼建置
# 或是從 GitHub Releases 下載預編譯的二進位檔
# 2. 啟動代理伺服器
madhyamas serve
# 代理伺服器監聽於 :8888，API/Web 管理介面監聽於 :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 <command> <subcommand> | references/cli-commands.md |
| REST API | 細粒度控制、自訂腳本、直接 HTTP 操作 | curl http://localhost:3001/api/... | references/rest-api.md |
三種介面都提供相同的基本功能。MCP 工具和 CLI 指令是 REST API 的包裝。
關鍵概念
- 代理埠號：代理伺服器監聽於
:8888（HTTP/HTTPS 流量），API/管理介面監聽於: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 |
| Harness 設定 | 為 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 | 各 Harness 的 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" }
}
}
}
各 Harness 的詳細設定（Claude Desktop、Windsurf、Cursor、OpenCode、CommandCode、Devin）請參閱 references/harness-setup.md。
常見模式
偵錯失敗的 API 呼叫：
- 啟動代理：
madhyamas serve - 設定用戶端使用代理
- 重現問題
- 檢查流量：
madhyamas traffic list --status 500或使用 MCP 的madhyamas_get_traffic搭配status=500 - 取得詳細資訊：
madhyamas traffic get <id>或 MCP 的madhyamas_get_traffic_entry
模擬 API 端點：
- 建立模擬：
madhyamas mocks create --url-pattern "*/api/auth*" --status-code 200 --body '{"token":"fake"}' - 或使用 MCP：
madhyamas_create_mock搭配url_pattern="*/api/auth*"、status_code=200、body='{"token":"fake"}' - 從您的用戶端測試被模擬的端點
在慢速網路下測試：
- 啟用限速：
madhyamas throttle set --download-bps 50000 --delay-ms 200 && madhyamas throttle enable - 或使用 MCP：
madhyamas_set_throttle搭配download_bps=50000, delay_ms=200, enabled=true - 重現您的工作流程以觀察在慢速環境下的行為