Proxyman MCP Setup 用于配置 AI 编程智能体通过 Proxyman 自带的 stdio 桥接与 Proxyman MCP 通信。
用途 当 Proxyman 已安装但智能体看不到工具，或需要为 Codex、Claude、Cursor、VS Code、GitHub Copilot CLI 等配置 Proxyman MCP 时使用本技能。
运行规则 本技能以 shell 为先，MCP 工具此时可能尚未连接。不要使用 API key 或直接 HTTP MCP 配置，Proxyman MCP 使用本地 stdio 桥接可执行文件。验证通过前，Proxyman 必须已安装、正在运行，并已在 Settings > MCP 中启用 MCP Server。保留智能体配置文件中已有的 MCP 服务器条目，仅新增或更新 proxyman 条目。当 Proxyman 设置中给出确切命令时，优先使用该命令。
工作原理 Proxyman MCP 包含两个本地部分：AI 智能体通过 stdio 启动 Proxyman 自带的 mcp-server 可执行文件；桥接从 Proxyman 应用数据文件夹读取 mcp-handshake.json，并将工具调用转发到运行中的应用 http://127.0.0.1:<临时端口>/mcp，使用握手文件中的 bearer token。桥接属于单个客户端会话，当客户端 stdin 到达 EOF 时退出，MCP 客户端应在下一会话再次启动它。不要硬编码 HTTP 端口或 token，应用会重新生成它们。
握手文件常见位置：macOS 原生应用位于 Proxyman Application Support bundle 文件夹（含常规与 Setapp bundle ID）；Windows Electron 应用位于 %APPDATA%\Proxyman；Linux Electron 应用位于 ${XDG_CONFIG_HOME:-$HOME/.config}/Proxyman。不要编辑握手文件，若缺失或过期，重启 Proxyman 并重新启用 Settings > MCP。
步骤 1：验证 Proxyman 已安装 macOS 检查 /Applications/Proxyman.app 或通过 mdfind 查找 bundle ID com.proxyman.NSProxy。Windows 通过 PowerShell 查询注册表卸载项中 DisplayName 含 Proxyman。Linux 检查 proxyman 命令或 Downloads 下的 AppImage。若未安装，停止并使用 proxyman-download-setup。
步骤 2：启动 Proxyman 并启用 MCP macOS 使用 open -a "Proxyman" 并等待；Windows 从候选路径启动 Proxyman.exe；Linux 使用命令或 AppImage 后台启动。随后请用户打开 Proxyman Settings > MCP 并启用 MCP Server。若 MCP 开关被锁定，用户需授权其 Proxyman 版本所需的计划/许可证。若已有 proxyman-cli，可持久化相同状态，但需查阅其 mcp --help 并使用 mcp on 操作，之后仍需启动 Proxyman。除非用户明确希望发送原始 headers、cookies、查询字符串或 body，否则保持启用 Redact Sensitive Data Before Sending to AI。Linux AppImage 构建中，启动 Proxyman 会让应用将打包的 MCP 桥接复制到稳定配置路径并标记为可执行。
步骤 3：解析桥接可执行文件 macOS 常规路径为 /Applications/Proxyman.app/Contents/MacOS/mcp-server，缺失时搜索已安装应用。Windows Electron 应用将 mcp-server.exe 复制到 Proxyman.exe 旁，若未找到则使用 Settings > MCP 中的确切命令。Linux 优先使用 ${XDG_CONFIG_HOME:-$HOME/.config}/Proxyman/bin/mcp-server。BRIDGE_PATH 必须是 stdio 桥接，而非 Proxyman 应用二进制。
步骤 4：检测智能体配置 优先使用环境变量，其次父进程，再次文件系统标记。支持检测 codex、claude-code、cursor、vscode、copilot-cli、claude-desktop。若检测到多个智能体，询问用户要配置哪一个。
步骤 5：添加 MCP 服务器 Codex CLI 使用 codex mcp add proxyman -- "$BRIDGE_PATH"，配置文件 ~/.codex/config.toml。Claude Code 使用 claude mcp add proxyman --transport stdio -- "$BRIDGE_PATH"，配置文件 ~/.claude.json。Claude Desktop 配置文件在 macOS 为 ~/Library/Application Support/Claude/claude_desktop_config.json，Windows 为 %APPDATA%\Claude\claude_desktop_config.json。Cursor 配置文件 ~/.cursor/mcp.json。VS Code / GitHub Copilot 配置文件在 macOS 为 ~/Library/Application Support/Code/User/mcp.json 或工作区 .vscode/mcp.json，Linux 为 ~/.config/Code/User/mcp.json，Windows 为 %APPDATA%\Code\User\mcp.json。GitHub Copilot CLI 配置文件 ~/.copilot/mcp-config.json。手动编辑 JSON 或 TOML 时尽量使用真实解析器解析并合并，绝不替换无关的 mcpServers 或 servers 条目。
步骤 6：验证 更改配置后重启或重新加载智能体。验证顺序：确认 Proxyman 正在运行；确认 Settings > MCP 显示服务器运行；让智能体列出 MCP 工具/资源/提示（若支持发现）；调用 get_version；调用 get_proxy_status。成功意味着智能体能看到 Proxyman 工具且 get_version 返回 Proxyman 应用/桥接响应。工具可用性因平台和构建而异，以实时工具列表为准。macOS 系统代理控制、Apple Terminal/iTerm/Ghostty 注入、.app Electron 注入及桥接应用控制工具偏向 macOS，除非服务器暴露适用 schema，否则不要在 Windows 或 Linux 上提供。
故障排除 Proxyman 未运行或 MCP 服务器未启动：桥接找不到 mcp-handshake.json，启动 Proxyman 并启用 Settings > MCP。握手文件无效：token 或端口过期，重启 Proxyman 后重新加载智能体。无法连接 Proxyman：应用关闭或 MCP 服务器停止，打开 Proxyman 并确认 MCP 状态。Linux 桥接路径缺失：AppImage 尚未在配置文件夹准备 mcp-server，启动 Proxyman、启用 Settings > MCP、重启 Proxyman，再检查 ${XDG_CONFIG_HOME:-$HOME/.config}/Proxyman/bin/mcp-server。智能体没有 Proxyman 工具：配置路径错误或智能体未重新加载，重新检查 BRIDGE_PATH、配置文件并重启智能体。设置后用户看不到流量：MCP 已连接但目标捕获未配置，使用 proxyman-https-capture，再用 proxyman-traffic-debugging 检查。
后续步骤 当 get_version 和 get_proxy_status 可用后：使用 proxyman-traffic-debugging 了解完整 MCP 操作面；使用 proxyman-https-capture 进行设备、模拟器、浏览器、运行时和框架的路由/信任设置；使用 proxyman-debugging-tools 获取当前官方功能文档；使用 proxyman-cli 进行版本匹配的 shell 自动化。