@webmcp-auto-ui/core 0.5.0 → 2.5.4

package/src/utils.ts

@@ -75,6 +75,86 @@ export function signalCompletion(completionEventName: string, detail?: unknown):
 // Item 19 — sanitizeSchema (for AI SDKs)
 // ---------------------------------------------------------------------------
 
+export interface SchemaPatch {
+  path: string;          // e.g. "root", "properties.params", "properties.data.items"
+  type: 'additionalProperties'; // what was patched
+  value: false;
+}
+
+/**
+ * Sanitize schema AND report patches applied for strict tool use.
+ * Use this when you need visibility into what was changed.
+ */
+export function sanitizeSchemaWithReport(schema: JsonSchema): { schema: JsonSchema; patches: SchemaPatch[] } {
+  if (typeof schema === 'boolean') return { schema, patches: [] };
+  const patches: SchemaPatch[] = [];
+  const result = sanitizeSchemaObjectWithReport({ ...schema } as JsonSchemaObject, new WeakSet(), 'root', patches);
+  return { schema: result, patches };
+}
+
+function sanitizeSchemaObjectWithReport(obj: JsonSchemaObject, seen: WeakSet<object>, path: string, patches: SchemaPatch[]): JsonSchemaObject {
+  if (seen.has(obj)) return obj;
+  seen.add(obj);
+
+  const result = { ...obj };
+
+  // Remove composition keywords that AI SDKs can't handle
+  delete result.oneOf;
+  delete result.anyOf;
+  delete result.allOf;
+  delete result.not;
+
+  // Remove conditional keywords
+  delete result.if;
+  delete result.then;
+  delete result.else;
+
+  // Remove $ref (needs dereferencing first)
+  delete result.$ref;
+
+  // Recursively sanitize nested schemas
+  if (result.properties) {
+    const sanitizedProps: Record<string, JsonSchema> = {};
+    for (const [key, value] of Object.entries(result.properties)) {
+      sanitizedProps[key] = typeof value === 'boolean'
+        ? value
+        : sanitizeSchemaObjectWithReport({ ...value } as JsonSchemaObject, seen, `${path}.properties.${key}`, patches);
+    }
+    result.properties = sanitizedProps;
+  }
+
+  if (result.items) {
+    if (Array.isArray(result.items)) {
+      result.items = result.items.map((item, i) =>
+        typeof item === 'boolean'
+          ? item
+          : sanitizeSchemaObjectWithReport({ ...item } as JsonSchemaObject, seen, `${path}.items[${i}]`, patches)
+      );
+    } else if (typeof result.items !== 'boolean') {
+      result.items = sanitizeSchemaObjectWithReport({ ...result.items } as JsonSchemaObject, seen, `${path}.items`, patches);
+    }
+  }
+
+  // Strict tool use: ensure additionalProperties is set on any object type
+  if ((result.type === 'object' || result.properties) && !('additionalProperties' in result)) {
+    result.additionalProperties = false;
+    patches.push({ path, type: 'additionalProperties', value: false });
+  }
+
+  if (result.additionalProperties && typeof result.additionalProperties === 'object') {
+    result.additionalProperties = sanitizeSchemaObjectWithReport(
+      { ...result.additionalProperties } as JsonSchemaObject,
+      seen,
+      `${path}.additionalProperties`,
+      patches
+    );
+  }
+
+  return result;
+}
+
+
+
 /**
  * Strip JSON Schema keywords that cause errors in AI SDKs
  * (e.g., Vercel AI SDK rejects oneOf/anyOf on non-STRING types).
@@ -129,6 +209,12 @@ function sanitizeSchemaObject(obj: JsonSchemaObject, seen: WeakSet<object>): Jso
     }
   }
 
+  // Strict tool use: ensure additionalProperties is set on any object type
+  // Anthropic requires this on ALL objects, even without properties
+  if ((result.type === 'object' || result.properties) && !('additionalProperties' in result)) {
+    result.additionalProperties = false;
+  }
+
   if (result.additionalProperties && typeof result.additionalProperties === 'object') {
     result.additionalProperties = sanitizeSchemaObject(
       { ...result.additionalProperties } as JsonSchemaObject,
@@ -139,6 +225,83 @@ function sanitizeSchemaObject(obj: JsonSchemaObject, seen: WeakSet<object>): Jso
   return result;
 }
 
+// ---------------------------------------------------------------------------
+// flattenSchema — flatten nested object properties for small LLMs
+// ---------------------------------------------------------------------------
+
+/**
+ * Flatten nested object schemas into flat key__subkey properties.
+ * Returns { schema, pathMap } where pathMap maps flat keys to nested paths.
+ * Only flattens properties of type "object" with their own properties.
+ */
+export function flattenSchema(schema: JsonSchema): { schema: JsonSchema; pathMap: Record<string, string[]> } {
+  if (typeof schema === 'boolean') return { schema, pathMap: {} };
+  const obj = schema as JsonSchemaObject;
+  if (!obj.properties) return { schema, pathMap: {} };
+
+  const flatProps: Record<string, JsonSchema> = {};
+  const pathMap: Record<string, string[]> = {};
+  const required = new Set(obj.required ?? []);
+  const flatRequired: string[] = [];
+
+  for (const [key, prop] of Object.entries(obj.properties)) {
+    if (typeof prop !== 'boolean' && prop.type === 'object' && prop.properties) {
+      // Flatten nested object
+      const nestedRequired = new Set((prop as JsonSchemaObject).required ?? []);
+      for (const [subKey, subProp] of Object.entries(prop.properties!)) {
+        const flatKey = `${key}__${subKey}`;
+        flatProps[flatKey] = subProp;
+        pathMap[flatKey] = [key, subKey];
+        if (required.has(key) && nestedRequired.has(subKey)) {
+          flatRequired.push(flatKey);
+        }
+      }
+    } else {
+      // Keep as-is
+      flatProps[key] = prop;
+      pathMap[key] = [key];
+      if (required.has(key)) flatRequired.push(key);
+    }
+  }
+
+  const result: JsonSchemaObject = {
+    ...obj,
+    properties: flatProps,
+  };
+  if (flatRequired.length > 0) result.required = flatRequired;
+  else delete result.required;
+
+  return { schema: result, pathMap };
+}
+
+/**
+ * Unflatten params using a pathMap from flattenSchema.
+ * Converts { a__b: 1, a__c: 2, d: 3 } back to { a: { b: 1, c: 2 }, d: 3 }
+ */
+export function unflattenParams(
+  params: Record<string, unknown>,
+  pathMap: Record<string, string[]>
+): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  for (const [flatKey, value] of Object.entries(params)) {
+    const path = pathMap[flatKey] ?? flatKey.split('__');
+    if (path.length === 1) {
+      result[path[0]] = value;
+    } else {
+      // Build nested structure
+      let current = result;
+      for (let i = 0; i < path.length - 1; i++) {
+        if (!(path[i] in current) || typeof current[path[i]] !== 'object') {
+          current[path[i]] = {};
+        }
+        current = current[path[i]] as Record<string, unknown>;
+      }
+      current[path[path.length - 1]] = value;
+    }
+  }
+  return result;
+}
+
 // ---------------------------------------------------------------------------
 // createToolGroup — ergonomic helper for SPA route-based tool registration
 // ---------------------------------------------------------------------------

package/src/validate.d.ts

@@ -0,0 +1,13 @@
+import type { JsonSchema } from './types.js';
+export interface ValidationError {
+    path: string;
+    message: string;
+    keyword: string;
+    expected?: unknown;
+    actual?: unknown;
+}
+export interface ValidationResult {
+    valid: boolean;
+    errors: ValidationError[];
+}
+export declare function validateJsonSchema(value: unknown, schema: JsonSchema, path?: string): ValidationResult;

package/src/webmcp-helpers.d.ts

@@ -0,0 +1,3 @@
+import type { ToolExecuteResult } from './types.js';
+export declare function textResult(text: string): ToolExecuteResult;
+export declare function jsonResult(data: unknown): ToolExecuteResult;

package/src/webmcp-helpers.ts

@@ -1,11 +1,14 @@
 // ---------------------------------------------------------------------------
 // @webmcp-auto-ui/core — WebMCP helpers
-// Thin layer on top of polyfill.ts: skill registry + result builders.
+// Result builders for tool execute callbacks.
 // Zero additional dependencies. SSR-safe.
+//
+// NOTE: The skill registry that used to live here (SkillDef, registerSkill,
+// unregisterSkill, etc.) has been removed. The canonical skill type and
+// registry now live in @webmcp-auto-ui/sdk (packages/sdk/src/skills/registry.ts).
 // ---------------------------------------------------------------------------
 
-import { executeToolInternal } from './polyfill.js';
-import type { ModelContextTool, ToolExecuteCallback, ToolExecuteResult } from './types.js';
+import type { ToolExecuteResult } from './types.js';
 
 // ---------------------------------------------------------------------------
 // Result builders
@@ -18,63 +21,3 @@ export function textResult(text: string): ToolExecuteResult {
 export function jsonResult(data: unknown): ToolExecuteResult {
   return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
 }
-
-// ---------------------------------------------------------------------------
-// Skill registry
-// ---------------------------------------------------------------------------
-
-export interface SkillDef {
-  id: string;
-  name: string;
-  description: string;
-  component: string;
-  presentation?: string;
-  version?: string;
-  tags?: string[];
-}
-
-const _skills = new Map<string, SkillDef>();
-
-function mcNav(): {
-  registerTool: (t: ModelContextTool & { execute: ToolExecuteCallback }) => void;
-  unregisterTool: (name: string) => void;
-} | null {
-  if (typeof navigator === 'undefined') return null;
-  return (navigator as unknown as Record<string, unknown>).modelContext as ReturnType<typeof mcNav> ?? null;
-}
-
-export function registerSkill(skill: SkillDef): void {
-  _skills.set(skill.id, skill);
-  const mc = mcNav();
-  if (!mc) return;
-  const toolName = `skill__${skill.id}`;
-  try { mc.unregisterTool(toolName); } catch { /* not yet registered */ }
-  mc.registerTool({
-    name: toolName,
-    description: `[Skill] ${skill.name} — ${skill.description}. Component: ${skill.component}.${skill.presentation ? ` Hints: ${skill.presentation}` : ''}`,
-    inputSchema: { type: 'object', properties: {} },
-    execute: () => jsonResult(skill),
-    annotations: { readOnlyHint: true },
-  });
-}
-
-export function unregisterSkill(id: string): void {
-  _skills.delete(id);
-  const mc = mcNav();
-  if (!mc) return;
-  try { mc.unregisterTool(`skill__${id}`); } catch { /* already gone */ }
-}
-
-export function getSkill(id: string): SkillDef | undefined {
-  return _skills.get(id);
-}
-
-export function listSkills(): SkillDef[] {
-  return Array.from(_skills.values());
-}
-
-export function clearSkills(): void {
-  for (const id of Array.from(_skills.keys())) unregisterSkill(id);
-}
-
-export { executeToolInternal };

package/src/webmcp-server.d.ts

@@ -0,0 +1,53 @@
+export interface WebMcpServerOptions {
+    description: string;
+}
+export interface WebMcpToolDef {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    execute: (params: Record<string, unknown>) => Promise<unknown>;
+}
+/** A vanilla renderer: receives a container + data, optionally returns a cleanup function. */
+export type WidgetRenderer = ((container: HTMLElement, data: Record<string, unknown>) => void | (() => void)) | unknown;
+export interface WidgetEntry {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    recipe: string;
+    renderer: WidgetRenderer;
+    group?: string;
+    /** True when the renderer is a plain function (not a framework component). */
+    vanilla: boolean;
+}
+export interface WebMcpServer {
+    readonly name: string;
+    readonly description: string;
+    registerWidget(recipeMarkdown: string, renderer: WidgetRenderer): void;
+    addTool(tool: WebMcpToolDef): void;
+    layer(): {
+        protocol: 'webmcp';
+        serverName: string;
+        description: string;
+        tools: WebMcpToolDef[];
+    };
+    getWidget(name: string): WidgetEntry | undefined;
+    listWidgets(): WidgetEntry[];
+}
+export interface ParsedFrontmatter {
+    frontmatter: Record<string, unknown>;
+    body: string;
+}
+/**
+ * Parse a markdown file with YAML frontmatter (--- delimited).
+ * Supports: scalars, nested objects (indentation), arrays (- item), inline values.
+ * No external YAML dependency.
+ */
+export declare function parseFrontmatter(markdown: string): ParsedFrontmatter;
+/**
+ * Mount a widget into a DOM container by searching registered servers.
+ * If the renderer is a function (vanilla renderer), it is called directly.
+ * Returns an optional cleanup function.
+ * Falls back to a text placeholder if no server provides the widget.
+ */
+export declare function mountWidget(container: HTMLElement, type: string, data: Record<string, unknown>, servers: WebMcpServer[]): (() => void) | void;
+export declare function createWebMcpServer(name: string, options: WebMcpServerOptions): WebMcpServer;