@mcp-b/webmcp-ts-sdk 5.0.3 → 6.0.0-beta.20261001010549

package/README.md

@@ -20,10 +20,7 @@ pnpm add @mcp-b/webmcp-ts-sdk @mcp-b/transports
 import { TabServerTransport } from '@mcp-b/transports';
 import { BrowserMcpServer } from '@mcp-b/webmcp-ts-sdk';
 
-const server = new BrowserMcpServer({
-  name: 'catalog-app',
-  version: '1.0.0',
-});
+const server = new BrowserMcpServer({ name: 'catalog-app', version: '1.0.0' });
 
 await server.connect(
   new TabServerTransport({
@@ -56,7 +53,7 @@ An `AbortSignal` owns each WebMCP tool registration. Aborting it removes the loc
 
 ## What the adapter owns
 
-- WebMCP `registerTool()`, `getTools()`, `ontoolchange`, and descriptor-based `executeTool()`
+- WebMCP `registerTool()`, `getTools()`, `ontoolchange`, `ontoolactivated`, `ontoolcancel`, and descriptor-based `executeTool()`
 - Native `document.modelContext` registration mirroring and tool reconciliation
 - MCP-B `registerPrompt()`, `registerResource()`, and `listTools()` extensions
 - MCP transport lifecycle through `connect()` and `close()`
@@ -67,32 +64,34 @@ Prompt and resource discovery also belongs to MCP. Use a connected MCP client in
 
 ## Native integration
 
-Pass an existing context as `native`, then reconcile its current tools:
+The constructor uses `document.modelContext`, installing the bundled `@mcp-b/webmcp-polyfill` (about 28 KB minified) when needed, and delegates browser discovery, execution, and access checks to that context. Without a WebMCP context (no `document`, or an insecure page), the server serves MCP only. The document property keeps exposing the underlying context; `@mcp-b/global` installs the extended API and connects its default transport.
+
+To select a context explicitly, pass it as `native`, then reconcile its current tools:
 
 ```ts
-const server = new BrowserMcpServer(
-  { name: 'catalog-app', version: '1.0.0' },
-  { native: document.modelContext }
-);
+const native = document.modelContext;
+if (!native) throw new Error('Install a WebMCP runtime first');
+const server = new BrowserMcpServer({ name: 'catalog-app', version: '1.0.0' }, { native });
 
 await server.syncNativeTools();
 ```
 
-`syncNativeTools()` resolves after reconciliation. Later native `toolchange` events trigger another reconciliation. Backfill requires Chrome's optional descriptor-based `executeTool()` extension.
+`syncNativeTools()` resolves after reconciliation, and later native `toolchange` events reconcile again. The [package reference](https://docs.mcp-b.ai/packages/webmcp-ts-sdk/reference) covers frame scope, native result conversion, lifecycle events, and the MCP-only mode.
 
 ## Schema boundary
 
-The browser-facing API accepts JSON Schema and Standard Schema inputs. The adapter converts them to the MCP SDK v2 contract. Direct upstream registrations can use Zod 4.2 or newer or the official `fromJsonSchema` helper; Zod 3 is unsupported.
+`BrowserMcpServer` accepts JSON Schema and Standard JSON Schema input metadata. The official MCP server validates input and `outputSchema` on **MCP client calls** only; direct `executeTool()` calls and native mirrors invoke the browser callback without that validation, so validate in the callback when both paths can call a tool. The [`@mcp-b/react-webmcp`](../react-webmcp/README.md) hook already does this.
 
-MCP requires an object-root tool input schema. An array-root WebMCP tool remains available through WebMCP but is omitted from MCP discovery.
+MCP requires an object-root tool input schema. An array-root WebMCP tool remains available through WebMCP but is omitted from MCP discovery. Direct registrations on `server.mcpServer` use the official SDK's schema APIs; Zod 4.2 or newer is supported, and Zod 3 is unsupported. See [the package reference](https://docs.mcp-b.ai/packages/webmcp-ts-sdk/reference#schema-boundary) for the contracts and [schemas and structured output](https://docs.mcp-b.ai/how-to/use-schemas-and-structured-output) for examples.
 
 ## Exports
 
-- `BrowserMcpServer`
-- `BrowserMcpServerOptions`
-- `isBrowserMcpServer`
-- `PromptDescriptor`
-- `ResourceDescriptor`
+- `BrowserMcpServer`, `BrowserMcpServerOptions`, `isBrowserMcpServer`
+- `PromptDescriptor`, `ResourceDescriptor`, `RegistrationHandle`
+- `ModelContext`, `ModelContextWithExtensions`, `RegisteredTool`, `ToolDescriptor`, `ToolDescriptorFromSchema`, `ToolListItem`, `InputSchema`, and the other MCP-B descriptor and inference types
+- `CallToolResult`, `ContentBlock`, `TextContent`, `JsonObject`, `JsonValue`, re-exported from `@modelcontextprotocol/server`
+- `WebMCP`, the upstream namespace re-exported through `@mcp-b/webmcp-polyfill`, which also brings the polyfill's `SubmitEvent` and `ModelContext` declarations into scope
+- `@mcp-b/webmcp-ts-sdk/schema`: `normalizeInputSchema()`, `normalizeToolResponse()`, `isMcpStandardSchema()`, `ToolInputSchema`, `NormalizedInputSchema`
 
 Import MCP clients, servers, schemas, transports, and validators from the official `@modelcontextprotocol/*` packages.
 

package/dist/common-CRzM40Z0.d.ts

@@ -0,0 +1,22 @@
+import { CallToolResult as CallToolResult$1, ContentBlock, JSONObject as JsonObject, JSONValue as JsonValue, TextContent } from "@modelcontextprotocol/server";
+import { WebMCP } from "webmcp-types";
+import { StandardJSONSchemaV1 } from "@standard-schema/spec";
+
+//#region src/common.d.ts
+/** JSON Schema object accepted at the WebMCP boundary. */
+type StandardJsonSchemaObject = ReturnType<StandardJSONSchemaV1.Converter['input']>;
+interface InputSchema extends StandardJsonSchemaObject {
+  type?: unknown;
+  properties?: Readonly<StandardJsonSchemaObject> | undefined;
+  required?: readonly string[] | undefined;
+}
+/** Object or array values accepted at the WebMCP runtime boundary. */
+type WebMcpToolObjectInput = Parameters<WebMCP.ToolExecuteCallback>[0];
+type WebMcpToolInput = WebMcpToolObjectInput | unknown[];
+/** Handle returned by MCP-B registration helpers. */
+interface RegistrationHandle {
+  unregister(): void;
+}
+//#endregion
+export { JsonValue as a, WebMcpToolInput as c, JsonObject as i, WebMcpToolObjectInput as l, ContentBlock as n, RegistrationHandle as o, InputSchema as r, TextContent as s, CallToolResult$1 as t };
+//# sourceMappingURL=common-CRzM40Z0.d.ts.map

package/dist/index.d.ts

@@ -1,18 +1,122 @@
-import { GetPromptResult, Implementation, McpServer, ReadResourceResult, ServerOptions, Transport, Variables } from "@modelcontextprotocol/server";
-import { ChromeModelContextExecuteToolOptions, InputSchema, ModelContext, ModelContextGetToolOptions, ModelContextWithExtensions, RegisteredTool, RegistrationHandle, ToolListItem } from "@mcp-b/webmcp-types";
+import { a as JsonValue, c as WebMcpToolInput, i as JsonObject, l as WebMcpToolObjectInput, n as ContentBlock, o as RegistrationHandle, r as InputSchema, s as TextContent, t as CallToolResult } from "./common-CRzM40Z0.js";
+import { WebMCP } from "@mcp-b/webmcp-polyfill";
+import { GetPromptResult, Implementation, JsonSchemaType, McpServer, ReadResourceResult, ServerOptions, ToolAnnotations as ToolAnnotations$1, Transport, Variables } from "@modelcontextprotocol/server";
+import { WebMCP as WebMCP$1 } from "webmcp-types";
 
+//#region src/json-schema.d.ts
+/** JSON Schema Draft 2020-12 accepted by the inference helpers. */
+type JsonSchemaForInference = JsonSchemaType;
+type JsonSchemaType$1 = 'string' | 'number' | 'integer' | 'boolean' | 'null' | 'object' | 'array';
+type Simplify<T> = { [K in keyof T]: T[K] } & {};
+type EmptyObject = Record<never, never>;
+type ConstValue<TSchema> = TSchema extends {
+  const: infer TValue;
+} ? TValue : never;
+type EnumValue<TSchema> = TSchema extends {
+  enum: readonly (infer TValue)[];
+} ? TValue : never;
+type Properties<TSchema> = TSchema extends {
+  properties: infer TProperties extends NonNullable<InputSchema['properties']>;
+} ? TProperties : EmptyObject;
+type RequiredKeys<TSchema> = TSchema extends {
+  required: readonly (infer TKey extends string)[];
+} ? string extends TKey ? never : Extract<TKey, keyof Properties<TSchema>> : never;
+type AdditionalProperties<TSchema> = TSchema extends {
+  additionalProperties: false;
+} ? keyof Properties<TSchema> extends never ? Record<string, never> : EmptyObject : keyof Properties<TSchema> extends never ? TSchema extends {
+  additionalProperties: infer TAdditional extends object;
+} ? Record<string, InferJsonSchema<TAdditional>> : WebMcpToolObjectInput : WebMcpToolObjectInput;
+type InferObject<TSchema> = Simplify<{ -readonly [K in keyof Properties<TSchema> as K extends RequiredKeys<TSchema> ? K : never]-?: InferJsonSchema<Properties<TSchema>[K]> } & { -readonly [K in keyof Properties<TSchema> as K extends RequiredKeys<TSchema> ? never : K]?: InferJsonSchema<Properties<TSchema>[K]> } & AdditionalProperties<TSchema>>;
+type TypeKeyword<TSchema> = TSchema extends {
+  type: infer TType;
+} ? TType : TSchema extends {
+  properties: unknown;
+} | {
+  required: unknown;
+} | {
+  additionalProperties: unknown;
+} ? 'object' : never;
+type TypeOptions<TSchema> = TypeKeyword<TSchema> extends readonly unknown[] ? Extract<TypeKeyword<TSchema>[number], JsonSchemaType$1> : Extract<TypeKeyword<TSchema>, JsonSchemaType$1>;
+type InferType<TSchema, TType extends JsonSchemaType$1> = TType extends 'object' ? InferObject<TSchema> : TType extends 'array' ? TSchema extends {
+  items: infer TItems;
+} ? InferJsonSchema<TItems>[] : unknown[] : TType extends 'string' ? string : TType extends 'number' | 'integer' ? number : TType extends 'boolean' ? boolean : TType extends 'null' ? null : unknown;
+/** Infers a TypeScript value from the supported JSON Schema keywords. */
+type InferJsonSchema<TSchema> = TSchema extends false ? never : TSchema extends true ? unknown : [InputSchema] extends [TSchema] ? unknown : [ConstValue<TSchema>] extends [never] ? [EnumValue<TSchema>] extends [never] ? TypeOptions<TSchema> extends never ? unknown : InferType<TSchema, TypeOptions<TSchema>> : EnumValue<TSchema> : ConstValue<TSchema>;
+/** Uses WebMCP's schema inference for the callback input. */
+type InferArgsFromInputSchema<TSchema extends object> = Parameters<WebMCP$1.ModelContextToolFromSchema<TSchema>['execute']>[0];
+//#endregion
+//#region src/tool.d.ts
+/** MCP annotations plus the WebMCP tool annotations. */
+type ToolAnnotations = ToolAnnotations$1 & WebMCP$1.ToolAnnotations;
+type MaybePromise<T> = WebMCP$1.MaybePromise<T>;
+/**
+ * Tool dictionary accepted by the standard browser API.
+ * @see https://webmachinelearning.github.io/webmcp/#dictdef-modelcontexttool
+ */
+interface ModelContextTool<TArgs extends object = WebMcpToolObjectInput, TResult = unknown, TName extends string = string> extends Omit<WebMCP$1.ModelContextTool, 'name' | 'inputSchema' | 'execute'> {
+  name: TName;
+  inputSchema?: InputSchema | undefined;
+  execute: (input: TArgs, options: WebMCP$1.ToolExecuteCallbackOptions) => MaybePromise<TResult>;
+}
+/** MCP-B tool dictionary with output metadata. */
+type ToolDescriptor<TArgs extends object = WebMcpToolObjectInput, TResult = unknown, TName extends string = string> = Omit<ModelContextTool<TArgs, TResult, TName>, 'annotations'> & {
+  outputSchema?: JsonSchemaForInference;
+  annotations?: ToolAnnotations;
+};
+/** MCP response with `structuredContent` inferred from an output schema. */
+type ToolResultFromOutputSchema<TOutputSchema extends JsonSchemaForInference | undefined = undefined> = [TOutputSchema] extends [undefined] ? CallToolResult : TOutputSchema extends JsonSchemaForInference ? Omit<CallToolResult, 'structuredContent'> & {
+  structuredContent: InferJsonSchema<TOutputSchema>;
+} : never;
+type ExecuteResult<TOutputSchema extends JsonSchemaForInference | undefined> = [TOutputSchema] extends [undefined] ? unknown : TOutputSchema extends JsonSchemaForInference ? InferJsonSchema<TOutputSchema> | ToolResultFromOutputSchema<TOutputSchema> : never;
+/** Tool dictionary with input and output inferred from JSON Schema literals. */
+type ToolDescriptorFromSchema<TInputSchema extends InputSchema, TOutputSchema extends JsonSchemaForInference | undefined = undefined, TName extends string = string> = Omit<ToolDescriptor<InferArgsFromInputSchema<TInputSchema>, ExecuteResult<TOutputSchema>, TName>, 'inputSchema' | 'outputSchema'> & {
+  inputSchema: TInputSchema;
+} & ([TOutputSchema] extends [undefined] ? {
+  outputSchema?: undefined;
+} : {
+  outputSchema: TOutputSchema;
+});
+/** Tool metadata returned by the MCP-B `listTools()` extension. */
+type ToolListItem<TName extends string = string> = Omit<ToolDescriptor<WebMcpToolObjectInput, unknown, TName>, 'execute' | 'inputSchema'> & {
+  inputSchema: InputSchema;
+};
+//#endregion
+//#region src/model-context.d.ts
+/** Options for tools exposed by descendant documents. */
+type ModelContextGetToolOptions = WebMCP$1.ModelContextGetToolOptions;
+/** Tool metadata returned by `document.modelContext.getTools()`. */
+type RegisteredTool = WebMCP$1.RegisteredTool;
+/** Options accepted by `ModelContext.registerTool()`. */
+type ModelContextRegisterToolOptions = WebMCP$1.ModelContextRegisterToolOptions;
+type WidenedSchema<TSchema extends InputSchema> = string extends TSchema['type'] ? unknown : never;
+/** The upstream WebMCP browser contract. */
+type ModelContext = WebMCP$1.ModelContext;
+/** Non-standard methods exposed by MCP-B runtimes. */
+interface ModelContextExtensions {
+  registerTool<const TInputSchema extends JsonSchemaForInference, const TOutputSchema extends JsonSchemaForInference | undefined = undefined, TName extends string = string>(tool: ToolDescriptorFromSchema<TInputSchema, TOutputSchema, TName>, options?: ModelContextRegisterToolOptions): Promise<void>;
+  registerTool<TInputSchema extends InputSchema, TArgs extends WebMcpToolInput = WebMcpToolInput, TName extends string = string>(tool: ToolDescriptor<TArgs, unknown, TName> & {
+    inputSchema: TInputSchema;
+  } & WidenedSchema<TInputSchema>, options?: ModelContextRegisterToolOptions): Promise<void>;
+  registerTool<TArgs extends WebMcpToolInput = WebMcpToolObjectInput, TName extends string = string>(tool: Omit<ToolDescriptor<TArgs, unknown, TName>, 'inputSchema'> & {
+    inputSchema?: undefined;
+  }, options?: ModelContextRegisterToolOptions): Promise<void>;
+  listTools(): ToolListItem[];
+}
+type ModelContextWithExtensions = Omit<ModelContext, 'registerTool'> & ModelContextExtensions;
+//#endregion
 //#region src/browser-server.d.ts
 declare const SERVER_MARKER_PROPERTY: "__isBrowserMcpServer";
 declare function isBrowserMcpServer(context: unknown): context is BrowserMcpServer;
+type ModelContextEventHandler = ModelContext['ontoolchange'];
 interface BrowserMcpServerOptions extends ServerOptions {
+  /** Underlying context. Defaults to document.modelContext, installing upstream if needed. */
   native?: ModelContext;
 }
 /**
  * Thin WebMCP-to-MCP v2 adapter.
  *
  * The official v2 `McpServer` owns MCP registration, validation, and transport
- * behavior. This class only adds the document-facing WebMCP contract and native
- * Chrome mirroring.
+ * behavior. This class extends the upstream WebMCP context with MCP capabilities.
  */
 declare class BrowserMcpServer extends EventTarget implements ModelContextWithExtensions {
   readonly [SERVER_MARKER_PROPERTY]: true;
@@ -29,19 +133,24 @@ declare class BrowserMcpServer extends EventTarget implements ModelContextWithEx
   private readonly removingNativeTools;
   private nativeSyncQueue;
   private nativeToolChangeQueue;
-  private nativeToolChangeListener;
+  private readonly nativeToolChangeListener;
   private closed;
   private closePromise;
-  private ontoolchangeHandler;
-  private readonly ontoolchangeListener;
+  private readonly eventHandlers;
+  private readonly eventHandlerListener;
+  private readonly nativeLifecycleListener;
   constructor(serverInfo: Implementation, options?: BrowserMcpServerOptions);
-  get ontoolchange(): ((this: ModelContext, event: Event) => unknown) | null;
-  set ontoolchange(handler: ((this: ModelContext, event: Event) => unknown) | null);
+  private getEventHandler;
+  private setEventHandler;
+  get ontoolchange(): ModelContextEventHandler;
+  set ontoolchange(handler: ModelContextEventHandler);
+  get ontoolactivated(): ModelContextEventHandler;
+  set ontoolactivated(handler: ModelContextEventHandler);
+  get ontoolcancel(): ModelContextEventHandler;
+  set ontoolcancel(handler: ModelContextEventHandler);
   private notifyProducerToolsChanged;
-  private getNativeStandardToolsApi;
   private registerNativeToolMirror;
   private abortNativeToolMirror;
-  private validateToolDescriptor;
   private registerToolInMcp;
   readonly registerTool: ModelContextWithExtensions['registerTool'];
   private removeTool;
@@ -51,15 +160,15 @@ declare class BrowserMcpServer extends EventTarget implements ModelContextWithEx
   registerPrompt(descriptor: PromptDescriptor): RegistrationHandle;
   listTools(): ToolListItem[];
   getTools(options?: ModelContextGetToolOptions): Promise<RegisteredTool[]>;
-  executeTool(tool: RegisteredTool, inputArgsJson: string, options?: ChromeModelContextExecuteToolOptions): Promise<string | null>;
+  executeTool(...args: Parameters<ModelContext['executeTool']>): Promise<string>;
   /**
    * Re-evaluate which registered tools may appear on the wire.
    *
-   * `exposedTo` narrows a tool to named embedder origins. The peer origin is only known
-   * once a transport that reports one has heard from its peer, so a restricted tool stays
-   * disabled until then — and stays disabled forever on transports that cannot name a peer
-   * at all. Failing closed keeps a tool that asked for a narrow audience from reaching a
-   * wider one; unrestricted tools are untouched and behave exactly as before.
+   * A published tool without `exposedTo` is enabled. `exposedTo` narrows a tool to named
+   * embedder origins. The peer origin is only known once a transport that reports one has
+   * heard from its peer, so a restricted tool stays disabled until then — and stays
+   * disabled forever on transports that cannot name a peer at all. Failing closed keeps a
+   * tool that asked for a narrow audience from reaching a wider one.
    */
   private applyToolExposure;
   /**
@@ -86,5 +195,5 @@ interface PromptDescriptor {
   get: (args: Record<string, string>) => Promise<GetPromptResult>;
 }
 //#endregion
-export { BrowserMcpServer, type BrowserMcpServerOptions, type PromptDescriptor, type ResourceDescriptor, isBrowserMcpServer };
+export { BrowserMcpServer, type BrowserMcpServerOptions, type CallToolResult, type ContentBlock, type InferArgsFromInputSchema, type InferJsonSchema, type InputSchema, type JsonObject, type JsonSchemaForInference, type JsonValue, type MaybePromise, type ModelContext, type ModelContextExtensions, type ModelContextGetToolOptions, type ModelContextRegisterToolOptions, type ModelContextTool, type ModelContextWithExtensions, type PromptDescriptor, type RegisteredTool, type RegistrationHandle, type ResourceDescriptor, type TextContent, type ToolAnnotations, type ToolDescriptor, type ToolDescriptorFromSchema, type ToolListItem, type ToolResultFromOutputSchema, type WebMCP, type WebMcpToolInput, type WebMcpToolObjectInput, isBrowserMcpServer };
 //# sourceMappingURL=index.d.ts.map