@paneui/mcp 0.0.23 → 0.0.25

package/dist/capabilities.d.ts

@@ -0,0 +1,9 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare const GUIDE_RESOURCE_URI = "pane://guide";
+export declare const GUIDE_PROMPT_NAME = "pane_guide";
+/**
+ * Register the `pane_guide` prompt and the `pane://guide` resource on `server`.
+ * `getGuide()` returns the current MCP-flavoured guide markdown (called lazily
+ * on each read so a relay can serve an updated guide without re-registering).
+ */
+export declare function registerGuideCapabilities(server: McpServer, getGuide: () => string | Promise<string>): void;

package/dist/capabilities.js

@@ -0,0 +1,50 @@
+// Register pane's MCP prompt + resource on an McpServer.
+//
+// Both the stdio server (packages/mcp/src/server.ts) and the relay's HTTP MCP
+// server call this so an MCP-native client can discover the conceptual guide
+// without a tool call:
+//
+//   - prompt   `pane_guide`   — surfaces the guide as a prompt the client can
+//                               insert into context ("teach me pane").
+//   - resource `pane://guide`  — the same guide as a readable resource.
+//
+// The guide text is supplied by the host: the relay composes it in-process
+// (MCP-INVOCATION.md + the core extracted from SKILL.md); the stdio server
+// fetches it from the relay over HTTP and falls back to a short pointer when
+// the relay is unreachable at registration time (registration must not block on
+// the network — the get_skill tool is the always-fresh path).
+export const GUIDE_RESOURCE_URI = "pane://guide";
+export const GUIDE_PROMPT_NAME = "pane_guide";
+/**
+ * Register the `pane_guide` prompt and the `pane://guide` resource on `server`.
+ * `getGuide()` returns the current MCP-flavoured guide markdown (called lazily
+ * on each read so a relay can serve an updated guide without re-registering).
+ */
+export function registerGuideCapabilities(server, getGuide) {
+    server.registerResource(GUIDE_PROMPT_NAME, GUIDE_RESOURCE_URI, {
+        title: "Pane usage guide",
+        description: "The pane conceptual guide for MCP clients: when to use pane, events vs records, schema design, the house style, and the round-trip mental model — with MCP tool-call invocation grammar.",
+        mimeType: "text/markdown",
+    }, async () => {
+        const text = await getGuide();
+        return {
+            contents: [
+                { uri: GUIDE_RESOURCE_URI, mimeType: "text/markdown", text },
+            ],
+        };
+    });
+    server.registerPrompt(GUIDE_PROMPT_NAME, {
+        title: "Pane usage guide",
+        description: "Insert the pane usage guide (MCP invocation + conceptual core) into the conversation so the model knows how to drive pane's tools.",
+    }, async () => {
+        const text = await getGuide();
+        return {
+            messages: [
+                {
+                    role: "user",
+                    content: { type: "text", text },
+                },
+            ],
+        };
+    });
+}

package/dist/config.d.ts

@@ -0,0 +1,65 @@
+import { PaneClient } 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 declare 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 declare const DEFAULT_PROFILE_NAME = "default";
+/** Absolute path to the shared CLI/MCP config file (honours XDG_CONFIG_HOME). */
+export declare function storePath(): string;
+/**
+ * Clear the active saved profile from the shared store (mirrors `pane agent
+ * logout` for the active-profile case). Removes the profile entry and unsets
+ * `current_profile` so the next resolve falls back to env / the default URL.
+ * Local-only: it does NOT revoke the key on the relay (use the `key` tool's
+ * `revoke` action for that). Idempotent — clearing an empty store is a no-op.
+ * Returns the profile name that was cleared (or null when nothing was active)
+ * and the store path.
+ */
+export declare function clearActiveProfile(): {
+    cleared: boolean;
+    profile: string | null;
+    path: string;
+};
+/** Resolve the relay URL using the same precedence as the CLI. */
+export declare function resolveUrl(): string;
+/**
+ * Describe how the server is currently configured WITHOUT touching the network
+ * — the resolved relay URL, the active profile name, where the key is coming
+ * from, and whether a key is present at all. Backs the `agent` tool's `whoami`
+ * action so an MCP client can introspect its own identity / relay binding the
+ * way `pane config show` does for the CLI. No secrets are returned (the API key
+ * plaintext is never surfaced — only its source + whether it exists).
+ */
+export declare function describeActiveConfig(): {
+    url: string;
+    profile: string | null;
+    api_key_present: boolean;
+    api_key_source: "env" | "profile" | "none";
+    store_path: string;
+};
+/**
+ * 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 declare function resolveClient(opts?: {
+    agentName?: string;
+    registerSecret?: string;
+}): Promise<PaneClient>;

package/dist/guide.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Extract every `<!-- pane:core:start -->…<!-- pane:core:end -->` block from a
+ * SKILL.md body, concatenated in document order (markers removed). Returns the
+ * transport-agnostic conceptual core with no CLI command grammar.
+ */
+export declare function extractCore(skillMarkdown: string): string;
+/**
+ * Build the full MCP guide: the MCP invocation layer followed by the shared
+ * conceptual core extracted from SKILL.md. `mcpInvocation` is the contents of
+ * skills/pane/MCP-INVOCATION.md; `skillMarkdown` is the contents of SKILL.md.
+ */
+export declare function composeMcpGuide(mcpInvocation: string, skillMarkdown: string): string;

package/dist/guide.js

@@ -0,0 +1,49 @@
+// Compose the MCP-flavoured pane guide from the shared conceptual core + the
+// MCP invocation layer.
+//
+// Single source of truth: the conceptual core lives in skills/pane/SKILL.md
+// between `<!-- pane:core:start -->` / `<!-- pane:core:end -->` markers (the
+// CLI invocation grammar lives OUTSIDE those markers, so the CLI document and
+// the MCP guide share the exact same prose for "when to use pane / events vs
+// records / schema design / house style / the round-trip mental model"). The
+// MCP invocation layer (tool-call grammar) lives in skills/pane/MCP-INVOCATION.md.
+//
+// The MCP guide = MCP-INVOCATION.md (with its trailing "the rest is the core"
+// pointer) + every core block extracted from SKILL.md, in document order. No
+// `pane ...` command grammar leaks into it.
+//
+// This is pure string manipulation so both the relay (which reads the files at
+// boot and serves the result) and any other consumer can share one
+// implementation without dragging in I/O.
+const CORE_START = "<!-- pane:core:start -->";
+const CORE_END = "<!-- pane:core:end -->";
+/**
+ * Extract every `<!-- pane:core:start -->…<!-- pane:core:end -->` block from a
+ * SKILL.md body, concatenated in document order (markers removed). Returns the
+ * transport-agnostic conceptual core with no CLI command grammar.
+ */
+export function extractCore(skillMarkdown) {
+    const blocks = [];
+    let cursor = 0;
+    for (;;) {
+        const start = skillMarkdown.indexOf(CORE_START, cursor);
+        if (start === -1)
+            break;
+        const afterStart = start + CORE_START.length;
+        const end = skillMarkdown.indexOf(CORE_END, afterStart);
+        if (end === -1)
+            break;
+        blocks.push(skillMarkdown.slice(afterStart, end).trim());
+        cursor = end + CORE_END.length;
+    }
+    return blocks.join("\n\n");
+}
+/**
+ * Build the full MCP guide: the MCP invocation layer followed by the shared
+ * conceptual core extracted from SKILL.md. `mcpInvocation` is the contents of
+ * skills/pane/MCP-INVOCATION.md; `skillMarkdown` is the contents of SKILL.md.
+ */
+export function composeMcpGuide(mcpInvocation, skillMarkdown) {
+    const core = extractCore(skillMarkdown);
+    return `${mcpInvocation.trim()}\n\n${core}\n`;
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/server.d.ts

@@ -0,0 +1,18 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { PaneClient } from "@paneui/core";
+export interface BuildServerOptions {
+    /** Display name for the auto-registered agent (when no key is configured). */
+    agentName?: string;
+    /** Registration secret for REGISTRATION_MODE=secret relays. */
+    registerSecret?: string;
+    /**
+     * Inject a pre-built client (tests). When set, the lazy resolver is skipped
+     * entirely and no network/store access happens.
+     */
+    client?: PaneClient;
+}
+/**
+ * Construct (but do not connect) the Pane MCP server. Call `.connect(transport)`
+ * on the returned server to start serving.
+ */
+export declare function buildServer(opts?: BuildServerOptions): McpServer;

package/dist/server.js

@@ -7,9 +7,11 @@
 // (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 { resolveClient, resolveUrl } from "./config.js";
 import { TOOLS } from "./tools.js";
 import { VERSION } from "./version.js";
+import { fetchMcpGuide } from "./skill.js";
+import { registerGuideCapabilities } from "./capabilities.js";
 /**
  * Construct (but do not connect) the Pane MCP server. Call `.connect(transport)`
  * on the returned server to start serving.
@@ -37,10 +39,37 @@ export function buildServer(opts = {}) {
         }
         return clientPromise;
     };
+    // MCP consumers get the MCP-flavoured guide (tool-call grammar), not the
+    // CLI-grammar SKILL.md. get_skill fetches /skills/pane/MCP.md from the
+    // configured relay; everything else keeps its CLI defaults (the stdio server
+    // reads identity from the shared CLI config store).
+    const toolEnv = {
+        getSkill: (versionOnly) => fetchMcpGuide(resolveUrl(), { version: versionOnly }),
+    };
+    // Conceptual guide as an MCP prompt + resource. Fetched from the relay lazily
+    // on read; a relay-unreachable read surfaces a short pointer to get_skill
+    // rather than failing registration.
+    registerGuideCapabilities(server, async () => {
+        try {
+            const { markdown } = await fetchMcpGuide(resolveUrl());
+            return markdown ?? "";
+        }
+        catch (e) {
+            const message = e instanceof Error ? e.message : String(e);
+            return ("# pane\n\nThe pane guide could not be fetched from the relay " +
+                `(${message}).\n\nCall the \`get_skill\` tool to retrieve it once the ` +
+                "relay is reachable.\n");
+        }
+    });
     for (const tool of TOOLS) {
         server.registerTool(tool.name, {
+            // `title` (top-level, display name) + `annotations` (the ToolAnnotations
+            // behavioural hints, which also carry a title) both flow into tools/list
+            // so MCP hosts / Anthropic's connector directory can classify the tool.
+            title: tool.annotations.title,
             description: tool.description,
             inputSchema: tool.inputSchema,
+            annotations: tool.annotations,
         }, async (args) => {
             let client;
             try {
@@ -62,7 +91,7 @@ export function buildServer(opts = {}) {
                     isError: true,
                 };
             }
-            return tool.handler(client, args);
+            return tool.handler(client, args, toolEnv);
         });
     }
     return server;

package/dist/skill.d.ts

@@ -0,0 +1,24 @@
+/**
+ * GET the relay's full SKILL.md markdown. `version: true` instead fetches just
+ * the relay's reported skill version (the "is my local copy stale?" probe).
+ * Throws on a non-2xx or network failure with a message the tool layer can
+ * surface.
+ */
+export declare function fetchSkill(relayUrl: string, opts?: {
+    version?: boolean;
+}): Promise<{
+    markdown?: string;
+    version?: string;
+}>;
+/**
+ * GET the relay's MCP-flavoured guide (the conceptual core + MCP tool-call
+ * invocation grammar) from GET /skills/pane/MCP.md, or just its version from
+ * GET /skills/pane/MCP.md/version. This is what an MCP consumer should read
+ * (not the CLI-grammar SKILL.md). Served unauthenticated, same as the skill.
+ */
+export declare function fetchMcpGuide(relayUrl: string, opts?: {
+    version?: boolean;
+}): Promise<{
+    markdown?: string;
+    version?: string;
+}>;

package/dist/skill.js

@@ -37,6 +37,34 @@ export async function fetchSkill(relayUrl, opts = {}) {
     const markdown = await res.text();
     return { markdown };
 }
+/**
+ * GET the relay's MCP-flavoured guide (the conceptual core + MCP tool-call
+ * invocation grammar) from GET /skills/pane/MCP.md, or just its version from
+ * GET /skills/pane/MCP.md/version. This is what an MCP consumer should read
+ * (not the CLI-grammar SKILL.md). Served unauthenticated, same as the skill.
+ */
+export async function fetchMcpGuide(relayUrl, opts = {}) {
+    const base = relayUrl.replace(/\/$/, "");
+    if (opts.version) {
+        const res = await fetchOrThrow(base + "/skills/pane/MCP.md/version");
+        let body;
+        try {
+            body = await res.json();
+        }
+        catch {
+            body = null;
+        }
+        const version = body !== null &&
+            typeof body === "object" &&
+            typeof body.version === "string"
+            ? body.version
+            : "0.0.0";
+        return { version };
+    }
+    const res = await fetchOrThrow(base + "/skills/pane/MCP.md");
+    const markdown = await res.text();
+    return { markdown };
+}
 async function fetchOrThrow(url) {
     let res;
     try {

package/dist/tools.d.ts

@@ -0,0 +1,51 @@
+import { z } from "zod";
+import type { ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
+import type { PaneClient } from "@paneui/core";
+/**
+ * A structured MCP tool result (text content + optional error flag). The
+ * index signature keeps it structurally assignable to the SDK's
+ * CallToolResult (which carries an open `[x: string]: unknown`).
+ */
+export interface ToolResult {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError?: boolean;
+    [key: string]: unknown;
+}
+/**
+ * Host-supplied capabilities for the handful of tools that aren't pure
+ * PaneClient wrappers. The stdio server leaves this undefined and the
+ * handlers fall back to the CLI config store + a network skill fetch; the
+ * relay's HTTP MCP server injects an `env` so those tools resolve against the
+ * relay itself (no CLI config on disk, no self-HTTP loop for the skill).
+ *
+ * This is the single seam that keeps the TOOLS array transport-agnostic and
+ * reusable by BOTH servers — every other tool is already a thin PaneClient
+ * call and needs nothing from the host.
+ */
+export interface ToolEnv {
+    /** `agent` action=whoami — describe the active identity (no secrets). */
+    describeConfig?: () => Record<string, unknown>;
+    /** `agent` action=logout — clear the locally-saved profile. */
+    clearProfile?: () => Record<string, unknown>;
+    /**
+     * `get_skill` — return the MCP-flavoured skill markdown + its version. The
+     * relay passes its in-process renderer; the stdio server fetches it over
+     * HTTP from the relay's /skills route.
+     */
+    getSkill?: (versionOnly: boolean) => Promise<{
+        markdown?: string;
+        version?: string;
+    }>;
+}
+/** One registered tool: name, human/LLM description, Zod input shape, handler. */
+export interface ToolDef {
+    name: string;
+    description: string;
+    inputSchema: z.ZodRawShape;
+    annotations: ToolAnnotations;
+    handler: (client: PaneClient, args: Record<string, unknown>, env?: ToolEnv) => Promise<ToolResult>;
+}
+export declare const TOOLS: ToolDef[];

package/dist/tools.js

@@ -265,7 +265,32 @@ const upgradePaneShape = {
         .int()
         .positive()
         .optional()
-        .describe("Target version of the SAME template. Defaults to the template head's latest version."),
+        .describe("Target version of the SAME template. Defaults to the template head's latest version. Mutually exclusive with `html`."),
+    html: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("INLINE EDIT: the new HTML. The relay appends a fresh template version with this HTML and re-pins the pane to it in one call — editing an INLINE pane's HTML in place (same id/URL), no separate version step needed. Any schema you don't pass below is inherited from the pane's current version, so to change only the HTML pass only `html`. Inline panes only; a named/reusable template must go through the `template` tool (action: version) + `template_version`. Mutually exclusive with `template_version`."),
+    template_type: z
+        .string()
+        .optional()
+        .describe("Type for the `html` version. Default: html-inline."),
+    event_schema: z
+        .unknown()
+        .optional()
+        .describe("New event schema for the `html` version. Omit to inherit."),
+    input_schema: z
+        .record(z.string(), z.unknown())
+        .optional()
+        .describe("New input schema for the `html` version. Omit to inherit."),
+    record_schema: z
+        .unknown()
+        .optional()
+        .describe("New record schema for the `html` version. Omit to inherit."),
+    template_record_schema: z
+        .unknown()
+        .optional()
+        .describe("New template-level record schema for the `html` version. Omit to inherit."),
     force: z
         .boolean()
         .optional()
@@ -683,8 +708,15 @@ const getSkillShape = {
 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 (pass `name` + `html`) OR reuse a saved template (pass `template_id`). The relay hosts it and returns a URL. ALWAYS give the returned 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, wizards. If the page captures input it emits events back to you (poll them with get_events) or mutates record collections (the record tools). Returns { pane_id, url, urls, title, expires_at }.",
+        description: "Hand the human a rich interactive UI by URL and (optionally) get structured data back. Build the UI as inline HTML (pass `name` + `html`) OR reuse a saved template (pass `template_id`). The relay hosts it and returns a URL. ALWAYS give the returned 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, wizards. If the page captures input it emits events back to you (poll them with get_events) or mutates record collections (the record tools). BEFORE authoring: call get_skill for the events-vs-records decision + schema grammar, and the `taste` tool (action: get) for the human's house style — both shape the HTML you write. Returns { pane_id, url, urls, title, expires_at }.",
         inputSchema: createPaneShape,
+        annotations: {
+            title: "Create Pane",
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
         handler: async (client, args) => {
             try {
                 const hasTemplateId = str(args, "template_id") !== undefined;
@@ -756,6 +788,11 @@ export const TOOLS = [
         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,
+        annotations: {
+            title: "Get Pane State",
+            readOnlyHint: true,
+            openWorldHint: false,
+        },
         handler: async (client, args) => {
             try {
                 return jsonResult(await client.getPane(String(args["pane_id"])));
@@ -769,6 +806,11 @@ export const TOOLS = [
         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,
+        annotations: {
+            title: "Get Events",
+            readOnlyHint: true,
+            openWorldHint: false,
+        },
         handler: async (client, args) => {
             try {
                 const page = await client.getEvents(String(args["pane_id"]), {
@@ -786,6 +828,13 @@ export const TOOLS = [
         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,
+        annotations: {
+            title: "Send to Pane",
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
         handler: async (client, args) => {
             try {
                 const res = await client.sendEvent(String(args["pane_id"]), {
@@ -804,6 +853,13 @@ export const TOOLS = [
         name: "update_pane",
         description: "Edit instance-level fields on a LIVE pane in place (PATCH) without minting a new one — the pane keeps its id, URL, event log, and template pin. Settable: ttl_seconds OR expires_at (mutually exclusive), title, preamble, input_data (replaced wholesale + revalidated), metadata, tags, icon_emoji / icon_attachment_id (or clear_* to drop the override). Pass at least one field. Returns the full new pane state + an updated_fields array. To swap the HTML/schemas, use upgrade_pane instead.",
         inputSchema: updatePaneShape,
+        annotations: {
+            title: "Update Pane",
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
         handler: async (client, args) => {
             try {
                 const body = {};
@@ -853,13 +909,36 @@ export const TOOLS = [
     },
     {
         name: "upgrade_pane",
-        description: "Re-pin a LIVE pane to another version of its SAME template (POST /upgrade) — swap the HTML (design) and event/input/record schemas in place. The human keeps the same URL; no new pane is created. Use after appending a new template version with the `template` tool (action: version). By default a strict schema-compat gate refuses an upgrade that would narrow the schema (returns schema_incompatible_upgrade + details.breaks); pass force:true to apply anyway. Returns { pane_id, template_version, upgraded, breaks, compat }.",
+        description: "Re-pin a LIVE pane to swap its HTML (design) + event/input/record schemas in place — same URL, no new pane. Two ways: (1) pass `html` to EDIT AN INLINE PANE'S HTML in one call — the relay appends a fresh version with that HTML and re-pins (schemas you omit are inherited from the current version, so to change only the HTML pass only `html`); inline panes only. (2) pass `template_version` to re-pin to a version you already appended with the `template` tool (action: version) — for named/reusable templates. By default a strict schema-compat gate refuses an upgrade that would narrow the schema (returns schema_incompatible_upgrade + details.breaks); pass force:true to apply anyway. Returns { pane_id, template_version, upgraded, breaks, compat }.",
         inputSchema: upgradePaneShape,
+        annotations: {
+            title: "Upgrade Pane",
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
         handler: async (client, args) => {
             try {
                 const opts = {};
                 if (args["template_version"] !== undefined)
                     opts.template_version = args["template_version"];
+                if (args["html"] !== undefined) {
+                    const tpl = {
+                        source: String(args["html"]),
+                    };
+                    if (args["template_type"] !== undefined)
+                        tpl.type = String(args["template_type"]);
+                    if (args["event_schema"] !== undefined)
+                        tpl.event_schema = args["event_schema"];
+                    if (args["input_schema"] !== undefined)
+                        tpl.input_schema = args["input_schema"];
+                    if (args["record_schema"] !== undefined)
+                        tpl.record_schema = args["record_schema"];
+                    if (args["template_record_schema"] !== undefined)
+                        tpl.template_record_schema = args["template_record_schema"];
+                    opts.template = tpl;
+                }
                 if (args["force"])
                     opts.compat = "force";
                 return jsonResult(await client.upgradePane(String(args["pane_id"]), opts));
@@ -873,6 +952,11 @@ export const TOOLS = [
         name: "list_panes",
         description: "Enumerate YOUR agent's panes (newest first). Use it to find a pane_id you lost, audit what's open, or get a cursor for pagination. No secrets in the response (participant tokens are unrecoverable — mint a fresh URL with the participant tool). Filter by status (open|closed|all) or template_id. Returns { items, next_cursor }.",
         inputSchema: listPanesShape,
+        annotations: {
+            title: "List Panes",
+            readOnlyHint: true,
+            openWorldHint: false,
+        },
         handler: async (client, args) => {
             try {
                 const opts = {};
@@ -895,6 +979,13 @@ export const TOOLS = [
         name: "delete_pane",
         description: "Close/delete a pane (idempotent — an already-closed pane still succeeds). The human's URL stops working. To merely edit a pane keep it alive with update_pane; to recover a soft-deleted pane use the trash tool (action: restore).",
         inputSchema: deletePaneShape,
+        annotations: {
+            title: "Delete Pane",
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
         handler: async (client, args) => {
             try {
                 await client.deletePane(String(args["pane_id"]));
@@ -910,6 +1001,11 @@ export const TOOLS = [
         name: "list_records",
         description: "List rows in a pane's mutable record collection (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. This also doubles as the POLL/watch for records (no streaming in MCP): pass the prior next_since to fetch only newer/changed rows. include_tombstones:true surfaces deletions. Returns { records, next_since, has_more }.",
         inputSchema: listRecordsShape,
+        annotations: {
+            title: "List Records",
+            readOnlyHint: true,
+            openWorldHint: false,
+        },
         handler: async (client, args) => {
             try {
                 const out = await client.listRecords(String(args["pane_id"]), String(args["collection"]), {
@@ -934,6 +1030,11 @@ export const TOOLS = [
         name: "get_record",
         description: "Fetch a single record row by its key from a pane collection (scans the collection — fine for a one-off lookup, not a hot loop). Returns { record } or an isError record_not_found.",
         inputSchema: getRecordShape,
+        annotations: {
+            title: "Get Record",
+            readOnlyHint: true,
+            openWorldHint: false,
+        },
         handler: async (client, args) => {
             try {
                 const row = await client.getRecord(String(args["pane_id"]), String(args["collection"]), String(args["record_key"]));
@@ -949,8 +1050,15 @@ export const TOOLS = [
     },
     {
         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 }.",
+        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. If you're still designing the pane, call get_skill first for the records-vs-events decision and the x-pane-collections schema grammar. Returns { record, deduped }.",
         inputSchema: upsertRecordShape,
+        annotations: {
+            title: "Upsert Record",
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
         handler: async (client, args) => {
             try {
                 const body = {
@@ -969,6 +1077,13 @@ export const TOOLS = [
         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,
+        annotations: {
+            title: "Update Record",
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
         handler: async (client, args) => {
             try {
                 const body = {
@@ -987,6 +1102,13 @@ export const TOOLS = [
         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). Pass if_match for an optimistic-locked delete. Returns { deleted: true }.",
         inputSchema: deleteRecordShape,
+        annotations: {
+            title: "Delete Record",
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
         handler: async (client, args) => {
             try {
                 await client.deleteRecord(String(args["pane_id"]), String(args["collection"]), String(args["record_key"]), args["if_match"] !== undefined
@@ -1003,6 +1125,13 @@ export const TOOLS = [
         name: "delete_record_collection",
         description: "Drop a WHOLE per-pane record collection at once: every row plus the collection row itself. Use this to reset or remove a collection (todo list, comment thread, board) rather than deleting rows one by one with delete_record. Owner-only and destructive, so it requires confirm:true. Collection names are immutable, so to rename a collection drop the old one and write under the new name. Returns { deleted: true, collection }.",
         inputSchema: deleteRecordCollectionShape,
+        annotations: {
+            title: "Delete Record Collection",
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
         handler: async (client, args) => {
             try {
                 if (args["confirm"] !== true) {
@@ -1021,6 +1150,17 @@ export const TOOLS = [
         name: "template",
         description: "Manage reusable, versioned UI templates (author once, instance many times via create_pane's template_id). ONE tool with an `action` enum: create | version | update | search | list | show | get_version | delete | publish | unpublish | search_public | set_icon. Required fields per action are documented on the `action` parameter. A template is HTML + an event schema (+ optional input/record/template-record schemas); a pane is one use of one version of it.",
         inputSchema: templateShape,
+        // Consolidated action-enum tool: read sub-actions (search/list/show/
+        // get_version/search_public) coexist with mutating ones (create/version/
+        // update/delete/publish/...). The hint reflects the most-privileged action
+        // (delete is destructive), so readOnlyHint:false + destructiveHint:true.
+        annotations: {
+            title: "Manage Templates",
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
         handler: async (client, args) => {
             const action = String(args["action"]);
             try {
@@ -1163,6 +1303,15 @@ export const TOOLS = [
         name: "template_records",
         description: "CRUD for TEMPLATE-level record collections — owner-curated content anchored to a template head and visible to every pane derived from any of its versions (vs per-pane records, which are the discrete record tools). ONE tool with an `action` enum: list | get | upsert | update | delete | delete_collection. The template version must declare the collection via template_record_schema (set it with the `template` tool first).",
         inputSchema: templateRecordsShape,
+        // Consolidated tool: read actions (list/get) + mutating ones (upsert/
+        // update/delete/delete_collection). Hint reflects the destructive action.
+        annotations: {
+            title: "Manage Template Records",
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
         handler: async (client, args) => {
             const action = String(args["action"]);
             const templateId = String(args["template_id"]);
@@ -1241,6 +1390,15 @@ export const TOOLS = [
         name: "participant",
         description: "Manage a pane's participant URLs (recovery + leak-containment). ONE tool with an `action` enum: list | new | revoke. Use `new` when you lost the original URL (the plaintext token is returned ONCE — save it). Token URLs are stored hashed and cannot be recovered.",
         inputSchema: participantShape,
+        // Consolidated tool: read action (list) + mutating ones (new mints a URL,
+        // revoke invalidates one). Hint reflects the destructive action.
+        annotations: {
+            title: "Manage Participants",
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
         handler: async (client, args) => {
             const action = String(args["action"]);
             const paneId = String(args["pane_id"]);
@@ -1272,6 +1430,16 @@ export const TOOLS = [
         name: "share",
         description: "Identity sharing on a pane (layered on top of participant tokens). ONE tool with an `action` enum: list (access_mode + grants) | invite (a human by email, role participant|viewer) | set_access (the /p access mode: invite_only|link|public) | revoke (one grant by id). Token (/s/<token>) links are independent of access_mode and keep working.",
         inputSchema: shareShape,
+        // Consolidated tool: read action (list) + mutating/side-effecting ones
+        // (invite emails a human, set_access, revoke). openWorld:true because
+        // invite delivers a message to an external recipient.
+        annotations: {
+            title: "Manage Pane Sharing",
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
         handler: async (client, args) => {
             const action = String(args["action"]);
             const paneId = String(args["pane_id"]);
@@ -1315,6 +1483,17 @@ export const TOOLS = [
         name: "attachments",
         description: "Binary attachments (images, PDFs, audio, video) referenced from event payloads / input_data via `format: pane-attachment-id`. ONE tool with an `action` enum: upload | download | show | list | delete | mint_token | revoke_token | list_tokens. upload reads an ABSOLUTE file_path; download writes to an ABSOLUTE out_path (or returns base64). Scope an upload to agent (default, reusable), pane, or template. mint_token returns a /b/<token> capability URL (ONCE) a browser can GET without your API key.",
         inputSchema: attachmentsShape,
+        // Consolidated tool: read actions (download/show/list/list_tokens) +
+        // mutating ones (upload/delete/mint_token/revoke_token). openWorld:true
+        // because upload pushes bytes into external relay storage + mint_token
+        // produces a publicly-fetchable capability URL.
+        annotations: {
+            title: "Manage Attachments",
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
         handler: async (client, args) => {
             const action = String(args["action"]);
             try {
@@ -1414,6 +1593,15 @@ export const TOOLS = [
         name: "taste",
         description: "Read / write / clear the agent's freeform UI taste notes (a small markdown document of presentation preferences learned from human feedback — 'denser layout', 'no rounded corners'). ONE tool with an `action` enum: get | set | clear. Call `get` BEFORE generating a pane so prior feedback shapes the output; `set` does a whole-document replace (not append). Keep entries about UI/presentation only.",
         inputSchema: tasteShape,
+        // Consolidated tool: read action (get) + mutating ones (set replaces the
+        // doc, clear deletes it). Hint reflects the destructive action.
+        annotations: {
+            title: "Manage UI Taste Notes",
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
         handler: async (client, args) => {
             const action = String(args["action"]);
             try {
@@ -1442,6 +1630,16 @@ export const TOOLS = [
         name: "key",
         description: "Inspect or revoke the calling agent's API key. ONE tool with an `action` enum: list (key info — agent_id, key_prefix, timestamps) | revoke (self-destruct the agent's OWN key; it stops working immediately and is irreversible — pass confirm:true). The relay scopes keys to the caller, so both act only on your own key.",
         inputSchema: keyShape,
+        // Consolidated tool: read action (list) + a mutating one (revoke
+        // self-destructs the agent's own key). Hint reflects the destructive
+        // action.
+        annotations: {
+            title: "Manage API Key",
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
         handler: async (client, args) => {
             const action = String(args["action"]);
             try {
@@ -1469,6 +1667,16 @@ export const TOOLS = [
         name: "trash",
         description: "Manage soft-deleted panes + templates. ONE tool with an `action` enum: list | restore (pane id) | restore_template (template id|slug) | purge (pane id) | purge_template (template id|slug). purge bypasses the retention window and is permanent. Soft-deleted rows live in trash until the sweeper reclaims them.",
         inputSchema: trashShape,
+        // Consolidated tool: read action (list) + mutating ones (restore/purge/
+        // restore_template/purge_template; purge is permanent). Hint reflects the
+        // destructive action.
+        annotations: {
+            title: "Manage Trash",
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
         handler: async (client, args) => {
             const action = String(args["action"]);
             try {
@@ -1508,6 +1716,15 @@ export const TOOLS = [
         name: "feedback",
         description: "Send or list feedback to the relay operator. ONE tool with an `action` enum: create (a bug|feature|note with a message, optional pane_id) | list (the agent's own submissions, newest first, paginated by before).",
         inputSchema: feedbackShape,
+        // Consolidated tool: read action (list) + a side-effecting one (create
+        // submits feedback to the relay operator). Hint reflects the write action.
+        annotations: {
+            title: "Manage Feedback",
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
         handler: async (client, args) => {
             const action = String(args["action"]);
             try {
@@ -1545,19 +1762,31 @@ export const TOOLS = [
         name: "agent",
         description: "Agent identity + binding. ONE tool with an `action` enum: whoami (the resolved relay URL, active profile, whether a key is configured — no network, no secrets) | claim (bind this agent to a human via a one-shot claim code from their Settings UI; one-way) | logout (clear the locally-saved key/profile; does NOT revoke it on the relay — use the `key` tool's revoke for that).",
         inputSchema: agentShape,
-        handler: async (client, args) => {
+        // Consolidated tool: read action (whoami) + mutating ones (claim binds
+        // this agent to a human, logout clears the local profile). Hint reflects
+        // the state-changing action.
+        annotations: {
+            title: "Manage Agent Identity",
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+        handler: async (client, args, env) => {
             const action = String(args["action"]);
             try {
                 switch (action) {
                     case "whoami":
-                        // No network — pure local config introspection.
-                        return jsonResult(describeActiveConfig());
+                        // No network — pure local config introspection. The relay's HTTP
+                        // server injects describeConfig (active token's agent identity);
+                        // the stdio server reads the CLI config store.
+                        return jsonResult((env?.describeConfig ?? describeActiveConfig)());
                     case "claim":
                         if (str(args, "code") === undefined)
                             return invalidArgs("claim requires `code`");
                         return jsonResult(await client.claimAgent(String(args["code"])));
                     case "logout":
-                        return jsonResult(clearActiveProfile());
+                        return jsonResult((env?.clearProfile ?? clearActiveProfile)());
                     default:
                         return invalidArgs(`unknown agent action '${action}'`);
                 }
@@ -1571,6 +1800,11 @@ export const TOOLS = [
         name: "run_query",
         description: "Run read-only SQL over YOUR scoped data (panes, records, events) — the relay scopes every row to panes you own. Use it to summarise activity, find panes/records by content, or build a report. Tables + columns and JSON projection operators are documented on the `sql` parameter. Default output is { columns, rows, truncated, scope, elapsed_ms } (format:json); csv/tsv/table render the rows as text. Capped at 10,000 rows; 10s timeout.",
         inputSchema: runQueryShape,
+        annotations: {
+            title: "Run SQL Query",
+            readOnlyHint: true,
+            openWorldHint: false,
+        },
         handler: async (client, args) => {
             try {
                 const result = await client.query(String(args["sql"]), str(args, "pane_id") !== undefined
@@ -1592,10 +1826,26 @@ export const TOOLS = [
         name: "get_skill",
         description: "Fetch the relay's auto-updating SKILL.md (the full Pane usage guide) — UNAUTHENTICATED, needs no API key. Call this to self-teach the Pane workflow (events vs records, schema grammars, the poll loop) before driving the other tools. Pass version_only:true to get just the relay's skill version string (to check if a cached copy is stale).",
         inputSchema: getSkillShape,
-        handler: async (_client, args) => {
+        annotations: {
+            title: "Get Skill Guide",
+            readOnlyHint: true,
+            openWorldHint: false,
+        },
+        handler: async (_client, args, env) => {
             try {
+                const versionOnly = args["version_only"] === true;
+                // The relay's HTTP server injects getSkill so MCP consumers receive
+                // the MCP-invocation rendering of the skill (tool-call grammar, not
+                // `pane ...` commands) straight from the relay image. The stdio server
+                // falls back to fetching SKILL.md over HTTP from its configured relay.
+                if (env?.getSkill) {
+                    const { markdown, version } = await env.getSkill(versionOnly);
+                    if (versionOnly)
+                        return jsonResult({ version });
+                    return textResult(markdown ?? "");
+                }
                 const url = resolveUrl();
-                if (args["version_only"]) {
+                if (versionOnly) {
                     const { version } = await fetchSkill(url, { version: true });
                     return jsonResult({ version });
                 }

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare const VERSION = "0.0.25";

package/dist/version.js

@@ -1,3 +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.23";
+export const VERSION = "0.0.25";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paneui/mcp",
-  "version": "0.0.23",
+  "version": "0.0.25",
   "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",
@@ -30,6 +30,12 @@
   "bin": {
     "pane-mcp": "dist/index.js"
   },
+  "exports": {
+    "./tools": "./dist/tools.js",
+    "./guide": "./dist/guide.js",
+    "./capabilities": "./dist/capabilities.js",
+    "./server": "./dist/server.js"
+  },
   "files": [
     "dist",
     "server.json",
@@ -44,7 +50,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.20.0",
-    "@paneui/core": "^0.0.23",
+    "@paneui/core": "^0.0.25",
     "zod": "^4.4.3"
   },
   "devDependencies": {

package/server.json

@@ -3,7 +3,7 @@
   "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.23",
+  "version": "0.0.25",
   "repository": {
     "url": "https://github.com/aerolalit/paneui",
     "source": "github"
@@ -13,7 +13,7 @@
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@paneui/mcp",
-      "version": "0.0.23",
+      "version": "0.0.25",
       "transport": {
         "type": "stdio"
       },