Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
Fix AI writing audit findings and rebuild onboarding flow
morlutoc2c3d989ebb4
diff --git a/AGENTS.md b/AGENTS.mdindex 25753c98b..792a1cdad 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -14,7 +14,7 @@ The server is a layered ESM TypeScript application. Dependencies flow inward: `d- `src/server/`: MCP request translation. `createServer.ts` assembles the MCP server, `registerOfficialTools.ts`/`registerEnhancedTools.ts` register each tool set, `toolResult.ts` maps `Result` values to MCP content.- `tests/`: Vitest suite. `tests/fixtures/` holds the fake launcher and fake Hopper bridge used as production seams.- `scripts/verify-real-hopper.mjs`: real-Hopper end-to-end verifier.-- `scripts/print-mcp-config.mjs`: prints a ready-to-paste MCP server config with absolute paths filled in (`npm run config:print -- /path/to/binary`).+- `scripts/print-mcp-config.mjs`: prints an MCP server config with absolute paths filled in (`npm run config:print -- /path/to/binary`).## Build, Test, and Development Commands@@ -26,7 +26,7 @@ The server is a layered ESM TypeScript application. Dependencies flow inward: `d- `npm run format:check`: verify Prettier formatting.- `npm run check`: run typecheck, lint, format:check, and tests.- `npm run verify:hopper`: build and run the real-Hopper verifier (requires a binary).-- `npm run config:print -- /path/to/binary`: print a ready-to-paste MCP server config with absolute paths.+- `npm run config:print -- /path/to/binary`: print an MCP server config with absolute paths.- `HOPPER_TARGET_PATH=/path/to/binary npm start`: launch Hopper and run the built stdio MCP server.## Configuration & Environment Variablesdiff --git a/README.md b/README.mdindex a572926ea..0b5e057e1 100644--- a/README.md+++ b/README.md@@ -1,21 +1,39 @@# betterBinaryMCP-A TypeScript MCP server for [Hopper Disassembler](https://www.hopperapp.com/). It preserves 31 familiar Hopper operations and adds 8 reverse-engineering workflows for Swift, Objective-C, decompilation, call graphs, cross-references, and binary summaries.+A TypeScript MCP server for [Hopper Disassembler](https://www.hopperapp.com/). It preserves 31 Hopper operations and adds 8 reverse-engineering workflows for Swift, Objective-C, decompilation, call graphs, cross-references, and binary summaries.++## Prerequisites++Check these before you start:++- **Node.js 20+** (`node --version`)+- **Hopper Disassembler 6+** on macOS, at `/Applications/Hopper Disassembler.app/`+- **A binary to analyze** (Mach-O executable, `.dylib`, `.hop` database, etc.)++Accessibility permission is not required.## Quick Start```bash-git clone <repo-url> && cd betterBinaryMCP+git clone https://github.com/morluto/betterBinaryMCP.git && cd betterBinaryMCPnpm ci && npm run build```-Generate a ready-to-paste MCP config with absolute paths filled in:+Generate an MCP config with absolute paths filled in:```bashnpm run config:print -- /path/to/your/binary```-Paste the output into your MCP client config (Claude Desktop, Cursor, etc.) and restart the client. That's it — the 39 tools are now available.+Paste the output into your client's MCP config file:++| Client | Config path |+| ----------------- | ------------------------------------------------------------------------- |+| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) |+| Cursor | `.cursor/mcp.json` in your project root |+| Other MCP clients | Check the client's docs for MCP server config |++Restart the client. The 39 tools appear in the tool list.```bash# For a .hop database:@@ -25,24 +43,24 @@ npm run config:print -- /path/to/file.hop --kind databasenpm run config:print -- /path/to/binary --loader-args '["-l","Mach-O","--aarch64"]'```+### What happens on first tool call++The server does not launch Hopper at startup. Hopper launches lazily on the first tool call that needs it, which means the first call can take 10-30 seconds while Hopper opens and analyzes the binary. Subsequent calls are fast. If the first call times out, see [Troubleshooting](#troubleshooting).++### Try it++Once connected, call `binary_overview` with no arguments. It returns segment layout, procedure count, and string count. If you get JSON back, the server is working.+### Set up with your agentPaste this prompt into Claude, Cursor, or any MCP-capable agent to have it do the setup for you:> I want to connect betterBinaryMCP (a Hopper Disassembler MCP server) to this client.>-> 1. Clone the repo and run `npm ci && npm run build`.+> 1. Clone `https://github.com/morluto/betterBinaryMCP.git` and run `npm ci && npm run build`.> 2. Run `npm run config:print -- /path/to/my/binary` to generate the MCP server config.> 3. Paste the output into this client's MCP config and restart.-> 4. Verify the 39 tools are listed.--## Prerequisites--- **Node.js 20+** — `node --version`-- **Hopper Disassembler 6+** on macOS — ships at `/Applications/Hopper Disassembler.app/`-- **A binary or Hopper database** to analyze--Accessibility permission is **not** required. Specify loader arguments for archives that would otherwise show an architecture chooser.+> 4. Call `binary_overview` with no arguments to verify the server is working.## Architecture@@ -157,4 +175,4 @@ If startup times out, verify the target path and reproduce the generated loader## License-MIT — see [LICENSE](LICENSE).+MIT, see [LICENSE](LICENSE).