# 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`.

```mermaid
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/`](docs/).

New to MCP? Follow the Mac-specific [`TUTORIAL.md`](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

```bash
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:

```bash
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](https://learn.chatgpt.com/docs/extend/mcp?surface=cli).

1. Build the project once:

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

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

   ```bash
   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:

   ```toml
   [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`](docs/codex-usage.md) for safe prompting and troubleshooting.

## Repository layout

```text
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.