Metadata-Version: 2.5
Name: aiui-mcp
Version: 0.12.0
Summary: MCP server for aiui — native desktop dialogs on macOS and Windows from any Claude Code session, local or remote.
Project-URL: Homepage, https://github.com/byte5ai/aiui
Project-URL: Repository, https://github.com/byte5ai/aiui
Project-URL: Issues, https://github.com/byte5ai/aiui/issues
Author-email: byte5 GmbH <cwendler@byte5.de>
License-Expression: MIT
Keywords: claude,dialog,macos,mcp,remote,ssh,tauri,ui,windows
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: User Interfaces
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: mcp<2,>=1.27.0
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# aiui-mcp

MCP server for [**aiui**](https://github.com/byte5ai/aiui) — lets Claude
Code sessions render native desktop dialogs on the user's own machine
(macOS, and Windows since aiui 0.10.1). Works for local and remote
Claude Desktop App setups.

## Install

You don't normally need to touch this package directly.

**On your own machine**, install [aiui](https://github.com/byte5ai/aiui/releases/latest)
— since v0.3.0 the MCP server is bundled as native Rust code inside the
app. `~/.claude.json` points directly at the app binary. No `uv`, no
`uvx`, no Python on the onboarding path.

**On a remote SSH host** (no aiui companion there), this package is the
right tool. aiui registers it automatically when you add the remote in
settings — `{command: "uvx", args: ["aiui-mcp==<version>"]}`, pinned to the
version of your companion so the two always speak the same contract (`uvx`
may be an absolute path when aiui found one on the remote). All dialogs
tunnel back through aiui on your own machine.

See the main repo for the full install flow and companion download:
<https://github.com/byte5ai/aiui>

## Tools

- `confirm` — hard yes/no with optional destructive styling
- `ask` — single- or multi-choice with per-option descriptions
- `form` — composite window with typed fields and action buttons
- `gallery` — image/video grid the user picks from
- `compare` — side-by-side diff of two texts or images
- `upload` — native file picker on the user's machine; the chosen file
  lands on the agent host
- `notify` — fire-and-forget OS notification, no dialog, no reply
- `aiui_health` — reachability check
- `version` — companion version, build info, binary path, updater endpoint
- `update` — silent update check + install on the user's machine

## Environment variables

None of these need setting — the defaults are what aiui registers for you.
A bad value is **warned about and ignored**, never fatal: a typo in one of
these must not turn into "the aiui MCP server failed to start".

| Variable | Default | Meaning |
| --- | --- | --- |
| `AIUI_ENDPOINT` | `http://127.0.0.1:7777` | Companion base URL — the local end of the SSH reverse-tunnel. |
| `AIUI_TOKEN_PATH` | `~/.config/aiui/token` (`%APPDATA%\aiui\token` on Windows) | Pairing token file, written by the companion and copied to each registered remote. |
| `AIUI_TIMEOUT_S` | `120` | Client timeout for the companion requests that are not polls: opening a dialog (`POST /render`), pushing local video/audio to the media cache (`/media`), `/notify` and `/update`. |
| `AIUI_HEALTH_TIMEOUT_S` | `3` | Seconds for `aiui_health` and `/version` — deliberately short; it is the diagnostic. |
| `AIUI_COLDSTART_WAIT_S` | `30` | Seconds to poll `/ping` before the first call, so a companion that is still starting gets time to serve. |
| `AIUI_UPLOAD_TIMEOUT_S` | `900` | Seconds for the held `POST /upload` — generous, because the user browses a file picker inside it. |
| `AIUI_LOG_LEVEL` | `INFO` | Any standard `logging` level name. |
| `AIUI_ALLOW_UNVERIFIED_COMPANION` | unset | Set to `1` to send the token to a companion too old to answer the challenge probe. Before its token leaves this host, the bridge makes the listener on the companion port prove it holds the same token (`GET /probe?nonce=…`, HMAC answer); a listener that cannot is refused, because on a shared host anything may hold that port while the SSH tunnel is down. Only an older companion answering 401 can be let through, and only with this opt-in — better: update aiui. |
| `AIUI_LIVE` | unset | Test-only: set to `1` to run the integration tests against a real companion. |

## Prompts

- `/aiui:teach` — briefs the agent on aiui (full widget catalog, design rules, anti-patterns)
- `/aiui:update` — agent calls the `update` tool and reports the outcome
- `/aiui:version` — reports the installed aiui version in one line
- `/aiui:health` — one-line health check of the companion
- `/aiui:test-dialog` — pops a demo dialog to verify the wiring end to end
- `/aiui:remotes` — lists the registered aiui remotes in chat
- `/aiui:upload` — hands a file from the user's machine to the agent session

## License

MIT — see [LICENSE](https://github.com/byte5ai/aiui/blob/main/LICENSE).
