@khanglvm/relay 0.10.3 → 0.12.0

package/README.md

@@ -38,6 +38,34 @@ Keep relay current with **`rly upgrade`** — it installs the latest CLI and
 refreshes the skill (via `npx skills`, falling back to the bundled copy) in one
 step, leaving any boards you have open untouched.
 
+## Inside the Claude & Codex apps (MCP App)
+
+relay also runs as an **MCP App** ([SEP-1865](https://modelcontextprotocol.io/seps/1865-mcp-apps-interactive-user-interfaces-for-mcp))
+— so the same board renders **inline, right in the conversation**, on Claude
+desktop **and mobile** and in Codex, no browser tab. `rly mcp` is a
+zero-dependency stdio MCP server; register it once and the agent gets two tools,
+`relay_ask` (collect decisions/feedback with real form controls) and
+`relay_show` (present a plan, diagram, diff, table, or prototype):
+
+```sh
+# Claude Code
+claude mcp add relay -- rly mcp
+
+# Claude Desktop / Codex — write the host config for you
+rly mcp install --target claude     # claude_desktop_config.json
+rly mcp install --target codex      # ~/.codex/config.toml
+
+# or print the snippet for any MCP host (incl. the raw JSON/TOML)
+rly mcp config
+```
+
+When the agent calls a relay tool, the host renders relay's `ui://relay/board`
+resource in a sandboxed iframe, hands it the board spec, and the user's answers
+flow back to the agent over the bridge (`ui/update-model-context`) — markdown,
+code, diffs, tables, charts, mermaid/graphviz diagrams, images, and forms, all
+in-chat. The classic browser board (`rly ask` / `rly show`) is unchanged; pick
+whichever surface fits.
+
 ## What it improves
 
 | Without relay | With relay |
@@ -61,6 +89,7 @@ Node ≥ 18; Chart.js / Mermaid / Graphviz are vendored and lazy-loaded offline.
 | `rly help` | every command at a glance |
 | `rly install --target <agent>` | write relay's rules into an agent's instruction file — `claude` `codex` `cursor` `copilot` `kiro` `windsurf` `cline` `gemini` `opencode` `droid` `agents`; `--all`, `--scope`, `--print`, `--list` |
 | `rly upgrade` | update the CLI **and** refresh the skill in one step (safe around open boards; `--dry-run`, `--cli-only`, `--skill-only`) |
+| `rly mcp` | run relay as an MCP App server so boards render **inline** in the chat — **stdio** for local desktop hosts (Claude Desktop, Codex), or `rly mcp --http` (Streamable HTTP) for web/mobile/remote; `rly mcp config` / `rly mcp install --target claude\|codex` to register it |
 | `rly agent` | the full agent guide — spec format, all block types, annotations, patterns ([docs/AGENT.md](docs/AGENT.md)) |
 | `rly schema` | board spec JSON Schema |
 | [skills/relay/SKILL.md](skills/relay/SKILL.md) | the bundled skill |
@@ -73,6 +102,49 @@ npm test     # zero-dep smoke tests (spawns real servers, fake-submits)
 
 ## Changelog
 
+### 0.11.0 — render inline inside the Claude & Codex apps (MCP App)
+- **`rly mcp` — relay as an MCP App** ([SEP-1865](https://modelcontextprotocol.io/seps/1865-mcp-apps-interactive-user-interfaces-for-mcp),
+  extension `io.modelcontextprotocol/ui`). A zero-dependency stdio MCP server
+  that declares a `ui://relay/board` resource (`text/html;profile=mcp-app`) and
+  two tools, **`relay_ask`** and **`relay_show`**, linked to it via
+  `_meta.ui.resourceUri` (plus `openai/outputTemplate` for ChatGPT/Codex). The
+  host renders the board **inline in the conversation** — Claude desktop **and
+  mobile**, Codex — instead of opening a browser tab.
+- **Same board, postMessage transport.** The inline board reuses relay's block
+  renderer (markdown, code, diff, table, chart, mermaid, graphviz, image, html)
+  over the MCP Apps JSON-RPC bridge: the spec arrives as the tool result, the
+  user's answers go back via `ui/update-model-context`, the iframe auto-sizes
+  via `ui/notifications/size-changed`, and vendored Chart.js / Mermaid / Viz.js
+  load on demand through the host's `resources/read` (no `/vendor` route, no
+  server in the sandbox).
+- **One-command setup** — `rly mcp install --target claude|codex` writes the
+  host config; `rly mcp config` prints the snippet for any MCP host. The classic
+  browser board is untouched.
+- **Streamable HTTP transport for web/mobile/remote** — `rly mcp --http
+  [--port N --host H --token SECRET --allow-origin ORIGIN]` serves the same tools
+  over MCP's Streamable HTTP transport (single `/mcp` endpoint, JSON responses,
+  CORS, Origin validation, bearer auth, `Mcp-Session-Id`, `$PORT`-aware). relay is
+  **stateless**, so one instance serves everyone — deploy it once with the repo
+  **`Dockerfile`** on any free MCP host (mcpdeploy.dev, mcphosting.io,
+  Render/Railway/Fly, Glama) or publish to **Smithery**, then add the URL as a
+  custom connector. Only the relay CLI is required — no tunnel/tailscale. stdio
+  stays the zero-setup path for local desktop.
+- **Native look** — the inline board **color-blends** onto the host's SEP-1865
+  style variables (surfaces, text, borders, primary button, fonts), pins
+  `color-scheme` so `light-dark()` tokens resolve, and uses the host's **own
+  full-screen** control (centering content to a readable column in fullscreen).
+  After submit it collapses to a one-line confirmation so the iframe shrinks.
+- **Progressive rendering** — when the host streams the tool call
+  (`ui/notifications/tool-input-partial`), the board renders valid blocks as they
+  arrive (a "Composing…" preview) instead of waiting for the whole spec.
+- **`palette` block** — color palettes as swatch cards (hover reveals hex, click
+  copies); mark one `featured` for a spotlight. **`color` question type** — native
+  picker + hex field + optional `presets`, returns a hex string. Both work on the
+  browser board and inline.
+- **Element annotations inline** — comment on chart points, diagram nodes, table
+  cells, images and text selections in the MCP board too, returned in
+  `annotations` exactly like the CLI board.
+
 ### 0.10.0 — open files, richer code, diffs & video
 - **Clickable local file-links.** Write a path in any markdown (`~/clip.mp4`,
   `./src/app.ts`, `/abs/report.pdf`, a `file://` URL, a backtick-wrapped path,

package/docs/AGENT.md

@@ -62,6 +62,63 @@ Answers **autosave in real time** as the user fills the board — a page reload
 restores them, and a draft survives timeouts/cancellation (included in those
 results), so partial input is never lost.
 
+## Inline mode — relay as an MCP App (Claude & Codex apps)
+
+Everything above is the **CLI** surface (you run `rly` in a terminal and read
+JSON from stdout). relay is **also** an MCP App (SEP-1865): when a host registers
+`rly mcp` (see `rly mcp config` / `rly mcp install --target claude|codex`), you
+get two tools that render the board **inline in the conversation** instead of a
+browser tab. `rly mcp` speaks the MCP **stdio** transport, so it pairs with a
+**local desktop** host — Claude Desktop and Codex today.
+
+- **`relay_ask`** — collect decisions/feedback with real form controls.
+- **`relay_show`** — present a plan, diagram, diff, table, or prototype.
+
+**Web / mobile / remote hosts** can't reach a stdio subprocess, so for those run
+the **Streamable HTTP** transport: `rly mcp --http [--port N]` serves the same
+tools at `/mcp`. relay needs **only its own CLI** for this — no tunnel tool, no
+extra infra. Because relay is **stateless** (answers go iframe→host→model, never
+back to the server), **one deployed instance serves everyone**, so deploy it once
+on any address the app can reach and register that URL as a custom connector:
+
+- **Free MCP hosts** — the repo's `Dockerfile` runs relay with zero config on
+  **mcpdeploy.dev**, **mcphosting.io**, **Render / Railway / Fly**, or **Glama**;
+  the platform's `$PORT` is honored automatically. Set `RLY_MCP_TOKEN` for a
+  bearer-protected endpoint.
+- **Smithery** (largest MCP marketplace) — publish the deployed URL with
+  `smithery mcp publish <url> -n @you/relay` for discovery + an OAuth gateway, or
+  distribute relay as a stdio bundle clients run locally.
+- **Tunnel (optional, dev only)** — `cloudflared`/`tailscale` is *only* for
+  exposing a NAT'd laptop; it's never required and not a relay dependency.
+
+A hosted instance can't see your local files (so `codeFile`/local-image blocks
+won't resolve there — pass URLs or inline content); run it on your own machine if
+you need local-file access.
+
+Progressive rendering: if the host streams the tool call as you write it, the
+board renders valid blocks/questions incrementally (a "Composing…" preview) and
+finalizes when your call completes — so the user sees it build, not a blank wait.
+
+Both take **the exact same board spec** documented below (the tool `inputSchema`
+*is* this spec). Call the tool with your spec; the host shows the board, the user
+fills it in, and their answers come back to you (answers, per-question notes,
+comment) — read them just as you would the CLI's result JSON. There is **no
+`--detach`/`rly wait` dance, no stdout parsing, and no timeout** in this mode; the
+board stays live until the user submits and the host delivers the result.
+
+**Near-full parity with the browser board.** Local `codeFile` / `htmlFile` /
+`diffFile` and local **image** files work inline too — the server inlines them
+(images as data URIs) while normalizing your spec, so the sandboxed board needs
+no file access. **Element-level annotations work inline** — the user can comment
+on chart points, diagram nodes, table cells, images and text selections, returned
+in `annotations` just like the CLI. The board also adopts the host's **theme,
+fonts and colors** and uses the host's **full-screen** control. The only
+inline-mode gaps vs. the browser board: **local video files** (use a
+YouTube/Vimeo/`https` URL instead — those play) and commenting on elements
+*inside* a custom-HTML mockup (every other annotation target works). Everything
+else — questions plus markdown/code/diff/table/chart/mermaid/graphviz/plantuml/
+image/palette/html — renders identically.
+
 ## Creating boards
 
 From a JSON spec file (`--file spec.json`), stdin (`--file -`), or quick
@@ -131,9 +188,11 @@ rly show --html-file prototype.html --title "Dashboard concept" --height 600
 | `text`     | `"string"`                          |
 | `textarea` | `"string"`                          |
 | `scale`    | number (`min`…`max`, default 1–5)   |
+| `color`    | hex string (e.g. `"#c2674b"`) — native picker + hex field; optional `presets:["#…"]` swatches |
 
 Aliases accepted: radio/choice/select→single, checkbox→multi,
-boolean/bool/yn→yesno, input→text, longtext→textarea, rating/likert→scale.
+boolean/bool/yn→yesno, input→text, longtext→textarea, rating/likert→scale,
+colour/swatch→color.
 
 ### Result JSON (stdout)
 
@@ -313,6 +372,17 @@ Rules of thumb:
 // for a huge / high-resolution image pass an http(s) URL (streamed, no size cap).
 { "type": "image", "src": "screenshots/variant-a.png", "alt": "Variant A", "height": 220 }
 { "type": "image", "src": "https://example.com/mock.png" }
+
+// palette — color palettes as swatch cards (hover reveals hex, click copies).
+// Mark one {"featured": true} to render it larger as a spotlight; the rest tile
+// into a responsive grid. Pairs with a "color" question to let the user pick.
+{ "type": "palette", "title": "Trending palettes", "palettes": [
+  { "name": "Mocha Mousse", "sub": "Pantone 2025 · warm", "tag": "Pantone", "tagTone": "warm",
+    "featured": true, "colors": ["#C4956A","#A67B52","#8B6240","#D4AB89","#EDD9C4"] },
+  { "name": "Digital Lavender", "mood": "soft tech", "tag": "Cool", "tagTone": "cool",
+    "colors": ["#C9BAF5","#A08EE8","#7B66CC","#5849A8"] } ] }
+{ "type": "palette", "name": "Brand", "colors": ["#c2674b", "#1c1b19", "#fcfbf9"] }  // single-palette shorthand
+// tagTone (optional pill color): warm | cool | neutral | nature | bold | digital
 ```
 
 ### Local file links — clickable, open in the default app
@@ -339,6 +409,7 @@ real path over telling the user to paste it into a terminal.
 | `diff` | proposed code changes / before-after — a unified diff rendered as a colored git-style comparison (no git needed) |
 | `video` | demos, screen recordings, walkthroughs — YouTube/Vimeo embeds, a media URL, or a local video file (streamed) |
 | `image` | screenshots, mockup exports, photos — local files embed and work offline |
+| `palette` | color palettes / themes — swatch cards with hover-hex + click-to-copy; pair with a `color` question to let the user pick |
 | `html` | anything else — pixel-perfect mockups, custom widgets, embeds |
 
 ### Height rules

package/package.json

@@ -1,11 +1,15 @@
 {
   "name": "@khanglvm/relay",
-  "version": "0.10.3",
-  "description": "Browser-based question boards with rich blocks (markdown, charts, mermaid, tables, code, diffs, video, sandboxed HTML), clickable local file-links, and element-level annotations for AI coding agents (Claude Code, Codex, …): ask users structured questions, present interactive visuals, collect inline comments, wait for submit, read answers as JSON.",
+  "version": "0.12.0",
+  "description": "Question boards with rich blocks (markdown, charts, mermaid, tables, code, diffs, video, sandboxed HTML), clickable local file-links, and element-level annotations for AI coding agents (Claude Code, Codex, …): ask users structured questions, present interactive visuals, collect inline comments, read answers as JSON — in a local browser board OR rendered INLINE inside the Claude & Codex apps as an MCP App (SEP-1865).",
   "keywords": [
     "ai-agents",
     "claude-code",
     "codex",
+    "mcp",
+    "mcp-app",
+    "mcp-ui",
+    "model-context-protocol",
     "cli",
     "interactive-questions",
     "human-in-the-loop",

package/skills/relay/SKILL.md

@@ -13,6 +13,13 @@ time; the tab auto-closes after submit.
 If `rly` is not installed: `npm i -g @khanglvm/relay` or invoke via
 `npx -y @khanglvm/relay <command …>`.
 
+**Inside the Claude or Codex app?** relay is also an MCP App: if the
+`relay_ask` / `relay_show` tools are available, call them with the same board
+spec (below) and the board renders **inline in the chat** — no terminal, no
+browser tab; the user's answers come straight back to you. Set it up once with
+`rly mcp install --target claude|codex` (or `rly mcp config`). Everything below
+describes the spec both surfaces share.
+
 **Full reference: run `rly agent` (complete guide) and `rly schema` (spec JSON
 Schema).** The essentials are below.
 
@@ -97,8 +104,9 @@ answers and any annotations written so far.
 }
 ```
 
-Types: `single`, `multi`, `yesno`, `text`, `textarea`, `scale`. Users may
-submit with unanswered questions (returned in `skipped`) unless
+Types: `single`, `multi`, `yesno`, `text`, `textarea`, `scale`, `color`
+(native picker + hex; optional `"presets":["#…"]`, returns a hex string). Users
+may submit with unanswered questions (returned in `skipped`) unless
 `"allowPartial": false` or per-question `"required": true`.
 
 Set `"note": true` on a question to add a small optional free-text field under
@@ -148,6 +156,8 @@ single/multi question.
 //   screen + zoom (⌘/Ctrl+wheel or −/+, up to 8× native) + drag-to-pan viewer,
 //   so detail is always reachable regardless of height. Local images embed up
 //   to 8 MB; for a huge/high-detail image pass an http(s) URL (streamed, no cap).
+{ "type": "palette",  "palettes": [{ "name":"Brand", "colors":["#3B8EA5","#6DBAD1","#1E6278"], "featured": true }] }
+// ^ color palettes as swatch cards: hover=hex, click=copy. Shorthand {"type":"palette","colors":[…]}; pair with a `color` question.
 ```
 
 ### Visual options — show each choice, don't describe it

package/skills/relay/examples/palette-and-color.json

@@ -0,0 +1,42 @@
+{
+  "title": "Brand color direction",
+  "intro": "Pick a direction from the curated palettes, then choose the exact accent.",
+  "blocks": [
+    {
+      "type": "palette",
+      "title": "Candidate palettes — hover a swatch for its hex, click to copy",
+      "palettes": [
+        { "name": "Coastal Calm", "sub": "ocean, serene", "tag": "Cool", "tagTone": "cool", "featured": true,
+          "colors": ["#3B8EA5", "#6DBAD1", "#1E6278", "#A8DDE9", "#D6EEF5"] },
+        { "name": "Peach Fuzz", "mood": "warm, optimistic", "tag": "Warm", "tagTone": "warm",
+          "colors": ["#F2A07B", "#E8795A", "#C4543C", "#FBCFB8"] },
+        { "name": "Muted Sage", "mood": "earthy, wellness", "tag": "Nature", "tagTone": "nature",
+          "colors": ["#8DB87E", "#5D9252", "#3A6B34", "#BDD9B3"] }
+      ]
+    },
+    { "type": "palette", "name": "Current brand", "colors": ["#c2674b", "#1c1b19", "#fcfbf9"] }
+  ],
+  "questions": [
+    {
+      "id": "direction",
+      "type": "single",
+      "label": "Which palette direction?",
+      "required": true,
+      "options": [
+        { "value": "coastal", "label": "Coastal Calm" },
+        { "value": "peach", "label": "Peach Fuzz" },
+        { "value": "sage", "label": "Muted Sage" },
+        { "value": "keep", "label": "Keep current brand" }
+      ]
+    },
+    {
+      "id": "accent",
+      "type": "color",
+      "label": "Exact accent color",
+      "description": "Use the picker or paste a hex; presets are the featured palette.",
+      "presets": ["#3B8EA5", "#E8795A", "#5D9252", "#c2674b"],
+      "default": "#3B8EA5"
+    }
+  ],
+  "submitLabel": "Lock the palette"
+}

package/src/cli.js

@@ -18,6 +18,7 @@ import {
   HOME,
 } from './store.js';
 import { runBoard } from './server.js';
+import { runMcp, runMcpHttp, mcpConfig } from './mcp.js';
 import { openUrl } from './open.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -31,6 +32,7 @@ const VALUED_FLAGS = new Set([
   'file', 'html', 'html-file', 'title', 'intro', 'timeout', 'port',
   'submit-label', 'height', 'limit', 'target', 'id', 'replies',
   'on-result', 'notify-cmd', 'idle-grace', 'scope',
+  'host', 'token', 'allow-origin',
 ]);
 
 function camel(key) {
@@ -1181,6 +1183,91 @@ async function cmdUpgrade(args) {
   return 0;
 }
 
+// `rly mcp` — run relay as an MCP App server, or print/write the host config.
+//   rly mcp                      serve over stdio (what a local desktop host launches)
+//   rly mcp --http [--port N]    serve over Streamable HTTP (web/mobile/remote hosts)
+//   rly mcp config [--print]     show setup for Claude / Codex / generic hosts
+//   rly mcp install --target claude|codex   write it into that host's config
+async function cmdMcp(rest) {
+  const sub = rest[0];
+  if (sub === 'config' || sub === 'setup' || sub === 'install' || sub === 'add') {
+    return cmdMcpConfig(parseArgs(rest.slice(1)), sub);
+  }
+  const args = parseArgs(rest);
+  if (args.http) {
+    // Port precedence: --port flag, then PaaS-injected $PORT / $RLY_MCP_PORT,
+    // then the default. PaaS hosts (Render, Railway, Fly, mcpdeploy, …) set $PORT.
+    const envPort = process.env.PORT || process.env.RLY_MCP_PORT;
+    return runMcpHttp({
+      port: args.port ? Number(args.port) : (envPort ? Number(envPort) : undefined),
+      host: typeof args.host === 'string' ? args.host : (process.env.RLY_MCP_HOST || '127.0.0.1'),
+      token: typeof args.token === 'string' ? args.token : (process.env.RLY_MCP_TOKEN || ''),
+      allowOrigin: typeof args.allowOrigin === 'string' ? args.allowOrigin : (process.env.RLY_MCP_ALLOW_ORIGIN || ''),
+    });
+  }
+  // Default: be the stdio server. main() never resolves this, so the CLI's
+  // post-run exit timer never arms — the server lives until stdin closes.
+  return runMcp();
+}
+
+// Resolve Claude Desktop's config path for this platform.
+function claudeDesktopConfigPath() {
+  const home = os.homedir();
+  if (process.platform === 'darwin') return path.join(home, 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json');
+  if (process.platform === 'win32') return path.join(process.env.APPDATA || path.join(home, 'AppData', 'Roaming'), 'Claude', 'claude_desktop_config.json');
+  return path.join(process.env.XDG_CONFIG_HOME || path.join(home, '.config'), 'Claude', 'claude_desktop_config.json');
+}
+
+function cmdMcpConfig(args, sub) {
+  const cfg = mcpConfig({ command: 'rly' });
+  const target = String(args.target || '').toLowerCase();
+  const wantInstall = (sub === 'install' || sub === 'add') && args.print !== true;
+
+  // --print, or `config`/`setup` with no writable target: show every option.
+  if (!wantInstall || !target) {
+    const claudePath = claudeDesktopConfigPath();
+    const codexPath = path.join(os.homedir(), '.codex', 'config.toml');
+    printJson({
+      note: 'Register relay as an MCP App server, then call relay_ask / relay_show from inside the host.',
+      claudeCode: 'claude mcp add relay -- rly mcp',
+      claudeDesktop: { file: claudePath, add: cfg.json },
+      codex: { file: codexPath, add: cfg.toml },
+      generic: { add: cfg.json },
+      webMobile: cfg.http,
+      install: 'rly mcp install --target claude   |   rly mcp install --target codex',
+    });
+    return 0;
+  }
+
+  if (target === 'claude' || target === 'claude-desktop') {
+    const file = claudeDesktopConfigPath();
+    let existing = {};
+    try { existing = JSON.parse(fs.readFileSync(file, 'utf8')); } catch { existing = {}; }
+    if (existing === null || typeof existing !== 'object' || Array.isArray(existing)) existing = {};
+    existing.mcpServers = existing.mcpServers && typeof existing.mcpServers === 'object' ? existing.mcpServers : {};
+    existing.mcpServers.relay = { command: cfg.command, args: cfg.args };
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(existing, null, 2) + '\n');
+    printJson({ installed: 'claude-desktop', file, server: 'relay', note: 'restart Claude Desktop to load it' });
+    return 0;
+  }
+  if (target === 'codex') {
+    const file = path.join(os.homedir(), '.codex', 'config.toml');
+    let body = '';
+    try { body = fs.readFileSync(file, 'utf8'); } catch { body = ''; }
+    if (/\[mcp_servers\.relay\]/.test(body)) {
+      printJson({ installed: 'codex', file, server: 'relay', note: 'already present — left as-is' });
+      return 0;
+    }
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const sep = body && !body.endsWith('\n') ? '\n\n' : body ? '\n' : '';
+    fs.writeFileSync(file, body + sep + cfg.toml);
+    printJson({ installed: 'codex', file, server: 'relay', note: 'restart Codex to load it' });
+    return 0;
+  }
+  throw new CliError(`unknown --target "${target}". Use claude or codex (or \`rly mcp config\` to print all).`, 4);
+}
+
 async function cmdServeInternal(args) {
   const id = args.id;
   if (!id) throw new CliError('__serve: missing --id');
@@ -1236,6 +1323,11 @@ USAGE
                                       --scope global|project · --print (copy/paste) · --all · --list (no flags)
   rly upgrade                         install the latest CLI globally + refresh the skill in one step
                                       --stop/--force handle running boards · --dry-run · --cli-only/--skill-only
+  rly mcp                             run relay as an MCP App server (stdio) — boards render INLINE in
+                                      a local desktop host (Claude Desktop, Codex) instead of a browser tab
+  rly mcp --http [--port N]           serve over Streamable HTTP for web/mobile/remote hosts
+                                      [--host H --token SECRET --allow-origin ORIGIN]
+  rly mcp config | install --target   print host setup, or write it (claude | codex)
 
 COMMON FLAGS
   --title <s> --intro <s> --html-file <f> --height <px> --submit-label <s>
@@ -1310,6 +1402,8 @@ export async function main(argv) {
       case 'schema':
         console.log(JSON.stringify(SPEC_SCHEMA, null, 2));
         return 0;
+      case 'mcp':
+        return await cmdMcp(rest);
       case '__serve':
         return await cmdServeInternal(parseArgs(rest));
       default: