shmsr/hopper-mcp

# Hopper MCP 一个 MCP 服务器，为 LLM 客户端提供结构化、事务安全的访问途径，以获取派生自 Hopper 的逆向工程快照，而无需将反汇编器置于模型的上下文窗口中。 生产级重写版本为 `crates/hopper-mcpd`。它负责管理 MCP stdio、快照索引、查询、资源、提示、本地事务、持久化、Rust 侧的实时提取编排，以及版本化的 `hopper-wire` 后端边界。JavaScript 服务器被保留作为迁移参考和实时导出桥接，直到原生/私有后端完全取代它。 公共分析层是 Hopper 原生的。它不暴露本地的 `otool`、`nm`、`strings` 或 `codesign` 回退工具；如果 Hopper 没有分析或导出证据，服务器将如实报告这一空缺，而不是捏造本地启发式结果。 ## 当前 Rust 范围 - `open_session` 将 Hopper 派生的 JSON 快照加载到索引化的 Rust 存储中。 - `ingest_current_hopper` 使用 mock 后端或已配置的私有 `hopper-wire` Unix 套接字代理来执行后端边界操作。 - `ingest_live_hopper` 由 Rust 守护进程暴露，并将安全的 Hopper Python 导出委托给 Node 实时桥接。 - 快照读取工具涵盖 list/search/resolve/procedure/xrefs/containing function 查询。 - 分析工具涵盖图切片、深度函数摘要、指纹、相似性、差异比较以及查询 DSL。 - 资源和提示通过 MCP `resources/*` 和 `prompts/*` 暴露。 - 本地事务支持重命名、注释和行内注释修改，并支持预览/提交/回滚。 - `hopper-wire` 使用版本化的请求/响应类型固定了守护进程到代理的 JSON 契约。 - `agents/hopper-agent` 构建了一个 Objective-C++ Unix 套接字代理工件，该工件实现了 `hopper-wire` 握手、当前文档和过程列表协议。 - `agents/hopper-tool-plugin` 构建了一个已签名的 Hopper Tool Plugin 包，可以使用官方 Hopper SDK 从 Hopper 内部暴露相同的 `hopper-wire` 协议。 私有 Hopper 实时提取在守护进程侧实现为一个故障即关闭的 `hopper-wire` Unix 套接字客户端，并在原生侧实现为打包的 Objective-C++ 代理。目前，非夹具的 `hopper-agent` 模式通过 Hopper 捆绑的 MCP 子进程桥接真实的 Hopper 证据，并在 Hopper 没有当前文档时返回结构化错误。`HopperMCPAgent.hopperTool` 是直接的 Hopper 内插件路径，使用官方 SDK 构建。该插件现在发布一个基于配置的插件套接字路径作为键值的 Foundation 桥接服务，并且 `hopper-agent --plugin-service auto` 可以通过现有的 `hopper-wire` Unix 套接字契约暴露该服务。仅当使用真实的 Apple 代码签名身份进行签名时，Hopper 才会实时加载该插件；即席签名足以进行打包冒烟测试，但不足以作为接受实时插件的证据。`hopper-agent --fixture` 仅用于测试/打包冒烟测试，因此夹具数据不会被误认为是实时 Hopper 证据。 ## 环境要求 - macOS - Rust 工具链 - Node.js 20+，用于 npm 封装器、迁移参考测试和 v1 实时导出桥接 - 已安装 Hopper.app，用于实时提取测试和工作流 ## 安装 ``` git clone hopper-mcp cd hopper-mcp npm install npm run build:rust npm run doctor npm run test:rust npm test ``` ## 添加至客户端 将 `/abs/path/to/hopper-mcp` 替换为您克隆仓库的绝对路径。 **Claude Code** ``` claude mcp add -s user hopper -- cargo run --manifest-path /abs/path/to/hopper-mcp/Cargo.toml -p hopper-mcpd -- ``` **Codex CLI** ``` codex mcp add hopper -- cargo run --manifest-path /abs/path/to/hopper-mcp/Cargo.toml -p hopper-mcpd -- ``` **Cursor / Claude Desktop / 通用 MCP** ``` { "mcpServers": { "hopper": { "command": "cargo", "args": ["run", "--manifest-path", "/abs/path/to/hopper-mcp/Cargo.toml", "-p", "hopper-mcpd", "--"], "env": {} } } } ``` **MCP Inspector** ``` npx @modelcontextprotocol/inspector cargo run --manifest-path /abs/path/to/hopper-mcp/Cargo.toml -p hopper-mcpd -- ``` ## 工作流 ### 加载 Hopper 快照 ``` // open_session { "session": { "sessionId": "calculator", "binary": { "name": "Calculator", "format": "hopper-snapshot", "arch": "arm64" }, "functions": { "0x100003f50": { "name": "_main", "size": 96, "callees": ["0x100004010"] } } } } ``` Rust 守护进程规范化地址，并从快照中索引函数、资源、名称、字符串、注释、调用边和事务状态。 ### 执行后端边界 ``` // ingest_current_hopper { "backend": "mock" } ``` Mock 后端返回一个最小的 `live-{documentId}` 会话，并验证守护进程到代理的接缝。要请求配置好的原生/私有代理，请设置 `HOPPER_MCP_PRIVATE_AGENT_SOCKET` 并调用： ``` // ingest_current_hopper { "backend": "private" } ``` 私有路径连接到 Unix 套接字，执行 `hopper-wire` 版本化握手，请求当前文档和过程列表，并在套接字缺失、通信版本被拒绝、Hopper 报告没有当前文档或配置的后端非私有时故障即关闭。`backend: "auto"` 使用守护进程配置的任何后端；它不会静默切换证据质量。默认情况下，`hopper-agent` 使用 Hopper 捆绑的 `HopperMCPServer` 作为其真实证据源；传递 `--official-mcp-command PATH` 以针对备用命令进行测试。 ### SIP-Off 私有后端强力模式 这与已签名的公共 Hopper Tool Plugin 路径是独立的通道。请使用以下命令显式选择它： ``` // ingest_current_hopper { "backend": "private" } ``` 在通过 `backend_status` 或 `backend_diagnostics` 提取前诊断配置的私有通道。一个健康的私有后端会报告 `backend: "private"`、`backendMode: "injected_private"` 和 `readiness: "ready"`。 要进行主机预检，请运行： ``` cargo run -p hopper-mcpd -- doctor --require-private-host ``` 该检查仅适用于指定的已禁用 SIP 的主机。在代码中，当 `csrutil status` 报告 SIP 已禁用，或者在主机检测不可用的受控运行器中设置了 `HOPPER_MCP_ASSUME_SIP_DISABLED=1` 时，它将通过检查。在受控环境中，请使用 `--csrutil-command PATH` 或 `HOPPER_MCP_CSRUTIL=PATH` 覆盖探测命令。 仅在指定的已禁用 SIP 的 Hopper 主机上验证完整的私有通道： ``` npm run --silent release:check:private-backend ``` 私有后端门控运行 `doctor --require-private-host`，构建 `hopper-agent` 以及仅限 Foundation 的 Hopper Tool Plugin，安装插件包，通过经过验证的实时导出 Hopper 路径打开真实目标，然后通过 `scripts/private-backend-runtime.mjs` 验证私有套接字握手、当前文档和过程列表。默认探测使用临时的 `HOPPER_MCP_PRIVATE_AGENT_SOCKET`，并让 Hopper Tool Plugin 直接在 Hopper 内部托管私有套接字服务器；自定义启动器路径仅用于合成测试夹具。此通道的成功并不证明已签名的公共 Hopper Tool Plugin 路径有效。自托管的实时 CI 工作流将生成的 JSON 存储为 `reports/release-check-private-backend.json`，并将其作为 `hopper-release-gate-reports` 制品包的一部分上传。 已放弃的 `DYLD_INSERT_LIBRARIES` 注入实验不属于受支持的生产路径，也不会作为公共构建目标发布。 ### 提取实时 Hopper 导出 ``` // ingest_live_hopper { "executable_path": "/bin/echo", "timeout_ms": 90000, "max_functions": 20, "max_strings": 50, "close_after_export": true } ``` Rust 守护进程调用实时桥接，将规范化的 Hopper 会话提取到 Rust 存储中，并返回 `session`、`launch` 和 `diagnostics`。Universal Mach-O 输入使用 Hopper 的 `FAT` 加载器链启动，以避免手动架构选择器。`close_after_export` 默认为 `false`；对于一次性代理/测试运行，即希望在导出后清理 Hopper 文档的情况下，请将其设置为 `true`。 实时提取有意的上限设置，使得一个 MCP 调用不能无限期地独占守护进程：`timeout_ms <= 600000`、`max_functions <= 50000`、`max_strings <= 250000` 和 `max_pseudocode_functions <= 1000`。对于 `full_export: true`，省略的函数/字符串限制将使用这些硬上限填充，而不是变为无限制。 ### 注解生命周期 ``` begin_transaction -> returns transactionId queue(kind: rename | comment | inline_comment) preview_transaction -> review queued operations commit_transaction -> applies atomically to the local Rust store rollback_transaction -> discards queued operations ``` ## 工具集 Rust 守护进程为每个工具暴露严格的 schema。未知参数将在运行时被拒绝。 | 组 | 工具 | |---|---| | 元信息 / 后端 | `capabilities`、`backend_status`、`backend_diagnostics` | | 生命周期 / 提取 | `open_session`、`ingest_current_hopper`、`ingest_live_hopper` | | 快照读取 | `procedure`、`search`、`list`、`xrefs`、`containing_function`、`resolve`、`query`、`analyze_function_deep`、`get_graph_slice` | | 事务 | `begin_transaction`、`queue`、`preview_transaction`、`commit_transaction`、`rollback_transaction` | | 分析 | `compute_fingerprints`、`find_similar_functions`、`diff_sessions` | 鉴别器风格工具（`procedure`、`search`、`list`、`queue`）接受一个用于选择变体的 `kind:` 或 `field:` 参数。 **资源** - `hopper://session/current`、`hopper://binary/metadata`、`hopper://functions`、`hopper://strings`、`hopper://names` 和 `hopper://transactions/pending`。 **提示** - `function_triage`、`hypothesis_workspace`。 ## Rust 命令 ``` npm run start:rust npm run doctor npm run doctor:json npm run package:release npm run package:release:ad-hoc npm run package:release:check npm run package:verify -- dist/hopper-mcp-0.1.0-darwin-arm64.tar.gz npm run package:smoke -- dist/hopper-mcp-0.1.0-darwin-arm64.tar.gz npm run package:notarize -- dist/hopper-mcp-0.1.0-darwin-arm64.tar.gz npm run fetch:hopper-sdk npm run build:agent npm run build:hopper-plugin npm run hopper-plugin:service-name -- --socket /tmp/hopper-plugin.sock npm run hopper-plugin:identities npm run hopper-plugin:install npm run hopper-plugin:probe npm run cleanup:hopper-state npm run test:agent npm run build:rust npm run check:rust npm run fmt:rust npm run clippy:rust npm run test:rust npm run test:live npm run test:live:corpus:dry-run npm run test:live:corpus npm run test:live:corpus:large-apps npm run release:check npm run release:check:live npm run release:check:private-backend npm run release:check:internal npm run release:check:internal-soak npm run release:check:plugin-live npm run release:check:distribution npm run release:check:public-release npm run release:check:public ``` 此仓库中的生产就绪性分为两个显式配置文件： - `internal`：非实时验证、实时 Hopper 验证，以及在指定 Hopper 运行器上的 SIP-off 私有后端通道 - `internal-soak`：完整的内部配置文件，加上可选的大型应用实时语料浸泡测试 - `public`：签名插件验收、签名分发打包和公证公共发布 当您的声明针对某个完整的发布配置文件而不是单个门控时，请使用下面的配置文件封装器。 非实时 CI 发布门控： ``` npm run release:check ``` 非实时门控现在发出带有 `phase` 字段的结构化 JSON，并运行 JS 语法/测试、Rust 格式化、拒绝警告的 `cargo clippy`、Rust 测试、doctor 检查和包发布验证。要进行机器解析，推荐使用 `npm run --silent release:check`。GitHub 托管的 CI 作业将生成的 JSON 存储为 `reports/release-check.json`，并将其作为 `hopper-nonlive-release-gate-report` 制品上传。 在安装了 Hopper 并拥有自动化权限的 macOS 机器上进行完整的本地发布门控： ``` npm run release:check:live ``` 实时门控现在以 `doctor` 预检开始，该预检强制要求当前机器上存在 Hopper，然后打开一次性 Hopper 文档，提取它们，通过 `HOPPER_MCP_ENABLE_OFFICIAL_WRITES=1` 和 `confirm_live_write=true` 验证官方回写路径，关闭文档而不保存，并运行具有内容/性能预算的默认实时语料库。在 `test:live` 和实时语料库运行之前，封装器会清除任何现有的 GUI Hopper 进程并取消设置 `HOPPER_MCP_PLUGIN_SOCKET`，以使过时的交互式 Hopper 状态不会影响发布门控。清理失败在原本成功的运行中是致命的，因此如果阶段完成后 Hopper 仍然存在，门控将不会返回成功。门控发出带有 `phase` 字段的结构化 JSON，以便 Hopper 就绪失败可以与非实时门控、实时测试套件或实时语料库中的失败区分开来。要进行机器解析，推荐使用 `npm run --silent release:check:live`。自托管的实时 CI 工作流将生成的 JSON 存储为 `reports/release-check-live.json`，并将其作为 `hopper-release-gate-reports` 制品包的一部分上传。该工作流现在还在 `if: always()` 的最后步骤中运行 `npm run --silent cleanup:hopper-state`，存储 `reports/cleanup-hopper-state.json`，并在作业结束前清除运行器中任何残留的 Hopper GUI 进程和 `HOPPER_MCP_PLUGIN_SOCKET`。 在指定的 Hopper 运行器上的内部/私有生产配置文件： ``` npm run release:check:internal ``` 此封装器按顺序运行 `release:check`、`release:check:live` 和 `release:check:private-backend`，并返回带有 `profile: "internal"` 的结构化 JSON。此处的成功结果意味着仓库在指定运行器上已达到内部/私有 Hopper 使用的生产就绪状态。它不满足下面签名的公共发布要求。 在指定重型应用工作站上的扩展内部/私有浸泡配置文件： ``` npm run release:check:internal-soak ``` 此封装器运行 `release:check:internal`，然后运行 `corpus/live-large-apps.json` 中可选的重型实时语料库清单。该清单记录了在加固期间使用的大型应用稳定性通道，并保持每个目标为 `optional`，因此没有 Capture One、Chrome、VS Code、Safari、Resolve、Photoshop 或可用 Xcode 包的机器将跳过这些条目，而不是导致浸泡运行失败。 在安装了 Hopper 并拥有真实 Apple 开发者签名身份的 macOS 机器已签名的 Hopper 内插件门控： ``` npm run release:check:plugin-live ``` 此门控在缺少代码签名身份时会快速失败，然后运行端到端插件探测，以便已签名的 `HopperMCPAgent.hopperTool` 路径作为第一方发布步骤进行验证，而不是临时的手动命令。在探测之前，封装器会清除任何现有的 Hopper GUI 进程并取消设置 `HOPPER_MCP_PLUGIN_SOCKET`，以使过时的交互状态不会影响签名插件验收运行。清理失败在原本成功的运行中是致命的，因此如果之后 Hopper 仍然存在，门控将不会返回成功。门控现在发出带有 `phase` 字段的结构化 JSON，以便 CI 和发布操作员可以区分签名就绪失败与探测失败。要进行机器解析，推荐使用 `npm run --silent release:check:plugin-live`。自托管的实时 CI 工作流将生成的 JSON 存储为 `reports/release-check-plugin-live.json`，并将其作为 `hopper-release-gate-reports` 制品包的一部分上传。 如果您只需要签名预检而不触碰 Hopper，请运行： ``` npm run doctor:plugin-live ``` 在具有真实签名身份的 macOS 机器上的签名分发门控： ``` npm run release:check:distribution ``` 这会运行非实时发布门控，然后要求通过 `npm run package:release` 构建真实的签名分发制品。门控发出带有 `phase` 字段的结构化 JSON，以便非实时门控中的失败可以与签名打包失败区分开来。它现在以 `doctor` 预检开始，该预检强制要求具有 `Developer ID Application` 分发身份和干净的 git 工作树，以使配置错误的发布主机在非实时门控中花费时间之前失败。 要进行机器解析，推荐使用 `npm run --silent release:check:distribution`。自托管的实时 CI 工作流将生成的 JSON 存储为 `reports/release-check-distribution.json`，并将其作为 `hopper-release-gate-reports` 制品包的一部分上传。 如果您只需要签名分发主机预检而不进行构建，请运行： ``` npm run doctor:distribution ``` 在具有真实签名身份和 Apple 公证凭据的 macOS 机器上的公共发布门控： ``` npm run release:check:public-release ``` 这会运行签名分发门控，然后通过 `package:notarize` 对生成的制品进行公证。它现在以 `doctor` 预检开始，该预检强制要求同时具有 `Developer ID Application` 分发身份和 Apple 公证凭据，以及干净的 git 工作树，以使配置错误的发布主机在进行构建工作之前失败。要进行机器解析，推荐使用 `npm run --silent release:check:public-release`。自托管的实时 CI 工作流将生成的 JSON 存储为 `reports/release-check-public-release.json`，并将其作为 `hopper-release-gate-reports` 制品包的一部分上传。 在准备好的 macOS 发布主机上的公共签名发布生产配置文件： ``` npm run release:check:public ``` 此封装器按顺序运行 `release:check:plugin-live`、`release:check:distribution` 和 `release:check:public-release`，并返回带有 `profile: "public"` 的结构化 JSON。此处的成功结果意味着已签名的 Hopper 插件、打包的分发制品和公证的公共发布路径均已达到生产就绪状态。 如果您只需要公共发布主机预检而不进行构建或公证，请运行： ``` npm run doctor:public-release ``` `npm run doctor` 验证存储路径、Node 实时桥接命令、桥接脚本、Hopper 安装、本地 Apple 代码签名身份可用性、公共分发身份就绪状态、Apple 公证凭据就绪状态，以及在配置时的私有代理套接字就绪状态。缺少 Hopper、缺少签名身份、缺少公共发布先决条件以及未设置的私有套接字默认为警告，以便非实时 CI 可以在干净的机器上运行；对于实时发布运行器，请使用 `cargo run -p hopper-mcpd -- doctor --require-hopper`。 结构化 JSON 报告现在包含一个可选的每个检查的 `remediation` 字段，文本输出将这些提示呈现为 `next:` 行，因此发布主机可以看到确切的后续命令或环境变量进行修复。 当您需要无法实时加载 Hopper Tool Plugin 的机器发生硬失败时，请使用 `cargo run -p hopper-mcpd -- doctor --require-plugin-identity`。当您需要无法生成签名公共分发制品的机器发生硬失败时，请使用 `cargo run -p hopper-mcpd -- doctor --require-distribution-identity`。当您需要发布主机从已提交的检出构建时才发生硬失败时，请使用 `cargo run -p hopper-mcpd -- doctor --require-clean-git-tree`，当您需要无法提交至 Apple 公证的机器发生硬失败时，请使用 `cargo run -p hopper-mcpd -- doctor --require-notary-credentials`。使用 `--private-agent-socket PATH` 或 `HOPPER_MCP_PRIVATE_AGENT_SOCKET=PATH` 使 doctor 探测原生/私有后端握手，在受控环境中使用 `--security-command PATH` 或 `HOPPER_MCP_SECURITY=PATH` 注入特定的 `security` 二进制文件。 仅在指定的已禁用 SIP 的私有后端主机上使用 `cargo run -p hopper-mcpd -- doctor --require-private-host`。该预检证明主机有资格进入私有通道，并且在代码中它通过 `csrutil status` 检测 SIP 状态，除非显式设置了 `HOPPER_MCP_ASSUME_SIP_DISABLED=1`。套接字级别的私有就绪状态随后由 `backend_diagnostics`、私有提取和 `release:check:private-backend` 证明。在受控环境中使用 `--csrutil-command PATH` 或 `HOPPER_MCP_CSRUTIL=PATH` 注入特定的探测二进制文件。 `npm run fetch:hopper-sdk` 从 Hopper 官方文件 API 下载当前公共 Hopper SDK 元数据，验证该 API 发布的 SDK zip SHA-1，并将其解压到 `.cache/hopper-sdk/` 下。该 SDK 未被供应商化至本仓库中。 `npm run build:hopper-plugin` 针对该 SDK 从 `agents/hopper-tool-plugin` 编译 `target/release/HopperMCPAgent.hopperTool`。该插件使用 Hopper 的公共 SDK 接口获取 `currentDocument`、过程地址、过程名称、基本块派生的大小，以及一个以配置的插件套接字路径为键值的 Foundation 分布式对象桥接。默认情况下，该套接字路径为 `~/Library/Application Support/hopper-mcp/hopper-plugin.sock`；在启动 Hopper 之前设置 `HOPPER_MCP_PLUGIN_SOCKET` 以覆盖它。外部原生辅助程序可以使用以下命令派生匹配的桥接服务名称： ``` npm run hopper-plugin:service-name -- --socket /tmp/hopper-plugin.sock ``` 使用以下命令将插件包安装并签名到 Hopper 官方用户插件目录： ``` npm run hopper-plugin:install ``` 该命令将构建好的包复制到 `~/Library/Application Support/Hopper/PlugIns/v4/Tools/HopperMCPAgent.hopperTool`，并在设置 `HOPPER_MCP_CODESIGN_IDENTITY` 时使用它进行签名。如果未配置身份，该命令现在将快速失败，而不是静默生成 Hopper 通常会拒绝加载的即席签名包。使用以下命令检查本地签名身份： ``` npm run hopper-plugin:identities ``` Hopper 的 SDK 文档指出，macOS 11+ 插件必须使用 Apple 开发者证书签名才能加载。在 `hopper-plugin:identities` 报告没有有效身份的机器上，Hopper 可能会拒绝甚至是最小的工具插件，并伴随通用的 "external function(s)" 加载器错误；请将此视为环境阻碍，而不是插件协议错误的证据。 如果您有意需要即席签名的包用于夹具或线束工作，请显式做出该选择： ``` npm run hopper-plugin:install -- --ad-hoc ``` 即席签名并非 Hopper 会在真实 macOS 11+ 主机上接受该插件的有效证据。 要使用一个命令验证整个 Hopper 内桥接路径，请使用： ``` npm run hopper-plugin:probe ``` 探测安装插件，默认要求真实的 Apple 代码签名身份，使用 `launchctl setenv` 将 `HOPPER_MCP_PLUGIN_SOCKET` 植入 GUI 启动域，在 `/bin/echo` 上启动 Hopper，启动 `hopper-agent --plugin-service auto`，验证 `hopper-wire` 握手以及 current-document/procedure 响应，然后在取消设置 GUI 域套接字变量之前终止探测启动的代理和 Hopper 进程。如果插件包链接了 `AppKit` 或 `Cocoa`，`hopper-plugin:install` 和 `hopper-plugin:probe` 现在都会快速失败；Hopper 内的 Tool Plugin 路径预期保持仅限 Foundation。仅在用于仅限夹具的开发或注入的测试线束时使用 `-- --skip-sign`；这不是 Hopper 会在真实 macOS 11+ 主机上接受该插件的证据。 `npm run package:release` 构建 `target/release/hopper-mcpd`，并在 `dist/` 下写入版本化的 tarball 以及 `.sha256` 校验和。在 macOS 上，发布构建现在要求通过 `HOPPER_MCP_CODESIGN_IDENTITY` 提供真实的签名身份；对于公共分发，该身份必须是 `Developer ID Application` 身份。签名分发构建还要求干净的 git 工作树，以便打包的来源与已提交的源状态匹配。该构建不再静默回退到分发制品的即席签名。对于分发级签名非主张的本地夹具或冒烟打包，请使用： ``` npm run package:release:ad-hoc ``` 发布构建编译并签名 `target/release/hopper-agent` 和 `target/release/HopperMCPAgent.hopperTool`。tarball 包含 `release-manifest.json`，其中包含每个文件的字节数、SHA-256 哈希以及 git 源来源（`commit` 加上干净/脏工作树状态），以及捆绑运行时文件的构建/签名来源（`nodeVersion`、`cargoVersion` 和即席与 Developer ID 签名模式）。对于相同的暂存输入，归档路径现在是确定性的：暂存的 mtimes 被规范化，tar 所有权元数据被固定，gzip 使用 `-n` 运行，以便压缩制品不带每次运行的 timestamp。该捆绑包将 `bin/hopper-mcp`、`target/release/hopper-mcpd`、`target/release/hopper-agent`、`target/release/HopperMCPAgent.hopperTool` 和 `src/live-bridge-cli.js` 保留在同一根目录下，以便 Rust 守护进程在提取后能够找到实时桥接和私有代理制品。 `npm run package:release:check` 在临时目录中构建相同的布局，验证校验和，将其解压，验证 `release-manifest.json`，拒绝不安全或意外的归档成员，针对受控格式错误请求执行打包的实时桥接，针对受控格式错误请求验证打包的守护进程签名，执行打包的 `hopper-agent` 夹具和真实桥接 `hopper-wire` 握手/current-document/procedure 冒烟测试，使用 `codesign` 验证打包的守护进程/代理/插件签名，验证打包的 Hopper Tool Plugin 不链接 AppKit/Cocoa，运行打包的 `doctor`，并执行 MCP 初始化握手。此验证路径在内部使用显式的即席打包模式，因此本地发布检查仍可在没有分发身份的机器上运行。在分发之前验证并对制品进行冒烟测试： ``` npm run package:verify -- dist/hopper-mcp-0.1.0-darwin-arm64.tar.gz npm run package:smoke -- dist/hopper-mcp-0.1.0-darwin-arm64.tar.gz ``` 对于 Apple 公证，首先构建并对 tarball 进行冒烟测试，然后运行： ``` HOPPER_MCP_NOTARY_PROFILE=profile-name npm run package:notarize -- dist/hopper-mcp-0.1.0-darwin-arm64.tar.gz ``` `package:notarize` 重新运行包冒烟验证，将提取的 tarball 内容包装在临时的 ZIP 提交有效负载中，验证打包的守护进程是否使用 `Developer ID Application` 身份签名，并调用 `xcrun notarytool submit --wait --output-format json`。构建 tarball 时使用 `HOPPER_MCP_CODESIGN_IDENTITY`，对于存储的 notarytool 钥匙串配置文件使用 `HOPPER_MCP_NOTARY_PROFILE`，或者为直接凭据设置 `APPLE_ID`、`APPLE_TEAM_ID` 和 `APPLE_PASSWORD`。 `npm run test:live:corpus` 通过实时 Hopper 提取运行 `corpus/live-smoke.json`，并发出带有每个目标计时/计数/断言的 JSON 报告。默认清单涵盖几个稳定的 macOS 系统二进制文件，并将 Finder 作为已解析但禁用的 app-bundle 目标用于更重的本地运行。使用 `npm run test:live:corpus:dry-run` 验证目标解析而不打开 Hopper。传递 `-- --report path/to/report.json` 以持久化报告；清单目标可以强制执行 `min_functions`、`min_strings` 和 `max_elapsed_ms` 预算。 `npm run test:live:corpus:large-apps` 运行可选的 `corpus/live-large-apps.json` 清单。它专为本地研究工作站设计，并记录了更重的真实应用浸泡通道，包含 Capture One、Chrome、VS Code、Safari、Resolve、Photoshop 和 Xcode 的可选目标。 ## 协议说明 - Stdio 传输，换行符分隔的 JSON-RPC。 - 支持的 MCP 协版本：`2025-11-25`。 - 工具结果同时包含 JSON 文本块和 `structuredContent`。 - 带有显式 `id: null` 的请求将被拒绝，而不是被视为通知。 ## 布局 ``` MCP client -> stdio JSON-RPC -> crates/hopper-mcpd/src/main.rs Rust process entry |- protocol.rs MCP/JSON-RPC response types |- model.rs normalized Hopper snapshot types |- store.rs indexed snapshot store and resources |- tools.rs strict tool registry and handlers |- transactions.rs local transaction lifecycle |- persistence.rs atomic JSON persistence |- live.rs subprocess live-export bridge `- backend.rs versioned backend boundary ``` ``` JavaScript migration reference only -> src/mcp-server.js |- src/server-tools.js |- src/server-resources.js |- src/server-prompts.js |- src/knowledge-store.js |- src/live-bridge-cli.js |- src/hopper-live.js `- src/official-hopper-backend.js ``` ``` Native private backend artifact -> agents/hopper-agent |- Makefile `- src/main.mm Objective-C++ hopper-wire socket agent Native Hopper Tool Plugin artifact -> agents/hopper-tool-plugin |- Makefile |- Info.plist `- src/HopperMCPAgent.m in-Hopper hopper-wire socket agent ``` 延伸阅读： - `docs/adapter-protocol.md` - 内部适配器通信格式 - `docs/official-hopper-mcp-notes.md` - 关于 Hopper 官方 MCP 服务器的说明 - `CONTRIBUTING.md` - 开发设置与 PR 约定 ## 许可证 MIT - 请参阅 `LICENSE`。

标签：DAST, DLL 劫持, DNS 反向解析, GNU通用公共许可证, Hopper反汇编器, macOS安全, MCP服务器, MITM代理, Node.js, Objective-C++, Python桥接, Rust重写, Unix域套接字, 二进制分析, 云安全监控, 云安全运维, 云资产清单, 人工智能辅助安全, 可视化界面, 大语言模型, 安全分析工具, 恶意软件分析, 数据可视化, 网络安全, 网络安全审计, 自定义脚本, 跨平台开发, 逆向工程, 隐私保护, 静态分析