@webmcp-auto-ui/sdk 2.5.36 → 2.5.37

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webmcp-auto-ui/sdk",
-  "version": "2.5.36",
+  "version": "2.5.37",
   "description": "Skills CRUD, HyperSkill format, Svelte 5 stores",
   "license": "AGPL-3.0-or-later",
   "type": "module",
@@ -27,6 +27,7 @@
     "build": "svelte-package -i src"
   },
   "dependencies": {
+    "@webmcp-auto-ui/core": "file:../core",
     "hyperskills": "^0.1.4"
   },
   "peerDependencies": {
@@ -34,7 +35,6 @@
   },
   "devDependencies": {
     "@sveltejs/package": "^2.3.0",
-    "@webmcp-auto-ui/core": "file:../core",
     "svelte": "^5.0.0",
     "svelte-check": "^4.0.0",
     "typescript": "^5.0.0"

package/src/index.ts

@@ -83,9 +83,9 @@ export {
 } from './skills/registry.js';
 export type { Skill, SkillBlock } from './skills/registry.js';
 
-// MCP demo servers
-export { MCP_DEMO_SERVERS } from './mcp-demo-servers.js';
-export type { McpDemoServer } from './mcp-demo-servers.js';
+// Remote MCP server registry
+export { REMOTE_MCP_REGISTRY } from './remote-mcp-registry.js';
+export type { RemoteMcpRegistryEntry } from './remote-mcp-registry.js';
 
 // Canvas store — browser-only (Svelte 5 runes), import directly from src:
 // import { canvas } from '@webmcp-auto-ui/sdk/canvas'

package/src/recipes/runner.ts

@@ -35,27 +35,180 @@ const AsyncFunction = Object.getPrototypeOf(async function () {}).constructor as
 interface RunnerCtx {
   log: (msg: string) => void;
   start: number;
+  widgets: Array<{ name: string; params: Record<string, unknown> }>;
 }
 
 function makeCtx(): RunnerCtx & { logs: RunLog[] } {
   const start = performance.now();
   const logs: RunLog[] = [];
+  const widgets: Array<{ name: string; params: Record<string, unknown> }> = [];
   return {
     start,
     logs,
+    widgets,
     log(msg: string) {
       logs.push({ t: Math.round(performance.now() - start), msg });
     },
   };
 }
 
-async function runJsLike(code: string, ctx: RunnerCtx): Promise<unknown> {
+/**
+ * Build the `call(toolName, args)` helper exposed to recipe JS sandboxes.
+ * Resolves a tool by name across all connected MCP servers, calls it, and
+ * returns the parsed text payload (JSON if possible) or the raw result.
+ */
+function makeCallHelper(multiClient: McpMultiClient | undefined, ctx: RunnerCtx) {
+  return async (toolName: string, args: Record<string, unknown> = {}) => {
+    const found = findToolOnAnyServer(multiClient, toolName);
+    if (!found || !multiClient) {
+      throw new Error(`No MCP server exposes tool "${toolName}"`);
+    }
+    ctx.log(`call(${toolName})`);
+    const res = await multiClient.callToolOn(found.url, toolName, args);
+    // MCP-spec: prefer structuredContent (typed payload) over content[].text.
+    const sc = (res as { structuredContent?: unknown }).structuredContent;
+    if (sc != null && typeof sc === 'object') return sc;
+    const textPart = res?.content?.find((c: { type: string }) => c.type === 'text') as
+      | { text?: string }
+      | undefined;
+    if (textPart?.text) {
+      try { return JSON.parse(textPart.text); } catch { return textPart.text; }
+    }
+    return res;
+  };
+}
+
+/**
+ * Build the `widget(name, params)` helper. Captures each call into the run
+ * context so the host can mount them stacked in the run panel.
+ */
+function makeWidgetHelper(ctx: RunnerCtx) {
+  return async (name: string, params: Record<string, unknown> = {}) => {
+    ctx.log(`widget(${name})`);
+    ctx.widgets.push({ name, params });
+    return { name, params };
+  };
+}
+
+/** Find the index of the matching close bracket for `code[startIdx]`. */
+function matchBracket(code: string, startIdx: number): number {
+  const open = code[startIdx];
+  const close = open === '[' ? ']' : open === '{' ? '}' : open === '(' ? ')' : '';
+  if (!close) return -1;
+  let depth = 0;
+  for (let i = startIdx; i < code.length; i++) {
+    if (code[i] === open) depth++;
+    else if (code[i] === close) { depth--; if (depth === 0) return i; }
+  }
+  return -1;
+}
+
+/** Extract identifier names from a destructuring pattern body (without
+ *  the outer brackets). Handles `[a, b]`, `{a, b}`, `{a: alias}`,
+ *  `[a, ...rest]`, default values `a = 1`, top-level commas only. */
+function namesFromPattern(content: string): string[] {
+  const parts: string[] = [];
+  let depth = 0, start = 0;
+  for (let i = 0; i < content.length; i++) {
+    const c = content[i];
+    if (c === '{' || c === '[' || c === '(') depth++;
+    else if (c === '}' || c === ']' || c === ')') depth--;
+    else if (c === ',' && depth === 0) { parts.push(content.slice(start, i)); start = i + 1; }
+  }
+  parts.push(content.slice(start));
+  const names: string[] = [];
+  for (let part of parts) {
+    part = part.trim();
+    if (!part) continue;
+    if (part.startsWith('...')) part = part.slice(3).trim();
+    // Strip default value `name = expr`
+    const eqIdx = part.indexOf('=');
+    if (eqIdx >= 0) part = part.slice(0, eqIdx).trim();
+    // Object rename `key: alias` → take alias side
+    const colonIdx = part.indexOf(':');
+    if (colonIdx >= 0) {
+      const alias = part.slice(colonIdx + 1).trim();
+      // alias may itself be a nested pattern — recurse
+      if (alias.startsWith('{') || alias.startsWith('[')) {
+        const end = matchBracket(alias, 0);
+        if (end > 0) names.push(...namesFromPattern(alias.slice(1, end)));
+      } else if (/^[a-zA-Z_$][\w$]*$/.test(alias)) {
+        names.push(alias);
+      }
+      continue;
+    }
+    if (/^[a-zA-Z_$][\w$]*$/.test(part)) names.push(part);
+  }
+  return names;
+}
+
+/** Match top-level `const|let|var name`, `function name`, `class name`,
+ *  plus destructuring `const [a, b] = ...` and `const { a, b } = ...`.
+ *  Skips matches that occur inside a `{}` block (e.g. callback bodies) by
+ *  counting unbalanced braces before the match position, on a sanitized copy
+ *  of the code where strings and comments are blanked out. */
+function extractTopLevelDecls(code: string): string[] {
+  const stripped = code
+    .replace(/\/\*[\s\S]*?\*\//g, '')
+    .replace(/\/\/[^\n]*/g, '')
+    .replace(/'(?:\\.|[^'\\])*'/g, "''")
+    .replace(/"(?:\\.|[^"\\])*"/g, '""')
+    .replace(/`(?:\\.|[^`\\])*`/g, '``');
+  const out = new Set<string>();
+  // Identifier-form decls (existing behavior)
+  const reId = /^[\t ]*(?:const|let|var|function|class)\s+([a-zA-Z_$][\w$]*)/gm;
+  let m: RegExpExecArray | null;
+  while ((m = reId.exec(stripped)) !== null) {
+    const before = stripped.slice(0, m.index);
+    const opens = (before.match(/\{/g) ?? []).length;
+    const closes = (before.match(/\}/g) ?? []).length;
+    if (opens === closes) out.add(m[1]);
+  }
+  // Destructuring: const|let|var followed by `[` or `{`
+  const reDestr = /^[\t ]*(?:const|let|var)\s+([\[\{])/gm;
+  while ((m = reDestr.exec(stripped)) !== null) {
+    const before = stripped.slice(0, m.index);
+    const opens = (before.match(/\{/g) ?? []).length;
+    const closes = (before.match(/\}/g) ?? []).length;
+    if (opens !== closes) continue;
+    const bracketStart = m.index + m[0].length - 1;
+    const end = matchBracket(stripped, bracketStart);
+    if (end < 0) continue;
+    const inner = stripped.slice(bracketStart + 1, end);
+    for (const n of namesFromPattern(inner)) out.add(n);
+  }
+  return Array.from(out);
+}
+
+async function runJsLike(
+  code: string,
+  ctx: RunnerCtx,
+  multiClient?: McpMultiClient,
+  scope?: Record<string, unknown>,
+): Promise<unknown> {
   // Wrap user code as the body of an async function that executes itself.
   // Users can use `await`, define vars, and return a final value.
-  const wrapped = `return (async () => {\n${code}\n})();`;
-  const fn = new AsyncFunction(wrapped);
+  // We inject `call` and `widget` helpers as parameters so recipes can
+  // invoke MCP tools and emit widgets without preamble.
+  // When a `scope` object is provided, top-level decls of prior blocks are
+  // re-injected as local consts (preamble), and the current block's top-level
+  // decls are written back at the end so the next block can read them.
+  const currentDecls = new Set(extractTopLevelDecls(code));
+  const priorKeys = scope
+    ? Object.keys(scope).filter((k) => /^[a-zA-Z_$][\w$]*$/.test(k) && !currentDecls.has(k))
+    : [];
+  const preamble = priorKeys.map((k) => `const ${k} = __scope__[${JSON.stringify(k)}];`).join('\n');
+  const writeback = scope
+    ? Array.from(currentDecls).map((k) => `__scope__[${JSON.stringify(k)}] = ${k};`).join('\n')
+    : '';
+  const wrapped = `return (async () => {\n${preamble}\n${code}\n${writeback}\n})();`;
+  const fn = new (AsyncFunction as unknown as new (
+    ...args: string[]
+  ) => (call: unknown, widget: unknown, __scope__: Record<string, unknown>) => Promise<unknown>)(
+    'call', 'widget', '__scope__', wrapped,
+  );
   ctx.log('dispatched (inline async)');
-  const out = await fn();
+  const out = await fn(makeCallHelper(multiClient, ctx), makeWidgetHelper(ctx), scope ?? {});
   ctx.log('resolved');
   return out;
 }
@@ -210,9 +363,71 @@ async function runViaMcp(
   return res;
 }
 
+function findBalancedBraces(text: string, fromIndex: number): string | null {
+  let depth = 0;
+  let start = -1;
+  for (let i = fromIndex; i < text.length; i++) {
+    const ch = text[i];
+    if (ch === '{') {
+      if (start === -1) start = i;
+      depth++;
+    } else if (ch === '}') {
+      depth--;
+      if (depth === 0 && start !== -1) return text.slice(start, i + 1);
+    }
+  }
+  return null;
+}
+
+/**
+ * Detect calls of the form `widget_display({name, params})` or
+ * `<server>_webmcp_widget_display({name, params})` in a recipe snippet.
+ * Recipes are bundled at build time from our own source, so `new Function`
+ * eval of the object literal is acceptable.
+ *
+ * Some recipes contain placeholders (`data: [...]`, `params: {...}`) that
+ * are not valid JS. We extract `name` via a separate regex so the widget can
+ * always render, even if the `params` literal cannot be eval'd; in that case
+ * we return `params: {}` rather than falling through to `run_script`.
+ */
+export function parseWidgetDisplayCall(
+  code: string,
+): { name: string; params: Record<string, unknown>; paramsParseFailed?: boolean } | null {
+  const m = /(?:^|\W)(?:[a-zA-Z_]\w*_)?widget_display\s*\(/m.exec(code);
+  if (!m) return null;
+  const objStart = code.indexOf('{', m.index + m[0].length - 1);
+  if (objStart === -1) return null;
+  const objLiteral = findBalancedBraces(code, objStart);
+  if (!objLiteral) return null;
+  // `name` is extracted independently so a broken `params` placeholder doesn't
+  // disqualify the call.
+  const nameMatch = /\bname\s*:\s*['"]([^'"]+)['"]/.exec(objLiteral);
+  if (!nameMatch) return null;
+  const name = nameMatch[1];
+  // Sanitize common placeholder forms before eval.
+  const sanitized = objLiteral
+    .replace(/\[\s*\.\.\.\s*\]/g, '[]')
+    .replace(/\{\s*\.\.\.\s*\}/g, '{}');
+  try {
+    const fn = new Function(`return (${sanitized});`);
+    const value = fn();
+    if (value && typeof value === 'object') {
+      const v = value as { params?: unknown };
+      if (v.params && typeof v.params === 'object') {
+        return { name, params: v.params as Record<string, unknown> };
+      }
+    }
+    return { name, params: {} };
+  } catch {
+    return { name, params: {}, paramsParseFailed: true };
+  }
+}
+
 /**
  * Run a snippet of code in a given language.
  *
+ * - `widget_display(...)` (in a `text`/untagged block): parsed locally and
+ *   surfaced via `result.widget` so the host can mount the widget live.
  * - JS / TS: executed inline via AsyncFunction (TS is NOT transpiled; code must
  *   be valid JS or the caller should keep type annotations minimal).
  * - SQL: dispatched to `query_sql` on any connected MCP server that exposes it.
@@ -222,15 +437,34 @@ async function runViaMcp(
 export async function runCode(
   code: string,
   lang: string,
-  multiClient?: McpMultiClient
+  multiClient?: McpMultiClient,
+  scope?: Record<string, unknown>,
 ): Promise<RunResult> {
   const ctx = makeCtx();
   const normLang = (lang || '').toLowerCase();
   const startedAt = ctx.start;
   try {
+    if (normLang === '' || normLang === 'text') {
+      const parsed = parseWidgetDisplayCall(code);
+      if (parsed) {
+        ctx.log(`widget_display: ${parsed.name}`);
+        if (parsed.paramsParseFailed) {
+          ctx.log('params placeholder — rendering with empty params');
+        }
+        const durationMs = Math.round(performance.now() - ctx.start);
+        return {
+          status: 'done',
+          startedAt,
+          durationMs,
+          tokens: estimateTokens(code),
+          widget: { name: parsed.name, params: parsed.params },
+          logs: ctx.logs,
+        };
+      }
+    }
     let output: unknown;
     if (JS_LANGS.has(normLang) || TS_LANGS.has(normLang) || normLang === '') {
-      output = await runJsLike(code, ctx);
+      output = await runJsLike(code, ctx, multiClient, scope);
     } else {
       output = await runViaMcp(code, normLang, multiClient, ctx);
     }
@@ -243,6 +477,7 @@ export async function runCode(
       tokens,
       output,
       logs: ctx.logs,
+      ...(ctx.widgets.length > 0 ? { widgets: ctx.widgets } : {}),
     };
   } catch (err) {
     const durationMs = Math.round(performance.now() - ctx.start);

package/src/recipes/types.ts

@@ -44,6 +44,18 @@ export interface RunResult {
   output?: unknown;
   error?: string;
   logs: RunLog[];
+  /**
+   * Set when the executed snippet was a `*widget_display({name, params})`
+   * call. The runner does not call the MCP tool in that case — instead it
+   * exposes the parsed widget to the host so it can be mounted live.
+   */
+  widget?: { name: string; params: Record<string, unknown> };
+  /**
+   * Set when the executed JS snippet called `widget(name, params)` one or
+   * more times via the in-sandbox helper. Each call is captured in order
+   * so the host can mount them stacked in the same run panel.
+   */
+  widgets?: Array<{ name: string; params: Record<string, unknown> }>;
 }
 
 export interface RunTab {

package/src/{mcp-demo-servers.ts → remote-mcp-registry.ts}

@@ -1,72 +1,71 @@
-// @webmcp-auto-ui/sdk — MCP demo servers registry
-// Lists all MCP servers available on the production VM (demos.hyperskills.net)
+// @webmcp-auto-ui/sdk — Remote MCP server registry
+// Single source of truth for the demo MCP servers exposed by the project.
+// Convention aligned with WEBMCP_SERVER_REGISTRY (packages/servers/src/registry.ts):
+// stable `id` as identity, `label` as display name.
 
-export interface McpDemoServer {
+export interface RemoteMcpRegistryEntry {
   id: string;
-  name: string;
+  label: string;
   description: string;
   url: string;
   tags?: string[];
+  /** Optional auth headers passed to McpClient on handshake (e.g. Bearer token). */
+  headers?: Record<string, string>;
 }
 
-/**
- * MCP demo servers available for webmcp-auto-ui demos.
- * tricoteuses has its own domain; others follow the pattern
- * https://demos.hyperskills.net/<id>/mcp
- */
-export const MCP_DEMO_SERVERS: McpDemoServer[] = [
+export const REMOTE_MCP_REGISTRY: RemoteMcpRegistryEntry[] = [
   {
     id: 'tricoteuses',
-    name: 'Tricoteuses',
+    label: 'Tricoteuses',
     description: 'French parliamentary database — amendments, votes, MPs, political groups.',
     url: 'https://mcp.code4code.eu/mcp',
     tags: ['politics', 'france', 'parliament', 'open-data'],
   },
   {
     id: 'hackernews',
-    name: 'Hacker News',
+    label: 'Hacker News',
     description: 'Hacker News stories, comments, and rankings.',
     url: 'https://demos.hyperskills.net/mcp-hackernews/mcp',
     tags: ['tech', 'news', 'community'],
   },
   {
     id: 'metmuseum',
-    name: 'Met Museum',
+    label: 'Met Museum',
     description: 'Metropolitan Museum of Art — collections, artworks, artists.',
     url: 'https://demos.hyperskills.net/mcp-metmuseum/mcp',
     tags: ['art', 'museum', 'culture', 'collections'],
   },
   {
     id: 'openmeteo',
-    name: 'Open-Meteo',
+    label: 'Open-Meteo',
     description: 'Weather data — forecasts, history, geolocation.',
     url: 'https://demos.hyperskills.net/mcp-openmeteo/mcp',
     tags: ['weather', 'climate', 'forecasts', 'geo'],
   },
   {
     id: 'wikipedia',
-    name: 'Wikipedia',
+    label: 'Wikipedia',
     description: 'Wikipedia search and content — articles, summaries, categories.',
     url: 'https://demos.hyperskills.net/mcp-wikipedia/mcp',
     tags: ['encyclopedia', 'knowledge', 'search'],
   },
   {
     id: 'inaturalist',
-    name: 'iNaturalist',
+    label: 'iNaturalist',
     description: 'Nature observations — species, taxa, biodiversity statistics.',
     url: 'https://demos.hyperskills.net/mcp-inaturalist/mcp',
     tags: ['nature', 'biodiversity', 'observations', 'citizen-science'],
   },
   {
     id: 'datagouv',
-    name: 'data.gouv.fr',
+    label: 'data.gouv.fr',
     description: 'French open data — public datasets, statistics, reference data.',
     url: 'https://demos.hyperskills.net/mcp-datagouv/mcp',
     tags: ['open-data', 'france', 'government', 'statistics'],
   },
   {
     id: 'nasa',
-    name: 'NASA',
+    label: 'NASA',
     description: 'NASA — space imagery, astronomical data, Mars rovers, asteroids.',
     url: 'https://demos.hyperskills.net/mcp-nasa/mcp',
   },

package/src/stores/canvas.svelte.ts

@@ -118,6 +118,8 @@ function createCanvas() {
     setDataServerMeta: canvasVanilla.setDataServerMeta.bind(canvasVanilla),
     setDataServerEnabled: canvasVanilla.setDataServerEnabled.bind(canvasVanilla),
     toggleDataServer: canvasVanilla.toggleDataServer.bind(canvasVanilla),
+    callTool: canvasVanilla.callTool.bind(canvasVanilla),
+    get multiClient() { return canvasVanilla.multiClient; },
 
     // HyperSkill
     buildSkillJSON: canvasVanilla.buildSkillJSON.bind(canvasVanilla),

package/src/stores/canvas.ts

@@ -5,23 +5,21 @@
  * Reactivity: subscribe(fn) / getSnapshot() pattern (useSyncExternalStore compatible).
  *
  * ---------------------------------------------------------------------------
- * Unified server model (2026-04-23 debloat)
+ * Unified server model
  * ---------------------------------------------------------------------------
- *
- * Historically this store had TWO parallel surfaces for MCP servers:
- *   - `mcpUrl` / `mcpName` / `mcpConnected` / `mcpConnecting` / `mcpTools`
- *     (flat, single-server or comma-joined multi) driven by legacy
- *     `setMcpConnected`/`setMcpConnecting`/`setMcpError` setters.
- *   - `dataServers: DataServer[]` (list, managed by MultiMcpBridge)
- *
- * They were the same concept. The legacy setters and the `primary` flag have
- * been removed; writes go through `addDataServer` / `setDataServerMeta` /
- * `setDataServerEnabled` / `addMcpServer` (url shorthand) exclusively. Flat
- * getters (`mcpConnected`, `mcpName`, `mcpUrl`, `mcpConnecting`, `mcpTools`)
- * remain as read-only derivations over the server list for UI back-compat.
+ * `dataServers: DataServer[]` is the single source of truth for MCP servers.
+ * The store owns an internal McpMultiClient and reconciles real connections
+ * with user intent (`enabled`) on every mutation. Writes go through
+ * `addDataServer` / `setDataServerMeta` / `setDataServerEnabled` /
+ * `addMcpServer` (url shorthand) exclusively. Flat getters
+ * (`mcpConnected`, `mcpName`, `mcpUrl`, `mcpConnecting`, `mcpTools`) remain
+ * as read-only derivations over the server list for UI back-compat.
  */
 
 import { encode, decode } from '../hyperskills.js';
+import { REMOTE_MCP_REGISTRY } from '../remote-mcp-registry.js';
+import { McpMultiClient } from '@webmcp-auto-ui/core';
+import type { McpTool } from '@webmcp-auto-ui/core';
 
 export type WidgetType =
   | 'stat' | 'kv' | 'list' | 'chart' | 'alert' | 'code' | 'text' | 'actions' | 'tags'
@@ -60,11 +58,15 @@ export interface McpToolInfo {
 
 /**
  * Single MCP server entry — the one true shape.
- * All servers are equal; there is no "primary" concept. The MultiMcpBridge
- * singleton reconciles connection state across all entries.
+ * All servers are equal; there is no "primary" concept. The store's internal
+ * sync reconciles real connection state with `enabled` on every mutation.
  */
 export interface DataServer {
-  name: string;         // user-chosen label
+  /** Stable identity key. Convention aligned with WEBMCP_SERVER_REGISTRY:
+   * registry id when matched (e.g. 'wikipedia'), or 'manual-<hash>' for
+   * arbitrary URLs. Replaces the previous URL-host derivation, which
+   * collided across servers sharing a host (e.g. demos.hyperskills.net). */
+  name: string;
   url: string;
   kind: 'data';         // legacy field, kept for schema stability
   enabled: boolean;     // user intent
@@ -73,8 +75,11 @@ export interface DataServer {
   tools?: McpToolInfo[];
   recipes?: { name: string; description?: string; body?: string }[];
   error?: string;
-  /** Real server name from MCP handshake (initResult.serverInfo.name, aliased).
-   * Canvas `.name` is URL-host; `.serverName` is what to display. */
+  /** Display label (registry label, or URL host for manual entries). */
+  label?: string;
+  /** Optional auth headers passed to the MCP transport on handshake. */
+  headers?: Record<string, string>;
+  /** Real server name from MCP handshake (initResult.serverInfo.name, aliased). */
   serverName?: string;
 }
 
@@ -103,6 +108,50 @@ type Listener = () => void;
 function uuid() { return 'w_' + Date.now().toString(36) + Math.random().toString(36).slice(2, 5); }
 function msgId() { return 'm_' + Date.now().toString(36) + Math.random().toString(36).slice(2, 5); }
 
+/** Deterministic short hash for synthesizing stable ids from URLs. */
+function stableHash(s: string): string {
+  let h = 5381;
+  for (let i = 0; i < s.length; i++) h = ((h << 5) + h + s.charCodeAt(i)) | 0;
+  return (h >>> 0).toString(36);
+}
+
+/** Extract `{ name, description?, body? }` items from an MCP tool response.
+ * Looks for a text chunk whose payload parses as JSON and contains either an
+ * array or an object with an `items`/`recipes` array. */
+function parseRecipesFromToolResponse(res: unknown): { name: string; description?: string; body?: string }[] | null {
+  if (!res || typeof res !== 'object') return null;
+  const content = (res as { content?: unknown }).content;
+  if (!Array.isArray(content)) return null;
+  for (const chunk of content) {
+    if (!chunk || typeof chunk !== 'object') continue;
+    const c = chunk as { type?: unknown; text?: unknown };
+    if (c.type !== 'text' || typeof c.text !== 'string') continue;
+    let parsed: unknown;
+    try { parsed = JSON.parse(c.text); } catch { continue; }
+    const candidate = Array.isArray(parsed)
+      ? parsed
+      : Array.isArray((parsed as { items?: unknown })?.items)
+        ? (parsed as { items: unknown[] }).items
+        : Array.isArray((parsed as { recipes?: unknown })?.recipes)
+          ? (parsed as { recipes: unknown[] }).recipes
+          : null;
+    if (!candidate) continue;
+    const out: { name: string; description?: string; body?: string }[] = [];
+    for (const it of candidate) {
+      if (!it || typeof it !== 'object') continue;
+      const o = it as { name?: unknown; id?: unknown; description?: unknown; body?: unknown };
+      const name = typeof o.name === 'string' ? o.name : typeof o.id === 'string' ? o.id : null;
+      if (!name) continue;
+      const entry: { name: string; description?: string; body?: string } = { name };
+      if (typeof o.description === 'string') entry.description = o.description;
+      if (typeof o.body === 'string') entry.body = o.body;
+      out.push(entry);
+    }
+    if (out.length > 0) return out;
+  }
+  return null;
+}
+
 const NAME_ALIAS: Record<string, string> = { 'moulineuse': 'Tricoteuses' };
 function aliasName(n: string): string { return NAME_ALIAS[n] ?? n; }
 
@@ -158,7 +207,7 @@ function createCanvasVanilla() {
   }
 
   // ── Server list actions (public, stable) ───────────────────────────────
-  function addDataServer(desc: { name: string; url: string }): DataServer {
+  function addDataServer(desc: { name: string; url: string; label?: string; headers?: Record<string, string> }): DataServer {
     const existing = _servers.find((s) => s.name === desc.name);
     if (existing) return existing;
     const srv: DataServer = {
@@ -167,6 +216,8 @@ function createCanvasVanilla() {
       kind: 'data',
       enabled: true,
       connected: false,
+      ...(desc.label ? { label: desc.label } : {}),
+      ...(desc.headers ? { headers: desc.headers } : {}),
     };
     _servers = [..._servers, srv];
     notify();
@@ -174,15 +225,21 @@ function createCanvasVanilla() {
   }
 
   /**
-   * Add a server by URL alone (derives name from the URL host). Returns the
-   * canvas name so callers can reference it later.
+   * Add a server by URL. Resolves identity from REMOTE_MCP_REGISTRY (by URL):
+   * matched entries get the registry `id` as canvas key and `label` as display;
+   * unmatched URLs get a stable synthetic id. Returns the canvas name (= id).
    */
-  function addMcpServer(url: string): string {
+  function addMcpServer(url: string, opts?: { headers?: Record<string, string> }): string {
     if (!url) return '';
-    let name: string;
-    try { name = new URL(url, 'http://local').host || url; }
-    catch { name = url; }
-    addDataServer({ name, url });
+    const reg = REMOTE_MCP_REGISTRY.find((e) => e.url === url);
+    const name = reg?.id ?? `manual-${stableHash(url)}`;
+    let label = reg?.label;
+    if (!label) {
+      try { label = new URL(url, 'http://local').host || url; }
+      catch { label = url; }
+    }
+    const headers = opts?.headers ?? reg?.headers;
+    addDataServer({ name, url, label, headers });
     setDataServerEnabled(name, true);
     return name;
   }
@@ -220,6 +277,96 @@ function createCanvasVanilla() {
     return setDataServerEnabled(name, !s.enabled);
   }
 
+  // ── Internal MCP transport + sync ──────────────────────────────────────
+  const multiClient = new McpMultiClient();
+  const inFlight = new Set<string>();
+
+  async function syncServer(name: string): Promise<void> {
+    const srv = _servers.find((s) => s.name === name);
+    if (!srv) return;
+    if (inFlight.has(name)) return;
+
+    const liveUrls = new Set(multiClient.listServers().map((s) => s.url));
+
+    if (srv.enabled && !srv.connected && !liveUrls.has(srv.url)) {
+      inFlight.add(name);
+      try {
+        const opts = srv.headers ? { headers: srv.headers } : undefined;
+        const { name: actualName, tools } = await multiClient.addServer(srv.url, opts);
+        let recipes: { name: string; description?: string; body?: string }[] = [];
+        if (tools.some((t: McpTool) => t.name === 'list_recipes')) {
+          try {
+            const res = await multiClient.callToolOn(srv.url, 'list_recipes', {});
+            recipes = parseRecipesFromToolResponse(res) ?? [];
+          } catch { /* no recipes */ }
+        }
+        // Prefetch full bodies in parallel so apps can render markdown / run
+        // code blocks without re-calling get_recipe per surface.
+        if (recipes.length && tools.some((t: McpTool) => t.name === 'get_recipe')) {
+          recipes = await Promise.all(recipes.map(async (r) => {
+            try {
+              const res = await multiClient.callToolOn(srv.url, 'get_recipe', { name: r.name, id: r.name });
+              const text = (res as { content?: { type?: string; text?: string }[] })
+                .content?.find((c) => c?.type === 'text')?.text;
+              if (!text) return r;
+              let body = text;
+              try {
+                const p = JSON.parse(text);
+                if (p && typeof p === 'object' && typeof (p as { content?: unknown }).content === 'string') {
+                  body = (p as { content: string }).content;
+                }
+              } catch { /* raw markdown */ }
+              return { ...r, body };
+            } catch { return r; }
+          }));
+        }
+        setDataServerMeta(name, {
+          connected: true, connecting: false,
+          tools: tools as McpToolInfo[],
+          recipes,
+          serverName: actualName,
+          error: undefined,
+        });
+      } catch (err) {
+        setDataServerMeta(name, {
+          connected: false, connecting: false,
+          tools: [],
+          error: err instanceof Error ? err.message : String(err),
+        });
+      } finally {
+        inFlight.delete(name);
+      }
+    } else if (!srv.enabled && (srv.connected || liveUrls.has(srv.url))) {
+      try { await multiClient.removeServer(srv.url); } catch { /* ignore */ }
+      setDataServerMeta(name, { connected: false });
+    }
+  }
+
+  function reconcile(): void {
+    for (const srv of _servers) void syncServer(srv.name);
+    // Drop transport entries for servers removed from the store entirely.
+    const storedUrls = new Set(_servers.map((s) => s.url));
+    for (const live of multiClient.listServers()) {
+      if (!storedUrls.has(live.url)) void multiClient.removeServer(live.url);
+    }
+  }
+
+  // Internal subscriber — fires reconcile() after every store mutation.
+  // The `inFlight` guard and the `srv.connected` checks prevent loops when
+  // syncServer itself triggers a notify via setDataServerMeta.
+  listeners.add(() => { reconcile(); });
+
+  /** Call a tool on a connected MCP server, addressed by canvas name (= id). */
+  async function callTool(
+    name: string,
+    toolName: string,
+    args: Record<string, unknown> = {},
+  ): Promise<unknown> {
+    const srv = _servers.find((s) => s.name === name);
+    if (!srv) throw new Error(`canvas.callTool: no server "${name}"`);
+    return multiClient.callToolOn(srv.url, toolName, args);
+  }
+
   // ── Widget actions ─────────────────────────────────────────────────────
   function addWidget(type: WidgetType, data: Record<string, unknown> = {}): Widget {
     const widget: Widget = { id: uuid(), type, data };
@@ -428,6 +575,8 @@ function createCanvasVanilla() {
     setDataServerMeta,
     setDataServerEnabled,
     toggleDataServer,
+    callTool,
+    get multiClient() { return multiClient; },
 
     buildSkillJSON, buildHyperskillParam, loadFromParam, loadFromUrl,