@napster-corp/webmcp-toolkit 1.0.0

package/src/index.ts

@@ -0,0 +1,66 @@
+// Public surface of @napster-corp/webmcp-toolkit.
+//
+// Importing this module, in a browser, does two things as an intentional side
+// effect (see package.json `sideEffects`):
+//   1. Guarantees `document.modelContext` exists, via the pinned WebMCP polyfill
+//      (a no-op when the browser supports WebMCP natively).
+//   2. Installs the MCP-shaped live-state resource extension onto it.
+//
+// Outside a browser (SSR, workers, edge runtimes) it does nothing and touches no
+// globals. The website developer writes STANDARD WebMCP — `document.modelContext
+// .registerTool(...)` — and never a Napster-specific method. Our value-adds
+// (safety tiers, live state, dev tooling) live off the call site, below.
+
+import { initializeWebMCPPolyfill } from '@mcp-b/webmcp-polyfill';
+import { getModelContext, isBrowserEnvironment } from './model-context.js';
+import { installResourceExtension } from './resources.js';
+import { debugLog } from './debug.js';
+
+if (isBrowserEnvironment()) {
+  // Guarantee the standard surface. We are the version gatekeeper: the polyfill
+  // is pinned exactly in package.json so upstream changes never reach customers
+  // untested. No-op when the browser already supports WebMCP natively.
+  initializeWebMCPPolyfill();
+  const mc = getModelContext();
+  if (mc) {
+    installResourceExtension(mc);
+    debugLog('document.modelContext ready (polyfill) + resource extension installed');
+  }
+}
+
+// ---- Standard-surface adapter (the single swap point) ----
+export {
+  getModelContext,
+  getModelContextWithResources,
+  isBrowserEnvironment,
+} from './model-context.js';
+
+// ---- Value-add #1: safety tiers (optional wrapper over standard registerTool) ----
+export { registerStatefulTool, getTier, getTierMap } from './tiers.js';
+
+// ---- Opt-in flow logging (off by default) ----
+export { setDebug } from './debug.js';
+
+// ---- Value-add #2: live state (MCP-shaped resource extension) ----
+export { installResourceExtension, registerResource } from './resources.js';
+
+// ---- Types ----
+export type {
+  // standard WebMCP surface
+  ModelContext,
+  ModelContextWithResources,
+  ToolAnnotations,
+  ToolContent,
+  ToolResult,
+  ToolDescriptor,
+  ToolInfo,
+  // tiers
+  SideEffect,
+  StatefulToolDescriptor,
+  TierMeta,
+  // resources
+  ResourceDescriptor,
+  ResourceInfo,
+  ResourceUpdate,
+  ResourceExtension,
+} from './types.js';

package/src/model-context.ts

@@ -0,0 +1,31 @@
+// The single point where the toolkit reads the standard WebMCP surface.
+//
+// Everything else in the package goes through `getModelContext()` and never
+// touches an MCP-B-specific symbol. That keeps the polyfill swappable: replacing
+// `@mcp-b/webmcp-polyfill` with our own implementation later touches only this
+// file and `index.ts` (the init call).
+
+import type { ModelContext, ModelContextWithResources } from './types.js';
+
+/** True only inside a browser-like environment (not SSR / workers / edge). */
+export function isBrowserEnvironment(): boolean {
+  return typeof window !== 'undefined' && typeof document !== 'undefined';
+}
+
+/**
+ * Return the standard `document.modelContext`, falling back to the deprecated
+ * `navigator.modelContext` alias. `document` is the canonical surface as of the
+ * May 2026 spec change; the navigator getter is retained only for back-compat.
+ * Returns `undefined` outside a browser or before the polyfill has installed.
+ */
+export function getModelContext(): ModelContext | undefined {
+  if (!isBrowserEnvironment()) return undefined;
+  const doc = document as Document & { modelContext?: ModelContext };
+  const nav = navigator as Navigator & { modelContext?: ModelContext };
+  return doc.modelContext ?? nav.modelContext;
+}
+
+/** Same as {@link getModelContext}, typed to include the toolkit's resource extension. */
+export function getModelContextWithResources(): ModelContextWithResources | undefined {
+  return getModelContext() as ModelContextWithResources | undefined;
+}

package/src/resources.ts

@@ -0,0 +1,207 @@
+// Live state as an MCP-shaped resource extension on `document.modelContext`.
+//
+// WebMCP is tools-only today, so this is entirely ours. We model it on the real
+// MCP resource pattern (URI identity, list/read/subscribe, an `updated` event)
+// so it reads as a natural extension and converges if/when WebMCP formalizes
+// resources. The methods attach directly onto `document.modelContext` (an
+// `EventTarget`) as an additive Napster surface — state lives on the standard
+// object rather than a separate global.
+//
+// Consumed by the Napster agent over our own path; NOT interoperable with
+// third-party WebMCP agents until the standard adds resources.
+
+import { getModelContextWithResources } from './model-context.js';
+import { debugLog } from './debug.js';
+import type {
+  ModelContext,
+  ModelContextWithResources,
+  ResourceDescriptor,
+  ResourceInfo,
+  ResourceUpdate,
+} from './types.js';
+
+/** Marker so we install the extension at most once per modelContext object. */
+const INSTALLED = Symbol.for('napster-webmcp-toolkit/resources-installed');
+
+const RESOURCE_UPDATED = 'resourceupdated';
+const RESOURCE_LIST_CHANGED = 'resourcelistchanged';
+
+interface InternalResource {
+  uri: string;
+  name: string;
+  description?: string;
+  mimeType?: string;
+  get: () => unknown | Promise<unknown>;
+}
+
+/**
+ * Install the resource extension onto a `document.modelContext` object. Safe to
+ * call repeatedly: the second call is a no-op. Mutates `mc` in place and returns
+ * it typed with the resource surface.
+ */
+export function installResourceExtension(mc: ModelContext): ModelContextWithResources {
+  const target = mc as ModelContextWithResources & { [INSTALLED]?: boolean };
+  if (target[INSTALLED]) return target;
+
+  // Per-page private registries. `producerUnsubs` holds the teardown for each
+  // resource's push source, so we can unwire it on re-register / unregister.
+  const registry = new Map<string, InternalResource>();
+  const producerUnsubs = new Map<string, () => void>();
+
+  function dispatchListChanged(): void {
+    target.dispatchEvent(new Event(RESOURCE_LIST_CHANGED));
+  }
+
+  // Read a resource's current value, re-reading the producer's getter. On
+  // failure, suppress the update and warn (the next change retries) — one
+  // failing resource must not break the channel.
+  async function emitUpdate(uri: string): Promise<void> {
+    const resource = registry.get(uri);
+    if (!resource) return;
+    let value: unknown;
+    try {
+      value = await resource.get();
+    } catch (err) {
+      warn(`resource '${uri}' get() threw during update; emission suppressed`, err);
+      return;
+    }
+    const detail: ResourceUpdate = { uri, value };
+    target.dispatchEvent(new CustomEvent<ResourceUpdate>(RESOURCE_UPDATED, { detail }));
+    debugLog(`resource "${uri}" changed →`, value);
+  }
+
+  function registerResource<T = unknown>(resource: ResourceDescriptor<T>): () => void {
+    if (!resource || typeof resource.uri !== 'string' || !resource.uri) {
+      throw new Error('[webmcp-toolkit] resource requires a non-empty uri');
+    }
+    if (typeof resource.name !== 'string' || !resource.name) {
+      throw new Error(`[webmcp-toolkit] resource '${resource.uri}' requires a non-empty name`);
+    }
+    if (typeof resource.get !== 'function') {
+      throw new Error(`[webmcp-toolkit] resource '${resource.uri}' requires a get() function`);
+    }
+
+    // Tear down any prior push subscription for this uri BEFORE installing the
+    // new one — re-registering must never leave a stale subscription wired up.
+    const priorUnsub = producerUnsubs.get(resource.uri);
+    if (priorUnsub) {
+      safeCall(priorUnsub);
+      producerUnsubs.delete(resource.uri);
+    }
+
+    const isNew = !registry.has(resource.uri);
+    registry.set(resource.uri, {
+      uri: resource.uri,
+      name: resource.name,
+      description: resource.description,
+      mimeType: resource.mimeType,
+      get: resource.get as () => unknown | Promise<unknown>,
+    });
+
+    if (typeof resource.subscribe === 'function') {
+      const unsub = resource.subscribe(() => {
+        void emitUpdate(resource.uri);
+      });
+      if (typeof unsub === 'function') {
+        producerUnsubs.set(resource.uri, unsub);
+      } else {
+        warn(
+          `resource '${resource.uri}' subscribe() did not return an unsubscribe function. ` +
+            'The subscription will leak. Return a teardown function from subscribe, or remove ' +
+            'subscribe to make the resource pull-only.',
+        );
+      }
+    }
+
+    if (isNew) {
+      dispatchListChanged();
+      debugLog(`registered resource "${resource.uri}" (${resource.name})`);
+    }
+
+    let unregistered = false;
+    return () => {
+      if (unregistered) return;
+      unregistered = true;
+      const u = producerUnsubs.get(resource.uri);
+      if (u) {
+        safeCall(u);
+        producerUnsubs.delete(resource.uri);
+      }
+      if (registry.delete(resource.uri)) dispatchListChanged();
+    };
+  }
+
+  function getResources(): ResourceInfo[] {
+    return Array.from(registry.values(), (r) => ({
+      uri: r.uri,
+      name: r.name,
+      description: r.description,
+      mimeType: r.mimeType,
+    }));
+  }
+
+  async function readResource<T = unknown>(uri: string): Promise<T | undefined> {
+    const resource = registry.get(uri);
+    if (!resource) return undefined;
+    try {
+      return (await resource.get()) as T;
+    } catch (err) {
+      warn(`readResource('${uri}') failed; returning undefined`, err);
+      return undefined;
+    }
+  }
+
+  function subscribeResource(
+    uri: string,
+    handler: (update: ResourceUpdate) => void,
+  ): () => void {
+    const listener = (evt: Event): void => {
+      const detail = (evt as CustomEvent<ResourceUpdate>).detail;
+      if (!detail || detail.uri !== uri) return;
+      try {
+        handler(detail);
+      } catch (err) {
+        // One bad handler must not break the dispatch for others.
+        warn(`subscribeResource('${uri}') handler threw`, err);
+      }
+    };
+    target.addEventListener(RESOURCE_UPDATED, listener);
+    return () => target.removeEventListener(RESOURCE_UPDATED, listener);
+  }
+
+  Object.defineProperties(target, {
+    registerResource: { value: registerResource, configurable: true, writable: true },
+    getResources: { value: getResources, configurable: true, writable: true },
+    readResource: { value: readResource, configurable: true, writable: true },
+    subscribeResource: { value: subscribeResource, configurable: true, writable: true },
+    [INSTALLED]: { value: true, configurable: true },
+  });
+
+  return target;
+}
+
+/**
+ * Producer-side convenience: register a live-state resource on
+ * `document.modelContext` without casting. Equivalent to
+ * `document.modelContext.registerResource(...)` but SSR-safe (a no-op when no
+ * model context is present). Returns an unregister function.
+ */
+export function registerResource<T = unknown>(resource: ResourceDescriptor<T>): () => void {
+  const mc = getModelContextWithResources();
+  if (!mc || typeof mc.registerResource !== 'function') return () => {};
+  return mc.registerResource(resource);
+}
+
+function safeCall(fn: () => void): void {
+  try {
+    fn();
+  } catch {
+    /* ignore teardown errors */
+  }
+}
+
+function warn(message: string, err?: unknown): void {
+  const detail = err ? `: ${err instanceof Error ? err.message : String(err)}` : '';
+  // eslint-disable-next-line no-console
+  console.warn(`[webmcp-toolkit] ${message}${detail}`);
+}

package/src/tiers.ts

@@ -0,0 +1,132 @@
+// Safety tiers — Napster value-add #1, kept OFF the standard call site.
+//
+// The standard `annotations` object only carries `readOnlyHint` and
+// `untrustedContentHint`. The richer tier (`reversible` vs `irreversible`) plus
+// `idempotent` have no standard field — and the pinned polyfill drops custom
+// annotation keys from `getTools()`, so they cannot ride on the tool. We store
+// them in a toolkit-side registry keyed by tool name instead.
+//
+// Developers who want gating call `registerStatefulTool(...)`, a one-line
+// superset of the standard `registerTool` that ALSO records the tier. Plain
+// `document.modelContext.registerTool(...)` still works and is treated as
+// `reversible` by consumers. The confirmation flow is enforced by the consumer
+// (Web SDK / agent), never by the model: `irreversible` requires explicit user
+// confirmation, `reversible` gets a brief announce, `read` is free.
+
+import { getModelContext } from './model-context.js';
+import { debugLog } from './debug.js';
+import type {
+  SideEffect,
+  StatefulToolDescriptor,
+  TierMeta,
+  ToolAnnotations,
+  ToolDescriptor,
+} from './types.js';
+
+/** Tier metadata keyed by tool name. Read by the dev panel and Web SDK. */
+const tierRegistry = new Map<string, TierMeta>();
+
+function annotationsForTier(
+  tier: SideEffect,
+  untrustedContent: boolean,
+  override: ToolAnnotations | undefined,
+): ToolAnnotations {
+  return {
+    readOnlyHint: tier === 'read',
+    ...(untrustedContent ? { untrustedContentHint: true } : {}),
+    ...(override ?? {}),
+  };
+}
+
+/**
+ * Register a STANDARD WebMCP tool and record its safety tier. The tool is a
+ * plain `document.modelContext` registration — any WebMCP agent can use it — so
+ * there is no lock-in; the only Napster-specific thing is that the tier is
+ * remembered for confirmation gating.
+ *
+ * Returns an unregister function (aborts the tool's registration signal and
+ * forgets its tier). In SSR / non-browser environments this is a no-op.
+ *
+ * @example
+ * registerStatefulTool({
+ *   name: 'cart.checkout',
+ *   description: 'Place the order for everything in the cart.',
+ *   inputSchema: { type: 'object', properties: {} },
+ *   napsterTier: 'irreversible',
+ *   async execute() {
+ *     await checkout();
+ *     return { content: [{ type: 'text', text: 'Order placed.' }] };
+ *   },
+ * });
+ */
+export function registerStatefulTool(tool: StatefulToolDescriptor): () => void {
+  if (!tool || typeof tool.name !== 'string' || !tool.name) {
+    throw new Error('[webmcp-toolkit] registerStatefulTool requires a non-empty name');
+  }
+  if (typeof tool.description !== 'string' || !tool.description) {
+    throw new Error(
+      `[webmcp-toolkit] tool '${tool.name}' requires a non-empty description. ` +
+        'The agent reads it to decide when to invoke the tool.',
+    );
+  }
+  if (typeof tool.execute !== 'function') {
+    throw new Error(`[webmcp-toolkit] tool '${tool.name}' requires an execute() function`);
+  }
+
+  const tier: SideEffect = tool.napsterTier ?? 'reversible';
+  const idempotent = tool.idempotent ?? false;
+
+  const mc = getModelContext();
+  if (!mc) {
+    // SSR / worker / pre-polyfill: nothing to register against. Stay silent and
+    // return a no-op unregister, mirroring the standard's SSR-safe behavior.
+    return () => {};
+  }
+
+  const standardTool: ToolDescriptor = {
+    name: tool.name,
+    title: tool.title,
+    description: tool.description,
+    inputSchema: tool.inputSchema,
+    annotations: annotationsForTier(tier, tool.untrustedContent ?? false, tool.annotations),
+    execute: tool.execute,
+  };
+
+  const controller = new AbortController();
+  tierRegistry.set(tool.name, {
+    tier,
+    idempotent,
+    requiresConfirmation: tier === 'irreversible',
+  });
+  // Forget the tier when the registration is aborted, so a removed tool's tier
+  // does not ghost in the registry.
+  controller.signal.addEventListener('abort', () => tierRegistry.delete(tool.name), {
+    once: true,
+  });
+
+  void mc.registerTool(standardTool, { signal: controller.signal });
+  debugLog(
+    `registered tool "${tool.name}" — tier=${tier}` +
+      `${idempotent ? ', idempotent' : ''}, readOnlyHint=${standardTool.annotations?.readOnlyHint ?? false}`,
+  );
+
+  let unregistered = false;
+  return () => {
+    if (unregistered) return;
+    unregistered = true;
+    controller.abort();
+  };
+}
+
+/** Read the safety tier recorded for a tool, or `undefined` if none. */
+export function getTier(name: string): TierMeta | undefined {
+  return tierRegistry.get(name);
+}
+
+/**
+ * All recorded tiers (read-only view). Consumers should treat any tool WITHOUT
+ * a recorded tier as `reversible` (announce-then-run).
+ */
+export function getTierMap(): ReadonlyMap<string, TierMeta> {
+  return tierRegistry;
+}

package/src/types.ts

@@ -0,0 +1,177 @@
+// Public types for the Napster WebMCP Toolkit.
+//
+// The toolkit re-bases on the WebMCP standard (`document.modelContext`). The
+// website developer writes STANDARD `registerTool` calls — these types describe
+// the standard surface we rely on, plus the two Napster extensions that live
+// OFF the standard call site: safety tiers (`registerStatefulTool`) and live
+// state (the MCP-shaped resource extension).
+
+// ---------------------------------------------------------------------------
+// Standard WebMCP surface (the subset we depend on)
+// ---------------------------------------------------------------------------
+
+/**
+ * Standard WebMCP tool annotations. The spec's `annotations` object carries
+ * exactly two hints — there is intentionally no field for richer safety tiers
+ * (see {@link SideEffect} / {@link StatefulToolDescriptor}).
+ */
+export interface ToolAnnotations {
+  /** True if the tool only reads state and never mutates it. */
+  readOnlyHint?: boolean;
+  /** True if the tool's output may contain untrusted / third-party content. */
+  untrustedContentHint?: boolean;
+}
+
+/** A single content item returned from a tool's `execute` callback. */
+export interface ToolContent {
+  type: string;
+  text?: string;
+  [key: string]: unknown;
+}
+
+/** Standard WebMCP tool result shape: `{ content: [{ type: 'text', text }] }`. */
+export interface ToolResult {
+  content: ToolContent[];
+}
+
+/** Standard `document.modelContext.registerTool(...)` descriptor. */
+export interface ToolDescriptor {
+  /** Domain-named identifier, e.g. 'cart.add'. */
+  name: string;
+  /** Optional human-readable label (top-level, not inside annotations). */
+  title?: string;
+  /** One-sentence description — the agent reads this to decide WHEN to call. */
+  description: string;
+  /** JSON Schema for the arguments. */
+  inputSchema?: Record<string, unknown>;
+  /** Standard hints. */
+  annotations?: ToolAnnotations;
+  /** Invokes the app's real operation and returns standard content. */
+  execute: (input: Record<string, unknown>) => ToolResult | Promise<ToolResult>;
+}
+
+/** Tool metadata as returned by `document.modelContext.getTools()` (read layer). */
+export interface ToolInfo {
+  name: string;
+  description: string;
+  inputSchema?: Record<string, unknown>;
+  title?: string;
+  origin?: string;
+}
+
+/**
+ * The standard `document.modelContext` object (an `EventTarget`). We type only
+ * the members the toolkit and Web SDK touch. `getTools()` / `executeTool()` are
+ * not yet in the formal WebIDL but are implemented by the pinned polyfill and
+ * by Chrome's native implementation; `toolchange` fires (a bare `Event`, no
+ * detail) whenever the tool list changes.
+ */
+export interface ModelContext extends EventTarget {
+  registerTool(tool: ToolDescriptor, options?: { signal?: AbortSignal }): void | Promise<void>;
+  getTools(): Promise<ToolInfo[]>;
+  executeTool(
+    tool: ToolInfo,
+    inputArgsJson: string,
+    options?: { signal?: AbortSignal },
+  ): Promise<string | null>;
+}
+
+// ---------------------------------------------------------------------------
+// Napster extension #1 — safety tiers (Option A: optional wrapper)
+// ---------------------------------------------------------------------------
+
+/**
+ * Side-effect tier — governs how carefully a consumer commits a tool. The
+ * standard `annotations` object cannot carry this (the polyfill drops custom
+ * annotation keys from `getTools()`), so the tier is stored in a toolkit-side
+ * registry keyed by tool name and read back via {@link TierMeta}.
+ */
+export type SideEffect = 'read' | 'reversible' | 'irreversible';
+
+/**
+ * Optional superset of {@link ToolDescriptor} for tools that want safety
+ * gating. Calling `registerStatefulTool` registers a STANDARD tool (so any
+ * WebMCP agent can use it) and additionally records its tier. Plain
+ * `document.modelContext.registerTool` still works and is treated as
+ * `reversible` (announce-then-run) by consumers.
+ */
+export interface StatefulToolDescriptor extends Omit<ToolDescriptor, 'annotations'> {
+  /** Governance tier — defaults to 'reversible' when omitted. */
+  napsterTier?: SideEffect;
+  /** True if re-running with the same args is safe to repeat. */
+  idempotent?: boolean;
+  /** True if output may contain untrusted content → sets `untrustedContentHint`. */
+  untrustedContent?: boolean;
+  /** Manual annotation override; merged last (rarely needed). */
+  annotations?: ToolAnnotations;
+}
+
+/** Tier metadata exposed to consumers (Web SDK / dev panel) for gating. */
+export interface TierMeta {
+  tier: SideEffect;
+  idempotent: boolean;
+  /** True when the consumer must get explicit user confirmation (tier === 'irreversible'). */
+  requiresConfirmation: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Napster extension #2 — live state as an MCP-shaped resource extension
+// ---------------------------------------------------------------------------
+
+/**
+ * A live-state resource the agent can PERCEIVE, modeled on MCP resources.
+ *
+ * Add a resource only for state that changes out-of-band — state the user edits
+ * by hand, or state that moves server-side. If a tool already returns the
+ * answer, do NOT add a resource that mirrors it. The genuine value here is
+ * *push* (live) state; pure pull state is better modeled as a read-only tool.
+ */
+export interface ResourceDescriptor<T = unknown> {
+  /** URI identity, mirrors MCP, e.g. 'state://cart'. */
+  uri: string;
+  /** Logical name, e.g. 'cart'. Required (mirrors MCP `Resource.name`). */
+  name: string;
+  /** Optional human description. */
+  description?: string;
+  /** Optional MIME type of the read value. */
+  mimeType?: string;
+  /** Returns the current, serializable value. Cheap, side-effect-free. */
+  get: () => T | Promise<T>;
+  /** Optional push source. Fires onChange on mutation; returns an unsubscribe. */
+  subscribe?: (onChange: () => void) => () => void;
+}
+
+/** Resource metadata as listed by `getResources()` (mirrors `resources/list`). */
+export interface ResourceInfo {
+  uri: string;
+  name: string;
+  description?: string;
+  mimeType?: string;
+}
+
+/** Payload of the `resourceupdated` event / `subscribeResource` handler. */
+export interface ResourceUpdate {
+  uri: string;
+  value: unknown;
+}
+
+/**
+ * The additive surface installed onto `document.modelContext` by the toolkit.
+ * Method names mirror the MCP resource methods (`resources/list`/`read`/
+ * `subscribe`). Consumed by the Napster agent over our own path — not
+ * interoperable with third-party WebMCP agents until the standard formalizes
+ * resources.
+ */
+export interface ResourceExtension {
+  /** Producer-side: register a live-state resource. Returns an unregister fn. */
+  registerResource<T = unknown>(resource: ResourceDescriptor<T>): () => void;
+  /** Consumer-side: list resources (mirrors `resources/list`). */
+  getResources(): ResourceInfo[];
+  /** Consumer-side: read one resource's current value (mirrors `resources/read`). */
+  readResource<T = unknown>(uri: string): Promise<T | undefined>;
+  /** Consumer-side: subscribe to one resource; returns an unsubscribe. */
+  subscribeResource(uri: string, handler: (update: ResourceUpdate) => void): () => void;
+}
+
+/** `document.modelContext` augmented with the toolkit's resource extension. */
+export type ModelContextWithResources = ModelContext & ResourceExtension;