Hopper MCP

An MCP server that gives an LLM client structured, transaction-safe access to Hopper-derived reverse-engineering snapshots without putting the disassembler in the model's context window.

The production rewrite is crates/hopper-mcpd. It owns MCP stdio, snapshot indexing, query, resources, prompts, local transactions, persistence, Rust-side live ingest orchestration, and the versioned hopper-wire backend boundary. The JavaScript server is retained as a migration reference and live-export bridge until the native/private backend fully replaces it.

The public analysis surface is Hopper-native. It does not expose local otool, nm, strings, or codesign fallback tools; if Hopper has not analyzed or exported evidence, the server reports that gap instead of fabricating local heuristics.

Current Rust Scope

• open_session loads a Hopper-derived JSON snapshot into the indexed Rust store.

• ingest_current_hopper exercises the backend boundary with either the mock backend or a configured private hopper-wire Unix-socket agent.

• ingest_live_hopper is exposed by the Rust daemon and delegates safe Hopper Python export to the Node live bridge.

• Snapshot read tools cover list/search/resolve/procedure/xrefs/containing function queries.

• Analysis tools cover graph slices, deep function summaries, fingerprints, similarity, diffs, and query DSL.

• Resources and prompts are exposed through MCP resources/* and prompts/*.

• Local transactions support rename, comment, and inline comment changes with preview/commit/rollback.

• hopper-wire pins the daemon-to-agent JSON contract with versioned request/response types.

• agents/hopper-agent builds an Objective-C++ Unix-socket agent artifact that speaks the hopper-wire handshake, current-document, and procedure-list protocol.

• agents/hopper-tool-plugin builds a signed Hopper Tool Plugin bundle that can expose the same hopper-wire protocol from inside Hopper using the official Hopper SDK.

Private Hopper live extraction is implemented on the daemon side as a fail-closed hopper-wire Unix-socket client and on the native side as packaged Objective-C++ agents. Today, non-fixture hopper-agent mode bridges real Hopper evidence through Hopper's bundled MCP subprocess and returns structured errors when Hopper has no current document. HopperMCPAgent.hopperTool is the direct in-Hopper plugin path and is built from the official SDK. The plugin now publishes a Foundation bridge service keyed off the configured plugin socket path, and hopper-agent --plugin-service auto can expose that service through the existing hopper-wire Unix socket contract. Hopper will only live-load that plugin when it is signed with a real Apple codesigning identity; ad-hoc signatures are sufficient for packaging smoke but are not sufficient evidence of live plugin acceptance. hopper-agent --fixture is only for tests/package smoke, so fixture data cannot be mistaken for live Hopper evidence.

Related MCP server: cutterMCP

Requirements

• macOS

• Rust toolchain

• Node.js 20+ for npm wrappers, migration-reference tests, and the v1 live-export bridge

• Hopper.app installed for live ingest tests and workflows

Install

git clone <this repo> hopper-mcp
cd hopper-mcp
npm install
npm run build:rust
npm run doctor
npm run test:rust
npm test

Add To A Client

Replace /abs/path/to/hopper-mcp with the absolute path to your clone.

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 / generic 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 --

Workflows

Load A Hopper Snapshot

// open_session
{
  "session": {
    "sessionId": "calculator",
    "binary": {
      "name": "Calculator",
      "format": "hopper-snapshot",
      "arch": "arm64"
    },
    "functions": {
      "0x100003f50": {
        "name": "_main",
        "size": 96,
        "callees": ["0x100004010"]
      }
    }
  }
}

The Rust daemon normalizes addresses and indexes functions, resources, names, strings, comments, call edges, and transaction state from the snapshot.

Exercise The Backend Boundary

// ingest_current_hopper
{ "backend": "mock" }

The mock backend returns a minimal live-{documentId} session and proves the daemon-to-agent seam. To require a configured native/private agent, set HOPPER_MCP_PRIVATE_AGENT_SOCKET and call:

// ingest_current_hopper
{ "backend": "private" }

The private path connects to the Unix socket, performs a hopper-wire versioned handshake, requests the current document and procedure list, and fails closed if the socket is missing, the wire version is rejected, Hopper reports no current document, or the configured backend is not private. backend: "auto" uses whichever backend the daemon was configured with; it does not silently switch evidence quality. By default, hopper-agent uses Hopper's bundled HopperMCPServer as its real evidence source; pass --official-mcp-command PATH to test against an alternate command.

SIP-Off Private Backend Power Mode

This is a separate lane from the signed public Hopper Tool Plugin path. Select it explicitly with:

// ingest_current_hopper
{ "backend": "private" }

Diagnose the configured private lane before ingesting with backend_status or backend_diagnostics. A healthy private backend reports backend: "private", backendMode: "injected_private", and readiness: "ready".

For host preflight, run:

cargo run -p hopper-mcpd -- doctor --require-private-host

That check is intended only for a designated SIP-disabled host. In code it passes when csrutil status reports SIP disabled, or when HOPPER_MCP_ASSUME_SIP_DISABLED=1 is set for controlled runners where host detection is unavailable. Override the probe command with --csrutil-command PATH or HOPPER_MCP_CSRUTIL=PATH in controlled environments.

Validate the full private lane only on a designated SIP-disabled Hopper host:

npm run --silent release:check:private-backend

The private-backend gate runs doctor --require-private-host, builds hopper-agent plus the Foundation-only Hopper Tool Plugin, installs the plugin bundle, opens a real target through the proven live-export Hopper path, then verifies private socket handshake, current document, and procedure list via scripts/private-backend-runtime.mjs. The default probe uses a temporary HOPPER_MCP_PRIVATE_AGENT_SOCKET and lets the Hopper Tool Plugin host the private socket server directly inside Hopper; the custom launcher path remains only for synthetic test fixtures. Success in this lane does not prove the signed public Hopper Tool Plugin path. The self-hosted live CI workflow stores the resulting JSON as reports/release-check-private-backend.json and uploads it as part of the hopper-release-gate-reports artifact bundle.

The abandoned DYLD_INSERT_LIBRARIES injection experiment is not part of the supported production path and is not shipped as a public build target.

Ingest A Live Hopper Export

// ingest_live_hopper
{
  "executable_path": "/bin/echo",
  "timeout_ms": 90000,
  "max_functions": 20,
  "max_strings": 50,
  "close_after_export": true
}

The Rust daemon invokes the live bridge, ingests the normalized Hopper session into the Rust store, and returns session, launch, and diagnostics. Universal Mach-O inputs are launched with Hopper's FAT loader chain to avoid the manual architecture picker. close_after_export defaults to false; set it to true for throwaway agent/test runs where the Hopper document should be cleaned up after export.

Live ingest is intentionally capped so one MCP call cannot monopolize the daemon indefinitely: timeout_ms <= 600000, max_functions <= 50000, max_strings <= 250000, and max_pseudocode_functions <= 1000. For full_export: true, omitted function/string limits are filled with those hard caps instead of becoming unbounded.

Annotation Lifecycle

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

Tool Surface

The Rust daemon exposes strict schemas for every tool. Unknown arguments are rejected at runtime.

Discriminator-style tools (procedure, search, list, queue) take a kind: or field: argument that selects the variant.

Resources - hopper://session/current, hopper://binary/metadata, hopper://functions, hopper://strings, hopper://names, and hopper://transactions/pending.

Prompts - function_triage, hypothesis_workspace.

Rust Commands

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

Production readiness in this repo is split into two explicit profiles:

• internal: non-live verification, live Hopper verification, and the SIP-off private-backend lane on a designated Hopper runner

• internal-soak: the full internal profile plus the optional large-app live corpus soak

• public: signed plugin acceptance, signed distribution packaging, and notarized public release

Use the profile wrappers below when your claim is about one complete release profile rather than a single gate.

Non-live CI release gate:

npm run release:check

The non-live gate now emits structured JSON with a phase field and runs JS syntax/tests, Rust formatting, cargo clippy with warnings denied, Rust tests, doctor checks, and package release verification. For machine parsing, prefer npm run --silent release:check. The GitHub-hosted CI job stores the resulting JSON as reports/release-check.json and uploads it as the hopper-nonlive-release-gate-report artifact.

Full local release gate on a macOS machine with Hopper installed and Automation permission:

npm run release:check:live

The live gate now starts with a doctor preflight that hard-requires Hopper on the current machine, then opens throwaway Hopper documents, ingests them, verifies the official write-back path with HOPPER_MCP_ENABLE_OFFICIAL_WRITES=1 plus confirm_live_write=true, closes the documents without saving, and runs the default live corpus with its content/performance budgets. Before test:live and before the live corpus run, the wrapper clears any existing GUI Hopper process and unsets HOPPER_MCP_PLUGIN_SOCKET so stale interactive Hopper state cannot poison the release gate. Cleanup failures are fatal on otherwise-successful runs, so the gate will not return green if Hopper still persists after a phase completes. The gate emits structured JSON with a phase field so Hopper-readiness failures are distinguishable from failures in the non-live gate, live suite, or live corpus. For machine parsing, prefer npm run --silent release:check:live. The self-hosted live CI workflow stores the resulting JSON as reports/release-check-live.json and uploads it as part of the hopper-release-gate-reports artifact bundle. That workflow now also runs npm run --silent cleanup:hopper-state as a final if: always() step, stores reports/cleanup-hopper-state.json, and clears any leftover Hopper GUI processes plus HOPPER_MCP_PLUGIN_SOCKET from the runner before the job ends.

Internal/private production profile on the designated Hopper runner:

npm run release:check:internal

This wrapper runs release:check, release:check:live, and release:check:private-backend in order and returns structured JSON with profile: "internal". A green result here means the repo is production-ready for internal/private Hopper use on the designated runner. It does not satisfy the signed public-release requirements below.

Extended internal/private soak profile on a designated heavy-app workstation:

npm run release:check:internal-soak

This wrapper runs release:check:internal and then the optional heavyweight live corpus manifest from corpus/live-large-apps.json. That manifest records the large-app stability lane used during hardening and keeps each target optional, so machines without Capture One, Chrome, VS Code, Safari, Resolve, Photoshop, or a usable Xcode bundle will skip those entries instead of failing the soak run.

Signed in-Hopper plugin gate on a macOS machine with Hopper installed and a real Apple developer signing identity:

npm run release:check:plugin-live

This gate fails fast on missing codesigning identities, then runs the end-to-end plugin probe so the signed HopperMCPAgent.hopperTool path is validated as a first-class release step rather than an ad hoc manual command. Before probing, the wrapper clears any existing Hopper GUI process and unsets HOPPER_MCP_PLUGIN_SOCKET so stale interactive state cannot poison the signed plugin acceptance run. Cleanup failures are fatal on otherwise-successful runs, so the gate will not return green if Hopper still persists afterward. The gate now emits structured JSON with a phase field so CI and release operators can distinguish a signing-readiness failure from a probe failure. For machine parsing, prefer npm run --silent release:check:plugin-live. The self-hosted live CI workflow stores the resulting JSON as reports/release-check-plugin-live.json and uploads it as part of the hopper-release-gate-reports artifact bundle.

If you only need the signing preflight without touching Hopper, run:

npm run doctor:plugin-live

Signed distribution gate on a macOS machine with a real signing identity:

npm run release:check:distribution

This runs the non-live release gate and then requires a real signed distribution artifact build via npm run package:release. The gate emits structured JSON with a phase field so failures in the non-live gate are distinguishable from signed packaging failures. It now starts with a doctor preflight that hard-requires a Developer ID Application distribution identity and a clean git worktree so misconfigured release hosts fail before spending time in the non-live gate. For machine parsing, prefer npm run --silent release:check:distribution. The self-hosted live CI workflow stores the resulting JSON as reports/release-check-distribution.json and uploads it as part of the hopper-release-gate-reports artifact bundle.

If you only need the signed-distribution host preflight without building, run:

npm run doctor:distribution

Public release gate on a macOS machine with a real signing identity and Apple notary credentials:

npm run release:check:public-release

This runs the signed distribution gate and then notarizes the resulting artifact through package:notarize. It now starts with a doctor preflight that hard-requires both a Developer ID Application distribution identity and Apple notarization credentials, plus a clean git worktree, so misconfigured release hosts fail before doing build work. For machine parsing, prefer npm run --silent release:check:public-release. The self-hosted live CI workflow stores the resulting JSON as reports/release-check-public-release.json and uploads it as part of the hopper-release-gate-reports artifact bundle.

Public signed-release production profile on a prepared macOS release host:

npm run release:check:public

This wrapper runs release:check:plugin-live, release:check:distribution, and release:check:public-release in order and returns structured JSON with profile: "public". A green result here means the signed Hopper plugin, packaged distribution artifact, and notarized public release paths are all production-ready.

If you only need the public-release host preflight without building or notarizing, run:

npm run doctor:public-release

npm run doctor validates the store path, Node live bridge command, bridge script, Hopper installation, local Apple codesigning identity availability, public distribution identity readiness, Apple notarization credential readiness, and private-agent socket readiness when configured. Missing Hopper, missing signing identities, missing public-release prerequisites, and an unset private socket are warnings by default so non-live CI can run on clean machines; use cargo run -p hopper-mcpd -- doctor --require-hopper for live release runners. The structured JSON report now includes an optional per-check remediation field, and text output renders those hints as next: lines, so release hosts can see the exact follow-up command or environment variable to fix. Use cargo run -p hopper-mcpd -- doctor --require-plugin-identity when you need a hard failure on machines that cannot live-load the Hopper Tool Plugin. Use cargo run -p hopper-mcpd -- doctor --require-distribution-identity when you need a hard failure on machines that cannot produce a signed public distribution artifact. Use cargo run -p hopper-mcpd -- doctor --require-clean-git-tree when you need a hard failure unless the release host is building from a committed checkout, and cargo run -p hopper-mcpd -- doctor --require-notary-credentials when you need a hard failure on machines that cannot submit to Apple notarization. Use --private-agent-socket PATH or HOPPER_MCP_PRIVATE_AGENT_SOCKET=PATH to make doctor probe the native/private backend handshake, and --security-command PATH or HOPPER_MCP_SECURITY=PATH to inject a specific security binary in controlled environments. Use cargo run -p hopper-mcpd -- doctor --require-private-host only on a designated SIP-disabled private-backend host. That preflight proves the host is eligible for the private lane, and in code it detects SIP state via csrutil status unless HOPPER_MCP_ASSUME_SIP_DISABLED=1 is set explicitly. Socket-level private readiness is then proven by backend_diagnostics, private ingest, and release:check:private-backend. Use --csrutil-command PATH or HOPPER_MCP_CSRUTIL=PATH to inject a specific probe binary in controlled environments.

npm run fetch:hopper-sdk downloads the current public Hopper SDK metadata from Hopper's official files API, verifies the SDK zip SHA-1 published by that API, and unpacks it under .cache/hopper-sdk/<version>. The SDK is not vendored into this repository.

npm run build:hopper-plugin compiles target/release/HopperMCPAgent.hopperTool from agents/hopper-tool-plugin against that SDK. The plugin uses Hopper's public SDK interfaces for currentDocument, procedure addresses, procedure names, basic-block-derived sizes, and a Foundation distributed-object bridge that is keyed off the configured plugin socket path. By default that socket path is ~/Library/Application Support/hopper-mcp/hopper-plugin.sock; set HOPPER_MCP_PLUGIN_SOCKET before launching Hopper to override it. The external native helper can derive the matching bridge service name with:

npm run hopper-plugin:service-name -- --socket /tmp/hopper-plugin.sock

Install and sign the plugin bundle into Hopper's official user plugin directory with:

npm run hopper-plugin:install

That command copies the built bundle into ~/Library/Application Support/Hopper/PlugIns/v4/Tools/HopperMCPAgent.hopperTool and signs it with HOPPER_MCP_CODESIGN_IDENTITY when set. If no identity is configured, the command now fails fast instead of silently producing an ad-hoc signed bundle that Hopper will usually refuse to load. Check local signing identities with:

npm run hopper-plugin:identities

Hopper's SDK documentation states that macOS 11+ plugins must be signed with an Apple developer certificate to load. On machines where hopper-plugin:identities reports no valid identities, Hopper may reject even minimal tool plugins with a generic "external function(s)" loader error; treat that as an environment blocker, not as evidence that the plugin protocol is wrong.

If you intentionally need an ad-hoc-signed bundle for fixture or harness work, make that choice explicit:

npm run hopper-plugin:install -- --ad-hoc

Ad-hoc signing is not valid evidence that Hopper will accept the plugin on a real macOS 11+ host.

To validate the whole in-Hopper bridge path with one command, use:

npm run hopper-plugin:probe

The probe installs the plugin, requires a real Apple codesigning identity by default, seeds HOPPER_MCP_PLUGIN_SOCKET into the GUI launch domain with launchctl setenv, launches Hopper on /bin/echo, starts hopper-agent --plugin-service auto, verifies the hopper-wire handshake plus current-document/procedure responses, and then terminates the probe-launched agent and Hopper processes before unsetting the GUI-domain socket variable again. Both hopper-plugin:install and hopper-plugin:probe now fail fast if the plugin bundle links AppKit or Cocoa; the in-Hopper Tool Plugin path is expected to stay Foundation-only. Use -- --skip-sign only for fixture-only development or injected test harnesses; it is not evidence that Hopper will accept the plugin on a real macOS 11+ host.

npm run package:release builds target/release/hopper-mcpd and writes a versioned tarball plus .sha256 checksum under dist/. On macOS the release build now requires a real signing identity through HOPPER_MCP_CODESIGN_IDENTITY; for public distribution that identity must be a Developer ID Application identity. Signed distribution builds also require a clean git worktree so the packaged provenance matches a committed source state. The build no longer silently falls back to ad-hoc signing for distribution artifacts. For local fixture or smoke packaging where distribution-grade signing is not the claim, use:

npm run package:release:ad-hoc

The release build compiles and signs target/release/hopper-agent and target/release/HopperMCPAgent.hopperTool. The tarball includes release-manifest.json with per-file byte counts, SHA-256 hashes, and git source provenance (commit plus clean/dirty tree state), plus build/signing provenance (nodeVersion, cargoVersion, and ad-hoc vs Developer ID signing mode) for the bundled runtime files. The archive path is now deterministic for identical staged inputs: staged mtimes are normalized, tar ownership metadata is fixed, and gzip runs with -n so the compressed artifact does not carry a per-run timestamp. The bundle keeps bin/hopper-mcp, target/release/hopper-mcpd, target/release/hopper-agent, target/release/HopperMCPAgent.hopperTool, and src/live-bridge-cli.js under the same root so the Rust daemon can find the live bridge and private agent artifacts after extraction. npm run package:release:check builds the same layout in a temporary directory, verifies the checksum, extracts it, validates release-manifest.json, rejects unsafe or unexpected archive members, executes the packaged live bridge against a controlled malformed request, verifies the packaged daemon signature against a controlled malformed request, executes a packaged hopper-agent fixture and real-bridge hopper-wire handshake/current-document/procedure smoke, verifies packaged daemon/agent/plugin signatures with codesign, verifies that the packaged Hopper Tool Plugin does not link AppKit/Cocoa, runs packaged doctor, and performs an MCP initialize handshake. This verification path uses an explicit ad-hoc packaging mode internally so local release checks still run on machines without a distribution identity. Verify and smoke-test an artifact before distributing it:

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

For Apple notarization, first build and smoke the tarball, then run:

HOPPER_MCP_NOTARY_PROFILE=profile-name npm run package:notarize -- dist/hopper-mcp-0.1.0-darwin-arm64.tar.gz

package:notarize re-runs package smoke verification, wraps the extracted tarball contents in a temporary ZIP submission payload, verifies that the packaged daemon is signed with a Developer ID Application identity, and calls xcrun notarytool submit --wait --output-format json. Use HOPPER_MCP_CODESIGN_IDENTITY when building the tarball, and use HOPPER_MCP_NOTARY_PROFILE for a stored notarytool keychain profile, or set APPLE_ID, APPLE_TEAM_ID, and APPLE_PASSWORD for direct credentials.

npm run test:live:corpus runs corpus/live-smoke.json through live Hopper ingest and emits a JSON report with per-target timing/counts/assertions. The default manifest covers several stable macOS system binaries and keeps Finder as a resolved-but-disabled app-bundle target for heavier local runs. Use npm run test:live:corpus:dry-run to validate target resolution without opening Hopper. Pass -- --report path/to/report.json to persist the report; manifest targets can enforce min_functions, min_strings, and max_elapsed_ms budgets.

npm run test:live:corpus:large-apps runs the optional corpus/live-large-apps.json manifest. It is intended for local research workstations and records the heavier real-app soak lane with optional targets for Capture One, Chrome, VS Code, Safari, Resolve, Photoshop, and Xcode.

Protocol Notes

• Stdio transport, newline-delimited JSON-RPC.

• Supported MCP protocol version: 2025-11-25.

• Tool results carry both a JSON text block and structuredContent.

• Requests with explicit id: null are rejected instead of treated as notifications.

Layout

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

Further reading:

• docs/adapter-protocol.md - internal adapter wire format

• docs/official-hopper-mcp-notes.md - notes on Hopper's official MCP server

• CONTRIBUTING.md - dev setup and PR conventions

License

MIT - see LICENSE.