aiui-mcp 0.2.0__tar.gz

aiui_mcp-0.2.0/.gitignore

@@ -0,0 +1,29 @@
+# build artifacts
+companion/dist/
+companion/src-tauri/target/
+companion/src-tauri/gen/schemas/
+
+# deps
+companion/node_modules/
+
+# packaged release
+aiui-*.zip
+aiui-*.dmg
+aiui-*.tar.gz
+latest.json
+
+# macOS
+.DS_Store
+
+# logs / local state
+*.log
+/tmp/aiui-trace.log
+
+# IDE / editor
+.vscode/
+.idea/
+*.swp
+.aider*
+
+# local release credentials
+.env.release

aiui_mcp-0.2.0/PKG-INFO

@@ -0,0 +1,62 @@
+Metadata-Version: 2.4
+Name: aiui-mcp
+Version: 0.2.0
+Summary: MCP server for aiui — native macOS dialogs 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 <cw@byte5.de>
+License-Expression: MIT
+Keywords: claude,dialog,macos,mcp,tauri,ui
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: User Interfaces
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp>=1.26.0
+Description-Content-Type: text/markdown
+
+# aiui-mcp
+
+MCP server for [**aiui**](https://github.com/byte5ai/aiui) — lets Claude Code
+sessions render native macOS dialogs on the user's Mac. Works for local and
+remote Claude Code setups.
+
+## Install
+
+Drop this into your project's `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "aiui": {
+      "command": "uvx",
+      "args": ["aiui-mcp"]
+    }
+  }
+}
+```
+
+`uvx` pulls the latest version automatically. The companion macOS app is
+distributed separately from <https://github.com/byte5ai/aiui/releases>.
+
+## Tools
+
+- `aiui.confirm` — hard yes/no with optional destructive styling
+- `aiui.ask` — single- or multi-choice with per-option descriptions
+- `aiui.form` — composite window with typed fields and action buttons
+- `aiui.aiui_health` — reachability check
+
+## Prompts
+
+- `/aiui:widgets` — full widget catalog with rules, patterns, anti-patterns
+
+## License
+
+MIT — see [LICENSE](https://github.com/byte5ai/aiui/blob/main/LICENSE).

aiui_mcp-0.2.0/README.md

@@ -0,0 +1,38 @@
+# aiui-mcp
+
+MCP server for [**aiui**](https://github.com/byte5ai/aiui) — lets Claude Code
+sessions render native macOS dialogs on the user's Mac. Works for local and
+remote Claude Code setups.
+
+## Install
+
+Drop this into your project's `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "aiui": {
+      "command": "uvx",
+      "args": ["aiui-mcp"]
+    }
+  }
+}
+```
+
+`uvx` pulls the latest version automatically. The companion macOS app is
+distributed separately from <https://github.com/byte5ai/aiui/releases>.
+
+## Tools
+
+- `aiui.confirm` — hard yes/no with optional destructive styling
+- `aiui.ask` — single- or multi-choice with per-option descriptions
+- `aiui.form` — composite window with typed fields and action buttons
+- `aiui.aiui_health` — reachability check
+
+## Prompts
+
+- `/aiui:widgets` — full widget catalog with rules, patterns, anti-patterns
+
+## License
+
+MIT — see [LICENSE](https://github.com/byte5ai/aiui/blob/main/LICENSE).

aiui_mcp-0.2.0/pyproject.toml

@@ -0,0 +1,51 @@
+[project]
+name = "aiui-mcp"
+version = "0.2.0"
+description = "MCP server for aiui — native macOS dialogs from any Claude Code session, local or remote."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+    { name = "byte5 GmbH", email = "cw@byte5.de" },
+]
+keywords = ["mcp", "claude", "ui", "dialog", "macos", "tauri"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: MacOS :: MacOS X",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: User Interfaces",
+]
+dependencies = [
+    "mcp>=1.26.0",
+    "httpx>=0.27",
+]
+
+[project.urls]
+Homepage = "https://github.com/byte5ai/aiui"
+Repository = "https://github.com/byte5ai/aiui"
+Issues = "https://github.com/byte5ai/aiui/issues"
+
+[project.scripts]
+aiui-mcp = "aiui_mcp.__main__:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/aiui_mcp"]
+
+[tool.hatch.build.targets.wheel.force-include]
+"src/aiui_mcp/skill.md" = "aiui_mcp/skill.md"
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/aiui_mcp",
+    "README.md",
+    "pyproject.toml",
+]

aiui_mcp-0.2.0/src/aiui_mcp/__init__.py

@@ -0,0 +1,4 @@
+"""aiui-mcp — MCP server that renders native macOS dialogs via the aiui companion."""
+from .server import main, mcp
+
+__all__ = ["main", "mcp"]

aiui_mcp-0.2.0/src/aiui_mcp/__main__.py

@@ -0,0 +1,4 @@
+from .server import main
+
+if __name__ == "__main__":
+    main()

aiui_mcp-0.2.0/src/aiui_mcp/server.py

@@ -0,0 +1,341 @@
+"""aiui MCP server — renders native macOS dialogs via the aiui companion.
+
+Topology:
+
+    Claude Code (local or remote) ──stdio──► aiui-mcp (this process)
+                                               │ HTTP
+                                               ▼
+                                     http://127.0.0.1:7777
+                                               │  (local, or via SSH reverse-tunnel)
+                                               ▼
+                                       Mac: aiui.app (Tauri companion)
+
+The aiui token is read from `~/.config/aiui/token` — installed once when
+the companion runs on the Mac, and scp'd automatically to each remote host
+registered in the companion's settings window.
+"""
+from __future__ import annotations
+
+import importlib.metadata
+import importlib.resources as resources
+import logging
+import os
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+import httpx
+from mcp.server.fastmcp import FastMCP
+
+
+def _version() -> str:
+    try:
+        return importlib.metadata.version("aiui-mcp")
+    except importlib.metadata.PackageNotFoundError:
+        return "dev"
+
+
+VERSION = _version()
+BUILD_INFO = f"aiui-mcp v{VERSION}"
+
+logging.basicConfig(
+    level=os.environ.get("AIUI_LOG_LEVEL", "INFO").upper(),
+    format="%(asctime)s.%(msecs)03d %(levelname)s %(name)s %(message)s",
+    datefmt="%Y-%m-%d %H:%M:%S",
+    stream=sys.stderr,
+)
+log = logging.getLogger("aiui")
+log.info("---- %s started pid=%d ----", BUILD_INFO, os.getpid())
+
+
+TOKEN_PATH = Path(os.environ.get("AIUI_TOKEN_PATH", "~/.config/aiui/token")).expanduser()
+ENDPOINT = os.environ.get("AIUI_ENDPOINT", "http://127.0.0.1:7777")
+TIMEOUT_S = float(os.environ.get("AIUI_TIMEOUT_S", "120"))
+HEALTH_TIMEOUT_S = float(os.environ.get("AIUI_HEALTH_TIMEOUT_S", "3"))
+
+mcp = FastMCP("aiui")
+
+
+def _token() -> str:
+    if not TOKEN_PATH.exists():
+        raise RuntimeError(
+            f"aiui token not found at {TOKEN_PATH}. "
+            "Install the aiui companion on your Mac and register this remote from its "
+            "settings window (adds the token automatically). "
+            "Download: https://github.com/byte5ai/aiui/releases/latest"
+        )
+    return TOKEN_PATH.read_text().strip()
+
+
+async def _preflight() -> None:
+    """Quick sanity check before every render call: the service on :7777 must
+    accept our bearer token. Guards against stale local aiui instances that
+    would otherwise hijack the SSH reverse-forward and hang dialogs silently.
+    """
+    async with httpx.AsyncClient(timeout=HEALTH_TIMEOUT_S) as client:
+        try:
+            r = await client.get(
+                f"{ENDPOINT}/health",
+                headers={"Authorization": f"Bearer {_token()}"},
+            )
+        except httpx.ConnectError as e:
+            raise RuntimeError(
+                f"aiui companion not reachable at {ENDPOINT}. "
+                f"Is Claude Desktop running on your Mac? For remote projects, the "
+                f"SSH reverse-tunnel must also be active (companion handles it "
+                f"automatically if this host is registered in its settings). "
+                f"Underlying error: {e}"
+            ) from e
+        except httpx.ReadTimeout as e:
+            raise RuntimeError(
+                f"aiui companion at {ENDPOINT} timed out on /health — likely a stale "
+                f"local aiui instance holding the port. Run `pkill -f '^aiui$'` on "
+                f"this host. ({e})"
+            ) from e
+
+        if r.status_code == 401:
+            raise RuntimeError(
+                f"aiui companion at {ENDPOINT} rejected our token (401). "
+                f"Another aiui process may be listening on this port with a different "
+                f"token. Run `pkill -f '^aiui$'` on this host, then re-register it "
+                f"from the companion's settings window to re-sync the token."
+            )
+        if r.status_code != 200:
+            raise RuntimeError(
+                f"aiui companion /health returned {r.status_code}: {r.text[:200]}"
+            )
+
+
+async def _post_render(spec: dict[str, Any]) -> dict[str, Any]:
+    await _preflight()
+    t0 = datetime.now(timezone.utc)
+    log.info("render → kind=%s", spec.get("kind"))
+    async with httpx.AsyncClient(timeout=TIMEOUT_S) as client:
+        r = await client.post(
+            f"{ENDPOINT}/render",
+            headers={"Authorization": f"Bearer {_token()}"},
+            json={"spec": spec},
+        )
+        r.raise_for_status()
+    dt = (datetime.now(timezone.utc) - t0).total_seconds()
+    data = r.json()
+    log.info(
+        "render ← kind=%s cancelled=%s took=%.2fs",
+        spec.get("kind"), data.get("cancelled"), dt,
+    )
+    return data
+
+
+def _format_result(payload: dict[str, Any]) -> dict[str, Any]:
+    if payload.get("cancelled"):
+        return {"cancelled": True}
+    return {"cancelled": False, **payload.get("result", {})}
+
+
+@mcp.tool()
+async def ask(
+    question: str,
+    options: list[dict[str, str]],
+    header: str | None = None,
+    multi_select: bool = False,
+    allow_other: bool = True,
+) -> dict[str, Any]:
+    """Single- or multi-choice picker with optional free-text fallback.
+
+    WHEN TO USE: 2–6 mutually-exclusive options where per-option context helps.
+    For yes/no, use `confirm`. For mixed inputs, use `form`.
+
+    WRITE OPTIONS:
+    - Label: noun or short imperative, ≤ 5 words, no punctuation, no emoji.
+    - Description: one sentence stating the trade-off or consequence.
+    - Keep options parallel in grammar.
+
+    ANTI-PATTERNS: > 8 options (use `form` with a `list` field); generic labels
+    like "Option 1"; redundant descriptions that just restate the label.
+
+    Returns `{cancelled, answers, other?}`. `answers` is a list of values.
+
+    Args:
+        question: Full question, imperative or interrogative.
+        options: List of `{"label": str, "description"?: str, "value"?: str}`.
+        header: Short chip above the question (≤ 14 chars).
+        multi_select: Allow selecting multiple options.
+        allow_other: Offer a free-text fallback.
+    """
+    spec = {
+        "kind": "ask",
+        "question": question,
+        "header": header,
+        "options": options,
+        "multiSelect": multi_select,
+        "allowOther": allow_other,
+    }
+    return _format_result(await _post_render(spec))
+
+
+@mcp.tool()
+async def form(
+    title: str,
+    fields: list[dict[str, Any]],
+    description: str | None = None,
+    header: str | None = None,
+    actions: list[dict[str, Any]] | None = None,
+    submit_label: str | None = None,
+    cancel_label: str | None = None,
+) -> dict[str, Any]:
+    """Composite window: multiple typed fields + multiple action buttons.
+
+    WHEN TO USE: ≥ 2 related inputs, or one input plus context/confirmation.
+    For yes/no, use `confirm`. For a single choice, use `ask`.
+
+    WRITE LABELS:
+    - Imperative or noun, ≤ 6 words, no punctuation, no emoji.
+    - Consistent register across all fields.
+    - Field-level descriptions only if the label alone is ambiguous.
+
+    BE RESTRAINT:
+    - ≤ 8 fields per dialog. Split logically if you need more.
+    - `static_text` only for context the user couldn't derive from labels.
+    - Defaults that a human would actually pick.
+
+    ACTION BUTTONS:
+    - Verb-based and concrete ("Create report"), not "OK".
+    - Destructive actions: `destructive: true` — never red a save button.
+    - `skip_validation: true` on escape hatches so required-field validation
+      doesn't trap the user.
+    - ≤ 3 actions.
+
+    FIELD KINDS:
+    - text:        {kind, name, label, placeholder?, default?, multiline?, required?}
+    - password:    {kind, name, label, placeholder?, required?}  — masked, treat as secret
+    - number:      {kind, name, label, default?, min?, max?, step?, required?}
+    - select:      {kind, name, label, options: [{label, value}], default?, required?}
+    - checkbox:    {kind, name, label, default?}
+    - slider:      {kind, name, label, min, max, step?, default?}
+    - date:        {kind, name, label, default?, required?}  — ISO YYYY-MM-DD
+    - date_range:  {kind, name, label, default?: {from, to}, required?}  — result {from, to}
+    - color:       {kind, name, label, default?}  — hex "#RRGGBB"
+    - static_text: {kind, text, tone?: "info"|"warn"|"muted"}  — display only
+    - list:        {kind, name, label?, items: [{label, value, description?}],
+                    selectable?, multi_select?, sortable?, default_selected?: [values]}
+      Result: {selected: [values], order: [values]}
+    - tree:        {kind, name, label?, items: [{label, value, description?, children?: [...]}],
+                    multi_select?, default_selected?: [values], default_expanded?: [values]}
+      Result: {selected: [values]}
+
+    Returns `{cancelled, action?, values: {name: value, ...}}`.
+
+    Args:
+        title: Window title. Same rules as labels.
+        fields: List of field blocks, each with a `kind` from above.
+        description: Subtitle, ≤ 2 sentences.
+        header: Chip above the title (≤ 14 chars).
+        actions: Footer buttons `[{label, value, primary?, destructive?, skip_validation?}]`.
+            Without actions, defaults to Cancel + Submit.
+        submit_label: Legacy fallback for the default submit button label.
+        cancel_label: Legacy fallback for the default cancel button label.
+    """
+    spec = {
+        "kind": "form",
+        "title": title,
+        "description": description,
+        "header": header,
+        "fields": fields,
+        "actions": actions,
+        "submitLabel": submit_label,
+        "cancelLabel": cancel_label,
+    }
+    return _format_result(await _post_render(spec))
+
+
+@mcp.tool()
+async def confirm(
+    title: str,
+    message: str | None = None,
+    header: str | None = None,
+    destructive: bool = False,
+    confirm_label: str | None = None,
+    cancel_label: str | None = None,
+) -> dict[str, Any]:
+    """Hard yes/no decision with optional destructive styling.
+
+    WHEN TO USE: irreversible or high-stakes step where "just proceed" is
+    unsafe. For pure information, respond in chat. For 3+ options, use `ask`.
+
+    WRITE:
+    - Title: the decision as a question, ≤ 10 words.
+    - Message: one sentence stating the concrete consequence.
+    - `destructive=True` for deletions/force-pushes/rollbacks — never for
+      saves or creates.
+    - Custom `confirm_label`/`cancel_label` when verbs clarify.
+
+    Returns `{cancelled, confirmed}`. `cancelled=True` means Escape or window
+    close. `cancelled=False, confirmed=False` means the explicit No button.
+
+    Args:
+        title: The decision phrased as a question.
+        message: One-sentence explanation of what happens on confirm.
+        header: Chip above the title.
+        destructive: Red confirm button.
+        confirm_label: Defaults to "Ja".
+        cancel_label: Defaults to "Nein".
+    """
+    spec = {
+        "kind": "confirm",
+        "title": title,
+        "message": message,
+        "header": header,
+        "destructive": destructive,
+        "confirmLabel": confirm_label,
+        "cancelLabel": cancel_label,
+    }
+    return _format_result(await _post_render(spec))
+
+
+@mcp.prompt()
+def widgets() -> str:
+    """The full aiui widget catalog — when to use which dialog, copy
+    conventions, anti-patterns, example payloads. Read before composing the
+    first dialog in a session."""
+    try:
+        return (resources.files("aiui_mcp") / "skill.md").read_text()
+    except Exception:
+        return (
+            "aiui skill doc not bundled with this install. "
+            "See https://github.com/byte5ai/aiui/blob/main/docs/skill.md"
+        )
+
+
+@mcp.tool()
+async def aiui_health() -> dict[str, Any]:
+    """Reachability + token check against the aiui companion.
+
+    Use this first if dialogs hang or fail — it distinguishes a cold companion
+    (user needs to launch Claude Desktop, or the SSH tunnel is down) from a
+    rogue local process holding the port with the wrong token.
+    """
+    try:
+        async with httpx.AsyncClient(timeout=HEALTH_TIMEOUT_S) as client:
+            r = await client.get(
+                f"{ENDPOINT}/health",
+                headers={"Authorization": f"Bearer {_token()}"},
+            )
+            r.raise_for_status()
+            data = r.json()
+            return {"ok": True, **data, "endpoint": ENDPOINT, "server": BUILD_INFO}
+    except Exception as e:
+        log.warning("health check failed: %s", e)
+        return {"ok": False, "error": str(e), "endpoint": ENDPOINT, "server": BUILD_INFO}
+
+
+def main() -> None:
+    """Entry point for the `aiui-mcp` console script. Default transport is
+    stdio (what Claude Code expects). Legacy `--stdio` flag is accepted for
+    compatibility with the old script-based invocation."""
+    # stdio is the only transport we support; flag-parsing kept minimal.
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

aiui_mcp-0.2.0/src/aiui_mcp/skill.md

@@ -0,0 +1,114 @@
+---
+name: aiui widgets
+description: Render native macOS dialogs on the user's Mac from any Claude Code session — remote or local. Use when the user benefits from structured input (multi-field forms, sortable lists, sliders) more than from chat.
+---
+
+# aiui — Dialog design for Claude agents
+
+aiui exposes three MCP tools that render native dialogs on the user's Mac:
+
+- `confirm` — irreversible yes/no
+- `ask` — single- or multi-choice with descriptions and optional free-text fallback
+- `form` — composite window with typed fields and multiple action buttons
+
+## When to reach for a dialog vs. chat
+
+Prefer chat when the answer fits in one line and the user would type it
+anyway. Prefer a dialog when:
+
+- Structured input beats free-form typing (numbers in a range, dates,
+  multi-select, ordered lists, secrets).
+- You need several related inputs collected in one step.
+- The decision is destructive or high-stakes and benefits from a clearly-framed
+  confirmation.
+
+Do **not** use a dialog to display information the chat can render just as
+well (status reports, tables, code snippets, logs).
+
+## Tool choice
+
+| Intent | Tool |
+|---|---|
+| Yes/no, especially destructive | `confirm` |
+| 2–6 options, possibly with per-option context | `ask` |
+| Multi-field input, multi-action footer | `form` |
+| Single free-text answer | just ask in chat |
+| More than 8 fields | split into multiple `form` calls; do not cram one dialog |
+
+## Writing labels and copy
+
+- Imperative or noun, ≤ 6 words per label, no punctuation, no emoji.
+- Parallel grammar within a dialog. Mix of styles ("Name" / "Bitte geben Sie
+  Ihr Alter ein" / "What's your role?") reads as AI slop.
+- Defaults that a real user would pick, not `"enter value here"`.
+- `description`/`static_text` only when the label alone is ambiguous —
+  avoid redundancy.
+
+## Action buttons (form only)
+
+- Verb-based, concrete. `"Bericht erstellen"` beats `"OK"`.
+- Destructive → `destructive: true`. Never style a save button red.
+- Offer an escape hatch (`skip_validation: true`) so required-field validation
+  never traps the user.
+- ≤ 3 actions. If you're tempted to add a fourth, rethink the flow.
+
+## The `list` field — one widget, four modes
+
+| `selectable` | `multi_select` | `sortable` | Mode |
+|---|---|---|---|
+| – | – | – | Static info list |
+| ✓ | – | – | Single-choice (radio) |
+| ✓ | ✓ | – | Multi-choice (checkboxes) |
+| – | – | ✓ | Ordering via drag handles |
+| ✓ | ✓ | ✓ | Pick-and-order |
+
+Result is always `{selected: [values], order: [values]}` — `order` reflects
+drag changes, `selected` reflects checkbox state.
+
+## Password fields
+
+Never collect credentials via `ask` or chat. Use `form` with a `password`
+field so the value stays out of the transcript.
+
+## Anti-patterns (gut vs. schlecht)
+
+| Slop | Clean |
+|---|---|
+| `confirm(title="Sicher?")` | `confirm(title="Tabelle 'orders' löschen?", destructive=True, message="18.432 Zeilen werden entfernt.")` |
+| `ask(question="Wählen", options=[{"label": "Option 1"}, …])` | `ask(question="Welche Strategie für die Migration?", options=[{"label":"In-place","description":"Schnell, kein Rollback."}, …])` |
+| `form` mit 15 `text`-Feldern | Aufteilen in logische Schritte oder ganz in Chat verlagern |
+| Button-Labels "OK" / "Abbrechen" | "Deploy starten" / "Verwerfen" |
+| `static_text` echot den Titel | `static_text` ergänzt Kontext, den die Labels nicht transportieren |
+
+## Quick reference example
+
+```python
+aiui.form(
+    title="Neuer Feature-Entwurf",
+    header="Discovery",
+    fields=[
+        {"kind": "text", "name": "job", "label": "User-Job",
+         "multiline": True, "required": True},
+        {"kind": "select", "name": "scope", "label": "Umfang",
+         "options": [{"label": "Quick Win", "value": "qw"},
+                     {"label": "Feature", "value": "f"},
+                     {"label": "Epic", "value": "e"}],
+         "default": "f"},
+        {"kind": "list", "name": "stakeholders", "label": "Beteiligte",
+         "items": [{"label": "Produkt", "value": "prod"},
+                   {"label": "Design", "value": "design"},
+                   {"label": "Engineering", "value": "eng"}],
+         "selectable": True, "multi_select": True,
+         "default_selected": ["prod", "eng"]},
+        {"kind": "date", "name": "deadline", "label": "Zieldatum"},
+    ],
+    actions=[
+        {"label": "Abbrechen", "value": "cancel", "skip_validation": True},
+        {"label": "Entwurf speichern", "value": "draft", "skip_validation": True},
+        {"label": "Anlegen", "value": "commit", "primary": True},
+    ],
+)
+```
+
+Response: `{cancelled: false, action: "commit", values: {job: "...",
+scope: "f", stakeholders: {selected: [...], order: [...]}, deadline: "..."}}`.