@khanglvm/relay 0.10.2 → 0.11.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,43 @@ 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`). Expose it via a tunnel
+  or small host and add it as a custom connector so a phone/web host can render
+  boards too — 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.
+
 ### 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

@@ -5,6 +5,14 @@ rich content blocks (markdown, charts, diagrams, tables, code, custom HTML),
 then **wait for them to click Submit** and read the answers as JSON from stdout.
 No "type 'done' in the terminal", no hand-rolled HTML+server.
 
+**Use relay even in plan mode** — for any clarifying or decision question (Claude
+Code / Codex), route it through a relay board, **not** the native
+`AskUserQuestion` / ask-user tool: that tool is **not** a substitute, even though
+plan-mode guidance suggests it. Do NOT ask in plain terminal text and do NOT
+reach for the native ask tool for anything beyond one trivial yes/no — open a
+board. Reserve the harness's `ExitPlanMode` strictly for the final plan-approval
+gate (it's a mode transition, not a question).
+
 **Tell the user** at the start of your intro text that they can hover chart
 points, diagram nodes, table cells, and any element of a custom-HTML block to
 leave comments, and select text in markdown blocks to annotate — their comments
@@ -54,6 +62,49 @@ 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 instead: `rly mcp --http [--port N]` serves the
+same tools at `http://127.0.0.1:<port>/mcp`. Expose that URL (e.g. a
+cloudflared/ngrok tunnel, or a small always-on host) and register it as a custom
+connector; add `--token <secret>` + `--allow-origin <host>` when it's public.
+`rly mcp config` prints the recipe. Note: an HTTP server only sees local files if
+it runs on the machine those files live on (tunnel from your dev box to keep
+local `codeFile`/image blocks working).
+
+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. The board also adopts the host's **theme, fonts and colors** and
+offers a **full-screen** toggle. The only inline-mode gaps vs. the browser board:
+**local video files** (use a YouTube/Vimeo/`https` URL instead — those play) and
+**element-level annotations** (comment-on-any-element) — per-question notes and
+the overall comment still carry feedback back to you. Everything else —
+questions plus markdown/code/diff/table/chart/mermaid/graphviz/plantuml/image/html
+— renders identically.
+
 ## Creating boards
 
 From a JSON spec file (`--file spec.json`), stdin (`--file -`), or quick
@@ -123,9 +174,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)
 
@@ -305,6 +358,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
@@ -331,6 +395,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.2",
-  "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.11.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.
 
@@ -31,8 +38,15 @@ Schema).** The essentials are below.
 | "Show me the diff" / git diff / code changes / before-after | **rly** (`diff` block — run `git diff`, render it; never dump it in the terminal) |
 | A demo, screen recording or walkthrough | **rly** (`video` block) |
 | Point the user at a file to open (log, capture, report) | **rly** (a clickable local file-link in markdown) |
+| Plan-mode clarifying question (Claude Code / Codex) | **rly** (not AskUserQuestion / the native ask tool) |
 | Something you can decide yourself from context | neither — just decide |
 
+This holds **in plan mode** too: route every clarifying or decision question
+through relay — the native `AskUserQuestion` / ask-user tool is **not** a
+substitute, even though plan-mode guidance suggests it. Reserve the harness's
+`ExitPlanMode` strictly for the final plan-approval gate (it's a mode
+transition, not a question).
+
 Once the user has answered one board in a session, prefer boards for later
 question rounds too — they've shown they engage with them. Batch related
 questions into ONE board rather than opening several in a row.

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) {
@@ -799,8 +801,12 @@ function stampSkillVersion() {
 const SKILL_RULES = `## relay — ask & show in the browser, not the terminal
 
 - Need the user's decisions, feedback, requirements, or approval (anything
-  beyond one trivial yes/no)? Do NOT ask in plain terminal text. Build a board
-  spec and run: \`rly ask --file spec.json --detach\`, then \`rly wait <boardId>\`.
+  beyond one trivial yes/no)? Do NOT ask in plain terminal text **and do NOT use
+  the native \`AskUserQuestion\` / ask-user tool** — for anything beyond one
+  trivial yes/no, open a relay board. Build a board spec and run:
+  \`rly ask --file spec.json --detach\`, then \`rly wait <boardId>\`. **This holds
+  in plan mode too** — route clarifying/decision questions through relay there as
+  well; reserve \`ExitPlanMode\` for the final plan-approval gate only.
 - Presenting a plan, structure, architecture, data, or a prototype? Show a
   relay board with mermaid/graphviz/chart/table/code/diff/video/image/html
   blocks — never ASCII diagrams or walls of prose.
@@ -1177,6 +1183,88 @@ 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) {
+    return runMcpHttp({
+      port: args.port ? Number(args.port) : (process.env.RLY_MCP_PORT ? Number(process.env.RLY_MCP_PORT) : undefined),
+      host: typeof args.host === 'string' ? args.host : '127.0.0.1',
+      token: typeof args.token === 'string' ? args.token : (process.env.RLY_MCP_TOKEN || ''),
+      allowOrigin: typeof args.allowOrigin === 'string' ? args.allowOrigin : '',
+    });
+  }
+  // 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');
@@ -1232,6 +1320,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>
@@ -1306,6 +1399,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: