@webmcp-auto-ui/ui 2.5.27 → 2.5.29

package/src/widgets/notebook/recipe-browser.ts

@@ -0,0 +1,350 @@
+// @ts-nocheck
+// ---------------------------------------------------------------------------
+// recipe-browser — vanilla widget renderer
+// Interactive browser: search, filter by kind/tags, layout toggle, preview, pick/download.
+// ---------------------------------------------------------------------------
+
+// NOTE: this widget lives in @webmcp-auto-ui/ui but imports runtime helpers from
+// @webmcp-auto-ui/agent, creating an ESM cycle ui <-> agent. The cycle is safe
+// because these imports are only used inside functions (no top-level eval).
+import { filterRecipes, sortRecipes, recipeToDownloadBlob, recipeToMarkdown } from '@webmcp-auto-ui/agent';
+import type { Recipe } from '@webmcp-auto-ui/agent';
+
+export interface RecipeBrowserData {
+  recipes: Recipe[];
+  filters?: { tags?: string[]; kind?: 'webmcp' | 'mcp' | 'all'; q?: string };
+  layout?: 'list' | 'grid';
+  onPick?: (recipe: Recipe) => void;
+}
+
+const STYLE_ID = 'rb-recipe-browser-styles';
+
+function injectStyles(): void {
+  if (document.getElementById(STYLE_ID)) return;
+  const s = document.createElement('style');
+  s.id = STYLE_ID;
+  s.textContent = `
+    .recipe-browser-root {
+      display: flex; flex-direction: column; gap: 10px;
+      font-family: var(--font-sans, system-ui, sans-serif);
+      color: var(--color-text1, #111);
+      background: var(--color-surface, #fff);
+      border: 1px solid var(--color-border, #e4e4e7);
+      border-radius: 10px;
+      padding: 14px;
+      min-height: 360px;
+      box-sizing: border-box;
+    }
+    .recipe-browser-root * { box-sizing: border-box; }
+    .rb-head {
+      display: flex; flex-wrap: wrap; gap: 8px; align-items: center;
+      padding-bottom: 10px;
+      border-bottom: 1px solid var(--color-border, #e4e4e7);
+    }
+    .rb-search {
+      flex: 1 1 200px; min-width: 160px;
+      padding: 7px 10px; font-size: 13px;
+      border: 1px solid var(--color-border, #e4e4e7);
+      border-radius: 6px;
+      background: var(--color-surface, #fff);
+      color: var(--color-text1, #111);
+      outline: none;
+    }
+    .rb-search:focus { border-color: var(--color-accent, #6a55ff); }
+    .rb-select {
+      padding: 7px 10px; font-size: 12px;
+      border: 1px solid var(--color-border, #e4e4e7);
+      border-radius: 6px;
+      background: var(--color-surface, #fff);
+      color: var(--color-text1, #111);
+    }
+    .rb-layout-toggle { display: inline-flex; border: 1px solid var(--color-border, #e4e4e7); border-radius: 6px; overflow: hidden; }
+    .rb-layout-btn {
+      background: var(--color-surface, #fff); color: var(--color-text2, #666);
+      border: 0; padding: 7px 10px; font-size: 12px; cursor: pointer;
+    }
+    .rb-layout-btn.rb-on { background: var(--color-accent, #6a55ff); color: #fff; }
+    .rb-body {
+      display: grid; grid-template-columns: minmax(220px, 320px) 1fr;
+      gap: 12px; min-height: 280px;
+    }
+    .rb-body[data-layout="grid"] { grid-template-columns: 1fr; }
+    .rb-body[data-layout="grid"] .rb-list { display: grid; grid-template-columns: repeat(auto-fill, minmax(200px, 1fr)); gap: 8px; max-height: none; }
+    .rb-list {
+      display: flex; flex-direction: column; gap: 6px;
+      max-height: 420px; overflow-y: auto;
+      padding-right: 4px;
+    }
+    .rb-item {
+      padding: 9px 11px; border-radius: 8px;
+      background: var(--color-surface2, #f4f4f5);
+      border: 1px solid transparent;
+      cursor: pointer; transition: background .12s, border-color .12s;
+    }
+    .rb-item:hover { background: var(--color-surface3, #eeeef0); }
+    .rb-item.rb-selected { border-color: var(--color-accent, #6a55ff); background: var(--color-surface3, #eeeef0); }
+    .rb-item-name { font-weight: 600; font-size: 13px; margin-bottom: 3px; }
+    .rb-item-desc { font-size: 11.5px; color: var(--color-text2, #666); margin-bottom: 6px; line-height: 1.35; }
+    .rb-item-foot { display: flex; flex-wrap: wrap; gap: 4px; align-items: center; }
+    .rb-chip {
+      font-size: 10.5px; font-family: var(--font-mono, monospace);
+      padding: 1px 6px; border-radius: 999px;
+      background: var(--color-surface, #fff);
+      border: 1px solid var(--color-border, #e4e4e7);
+      color: var(--color-text2, #666);
+    }
+    .rb-chip.rb-srv { background: var(--color-accent, #6a55ff); color: #fff; border-color: transparent; }
+    .rb-preview {
+      display: flex; flex-direction: column; min-height: 260px;
+      border: 1px solid var(--color-border, #e4e4e7);
+      border-radius: 8px; overflow: hidden;
+      background: var(--color-surface, #fff);
+    }
+    .rb-preview-head {
+      display: flex; align-items: center; gap: 8px;
+      padding: 9px 12px;
+      border-bottom: 1px solid var(--color-border, #e4e4e7);
+      background: var(--color-surface2, #f4f4f5);
+    }
+    .rb-preview-title { flex: 1; font-weight: 600; font-size: 13px; }
+    .rb-preview-body {
+      flex: 1; padding: 12px; overflow-y: auto;
+      font-size: 12.5px; line-height: 1.5;
+      max-height: 420px;
+    }
+    .rb-preview-body pre {
+      background: var(--color-surface2, #f4f4f5);
+      padding: 10px; border-radius: 6px;
+      overflow-x: auto;
+      font-family: var(--font-mono, monospace);
+      font-size: 11.5px;
+      white-space: pre-wrap;
+      margin: 0;
+    }
+    .rb-btn {
+      background: var(--color-surface2, #f4f4f5);
+      border: 1px solid var(--color-border, #e4e4e7);
+      border-radius: 6px; padding: 6px 12px; font-size: 12px;
+      color: var(--color-text1, #111);
+      cursor: pointer;
+    }
+    .rb-btn:hover { background: var(--color-surface3, #eeeef0); }
+    .rb-btn-primary { background: var(--color-accent, #6a55ff); color: #fff; border-color: transparent; }
+    .rb-btn-primary:hover { filter: brightness(1.08); }
+    .rb-empty { padding: 24px; text-align: center; color: var(--color-text2, #666); font-size: 12px; }
+    .rb-placeholder { color: var(--color-text2, #666); font-size: 12px; padding: 24px; text-align: center; }
+  `;
+  document.head.appendChild(s);
+}
+
+function escapeHtml(s: unknown): string {
+  return String(s ?? '').replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}
+
+function detectKind(r: Recipe): 'webmcp' | 'mcp' {
+  // Heuristic: if frontmatter 'servers' present and non-empty, treat as MCP-connected.
+  const srv = (r as any).server ?? (r as any).serverName;
+  if (typeof srv === 'string' && srv && srv !== 'webmcp') return 'mcp';
+  return 'webmcp';
+}
+
+function recipeTags(r: Recipe): string[] {
+  const out: string[] = [];
+  if (Array.isArray(r.servers)) out.push(...r.servers);
+  if (Array.isArray(r.components_used)) out.push(...r.components_used.slice(0, 3));
+  return out;
+}
+
+function serverLabel(r: Recipe): string {
+  const srv = (r as any).server ?? (r as any).serverName;
+  if (typeof srv === 'string' && srv) return srv;
+  if (Array.isArray(r.servers) && r.servers.length) return r.servers[0];
+  return 'webmcp';
+}
+
+function simpleMarkdown(body: string): string {
+  // Minimal safe rendering: escape + preserve paragraphs + wrap fences in <pre>.
+  const escaped = escapeHtml(body);
+  // Code fences
+  const withFences = escaped.replace(/```([a-zA-Z0-9_-]*)\n([\s\S]*?)```/g, (_m, _lang, code) => {
+    return `<pre><code>${code}</code></pre>`;
+  });
+  // Paragraphs (double newlines)
+  const paras = withFences.split(/\n{2,}/).map((p) => {
+    if (p.startsWith('<pre>')) return p;
+    return `<p>${p.replace(/\n/g, '<br/>')}</p>`;
+  });
+  return paras.join('\n');
+}
+
+export function render(container: HTMLElement, data: RecipeBrowserData): () => void {
+  injectStyles();
+
+  const all: Recipe[] = Array.isArray(data?.recipes) ? data.recipes : [];
+  if (!all.length) {
+    container.innerHTML = '<div class="recipe-browser-root"><div class="rb-empty">No recipes available.</div></div>';
+    return () => { container.innerHTML = ''; };
+  }
+
+  const initialFilters = data?.filters ?? {};
+  let q = initialFilters.q ?? '';
+  let kind: 'all' | 'webmcp' | 'mcp' = initialFilters.kind ?? 'all';
+  let layout: 'list' | 'grid' = data?.layout === 'grid' ? 'grid' : 'list';
+  let selectedId: string | null = null;
+
+  const root = document.createElement('div');
+  root.className = 'recipe-browser-root';
+  root.innerHTML = `
+    <div class="rb-head">
+      <input type="search" class="rb-search" placeholder="Search recipes..." value="${escapeHtml(q)}" />
+      <select class="rb-select" data-role="kind">
+        <option value="all"${kind === 'all' ? ' selected' : ''}>All kinds</option>
+        <option value="webmcp"${kind === 'webmcp' ? ' selected' : ''}>WebMCP</option>
+        <option value="mcp"${kind === 'mcp' ? ' selected' : ''}>MCP</option>
+      </select>
+      <div class="rb-layout-toggle">
+        <button type="button" class="rb-layout-btn${layout === 'list' ? ' rb-on' : ''}" data-layout="list">list</button>
+        <button type="button" class="rb-layout-btn${layout === 'grid' ? ' rb-on' : ''}" data-layout="grid">grid</button>
+      </div>
+    </div>
+    <div class="rb-body" data-layout="${layout}">
+      <div class="rb-list" data-role="list"></div>
+      <div class="rb-preview" data-role="preview">
+        <div class="rb-placeholder">Select a recipe to preview.</div>
+      </div>
+    </div>
+  `;
+  container.innerHTML = '';
+  container.appendChild(root);
+
+  const searchEl = root.querySelector('.rb-search') as HTMLInputElement;
+  const kindEl = root.querySelector('[data-role="kind"]') as HTMLSelectElement;
+  const bodyEl = root.querySelector('.rb-body') as HTMLElement;
+  const listEl = root.querySelector('[data-role="list"]') as HTMLElement;
+  const previewEl = root.querySelector('[data-role="preview"]') as HTMLElement;
+  const layoutBtns = Array.from(root.querySelectorAll('.rb-layout-btn')) as HTMLButtonElement[];
+
+  const listeners: Array<{ el: EventTarget; type: string; fn: EventListener }> = [];
+  function on<T extends EventTarget>(el: T, type: string, fn: EventListener) {
+    el.addEventListener(type, fn);
+    listeners.push({ el, type, fn });
+  }
+
+  function applyFilters(): Recipe[] {
+    let filtered = all.slice();
+    if (kind !== 'all') filtered = filtered.filter((r) => detectKind(r) === kind);
+    // Tag filter (optional): keep only recipes whose tags intersect data.filters.tags
+    const wantTags = initialFilters.tags;
+    if (Array.isArray(wantTags) && wantTags.length) {
+      const wanted = new Set(wantTags.map((t) => String(t).toLowerCase()));
+      filtered = filtered.filter((r) => recipeTags(r).some((t) => wanted.has(String(t).toLowerCase())));
+    }
+    filtered = filterRecipes(filtered, q);
+    return sortRecipes(filtered);
+  }
+
+  function renderList() {
+    const items = applyFilters();
+    listEl.innerHTML = '';
+    if (!items.length) {
+      const empty = document.createElement('div');
+      empty.className = 'rb-empty';
+      empty.textContent = 'No matches.';
+      listEl.appendChild(empty);
+      return;
+    }
+    for (const r of items) {
+      const id = r.id ?? r.name ?? '';
+      const node = document.createElement('div');
+      node.className = 'rb-item' + (id === selectedId ? ' rb-selected' : '');
+      const tags = recipeTags(r).slice(0, 4);
+      node.innerHTML = `
+        <div class="rb-item-name">${escapeHtml(r.name || 'Untitled')}</div>
+        <div class="rb-item-desc">${escapeHtml(r.description || 'No description')}</div>
+        <div class="rb-item-foot">
+          <span class="rb-chip rb-srv">${escapeHtml(serverLabel(r))}</span>
+          ${tags.map((t) => `<span class="rb-chip">${escapeHtml(t)}</span>`).join('')}
+        </div>
+      `;
+      on(node, 'click', () => {
+        selectedId = id;
+        renderList();
+        renderPreview(r);
+      });
+      listEl.appendChild(node);
+    }
+  }
+
+  function renderPreview(r: Recipe) {
+    const md = typeof r.body === 'string' && r.body.trim()
+      ? r.body
+      : (() => { try { return recipeToMarkdown(r as any); } catch { return ''; } })();
+    previewEl.innerHTML = `
+      <div class="rb-preview-head">
+        <span class="rb-preview-title">${escapeHtml(r.name || 'Untitled')}</span>
+        <button type="button" class="rb-btn" data-act="download">Download .md</button>
+        <button type="button" class="rb-btn rb-btn-primary" data-act="pick">Pick</button>
+      </div>
+      <div class="rb-preview-body">${md ? simpleMarkdown(md) : '<div class="rb-placeholder">No body.</div>'}</div>
+    `;
+
+    const pickBtn = previewEl.querySelector('[data-act="pick"]') as HTMLButtonElement | null;
+    const dlBtn = previewEl.querySelector('[data-act="download"]') as HTMLButtonElement | null;
+
+    if (pickBtn) {
+      on(pickBtn, 'click', () => {
+        if (typeof data.onPick === 'function') {
+          data.onPick(r);
+        } else {
+          container.dispatchEvent(new CustomEvent('widget:interact', {
+            bubbles: true,
+            detail: { action: 'pick', payload: r },
+          }));
+        }
+      });
+    }
+    if (dlBtn) {
+      on(dlBtn, 'click', () => {
+        try {
+          const { blob, filename } = recipeToDownloadBlob(r as any);
+          triggerDownload(blob, filename);
+        } catch {
+          // fallback
+          const body = typeof r.body === 'string' ? r.body : '';
+          const blob = new Blob([body], { type: 'text/markdown' });
+          const filename = (r.name || r.id || 'recipe').replace(/[^a-z0-9_.-]/gi, '-').toLowerCase() + '.md';
+          triggerDownload(blob, filename);
+        }
+      });
+    }
+  }
+
+  function triggerDownload(blob: Blob, filename: string) {
+    const url = URL.createObjectURL(blob);
+    const a = document.createElement('a');
+    a.href = url;
+    a.download = filename;
+    document.body.appendChild(a);
+    a.click();
+    a.remove();
+    setTimeout(() => URL.revokeObjectURL(url), 500);
+  }
+
+  on(searchEl, 'input', () => { q = searchEl.value; renderList(); });
+  on(kindEl, 'change', () => { kind = (kindEl.value as any); renderList(); });
+  for (const btn of layoutBtns) {
+    on(btn, 'click', () => {
+      layout = (btn.dataset.layout as 'list' | 'grid') || 'list';
+      bodyEl.setAttribute('data-layout', layout);
+      layoutBtns.forEach((b) => b.classList.toggle('rb-on', b === btn));
+    });
+  }
+
+  renderList();
+
+  return () => {
+    for (const { el, type, fn } of listeners) el.removeEventListener(type, fn);
+    listeners.length = 0;
+    container.innerHTML = '';
+  };
+}

package/src/widgets/notebook/recipes/notebook.md

@@ -0,0 +1,124 @@
+---
+widget: notebook
+description: Publication-ready notebook with serif prose and inline cells, all drag-and-droppable in a single ordered flow. Inspired by Observable — cells can be prose paragraphs, sql queries, or js charts, mixed freely in any order to build an article-like narrative.
+schema:
+  type: object
+  properties:
+    id:
+      type: string
+    title:
+      type: string
+    mode:
+      type: string
+      enum: [edit, view]
+    kicker:
+      type: string
+      description: Small uppercase label above the title (e.g. "analysis", "memo", "brief"). Editable inline. Defaults to "untitled".
+    hideLiveToggle:
+      type: boolean
+      default: false
+      description: When true, hides the "Live data" toggle in the header (useful for embedded/host-controlled contexts where the autoRun flag is managed externally).
+    cells:
+      type: array
+      description: Mixed flow of prose and code cells. All share the same ordering and can be reordered together.
+      items:
+        type: object
+        required: [type, content]
+        properties:
+          type:
+            type: string
+            enum: [md, sql, js]
+            description: md = prose paragraph (markdown rendered + sanitized), sql = query cell with table output, js = code cell with chart output
+          content:
+            type: string
+          hideSource:
+            type: boolean
+          hideResult:
+            type: boolean
+---
+
+## When to use
+
+Use `notebook` when the notebook is meant to be published or shared as a finished artifact:
+- Research memos with code appendices visible on demand
+- Blog-style writeups mixing narrative and runnable code
+- Final deliverables where prose leads and code supports
+
+The distinguishing feature: prose paragraphs and code cells share a single ordered list, both drag-and-droppable with the same handle. This lets users rearrange the story freely without thinking about "sections".
+
+## How to use
+
+1. **Start with prose-first seed content** and intersperse code cells:
+   ```
+   widget_display({name: "notebook", params: {
+     title: "Q3 observations",
+     kicker: "memo",
+     cells: [
+       {type: "md", content: "This memo covers the highlights of last quarter."},
+       {type: "md", content: "We first look at revenue, then at churn."},
+       {type: "sql", content: "select * from source limit 10"},
+       {type: "md", content: "The table above suggests..."},
+       {type: "js", content: "// render a chart"}
+     ]
+   }})
+   ```
+
+2. **Use prose paragraphs as transitions** between code blocks. The layout emphasizes reading flow.
+
+3. **Code cells render their result in the editorial style**:
+   - SQL cells show a minimal mono-spaced table (live data from the connected MCP server's `*_query_sql` tool).
+   - JS cells run in an isolated Web Worker with upstream named outputs in scope.
+
+4. **Reorder cells freely** — the user can drag a prose paragraph from the bottom to the top, or swap a chart and its introduction, all via the same handle.
+
+## Notes
+
+- The serif font (EB Garamond, with Georgia fallback) applies only to prose content inside this widget — it signals "publication" the moment the user sees it.
+- The **kicker** above the title ("analysis", "memo", "internal") is editable inline — click to rename. Keep it short.
+- Prose cells are rendered via an HTML-sanitizing markdown pipeline: markdown syntax is resolved, unsafe tags are stripped (XSS closed), `<mark>` and other editorial tags are preserved.
+- The footer exposes a single `share` button.
+- Run / Stop controls are at the left of each code cell's header, same as the other notebook layouts.
+- Unlike the other widgets, `notebook` does not separate prose and code into different flows — they are the same flow in one list.
+
+## Left pane — resources from connected servers
+
+A collapsible **left pane** (bookmark-bar styling, collapsed by default) lists recipes and tools exposed by connected MCP data servers. Clicking any recipe opens a viewer modal; fenced code blocks expose a `↳ inject` button that drops the snippet into the article flow as a new cell.
+
+Two toolbar buttons flank this pane:
+
+- **`+ md`** — 3-tab modal (New / File / URL) to insert a prose paragraph from scratch, a local `.md` file, or a URL.
+- **`+ recipe`** — 3-tab modal (Browser / File / URL) to import a recipe from a connected server, a local `.recipe.md` file, or a URL.
+
+## Share
+
+The `share` button in the footer offers **four formats**:
+
+- **Hyperskill link** — copies both the canonical Hyperskill URL and a short domain-scoped URL (`?n=<token>`). The read-only public viewer lives at `nb.hyperskills.net`.
+- **Markdown** — downloads a `.md` file.
+- **PNG** — snapshots the rendered article.
+- **JSON** — exports full widget state.
+
+## Integration with connected data servers
+
+An editorial piece earns its weight when the prose is anchored to real material. If a MCP **data** server is connected (say `tricoteuses` or `metmuseum`), the agent should — before composing the memo — go and see what the server has to offer:
+
+1. Call `{server}_list_recipes()` or `{server}_search_recipes(query)` to find recipes that speak to the subject at hand.
+2. Call `{server}_list_tools()` to survey the available tables and endpoints.
+3. For each recipe or table worth citing, seed one cell that lets the reader touch the evidence — a modest SQL `SELECT ... LIMIT 10`, a `run_script` call, or a prose paragraph that introduces the figure to come. Let prose and code alternate; the editorial flow is built for exactly that.
+4. Pass the server metadata through the `servers:` param so the footer's share affordance, the left pane, and the connect modal reflect the provenance of the piece:
+
+   ```ts
+   widget_display({
+     name: 'notebook',
+     params: {
+       title: '...',
+       kicker: 'memo',
+       cells: [...],
+       servers: [{ name: 'tricoteuses', url: 'https://...', kind: 'data' }]
+     }
+   })
+   ```
+
+When no data server is connected, seed a prose-first skeleton that stakes out the argument and gently invites the reader to connect an MCP server so the memo can take on flesh.
+
+**Filter rule**: only MCP *data* servers (`kind: 'data'`) belong in `servers:`. WebMCP UI servers like `autoui` are kept out — they hold no queryable material and have no place in the editorial masthead.

package/src/widgets/notebook/resource-extractor.ts

@@ -0,0 +1,162 @@
+// @ts-nocheck
+// ---------------------------------------------------------------------------
+// Extract notebook cells from imported resources (recipe body, tool def, md).
+// Consumed by import-modals.ts and left-pane.ts.
+// ---------------------------------------------------------------------------
+
+import { parseBody } from '@webmcp-auto-ui/sdk';
+import { uid, defaultCellContent } from './shared.js';
+import type { NotebookCell, CellType } from './shared.js';
+
+// Languages we map directly to a code cell type
+const LANG_TO_TYPE: Record<string, CellType> = {
+  sql: 'sql',
+  psql: 'sql',
+  mysql: 'sql',
+  sqlite: 'sql',
+  js: 'js',
+  javascript: 'js',
+  ts: 'js',       // treat TS as js source (stripped at runtime is user's concern)
+  typescript: 'js',
+  node: 'js',
+};
+
+/** Languages that map to 'js' but use a syntax superset that will fail at
+ *  runtime (interfaces, type annotations, `as` casts, etc.). We log a warning
+ *  whenever such a fence is mapped so the user gets a hint. */
+const TS_LIKE_LANGS = new Set(['ts', 'typescript']);
+
+export function fenceLangToCellType(lang: string): CellType | null {
+  const key = (lang || '').toLowerCase().trim();
+  if (TS_LIKE_LANGS.has(key)) {
+    try {
+      console.warn(
+        `[notebook] Fence language "${key}" mapped to JS — TS-specific syntax (interfaces, type annotations, "as" casts) will fail at runtime.`
+      );
+    } catch { /* ignore */ }
+  }
+  return LANG_TO_TYPE[key] ?? null;
+}
+
+/**
+ * Build a notebook cell from a single fence (lang + content).
+ * Unsupported languages fall back to a markdown cell wrapping the fence.
+ */
+export function extractCellFromFence(lang: string, content: string): NotebookCell {
+  const cellType = fenceLangToCellType(lang);
+  if (cellType) {
+    return { id: uid(), type: cellType, content: content.trim(), hideSource: false, hideResult: false };
+  }
+  // Detect pseudo-code MCP tool calls like: query_sql({sql: "..."})
+  // Only attempted when the fence language is unknown/text (cellType === null).
+  const trimmed = content.trim();
+  const callMatch = trimmed.match(/^([A-Za-z_][\w]*)\s*\(\s*(\{[\s\S]*\})\s*\)\s*;?\s*$/);
+  if (callMatch) {
+    const name = callMatch[1];
+    const argsRaw = callMatch[2];
+    if (name === 'query_sql') {
+      const sql = extractSqlFromLooseObject(argsRaw);
+      if (sql != null) {
+        return { id: uid(), type: 'sql', content: sql.trim(), hideSource: false, hideResult: false };
+      }
+    }
+    return {
+      id: uid(),
+      type: 'js',
+      content: `// MCP tool call: ${name}\nawait callTool('${name}', ${argsRaw});`,
+      hideSource: false,
+      hideResult: false,
+    };
+  }
+  // Preserve the original fence in markdown so users see it verbatim
+  return {
+    id: uid(),
+    type: 'md',
+    content: '```' + (lang || '') + '\n' + content.trim() + '\n```',
+    hideSource: false,
+    hideResult: false,
+  };
+}
+
+/**
+ * Best-effort extraction of the `sql` property value from a loose JS-object literal
+ * (unquoted keys, possibly single-quoted strings). Returns null if no sql key found.
+ */
+function extractSqlFromLooseObject(argsRaw: string): string | null {
+  // Essai 1: JSON.parse direct (cheap, rarely works for loose objects)
+  try {
+    const parsed = JSON.parse(argsRaw);
+    if (parsed && typeof parsed === 'object' && typeof parsed.sql === 'string') {
+      return parsed.sql;
+    }
+  } catch {
+    /* fallthrough */
+  }
+  // Essai 2: regex extract sql: "..." (double-quoted)
+  const dq = argsRaw.match(/sql\s*:\s*"([\s\S]*?)"/);
+  if (dq) return dq[1];
+  // Essai 3: regex extract sql: '...' (single-quoted)
+  const sq = argsRaw.match(/sql\s*:\s*'([\s\S]*?)'/);
+  if (sq) return sq[1];
+  return null;
+}
+
+/**
+ * Extract cells from a full recipe body (markdown with frontmatter already stripped).
+ * Returns: a single intro markdown cell (first prose block) + one cell per fenced block.
+ */
+export function extractCellsFromRecipe(body: string, opts?: { title?: string; description?: string }): NotebookCell[] {
+  const cells: NotebookCell[] = [];
+  if (opts?.title || opts?.description) {
+    const md = ['# ' + (opts?.title ?? 'Imported recipe'), opts?.description ?? ''].filter(Boolean).join('\n\n');
+    cells.push({ id: uid(), type: 'md', content: md, hideSource: false, hideResult: false });
+  }
+  const segments = parseBody(body || '');
+  for (const seg of segments) {
+    if (seg.type === 'markdown') {
+      cells.push({ id: uid(), type: 'md', content: seg.content.trim(), hideSource: false, hideResult: false });
+    } else {
+      cells.push(extractCellFromFence(seg.lang || 'text', seg.content));
+    }
+  }
+  return cells;
+}
+
+/**
+ * Produce 2 cells for a tool: md (name + description + schema) + a starter call cell.
+ */
+export interface McpToolLike {
+  name: string;
+  description?: string;
+  inputSchema?: unknown;
+  schema?: unknown;
+  serverName?: string;
+}
+
+export function extractCellsFromTool(tool: McpToolLike): NotebookCell[] {
+  const schema = tool.inputSchema ?? tool.schema ?? {};
+  const schemaStr = JSON.stringify(schema, null, 2);
+  const mdParts: string[] = [
+    `## ${tool.name}${tool.serverName ? ` · \`${tool.serverName}\`` : ''}`,
+  ];
+  if (tool.description) mdParts.push(tool.description);
+  mdParts.push('```json\n' + schemaStr + '\n```');
+
+  const isSql = /(_|^)query_sql$|(^|_)sql_query$/i.test(tool.name);
+  const cellType: CellType = isSql ? 'sql' : 'js';
+  const template = isSql
+    ? '-- call via MCP bridge: ' + tool.name + '\n' + defaultCellContent('sql')
+    : '// call via MCP bridge\nawait callTool(' + JSON.stringify(tool.name) + ', {});';
+
+  return [
+    { id: uid(), type: 'md', content: mdParts.join('\n\n'), hideSource: false, hideResult: false },
+    { id: uid(), type: cellType, content: template, hideSource: false, hideResult: false },
+  ];
+}
+
+/**
+ * Wrap raw markdown content as a single md cell.
+ */
+export function extractCellFromMarkdown(md: string): NotebookCell {
+  return { id: uid(), type: 'md', content: (md || '').trim(), hideSource: false, hideResult: false };
+}