@paneui/mcp 0.0.19 → 0.0.20

package/README.md

@@ -94,21 +94,62 @@ Config precedence mirrors the CLI: env vars win over the saved profile, which fa
 
 ## 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.
+This server has **full parity with the [`pane` CLI](https://www.npmjs.com/package/@paneui/cli)** — every capability the CLI exposes is reachable here.
+
+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); to watch a record collection, re-call `list_records` with the prior `since`. Each tool description spells out the pattern for the model.
+
+To keep the tool list compact (a flat 50+ tools would bloat client context and degrade selection), **hot-path nouns stay discrete tools** while **multi-verb management nouns collapse into one tool each with a required `action` enum**.
+
+### Hot-path (discrete) tools
 
 | 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.** |
+| `create_pane` | Create a pane — inline HTML (`name`+`html`) **or** reuse a saved template (`template_id`). Optional event/input/record schema, participants, tags, icon, callback, `context_key`. Returns `{ pane_id, url, urls, title, 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…). |
+| `update_pane` | Edit a live pane in place (ttl/title/preamble/input_data/metadata/tags/icon). |
+| `upgrade_pane` | Re-pin a live pane to another version of its template (swap HTML+schemas, same URL). |
+| `list_panes` | Enumerate your panes (filter by status/template_id; paginated). |
+| `delete_pane` | Close/delete a pane. |
+| `list_records` | List rows in a pane's mutable record collection (also the records poll/watch). |
+| `get_record` | Fetch one record row by key. |
 | `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). |
 
+### Consolidated tools (one tool, required `action`)
+
+| Tool | Actions |
+| --- | --- |
+| `template` | `create` · `version` · `update` · `search` · `list` · `show` · `get_version` · `delete` · `publish` · `unpublish` · `search_public` · `set_icon` |
+| `template_records` | `list` · `get` · `upsert` · `update` · `delete` · `delete_collection` |
+| `participant` | `list` · `new` · `revoke` |
+| `share` | `list` · `invite` · `set_access` · `revoke` |
+| `attachments` | `upload` · `download` · `show` · `list` · `delete` · `mint_token` · `revoke_token` · `list_tokens` |
+| `taste` | `get` · `set` · `clear` |
+| `key` | `list` · `revoke` |
+| `trash` | `list` · `restore` · `restore_template` · `purge` · `purge_template` |
+| `feedback` | `create` · `list` |
+| `agent` | `whoami` · `claim` · `logout` |
+
+### Single-purpose tools
+
+| Tool | What it does |
+| --- | --- |
+| `run_query` | Read-only SQL over your scoped panes/records/events (`format`: json/csv/tsv/table). |
+| `get_skill` | Fetch the relay's auto-updating `SKILL.md` (unauthenticated) to self-teach the workflow. |
+
+**Attachments** take/return file paths: `upload` reads an absolute `file_path`; `download` writes to an absolute `out_path` (or returns base64 when omitted).
+
 **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.
 
+### Not exposed (and why)
+
+- The CLI's `config show` is replaced by `agent`→`whoami` (resolved relay URL + active profile + whether a key is set; no secrets).
+- `agent register` isn't a tool — the server auto-registers on first use and shares the CLI's key store; `agent`→`claim` binds it to a human afterward.
+- `demo` (the interactive 60-second terminal tour) and the CLI self-updater are terminal/CLI concerns with no agent use; omitted.
+
 ## Typical flow
 
 1. `create_pane` with your HTML + an `event_schema` declaring the events the page emits → returns a `url`.

package/dist/config.js

@@ -118,6 +118,29 @@ function upsertProfile(name, patch, setCurrent) {
     writeFileSync(path, serialize(store), { mode: 0o600 });
     chmodSync(path, 0o600);
 }
+/**
+ * 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 function clearActiveProfile() {
+    const store = readStore();
+    const path = storePath();
+    const name = store.currentProfile;
+    if (name === undefined || store.profiles[name] === undefined) {
+        return { cleared: true, profile: null, path };
+    }
+    delete store.profiles[name];
+    store.currentProfile = undefined;
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, serialize(store), { mode: 0o600 });
+    chmodSync(path, 0o600);
+    return { cleared: true, profile: name, path };
+}
 /** Resolve the relay URL using the same precedence as the CLI. */
 export function resolveUrl() {
     const store = readStore();
@@ -127,6 +150,38 @@ export function resolveUrl() {
     const url = process.env.PANE_URL ?? active?.url ?? DEFAULT_RELAY_URL;
     return url.replace(/\/$/, "");
 }
+/**
+ * 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 function describeActiveConfig() {
+    const store = readStore();
+    const url = resolveUrl();
+    const profile = store.currentProfile ?? null;
+    let source = "none";
+    if ((process.env.PANE_API_KEY && process.env.PANE_API_KEY !== "") ||
+        (process.env.PANE_TOKEN && process.env.PANE_TOKEN !== "")) {
+        source = "env";
+    }
+    else {
+        const active = store.currentProfile
+            ? store.profiles[store.currentProfile]
+            : undefined;
+        if (active?.apiKey && active.apiKey !== "")
+            source = "profile";
+    }
+    return {
+        url,
+        profile,
+        api_key_present: source !== "none",
+        api_key_source: source,
+        store_path: storePath(),
+    };
+}
 /** Resolve the API key (env → PANE_TOKEN alias → active profile). */
 function resolveApiKey() {
     const store = readStore();

package/dist/index.js

@@ -65,8 +65,11 @@ Environment:
   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.
+Tools exposed (full CLI parity): create_pane, get_pane_state, get_events,
+send_to_pane, update_pane, upgrade_pane, list_panes, delete_pane,
+list_records, get_record, upsert_record, update_record, delete_record,
+template, template_records, participant, share, attachments, taste, key,
+trash, feedback, agent, run_query, get_skill.
 
 See https://github.com/aerolalit/paneui for docs.
 `;

package/dist/skill.js

@@ -0,0 +1,54 @@
+// Fetch the relay's auto-updating SKILL.md over plain HTTP.
+//
+// Mirrors `pane skill show|version` (packages/cli/src/commands/skill.ts): the
+// relay serves its skill at GET /skills/pane/SKILL.md and the version at GET
+// /skills/pane/SKILL.md/version. Both routes are UNAUTHENTICATED — no API key
+// needed — so an MCP client can self-teach the Pane workflow before (or without)
+// provisioning a key. We don't go through PaneClient here precisely because no
+// auth is required and the skill routes are exempt from the version-skew check.
+import { VERSION } from "./version.js";
+/**
+ * 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 async function fetchSkill(relayUrl, opts = {}) {
+    const base = relayUrl.replace(/\/$/, "");
+    if (opts.version) {
+        const target = base + "/skills/pane/SKILL.md/version";
+        const res = await fetchOrThrow(target);
+        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 target = base + "/skills/pane/SKILL.md";
+    const res = await fetchOrThrow(target);
+    const markdown = await res.text();
+    return { markdown };
+}
+async function fetchOrThrow(url) {
+    let res;
+    try {
+        res = await fetch(url, { headers: { "x-pane-cli-version": VERSION } });
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        throw new Error(`could not reach ${url}: ${msg}`, { cause: e });
+    }
+    if (!res.ok) {
+        const body = await res.text().catch(() => "");
+        throw new Error(`relay returned ${res.status} for ${url}${body ? ": " + body.slice(0, 200) : ""}`);
+    }
+    return res;
+}