# macOS MCP Setup

ITHZ-MCP can run as a local stdio MCP server on macOS through Python.

This package includes POSIX shell launchers and host installer scripts for Codex, Claude Code, Cursor, Antigravity and generic JSON-RPC clients.

## What Works On macOS

- Python MCP server over stdin/stdout.
- Read-only and explicit write-enabled MCP profiles.
- Deterministic search/context-pack workflow.
- Host config generation and scripted MCP client smoke.
- Legacy local JSON storage profile.

## Native Archive Storage

Native `project.ithz` storage on macOS requires a macOS build of `ithz-native`.

The Windows product package includes Windows `ithz-native.exe` binaries for native archive storage. Those binaries do not run on macOS. Until a macOS `ithz-native` binary is supplied, generated macOS host configs default to:

```text
--storage-profile legacy
```

This is an automatic safe fallback, not a user-choice prompt. A macOS agent installing ITHZ-MCP should continue with the supported subset: MCP host config, `*.ithz` Git diff/merge driver, ITHZ Drive/open-temp fallback if present, and a clear native-binary gap report. It should not ask the user whether to proceed unless it is about a destructive operation or a non-standard path.

If a compatible macOS `ithz-native` is available later, regenerate configs with `--storage-profile native-archive` or set:

```sh
export ITHZ_MCP_STORAGE_PROFILE=native-archive
```

before running the POSIX host installer.

## Optional macOS Intel Native Runtime

For Intel Macs, native archive storage requires an `x86_64` `ithz-native`
package built on macOS. This package is not a guaranteed public download from
`ithz.dev`; use it only when the user supplies it locally or when it is
available as a trusted CI artifact.

```sh
unzip ithz-native-preview-v0.1-alpha-rc2-macos-x86_64.zip
cd ithz-native-preview-v0.1-alpha-rc2-macos-x86_64
chmod +x install_macos_native.sh smoke_test.sh sample_commands.sh bin/ithz-native
./smoke_test.sh
./install_macos_native.sh
export ITHZ_NATIVE_EXE="$HOME/.local/share/ithz-mcp/native/ithz-native"
```

Validate:

```sh
"$ITHZ_NATIVE_EXE" --version
"$ITHZ_NATIVE_EXE" --self-test
```

The repository workflow `.github/workflows/build-macos-native.yml` builds this
Intel package on the GitHub `macos-13` runner and uploads the zip plus SHA-256
manifest as CI artifacts. If that artifact is not available, do not guess a
download URL; install the MCP host config, Git driver and Drive/open-temp
fallback with legacy storage, then report the native-binary gap.

## Cursor With Native Archive Storage

After installing the native runtime and unpacking the MCP macOS package:

```sh
cd /path/to/your/project
ITHZ_NATIVE_EXE="$HOME/.local/share/ithz-mcp/native/ithz-native" \
ITHZ_MCP_STORAGE_PROFILE=native-archive \
/path/to/ithz-mcp-macos/host_installers_macos/install_cursor_mcp.sh --project "$PWD" --apply
```

Restart Cursor after writing `.cursor/mcp.json`. The read-only server should
then expose native archive context/status tools against `project.ithz`. Enable
a write-enabled profile only after read-only native status and safe verify work.

If `project.ithz` already exists from Git, verify and reuse it. Do not replace
it during setup.

## Smoke Test

From the unpacked package directory:

```sh
chmod +x ithz_mcp_server.sh smoke_test.sh mcp_client_smoke.sh sample_commands.sh host_installers_macos/*.sh
./smoke_test.sh
./mcp_client_smoke.sh
```

## Install Host Config

Dry-run first:

```sh
host_installers_macos/install_codex_mcp.sh --project /path/to/project
host_installers_macos/install_claude_code_mcp.sh --project /path/to/project
host_installers_macos/install_cursor_mcp.sh --project /path/to/project
host_installers_macos/install_antigravity_mcp.sh --project /path/to/project
```

Apply after review:

```sh
host_installers_macos/install_codex_mcp.sh --project /path/to/project --apply
host_installers_macos/install_claude_code_mcp.sh --project /path/to/project --apply
```

The Codex installer appends to `~/.codex/config.toml`. Claude Code uses project `.mcp.json`. Cursor and Antigravity use project-local config paths when supported by the host.

## Boundaries

- ITHZ-MCP does not replace Git.
- ITHZ-MCP is not a production database.
- ITHZ-MCP is not cloud sync.
- ITHZ-MCP does not make a general token-saving claim.
- ITHZ Drive / Windows Explorer shell integration is Windows-only; this document covers the MCP server package.
- macOS Drive fallback can open/extract archives only when `ITHZ_NATIVE_EXE`
  points to a compatible macOS `ithz-native`.
