proxypin-mcp-workbench

# ProxyPin MCP Workbench 中文 | [English](README_EN.md) 基于 ProxyPin 与 Model Context Protocol（MCP）的自动化抓包、API 分析、Mock 场景和数据归档工作台。 本项目面向开发、测试和个人数据迁移场景，将传统抓包工具里的“查看单条请求”扩展为可以长期复用的工作流：按任务归档请求、整理 API 资产、组合 Mock 规则，并让本地 AI 客户端通过 MCP 分析当前抓包会话。 > 本项目是非官方衍生项目，与 ProxyPin 及下列上游作者不存在官方隶属、授权代理或背书关系。请只分析自己拥有或明确获授权的设备、账号、应用和流量。 ## 下载与版本 当前公开安装包为 **[v1.3.0](https://github.com/sinyu1012/proxypin-mcp-workbench/releases/tag/v1.3.0)**： | 平台 | 下载 | | --- | --- | | macOS（Apple Silicon + Intel） | [Universal ZIP](https://github.com/sinyu1012/proxypin-mcp-workbench/releases/download/v1.3.0/proxypin-mcp-workbench-macos-1.3.0.zip) | | Windows | [安装程序](https://github.com/sinyu1012/proxypin-mcp-workbench/releases/download/v1.3.0/proxypin-mcp-workbench-windows-1.3.0-setup.exe) / [免安装 ZIP](https://github.com/sinyu1012/proxypin-mcp-workbench/releases/download/v1.3.0/proxypin-mcp-workbench-windows-1.3.0.zip) | - macOS 包为 ad-hoc 签名，尚未经过 Apple 公证；安装说明与 SHA-256 见版本页面。 - `main` 已包含 v1.3.0 之后的 socket 泄漏修复、第一跳代理修复、系统代理特权服务和本机/外部设备独立抓包开关，**上述下载包尚未包含这些更新**。详见 [更新日志](CHANGELOG.md)。 - v1.3.0 未提供 Android、iOS 或 Linux 安装包。通过桌面代理抓取手机流量，不要求在手机安装本项目 App。 - Workbench 的部分标题、标签和按钮仍为中文；英文说明不代表界面已完整英文化。 ## 界面预览 以下截图使用空白状态或匿名示例数据，不包含真实 Token、Cookie、设备标识、用户资料或业务域名。截图展示界面结构，不代表已完成一次实际抓包或 Mock 命中验证。  本机抓包会将 macOS 流量从普通设备抓包中单独归拢，并支持按来源应用筛选。   ## 主要能力 - **自动化工作台**：统一管理抓包项目、API 资产、数据导出和 Mock 场景。 - **抓包项目归档**：按任务隔离请求并持续写入独立归档，清空实时列表也不会丢失项目记录。 - **采集方案**：保存域名范围和人工操作步骤，下次可以按同一流程重新采集。 - **API 资产整理**：按方法、主机和归一化路径聚合请求，汇总已观察到的字段与响应结构，减少重复翻找。 - **数据导出**：从归档中提取结构化记录，在界面中导出 JSON 或 CSV；内置常见凭据字段脱敏，导出前仍需检查个人数据。 - **Mock 场景合集**：多条请求重写规则归入同一合集，通过一个开关整体启停。 - **双列详情视图**：宽屏同时查看 Request 与 Response；窄屏自动回退为标签页。 - **本机应用归类**：将 macOS 本机流量单独归拢，按已捕获应用筛选请求，同时保留手机与远端设备抓包视图。 - **MCP 自动化**：本地 AI 客户端可以搜索请求、读取详情、对比接口和管理授权范围内的 Mock。 MCP 集成承接上游实现；本仓库新增和扩展的是抓包项目、采集方案、API 资产、数据导出、Mock 场景及工作台流程。AI 分析由你选择的外部客户端完成，应用不内置模型。 代码、配置和截图中的产品名称、业务域名与场景均使用匿名或公开示例，例如“示例育儿应用”“示例订阅应用”和 `example.com`。 ## 体验流程：从真实响应到空状态 Mock 以下是可复现的操作指引，尚未提供对应的端到端演示录像。请在自己的测试 App 和测试 API 上操作： 1. 通过代理抓取一次正常的商品列表请求。 2. 接通 MCP 后，让 AI 按测试域名和路径查找请求，确认响应中列表字段的位置。 3. 要求 AI 保持响应结构，只把列表改为空数组，使用 `add_rewrite_rule` 创建 `responseReplace` 规则并归入专用场景。创建前先查看已有规则；此工具会开启重写总开关，且没有 HTTP method 参数。 4. 刷新测试 App，确认实际出现空状态；对刷新后捕获的请求调用 `diagnose_mock`，检查规则选择与命中统计。 5. 重新读取规则列表，确认本次规则的当前索引，再移除它并刷新，验证正常响应恢复。 可交给 AI 的任务示例： > 查找测试 App 的商品列表请求，先展示响应结构，再创建空列表响应 Mock。保持其他字段不变，限定到测试域名和路径并归入独立场景，不改动已有规则。刷新后检查 Mock 命中情况和匹配范围。 此流程使用固定响应重写；不会在每次请求时调用 AI 生成内容。规则沿用现有通配符和正则匹配语义，填写完整 URL 不等于字符串精确匹配，需核对匹配范围。响应重写仍可能访问上游服务。英文操作说明见 [README_EN.md](README_EN.md)。 ## 快速开始 使用安装包可跳过编译步骤。以下命令供从源码运行的开发者使用。 ### 环境要求 - Flutter（当前 GitHub Actions 使用 3.41.2；仓库未固定 FVM 配置，需先自行选择兼容 SDK） - macOS、Windows、Linux、Android 或 iOS 开发环境 - macOS 桌面调试需要 Xcode 与 CocoaPods ### 启动 macOS Debug 版本 ```bash fvm use 3.41.2 fvm flutter pub get fvm flutter run -d macos ``` 如果没有安装 FVM，也可以使用兼容版本的 `flutter` 命令。 ### 手机抓包 1. 让手机和运行本项目的电脑连接同一局域网。 2. 在手机 Wi-Fi 中把 HTTP 代理指向电脑的局域网 IP 和应用显示的 HTTP 端口。 3. 先验证普通 HTTP 转发，再安装由当前设备本地生成的 CA。 4. iPhone 安装描述文件后，还需要在“证书信任设置”中开启完全信任。 5. HTTPS 解密尽量限定到正在测试的域名。 6. 完成后关闭手机代理、移除不再使用的 CA，并清理包含凭据的导出文件。 详细流程见仓库内置的 [ProxyPin 抓包工作流 Skill](skills/proxypin-capture-workflow/SKILL.md)。 ## MCP 连接 先打开应用的抓包页面，再到 MCP 页面确认服务已运行（未运行时点击 Start）并核对实际端口。MCP 服务只监听本机回环地址；默认 9101 被占用时会尝试递增端口。手机连接的是应用显示的 HTTP 代理端口（默认 9099），AI 客户端连接的是 MCP 端口，两者不要混用。 ```text MCP 健康检查：http://127.0.0.1:9101/health MCP JSON-RPC：http://127.0.0.1:9101/message ``` 使用仓库内的脱敏客户端： ```bash python3 skills/proxypin-capture-workflow/scripts/proxypin_mcp.py health python3 skills/proxypin-capture-workflow/scripts/proxypin_mcp.py tools python3 skills/proxypin-capture-workflow/scripts/proxypin_mcp.py \ call search_requests '{"urlKeyword":"example.com","limit":20}' ``` 命令在仓库根目录执行，需要 Python 3.10 或更新版本，无需额外 Python 依赖。若 MCP 实际端口不同，在子命令前添加 `--base-url http://127.0.0.1:实际端口`。 辅助脚本通过 `/message` 发送 `tools/list` 和 `tools/call` JSON-RPC，并默认遮盖常见 Token、Authorization、Cookie 和密码字段；此脱敏不是所有 MCP 连接共享的服务端过滤。只有确实需要在本机完成转换时才使用 `--raw`，不要把原始输出提交到仓库或粘贴到公开 Issue。 其他客户端可按其支持情况接入 `/sse`；`/message` 不能直接当作 Streamable HTTP 的 `/mcp` 地址。以当前 `tools/list` 为准：`replay_request`、`release_intercept`、`create_or_update_script` 等工具未向此构建的 MCP 客户端开放。 ## 安装 Codex Skill 本项目附带一套可复用的 ProxyPin 工作流： ```text skills/proxypin-capture-workflow/ ├── SKILL.md ├── agents/openai.yaml ├── references/ │ ├── capture-setup.md │ ├── export-and-mock.md │ └── mcp-analysis.md └── scripts/proxypin_mcp.py ``` 可以将整个目录复制到 Codex Skills 目录： ```bash cp -R skills/proxypin-capture-workflow ~/.codex/skills/ ``` Skill 包含手机代理诊断、iOS/Android CA 配置、MCP 请求分析、个人数据导出校验和 Mock 合集管理边界。 ## 安全与隐私 - 抓包和归档保存在本机，但 AI 客户端读取的请求可能发送给其模型服务商，取决于客户端和模型配置。服务监听 `127.0.0.1` 不代表模型推理也在本机完成。 - MCP 请求详情可包含原始头和正文。辅助脚本和导出功能的脱敏仅覆盖部分凭据字段，不保证移除所有个人信息或嵌套文本中的秘密。 - 仅处理自己拥有或明确获授权的流量。 - 不要提交 HAR、抓包历史、运行日志、导出数据、Cookie、Authorization、查询 Token、设备标识或家庭成员资料。 - 不要把 MCP 服务暴露到局域网或公网。 - 不提供证书固定绕过、越狱、Root、Frida 注入或第三方付费权益绕过方案。 - Mock 只能用于自己的应用或明确授权的测试环境。 - 安装 CA 等同于授予 HTTPS 解密能力；只信任当前设备本地生成且指纹可核对的 CA。 本分支不再随安装包分发共享 CA 私钥。新安装会在首次启动时于本机应用数据目录生成唯一 CA，私钥在 macOS/Linux 上限制为仅当前用户可读写。由旧版本升级的用户应在证书管理中重新生成一次 CA，并重新安装、核对和信任新证书。更多说明见 [SECURITY.md](SECURITY.md)。 ## 当前边界 - macOS `main` 新增的系统代理特权服务要求可信开发者签名；ad-hoc 自编译版本会被该服务的签名校验拒绝（`SYSTEM_PROXY_HELPER_UNTRUSTED_BUILD`）。v1.3.0 安装包尚未引入此服务，不能用旧版安装体验代替新版服务验收。 - 安装 CA 不保证所有应用流量可解密；证书固定、独立信任库或未经过代理的流量可能无法读取正文。 - API 资产反映已捕获的样本，不等同于完整 OpenAPI 契约；MCP 数据导出提供预览，文件导出在界面中完成。 - Mock 场景互斥切换针对已分组规则；未分组规则仍可能生效。 - MCP 命中诊断会根据当前配置评估请求，并返回运行时命中统计。配置评估不能代替刷新 App 后的响应验证。 ## 开发与验证 ```bash fvm flutter analyze lib/network/util/crts.dart lib/features/workbench fvm flutter test test/capture_plan_test.dart \ test/har_archive_recovery_test.dart \ test/network_panel_split_layout_test.dart \ test/channel_lifecycle_test.dart fvm flutter build macos --debug git diff --check ``` 仓库还保留了部分上游的手工联调脚本，它们依赖本机证书样本、临时文件或本地 HTTP 服务，不属于可离线重复执行的自动化测试；公开发布前以以上定向测试和实际构建为准。 界面改动至少应验证：宽屏与窄屏布局、Request/Response 正文、SSE/WebSocket、Cookies、Mock 诊断和跨断点窗口缩放。 ## 上游与致谢 本公开仓库从经过脱敏的代码快照开始记录历史，并基于以下项目继续开发： - [wanghongenpin/proxypin](https://github.com/wanghongenpin/proxypin)：原始 ProxyPin 项目。 - [SuxyEE/proxypin-mcp](https://github.com/SuxyEE/proxypin-mcp)：早期 MCP 集成实现。 - [ouy160/proxypin-mcp-model](https://github.com/ouy160/proxypin-mcp-model)：本仓库直接采用的代码基线。 感谢所有上游作者和贡献者。上游链接、许可证与详细署名见 [NOTICE](NOTICE)；需要追溯原始实现时，请以对应上游仓库的公开历史为准。 ## 许可证 本项目继续采用 [Apache License 2.0](LICENSE)。原项目的版权、许可证和署名信息予以保留；新增代码及修改部分的版权归相应贡献者所有。