@paneui/mcp 0.0.19

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lalit Singh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,125 @@
+# @paneui/mcp
+
+A thin **stdio [Model Context Protocol](https://modelcontextprotocol.io) server** for [Pane](https://github.com/aerolalit/paneui). It lets any MCP client — Claude Desktop, Cursor, Windsurf, Cline, your own host — hand a human a rich interactive UI by URL and get structured data back: forms, approvals, pickers, surveys, dashboards, diff/doc review, multi-step wizards.
+
+It is a wrapper, not a reimplementation: all relay I/O goes through [`@paneui/core`](https://www.npmjs.com/package/@paneui/core), and config is shared with the [`pane` CLI](https://www.npmjs.com/package/@paneui/cli) (`~/.config/pane/config.json`) — so the CLI and this server use the **same agent identity**.
+
+## Runtime requirement: Node.js >= 20
+
+The binary is `pane-mcp`. It speaks MCP over stdio and is meant to be launched by an MCP host, not run interactively.
+
+## Quickstart
+
+No global install needed — point your MCP client at `npx @paneui/mcp`. On first use, if no API key is configured, the server auto-registers a fresh agent against the hosted relay and saves the key to the shared CLI store; nothing else to set up.
+
+### Claude Desktop
+
+Edit `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "pane": {
+      "command": "npx",
+      "args": ["-y", "@paneui/mcp"]
+    }
+  }
+}
+```
+
+To pin an existing agent key instead of auto-registering, add an `env` block:
+
+```json
+{
+  "mcpServers": {
+    "pane": {
+      "command": "npx",
+      "args": ["-y", "@paneui/mcp"],
+      "env": { "PANE_API_KEY": "pane_..." }
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project):
+
+```json
+{
+  "mcpServers": {
+    "pane": {
+      "command": "npx",
+      "args": ["-y", "@paneui/mcp"],
+      "env": { "PANE_API_KEY": "pane_..." }
+    }
+  }
+}
+```
+
+### Generic MCP host
+
+Any client that takes a `command` + `args` + `env` works the same way:
+
+```json
+{
+  "mcpServers": {
+    "pane": {
+      "command": "npx",
+      "args": ["-y", "@paneui/mcp"],
+      "env": {
+        "PANE_URL": "https://relay.paneui.com",
+        "PANE_API_KEY": "pane_..."
+      }
+    }
+  }
+}
+```
+
+If you'd rather install it globally (`npm i -g @paneui/mcp`), use `"command": "pane-mcp"` with no `args`.
+
+## Configuration
+
+All environment variables are optional — the defaults target the hosted relay and auto-register on first use.
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `PANE_URL` | `https://relay.paneui.com` | Relay base URL. Set to point at a self-hosted relay. |
+| `PANE_API_KEY` | _(auto-registered)_ | Agent API key. If unset, the server registers an agent on first use and saves the key to `~/.config/pane/config.json` (shared with the CLI). |
+| `PANE_TOKEN` | — | Alias for `PANE_API_KEY` (for hosts that name secrets `*_TOKEN`). `PANE_API_KEY` wins if both are set. |
+| `PANE_AGENT_NAME` | `pane-mcp` | Display name for the auto-registered agent. |
+| `PANE_REGISTER_SECRET` | — | Registration secret, only for relays running `REGISTRATION_MODE=secret`. |
+
+Config precedence mirrors the CLI: env vars win over the saved profile, which falls back to the default relay URL.
+
+## Tools
+
+MCP tools are request/response — there is no long-lived "watch". To receive a human's response you **poll** `get_events` with the cursor from the previous call (optionally with `wait_seconds` to long-poll). Each tool description spells out the pattern for the model.
+
+| Tool | What it does |
+| --- | --- |
+| `create_pane` | Create a pane from inline HTML (+ optional event/record schema). Returns `{ pane_id, url, expires_at }`. **Give `url` to the human.** |
+| `get_pane_state` | Fetch a pane's metadata (status, title, expiry) without its event log. |
+| `get_events` | Poll the pane's append-only event log for what the human did. Pass `since` (cursor) and optional `wait_seconds` (long-poll). |
+| `send_to_pane` | Push an event into an open pane to update the live UI. |
+| `list_records` | List rows in a pane's mutable record collection (todos, line items, comments…). |
+| `upsert_record` | Create/return a record row (dedups on `record_key`). |
+| `update_record` | Update a record row (optional `if_match` optimistic lock). |
+| `delete_record` | Soft-delete a record row (the page sees it live). |
+
+**Events vs records.** Events are an append-only journal — forms, approvals, surveys, pickers. Records are a mutable collection where the current state matters more than the edit history — todo lists, kanban boards, comment threads. Reach for records when the page shows several mutable items.
+
+## Typical flow
+
+1. `create_pane` with your HTML + an `event_schema` declaring the events the page emits → returns a `url`.
+2. Paste the `url` into the conversation and ask the human to open it.
+3. `get_events` with `wait_seconds: 25` in a loop, passing the prior `next_cursor` as `since`, until the awaited event appears.
+4. Optionally `send_to_pane` to update the live UI, or use the record tools for mutable collections.
+
+## MCP registry
+
+`server.json` (in this package) carries the metadata for the [official MCP registry](https://registry.modelcontextprotocol.io). Publishing there is a follow-up step for the maintainer.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/config.js

@@ -0,0 +1,172 @@
+// Relay config resolution for the MCP server.
+//
+// Mirrors how `@paneui/cli` resolves config (see packages/cli/src/config.ts +
+// store.ts) and shares the SAME on-disk store — ${XDG_CONFIG_HOME or
+// ~/.config}/pane/config.json — so a key obtained via `pane agent register`
+// is reused here, and a key obtained here (auto-register on first use) is
+// reused by the CLI.
+//
+// Precedence (highest first):
+//   url:    PANE_URL env  → active profile's url   → DEFAULT_RELAY_URL
+//   apiKey: PANE_API_KEY  → PANE_TOKEN  → active profile's api_key
+//
+// PANE_TOKEN is accepted as an alias for PANE_API_KEY: MCP host config files
+// (Claude Desktop / Cursor) commonly name secrets "*_TOKEN", and the task
+// brief calls it PANE_TOKEN. PANE_API_KEY wins if both are set.
+//
+// The store is read/written WITHOUT a dependency on @paneui/cli (it doesn't
+// export its store module). The on-disk shape is kept byte-compatible with
+// the CLI's store.ts so the two stay interchangeable.
+import { readFileSync, writeFileSync, mkdirSync, chmodSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+import { PaneClient, registerAgent } from "@paneui/core";
+/**
+ * The hosted Pane relay — the URL fallback when nothing else is set. A
+ * self-hoster overrides it with PANE_URL or a registered profile.
+ */
+export const DEFAULT_RELAY_URL = "https://relay.paneui.com";
+/**
+ * Profile name used when this server auto-registers a fresh agent. Matches the
+ * CLI's DEFAULT_PROFILE_NAME so the two share the same default identity.
+ */
+export const DEFAULT_PROFILE_NAME = "default";
+/** Absolute path to the shared CLI/MCP config file (honours XDG_CONFIG_HOME). */
+export function storePath() {
+    const base = process.env.XDG_CONFIG_HOME && process.env.XDG_CONFIG_HOME.trim() !== ""
+        ? process.env.XDG_CONFIG_HOME
+        : join(homedir(), ".config");
+    return join(base, "pane", "config.json");
+}
+/**
+ * Read the persisted store. Returns an empty store if the file is missing,
+ * unparseable, or malformed — mirrors the CLI's tolerant reader so a corrupt
+ * file degrades to "no saved profile" instead of crashing.
+ */
+function readStore() {
+    let text;
+    try {
+        text = readFileSync(storePath(), "utf8");
+    }
+    catch {
+        return { profiles: {} };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return { profiles: {} };
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return { profiles: {} };
+    }
+    const obj = parsed;
+    if (!obj["profiles"] || typeof obj["profiles"] !== "object") {
+        return { profiles: {} };
+    }
+    const rawProfiles = obj["profiles"];
+    const profiles = {};
+    for (const [name, raw] of Object.entries(rawProfiles)) {
+        if (raw === null || typeof raw !== "object")
+            continue;
+        const p = raw;
+        const profile = {};
+        if (typeof p["url"] === "string")
+            profile.url = p["url"];
+        if (typeof p["api_key"] === "string")
+            profile.apiKey = p["api_key"];
+        profiles[name] = profile;
+    }
+    const currentProfile = typeof obj["current_profile"] === "string"
+        ? obj["current_profile"]
+        : undefined;
+    return {
+        currentProfile: currentProfile && profiles[currentProfile] !== undefined
+            ? currentProfile
+            : undefined,
+        profiles,
+    };
+}
+/** Serialise a Store to the CLI's on-disk JSON shape (snake_case fields). */
+function serialize(store) {
+    const profilesOut = {};
+    for (const [name, p] of Object.entries(store.profiles)) {
+        const o = {};
+        if (p.url !== undefined)
+            o["url"] = p.url;
+        if (p.apiKey !== undefined)
+            o["api_key"] = p.apiKey;
+        profilesOut[name] = o;
+    }
+    const body = { profiles: profilesOut };
+    if (store.currentProfile !== undefined) {
+        body["current_profile"] = store.currentProfile;
+    }
+    return JSON.stringify(body, null, 2) + "\n";
+}
+/** Upsert one profile and persist (mode 0600). Used by auto-register. */
+function upsertProfile(name, patch, setCurrent) {
+    const store = readStore();
+    const merged = { ...(store.profiles[name] ?? {}), ...patch };
+    store.profiles[name] = merged;
+    if (setCurrent || store.currentProfile === undefined) {
+        store.currentProfile = name;
+    }
+    const path = storePath();
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, serialize(store), { mode: 0o600 });
+    chmodSync(path, 0o600);
+}
+/** Resolve the relay URL using the same precedence as the CLI. */
+export function resolveUrl() {
+    const store = readStore();
+    const active = store.currentProfile
+        ? store.profiles[store.currentProfile]
+        : undefined;
+    const url = process.env.PANE_URL ?? active?.url ?? DEFAULT_RELAY_URL;
+    return url.replace(/\/$/, "");
+}
+/** Resolve the API key (env → PANE_TOKEN alias → active profile). */
+function resolveApiKey() {
+    const store = readStore();
+    const active = store.currentProfile
+        ? store.profiles[store.currentProfile]
+        : undefined;
+    const key = process.env.PANE_API_KEY ?? process.env.PANE_TOKEN ?? active?.apiKey;
+    return key && key !== "" ? key : undefined;
+}
+/**
+ * Resolve a ready-to-use PaneClient.
+ *
+ * First-run setup: if no API key is resolvable from the environment or the
+ * shared store, the server auto-registers a fresh agent against the relay and
+ * persists the key under the `default` profile in the shared store — so the
+ * CLI and any later MCP launch reuse the same identity, and the human never
+ * has to run `pane agent register` by hand.
+ *
+ * A self-hoster on a `secret`-mode relay (or anyone who prefers explicit
+ * provisioning) sets PANE_API_KEY / PANE_TOKEN and the auto-register path is
+ * never taken.
+ *
+ * `opts.agentName` labels the auto-registered agent on the relay.
+ * `opts.registerSecret` is forwarded as the registration secret for
+ * REGISTRATION_MODE=secret relays.
+ */
+export async function resolveClient(opts = {}) {
+    const url = resolveUrl();
+    let apiKey = resolveApiKey();
+    if (apiKey === undefined) {
+        // No key anywhere — provision one and persist it under `default`.
+        const result = await registerAgent({
+            url,
+            name: opts.agentName ?? "pane-mcp",
+            ...(opts.registerSecret !== undefined && opts.registerSecret !== ""
+                ? { secret: opts.registerSecret }
+                : {}),
+        });
+        upsertProfile(DEFAULT_PROFILE_NAME, { url, apiKey: result.api_key }, true);
+        apiKey = result.api_key;
+    }
+    return new PaneClient({ url, apiKey });
+}

package/dist/index.js

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+// `pane-mcp` — a thin stdio Model Context Protocol server wrapping Pane.
+//
+// Speaks MCP over stdio so any MCP client (Claude Desktop, Cursor, …) can use
+// Pane: create panes, push updates, and poll for the human's response. All
+// relay I/O goes through @paneui/core (no duplicated transport logic), and
+// config is shared with the `pane` CLI (~/.config/pane/config.json) — so the
+// CLI and this server use the same agent identity.
+//
+// Config (all optional — sensible defaults; auto-registers an agent on first
+// use if no key is found):
+//   PANE_URL              relay base URL (default https://relay.paneui.com)
+//   PANE_API_KEY          agent API key (or use the shared CLI store)
+//   PANE_TOKEN            alias for PANE_API_KEY (for MCP host "*_TOKEN" config)
+//   PANE_AGENT_NAME       label for the auto-registered agent
+//   PANE_REGISTER_SECRET  registration secret (REGISTRATION_MODE=secret relays)
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { buildServer } from "./server.js";
+import { VERSION } from "./version.js";
+async function main() {
+    // --version / --help are answered locally without starting the transport, so
+    // a human poking at the binary gets a useful response instead of a hung
+    // stdio session waiting for JSON-RPC.
+    const argv = process.argv.slice(2);
+    if (argv.includes("--version") || argv.includes("-v")) {
+        process.stdout.write(`pane-mcp ${VERSION}\n`);
+        return;
+    }
+    if (argv.includes("--help") || argv.includes("-h")) {
+        process.stdout.write(HELP);
+        return;
+    }
+    const server = buildServer({
+        agentName: process.env.PANE_AGENT_NAME,
+        registerSecret: process.env.PANE_REGISTER_SECRET,
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // Stdio MCP servers run until the host closes stdin; keep the process alive.
+    // The transport resolves connect() immediately, so without this the event
+    // loop would otherwise stay open only because of the stdin reader — which is
+    // the intended behaviour. Nothing more to do here.
+}
+const HELP = `pane-mcp ${VERSION} — Pane Model Context Protocol server (stdio)
+
+Run by an MCP client over stdio; not meant to be invoked interactively. Add it
+to your MCP client config, e.g. Claude Desktop / Cursor:
+
+  {
+    "mcpServers": {
+      "pane": {
+        "command": "npx",
+        "args": ["-y", "@paneui/mcp"],
+        "env": { "PANE_API_KEY": "pane_..." }
+      }
+    }
+  }
+
+Environment:
+  PANE_URL              Relay base URL (default https://relay.paneui.com)
+  PANE_API_KEY          Agent API key. If unset, the server auto-registers an
+  PANE_TOKEN            agent on first use and saves the key to the shared CLI
+                        store (~/.config/pane/config.json). PANE_TOKEN is an
+                        alias for PANE_API_KEY.
+  PANE_AGENT_NAME       Display name for the auto-registered agent.
+  PANE_REGISTER_SECRET  Registration secret (REGISTRATION_MODE=secret relays).
+
+Tools exposed: create_pane, get_pane_state, get_events, send_to_pane,
+list_records, upsert_record, update_record, delete_record.
+
+See https://github.com/aerolalit/paneui for docs.
+`;
+main().catch((e) => {
+    process.stderr.write(`pane-mcp: fatal: ${e instanceof Error ? (e.stack ?? e.message) : String(e)}\n`);
+    process.exit(1);
+});

package/dist/server.js

@@ -0,0 +1,69 @@
+// Builds the Pane MCP server: registers every tool from ./tools.ts against an
+// McpServer and wires each handler to a lazily-resolved PaneClient.
+//
+// The PaneClient is resolved ONCE, on the first tool call, then cached — so the
+// (potentially network-touching) auto-register-on-first-use path runs lazily,
+// not at process start. This keeps `initialize` / `tools/list` fast and offline
+// (an MCP host can enumerate the tools without the relay being reachable), and
+// only the first actual tool call provisions a key if needed.
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { resolveClient } from "./config.js";
+import { TOOLS } from "./tools.js";
+import { VERSION } from "./version.js";
+/**
+ * Construct (but do not connect) the Pane MCP server. Call `.connect(transport)`
+ * on the returned server to start serving.
+ */
+export function buildServer(opts = {}) {
+    const server = new McpServer({
+        name: "pane",
+        version: VERSION,
+    });
+    // Lazily resolve + memoise the client. A failed resolution is not cached, so
+    // a transient error (e.g. relay unreachable during auto-register) can be
+    // retried on the next tool call.
+    let clientPromise;
+    const getClient = () => {
+        if (opts.client)
+            return Promise.resolve(opts.client);
+        if (clientPromise === undefined) {
+            clientPromise = resolveClient({
+                agentName: opts.agentName,
+                registerSecret: opts.registerSecret,
+            }).catch((e) => {
+                clientPromise = undefined;
+                throw e;
+            });
+        }
+        return clientPromise;
+    };
+    for (const tool of TOOLS) {
+        server.registerTool(tool.name, {
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+        }, async (args) => {
+            let client;
+            try {
+                client = await getClient();
+            }
+            catch (e) {
+                const message = e instanceof Error ? e.message : String(e);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                error: "config_error",
+                                message,
+                                hint: "Set PANE_API_KEY (or PANE_TOKEN), or ensure the relay at PANE_URL is reachable so the server can auto-register an agent.",
+                            }, null, 2),
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            return tool.handler(client, args);
+        });
+    }
+    return server;
+}

package/dist/tools.js

@@ -0,0 +1,340 @@
+// Tool definitions for the Pane MCP server.
+//
+// Each tool wraps a @paneui/core PaneClient operation. The descriptions are
+// written for the LLM consumer — they ARE the docs the model reads to decide
+// when and how to call each tool. Keep them concrete and action-oriented.
+//
+// Design notes:
+//   - MCP tools are request/response. There is no long-lived "watch" — instead
+//     `get_events` is a poll: the model calls it with the cursor from the last
+//     call until the awaited event appears. Each description spells out the
+//     poll loop so the model drives it correctly.
+//   - Schema validation is done with Zod raw shapes (the shape the MCP SDK's
+//     registerTool expects); the SDK validates arguments against them before
+//     the handler runs, so handlers receive typed, validated input.
+import { z } from "zod";
+import { PaneApiError } from "@paneui/core";
+/** Wrap a JSON-able value as a single text-content tool result. */
+function jsonResult(value) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(value, null, 2) }],
+    };
+}
+/**
+ * Turn any thrown error into a structured `isError` tool result. PaneApiError
+ * carries the relay's `code`, HTTP `status`, and an optional remediation
+ * `hint`; surface all of it so the model can self-correct (e.g. fix an event
+ * type the schema rejected) instead of getting an opaque failure.
+ */
+function errorResult(e) {
+    if (e instanceof PaneApiError) {
+        const payload = {
+            error: e.code,
+            status: e.status,
+            message: e.message,
+        };
+        if (e.hint)
+            payload["hint"] = e.hint;
+        if (e.details !== undefined)
+            payload["details"] = e.details;
+        if (e.retryable !== undefined)
+            payload["retryable"] = e.retryable;
+        return {
+            content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+            isError: true,
+        };
+    }
+    const message = e instanceof Error ? e.message : String(e);
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({ error: "internal", message }, null, 2),
+            },
+        ],
+        isError: true,
+    };
+}
+// ---------------------------------------------------------------------------
+// Tool input schemas
+// ---------------------------------------------------------------------------
+const createPaneShape = {
+    name: z
+        .string()
+        .min(1)
+        .describe("Short human-readable label for the auto-created template, shown in the owner UI (e.g. 'Deploy approval', 'Vendor picker')."),
+    html: z
+        .string()
+        .min(1)
+        .describe("The pane's UI as a complete inline HTML document. To send data back to you, the page calls window.pane.emit(eventType, payload) — every emitted eventType MUST be declared in event_schema below with 'page' in its emittedBy. Read window.pane.inputData for seed data passed via input_data."),
+    event_schema: z
+        .record(z.string(), z.unknown())
+        .optional()
+        .describe("Optional. Declares which events the page (and you) may emit and validates each payload. Shape: { events: { '<type>': { emittedBy: ['page'|'agent'...], payload: <JSON Schema> } } }. OMIT for a read-only pane (dashboard/status view the human only looks at — it then accepts no events)."),
+    input_data: z
+        .record(z.string(), z.unknown())
+        .optional()
+        .describe("Optional seed data for this pane instance, readable in the page as window.pane.inputData (e.g. the diff to review, the options to pick from)."),
+    input_schema: z
+        .record(z.string(), z.unknown())
+        .optional()
+        .describe("Optional JSON Schema validating input_data. Only needed if input_data references uploaded attachment ids the page must download."),
+    title: z
+        .string()
+        .optional()
+        .describe("Optional browser tab title for the human (≤80 chars). Defaults to `name`."),
+    preamble: z
+        .string()
+        .max(300)
+        .optional()
+        .describe("Optional one/two-line context shown above the UI — 'who is asking, and why'. Use it whenever the pane isn't self-explanatory."),
+    ttl_seconds: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("Optional pane lifetime in seconds. The relay clamps to its max; the returned expires_at is authoritative."),
+    context_key: z
+        .string()
+        .min(1)
+        .max(256)
+        .optional()
+        .describe("Optional natural key (e.g. 'pr-42', 'deal-1138'). Repeated create_pane calls with the same (template, key) return the SAME pane instead of a new one — use it to make retries idempotent."),
+};
+const getPaneStateShape = {
+    pane_id: z.string().min(1).describe("The pane id returned by create_pane."),
+};
+const getEventsShape = {
+    pane_id: z.string().min(1).describe("The pane id to read events from."),
+    since: z
+        .string()
+        .optional()
+        .describe("Opaque cursor from a previous get_events call's next_cursor. Omit on the first call to read from the beginning."),
+    wait_seconds: z
+        .number()
+        .int()
+        .min(0)
+        .max(30)
+        .optional()
+        .describe("Optional long-poll: how long the relay holds the request open waiting for a new event (0–30s, relay-capped). Use ~25 when waiting for a human to act, so each poll either returns promptly with the event or returns empty and you call again with the same cursor."),
+};
+const sendToPaneShape = {
+    pane_id: z.string().min(1).describe("The pane id to push the event into."),
+    type: z
+        .string()
+        .min(1)
+        .describe("Event type. Must be declared in the pane's event_schema with 'agent' in its emittedBy list (the page sees it live)."),
+    data: z
+        .unknown()
+        .describe("Event payload — any JSON value valid against the type's payload schema. Use {} or null for a no-payload event."),
+    idempotency_key: z
+        .string()
+        .optional()
+        .describe("Optional dedup key — a repeat send with the same key is a no-op."),
+};
+const listRecordsShape = {
+    pane_id: z.string().min(1).describe("The pane id."),
+    collection: z
+        .string()
+        .min(1)
+        .describe("The record collection name declared in the pane's record schema."),
+    since: z
+        .number()
+        .int()
+        .optional()
+        .describe("Optional cursor (next_since from a prior call) for pagination."),
+    limit: z.number().int().positive().optional().describe("Optional page size."),
+};
+const upsertRecordShape = {
+    pane_id: z.string().min(1).describe("The pane id."),
+    collection: z.string().min(1).describe("The record collection name."),
+    record_key: z
+        .string()
+        .optional()
+        .describe("Optional stable key for this record. Reusing an existing key returns the existing row (deduped:true) rather than creating a duplicate; omit to let the relay assign one."),
+    data: z
+        .unknown()
+        .describe("The record body — any JSON value valid against the collection schema."),
+};
+const updateRecordShape = {
+    pane_id: z.string().min(1).describe("The pane id."),
+    collection: z.string().min(1).describe("The record collection name."),
+    record_key: z.string().min(1).describe("The key of the record to update."),
+    data: z.unknown().describe("The new record body (replaces the row's data)."),
+    if_match: z
+        .number()
+        .int()
+        .optional()
+        .describe("Optional optimistic-lock version. If it doesn't match the current row, the update is rejected with the current row in details.current."),
+};
+const deleteRecordShape = {
+    pane_id: z.string().min(1).describe("The pane id."),
+    collection: z.string().min(1).describe("The record collection name."),
+    record_key: z.string().min(1).describe("The key of the record to delete."),
+};
+// ---------------------------------------------------------------------------
+// Tool definitions
+// ---------------------------------------------------------------------------
+export const TOOLS = [
+    {
+        name: "create_pane",
+        description: "Hand the human a rich interactive UI by URL and (optionally) get structured data back. Build the UI as inline HTML; the relay hosts it and returns a URL. ALWAYS give the returned url (result.url) to the human — paste it into the conversation and ask them to open it. Reach for this whenever a text reply is the wrong shape: forms, approvals, pickers, surveys, dashboards, diff/doc review, multi-step wizards. If the page captures input it emits events back to you (poll them with get_events). A read-only dashboard with no event_schema is valid too. Returns { pane_id, url, expires_at }.",
+        inputSchema: createPaneShape,
+        handler: async (client, args) => {
+            try {
+                const template = {
+                    name: args["name"],
+                    type: "html-inline",
+                    source: args["html"],
+                };
+                if (args["event_schema"] !== undefined)
+                    template["event_schema"] = args["event_schema"];
+                if (args["input_schema"] !== undefined)
+                    template["input_schema"] = args["input_schema"];
+                const req = { template };
+                if (args["input_data"] !== undefined)
+                    req["input_data"] = args["input_data"];
+                if (args["title"] !== undefined)
+                    req["title"] = args["title"];
+                if (args["preamble"] !== undefined)
+                    req["preamble"] = args["preamble"];
+                if (args["ttl_seconds"] !== undefined)
+                    req["ttl"] = args["ttl_seconds"];
+                if (args["context_key"] !== undefined)
+                    req["context_key"] = args["context_key"];
+                const res = await client.createPane(req);
+                const humanUrl = res.urls.humans[0] ?? null;
+                return jsonResult({
+                    pane_id: res.pane_id,
+                    // The single URL to deliver to the human. (urls.humans carries all
+                    // of them when participants > 1.)
+                    url: humanUrl,
+                    urls: res.urls.humans,
+                    title: res.title,
+                    expires_at: res.expires_at,
+                });
+            }
+            catch (e) {
+                return errorResult(e);
+            }
+        },
+    },
+    {
+        name: "get_pane_state",
+        description: "Fetch a pane's current metadata (status, title, template version, timestamps, expires_at) WITHOUT its event log. Use it to check whether a pane is still open or has expired. To read what the human did, use get_events.",
+        inputSchema: getPaneStateShape,
+        handler: async (client, args) => {
+            try {
+                const state = await client.getPane(String(args["pane_id"]));
+                return jsonResult(state);
+            }
+            catch (e) {
+                return errorResult(e);
+            }
+        },
+    },
+    {
+        name: "get_events",
+        description: "Poll a pane's append-only event log for what the human did (form submissions, approvals, picks). This is how you receive the round-trip result — there is no push/streaming in MCP. Poll loop: call with no `since` first; process the returned events; remember next_cursor; call again passing it as `since` to get only newer events. To WAIT for a human who hasn't acted yet, pass wait_seconds (~25) so the relay holds the request open until an event arrives or it times out, then call again with the same cursor. Returns { events, next_cursor }.",
+        inputSchema: getEventsShape,
+        handler: async (client, args) => {
+            try {
+                const page = await client.getEvents(String(args["pane_id"]), {
+                    since: args["since"],
+                    waitSeconds: args["wait_seconds"],
+                });
+                return jsonResult(page);
+            }
+            catch (e) {
+                return errorResult(e);
+            }
+        },
+    },
+    {
+        name: "send_to_pane",
+        description: "Push an event INTO an open pane — update the live UI the human is looking at (progress, a new message, a status change, fresh data). The event type must be declared in the pane's event_schema with 'agent' in its emittedBy. For mutable collections (todos, line items, comment threads) prefer the record tools instead. Returns { event, deduped }.",
+        inputSchema: sendToPaneShape,
+        handler: async (client, args) => {
+            try {
+                const res = await client.sendEvent(String(args["pane_id"]), {
+                    type: String(args["type"]),
+                    data: args["data"],
+                    idempotencyKey: args["idempotency_key"],
+                });
+                return jsonResult(res);
+            }
+            catch (e) {
+                return errorResult(e);
+            }
+        },
+    },
+    {
+        name: "list_records",
+        description: "List rows in a pane's mutable record collection (e.g. a todo list, shopping list, kanban board, comment thread). Records are the right primitive when the page shows several mutable items and the CURRENT state matters more than the history of edits. Includes tombstones (deleted_at set) so you can observe deletions. Returns { records, next_since, has_more }.",
+        inputSchema: listRecordsShape,
+        handler: async (client, args) => {
+            try {
+                const out = await client.listRecords(String(args["pane_id"]), String(args["collection"]), {
+                    since: args["since"],
+                    limit: args["limit"],
+                });
+                return jsonResult(out);
+            }
+            catch (e) {
+                return errorResult(e);
+            }
+        },
+    },
+    {
+        name: "upsert_record",
+        description: "Create a row in a pane's record collection, or return the existing row if record_key is already present (deduped:true). Use to add a todo, a line item, a comment, etc. The collection must be declared in the pane's record schema with 'agent' allowed to write. Returns { record, deduped }.",
+        inputSchema: upsertRecordShape,
+        handler: async (client, args) => {
+            try {
+                const body = {
+                    data: args["data"],
+                };
+                if (args["record_key"] !== undefined)
+                    body.record_key = String(args["record_key"]);
+                const out = await client.upsertRecord(String(args["pane_id"]), String(args["collection"]), body);
+                return jsonResult(out);
+            }
+            catch (e) {
+                return errorResult(e);
+            }
+        },
+    },
+    {
+        name: "update_record",
+        description: "Update an existing row in a pane's record collection (replaces its data). Pass if_match with the row's current version for an optimistic-locked update — on a version mismatch the relay returns the current row so you can retry. Returns { record }.",
+        inputSchema: updateRecordShape,
+        handler: async (client, args) => {
+            try {
+                const body = {
+                    data: args["data"],
+                };
+                if (args["if_match"] !== undefined)
+                    body.if_match = args["if_match"];
+                const out = await client.updateRecord(String(args["pane_id"]), String(args["collection"]), String(args["record_key"]), body);
+                return jsonResult(out);
+            }
+            catch (e) {
+                return errorResult(e);
+            }
+        },
+    },
+    {
+        name: "delete_record",
+        description: "Soft-delete a row from a pane's record collection. The page sees the deletion live (the row becomes a tombstone in list_records). Returns { deleted: true }.",
+        inputSchema: deleteRecordShape,
+        handler: async (client, args) => {
+            try {
+                await client.deleteRecord(String(args["pane_id"]), String(args["collection"]), String(args["record_key"]));
+                return jsonResult({ deleted: true });
+            }
+            catch (e) {
+                return errorResult(e);
+            }
+        },
+    },
+];

package/dist/version.js

@@ -0,0 +1,3 @@
+// Single source of the package version, reported in the MCP server's
+// serverInfo. Kept in sync with package.json by the release tooling.
+export const VERSION = "0.0.18";

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@paneui/mcp",
+  "version": "0.0.19",
+  "description": "Model Context Protocol (stdio) server for Pane: lets any MCP client (Claude Desktop, Cursor, …) hand a human a rich interactive UI by URL and get structured data back.",
+  "license": "MIT",
+  "type": "module",
+  "keywords": [
+    "pane",
+    "mcp",
+    "model-context-protocol",
+    "agent",
+    "relay",
+    "human-in-the-loop"
+  ],
+  "homepage": "https://github.com/aerolalit/paneui#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aerolalit/paneui.git",
+    "directory": "packages/mcp"
+  },
+  "bugs": {
+    "url": "https://github.com/aerolalit/paneui/issues"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "pane-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "server.json",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:unit": "vitest run"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.20.0",
+    "@paneui/core": "^0.0.19",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.2",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.8"
+  }
+}

package/server.json

@@ -0,0 +1,48 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.aerolalit/pane",
+  "title": "Pane",
+  "description": "Hand a human a rich interactive UI by URL and get structured data back — forms, approvals, pickers, dashboards, diff review — from any MCP client.",
+  "version": "0.0.18",
+  "repository": {
+    "url": "https://github.com/aerolalit/paneui",
+    "source": "github"
+  },
+  "packages": [
+    {
+      "registryType": "npm",
+      "registryBaseUrl": "https://registry.npmjs.org",
+      "identifier": "@paneui/mcp",
+      "version": "0.0.18",
+      "transport": {
+        "type": "stdio"
+      },
+      "environmentVariables": [
+        {
+          "name": "PANE_API_KEY",
+          "description": "Pane agent API key. If unset, the server auto-registers a fresh agent against the relay on first use and saves the key to the shared CLI store (~/.config/pane/config.json).",
+          "isRequired": false,
+          "isSecret": true
+        },
+        {
+          "name": "PANE_URL",
+          "description": "Pane relay base URL. Defaults to the hosted relay https://relay.paneui.com; set this to point at a self-hosted relay.",
+          "isRequired": false,
+          "isSecret": false
+        },
+        {
+          "name": "PANE_AGENT_NAME",
+          "description": "Display name for the auto-registered agent on the relay.",
+          "isRequired": false,
+          "isSecret": false
+        },
+        {
+          "name": "PANE_REGISTER_SECRET",
+          "description": "Registration secret, required only for relays running REGISTRATION_MODE=secret.",
+          "isRequired": false,
+          "isSecret": true
+        }
+      ]
+    }
+  ]
+}