# Ubuntu MCP Setup

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

The Ubuntu package contains:

- `ithz_mcp_server.sh`;
- `install.sh` and `uninstall.sh` for user-local install;
- `install_ithz.md` as the one-file agent installation playbook;
- `host_installers_linux/` for Codex, Claude Code, Cursor, Antigravity and generic JSON-RPC configs;
- `native_build_kit/` with the native `ithz-native` source build kit for Ubuntu;
- `build_linux_native_package.sh` and `install_linux_native.sh`;
- fallback archive commands: `ithz-verify`, `ithz-list`, `ithz-extract-here` and `ithz-open-temp`;
- `smoke_test_ubuntu.sh`;
- sample project and documentation.

## Install from tarball

```sh
tar -xzf ithz-mcp-ubuntu.tar.gz
cd ithz-mcp-ubuntu
./install.sh
ithz-mcp version
```

By default this installs to:

```text
~/.local/share/ithz-mcp
~/.local/bin/ithz-mcp
~/.local/bin/ithz-mcp-server
```

Use custom paths with:

```sh
PREFIX=/opt/ithz-mcp BIN_DIR=/usr/local/bin ./install.sh
```

## Install from `.deb`

```sh
sudo apt install ./ithz-mcp-ubuntu.deb
ithz-mcp version
```

The `.deb` installs the runtime under `/opt/ithz-mcp` and wrappers under `/usr/bin`.

## Native archive fallback

The Ubuntu package does not bundle a prebuilt Linux `ithz-native` binary from the Windows build machine. It includes a source build kit instead.

On Ubuntu:

```sh
sudo apt update
sudo apt install build-essential cmake
./install_linux_native.sh
ithz-native-resolve
```

The Linux native build kit dynamically loads `libz.so.1` / `libz.so`, so native
`project.ithz` archive operations should work after the normal Ubuntu zlib
runtime is present. If native archive storage still fails, report the native
error and fall back to legacy storage rather than looping or increasing
timeouts.

After that, these fallback archive commands are available:

```sh
ithz-verify archive.ithz
ithz-list archive.ithz
ithz-extract-here archive.ithz
ithz-open-temp archive.ithz
```

`ithz-open-temp` extracts the archive to a temporary folder and opens it with `xdg-open` when available. This is not a Linux Drive/FUSE provider.

The resolver searches in this order:

1. `ITHZ_NATIVE_EXE`;
2. package-local `native/ithz-native`;
3. `~/.local/share/ithz-mcp/native/ithz-native`;
4. `/opt/ithz-mcp/native/ithz-native`;
5. `ithz-native` on `PATH`.

## Configure an MCP host

From the unpacked package:

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

The generated configs start in read-only mode and include a separate explicit write-enabled profile where supported.

## Smoke test

```sh
./smoke_test_ubuntu.sh
```

## Native archive note

The Ubuntu MCP package is a Python stdio MCP package plus an optional Linux native build kit. Generated Ubuntu host configs default to `legacy` storage unless a compatible Linux `ithz-native` binary is supplied. After `./install_linux_native.sh`, set `ITHZ_NATIVE_EXE` or regenerate host configs with native archive storage.

Full Linux Drive/FUSE support is not included yet. The package provides extraction-backed `open-temp` and `extract-here` fallback commands.

This is not a Git replacement, production database, cloud sync product or
general token-saving claim.
