bitslicer-mcp

A safety-bounded, macOS ARM64 bridge that lets Codex use Bit Slicer's real memory-inspection engine through the Model Context Protocol (MCP). It does not automate the GUI: a TypeScript stdio server talks over a user-only Unix socket to a separately built Bit Slicer MCP application.

Authorization requirement: Use this project only with software and processes you own or are explicitly authorized to assess. The bridge is read-only by default. Memory writes require explicit opt-in at both server layers, approval of the target, and a short-lived edit session. This project does not provide injection, target code execution, stealth, anti-cheat bypass, arbitrary shell access, unrestricted process control, or automatic page-protection changes.

Status

The read-only native integration is implemented against pinned upstream Bit Slicer commit 035ca123781152a97245d2f8b9d1a8149202386d. Process listing, explicit attachment, VM regions, bounded reads/dumps, typed exact scans, exact and relative refinement, pointer-chain resolution, loaded Mach-O images, and bounded ARM64 disassembly call verified Bit Slicer source APIs. All real-target writes remain disabled.

The build is named Bit Slicer MCP, uses bundle ID com.krisgnyc.BitSlicerMCP, and is emitted under this repository. It neither changes nor replaces /Applications/Bit Slicer.app.

flowchart LR
    C["Codex / ChatGPT desktop"] -->|"MCP over stdio"| M["TypeScript MCP server"]
    M -->|"newline JSON + launch token"| U["0600 Unix socket"]
    U --> N["Native companion in Bit Slicer fork"]
    N --> B["Pinned, inspected Bit Slicer internal abstractions"]
    N --> P["Native target approval"]
    M -. local tests .-> K["In-memory mock bridge"]

What is included

• 16 MCP tools covering connection health, processes, explicit attachment, regions, bounded reads, value scans and filtering, pointer chains, loaded Mach-O images, bounded dumps, ARM64 disassembly, and controlled edit sessions.
• A newline-delimited JSON protocol with a per-launch token and checked request/response IDs.
• A Swift socket-listener skeleton for protocol development plus a real Objective-C overlay linked into a pinned Bit Slicer source checkout.
• A complete mock target and integration tests for attach/read/scan/patch/apply/undo behavior.
• Protocol notes, threat model, tool reference, integration plan, and roadmap in docs/.

New to MCP? Follow the Mac-specific TUTORIAL.md, an absolute beginner's guide with copy-and-paste Codex prompts for attaching, scanning, refining, reading, and disassembling.

Requirements

• Apple Silicon Mac, macOS 13 or later
• Node.js 20 or later and npm
• Xcode 16 or newer for the integrated application build

Build and test

cd /absolute/path/to/bitslicer-mcp
npm install
npm run check
./scripts/build-bit-slicer-mcp.sh

npm run check runs the TypeScript/mock and Swift-package tests. The build script obtains the pinned upstream checkout under ignored upstream/, applies the reviewed overlay, builds arm64, ad-hoc signs a distinct product, and emits build/Bit Slicer MCP/Bit Slicer MCP.app.

Try it locally with the mock bridge

Generate a fresh token for this launch and keep the same shell environment for both processes:

cd /absolute/path/to/bitslicer-mcp
export BITSLICER_SESSION_TOKEN="$(openssl rand -hex 32)"
export BITSLICER_SOCKET_PATH="/tmp/bitslicer-mcp-$UID.sock"
export BITSLICER_ENABLE_WRITES=false
npm run build
npm run mock

The mock process is PID 4242; attachment still requires a meaningful authorizationReason. Set BITSLICER_ENABLE_WRITES=true in both bridge and MCP-server environments only for an authorized patching exercise.

Connect Codex exactly

Codex supports local stdio MCP servers and stores shared configuration in ~/.codex/config.toml or a trusted project's .codex/config.toml. See the official MCP configuration documentation.

1. Build the project once:

   cd /absolute/path/to/bitslicer-mcp
   npm install && npm run build
   

2. Start the integrated app with the automated launcher. On this Mac:

   cd /Volumes/Ex-SSD/REV-ENG/bitslicer-mcp
   npm run launch
   

   Alternatively, double-click Launch Bit Slicer MCP.command in Finder. The app generates a fresh token, writes a mode-0600 session descriptor under the current user's Application Support directory, and removes it when the app exits. The MCP server rereads it for every request, so relaunching the bridge does not require restarting Codex. The MCP ● menu-bar item shows listener/target status.

3. Add this exact table to ~/.codex/config.toml, replacing both absolute paths:

   [mcp_servers.bitslicer]
   command = "/absolute/path/to/node"
   args = ["/absolute/path/to/bitslicer-mcp/dist/src/server.js"]
   default_tools_approval_mode = "writes"
   startup_timeout_sec = 10
   tool_timeout_sec = 75
   enabled = true
   

   Find the Node path with command -v node. No secret is stored in Codex configuration.

4. Restart the Codex app/CLI host once after installing or changing this entry. Future Bit Slicer MCP launches do not require a Codex restart. Run codex mcp list or type /mcp in the Codex TUI to confirm the server, then call ping before listing processes.

5. Call attach with a PID and an explicit authorization reason. Bit Slicer MCP shows a local approval prompt before acquiring the task. Real-target writes are not available in this build even if the environment flag is changed.

See docs/codex-usage.md for safe prompting and troubleshooting.

Repository layout

src/       TypeScript MCP server, client, validation, and mock bridge
test/      Node unit and Unix-socket integration tests
native/    Swift package and Bit Slicer integration seam
integration/ Reviewed Objective-C overlay using verified upstream APIs
scripts/    Reproducible pinned-source preparation and app build
protocol/  Machine-readable JSON Schema
docs/      Architecture, protocol, threat model, tool reference, and roadmap

Design boundaries

• Socket access is local and file mode 0600; every request also carries a high-entropy token generated automatically by the native app for that launch. Its session descriptor is stored in a mode-0700 directory with mode-0600 permissions.
• A target must be explicitly attached and approved before target operations.
• Reads, dumps, pointer depth, scan results, disassembly, and patch sizes are bounded.
• Dumps are returned as data; neither MCP nor bridge exposes arbitrary filesystem paths.
• The integrated app exposes no write primitive and never changes page protections.
• Patch preview compares expected bytes; apply compares them again and consumes a one-time confirmation. Undo also compares the post-patch bytes before restoring.

License

MIT. This repository is independent and does not include Bit Slicer source code.