@mcp-b/webmcp-types 4.0.0 → 5.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcp-b/webmcp-types",
-  "version": "4.0.0",
+  "version": "5.0.0",
   "description": "Strict TypeScript type definitions for the WebMCP core API (document.modelContext)",
   "keywords": [
     "document-modelcontext",
@@ -32,7 +32,6 @@
   ],
   "type": "module",
   "sideEffects": false,
-  "main": "",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
@@ -43,25 +42,26 @@
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
+  "dependencies": {
+    "@modelcontextprotocol/server": "2.0.0"
+  },
   "devDependencies": {
-    "@vitest/coverage-v8": "^4.1.7",
-    "playwright": "^1.60.0",
     "typescript": "^5.8.3",
     "vite-plus": "^0.1.22",
     "vitest": "npm:@voidzero-dev/vite-plus-test@latest"
   },
+  "engines": {
+    "node": ">=20"
+  },
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
+    "build": "pnpm run clean && tsc -p tsconfig.build.json",
     "check": "vp check --fix",
     "clean": "rm -rf dist",
     "format": "vp fmt --write",
     "lint": "vp lint --fix",
     "publish:dry": "pnpm publish --access public --dry-run",
     "publish:npm": "pnpm publish --access public",
-    "test": "vp test run && pnpm run test:conformance",
-    "test:browser": "vp test run --config vitest.browser.config.ts --browser.headless",
-    "test:browser:ui": "vp test --config vitest.browser.config.ts --browser",
-    "test:conformance": "vp test run --config vitest.conformance.config.ts",
-    "typecheck": "tsc --noEmit && vp test run --typecheck --silent"
+    "test": "vp test run",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.strict-null-checks-false.json && vp test run --typecheck --silent"
   }
 }

package/src/common.ts

@@ -1,368 +1,23 @@
-// ============================================================================
-// Common Types for the Web Model Context API
-// ============================================================================
-
-/**
- * Primitive JSON value.
- */
-export type JsonPrimitive = string | number | boolean | null;
-
-/**
- * Object-shaped JSON value.
- */
-export interface JsonObject {
-  [key: string]: JsonValue;
-}
-
-/**
- * Any valid JSON value.
- */
-export type JsonValue = JsonPrimitive | JsonObject | JsonValue[];
-
-/**
- * JSON Schema property definition.
- *
- * @see {@link https://json-schema.org/}
- */
-export interface InputSchemaProperty {
-  /**
-   * JSON Schema type for this property.
-   */
-  type?: string;
-
-  /**
-   * Human-readable description of the property.
-   */
-  description?: string;
-
-  /**
-   * Additional JSON Schema keywords.
-   */
-  [key: string]: unknown;
-}
-
-/**
- * JSON Schema definition for tool input parameters.
- *
- * @see {@link https://json-schema.org/}
- */
+export type {
+  CallToolResult,
+  ContentBlock,
+  JSONObject as JsonObject,
+  JSONValue as JsonValue,
+  TextContent,
+} from '@modelcontextprotocol/server';
+
+/** JSON Schema object accepted at the WebMCP boundary. */
 export interface InputSchema {
-  /**
-   * JSON Schema type for the root value (usually `'object'` for tool args).
-   */
-  type?: string;
-
-  /**
-   * Property definitions for object schemas.
-   */
-  properties?: Record<string, InputSchemaProperty>;
-
-  /**
-   * List of required property names.
-   */
-  required?: readonly string[];
-
-  /**
-   * Additional JSON Schema keywords.
-   */
-  [key: string]: unknown;
-}
-
-// ============================================================================
-// Content Types (MCP spec shapes, defined inline)
-// ============================================================================
-
-/**
- * Plain text content.
- */
-export interface TextContent {
-  /**
-   * Discriminator for text content.
-   */
-  type: 'text';
-
-  /**
-   * UTF-8 text value.
-   */
-  text: string;
-}
-
-/**
- * Base64-encoded image content.
- */
-export interface ImageContent {
-  /**
-   * Discriminator for image content.
-   */
-  type: 'image';
-
-  /**
-   * Base64 payload.
-   */
-  data: string;
-
-  /**
-   * MIME type for the encoded image.
-   */
-  mimeType: string;
-}
-
-/**
- * Base64-encoded audio content.
- */
-export interface AudioContent {
-  /**
-   * Discriminator for audio content.
-   */
-  type: 'audio';
-
-  /**
-   * Base64 payload.
-   */
-  data: string;
-
-  /**
-   * MIME type for the encoded audio.
-   */
-  mimeType: string;
-}
-
-/**
- * Text resource contents.
- */
-export interface TextResourceContents {
-  /**
-   * Canonical resource URI.
-   */
-  uri: string;
-
-  /**
-   * Optional MIME type.
-   */
-  mimeType?: string;
-
-  /**
-   * UTF-8 resource payload.
-   */
-  text: string;
-}
-
-/**
- * Binary resource contents encoded as base64.
- */
-export interface BlobResourceContents {
-  /**
-   * Canonical resource URI.
-   */
-  uri: string;
-
-  /**
-   * Optional MIME type.
-   */
-  mimeType?: string;
-
-  /**
-   * Base64-encoded binary payload.
-   */
-  blob: string;
-}
-
-/**
- * Resource contents returned by resource reads.
- */
-export type ResourceContents = TextResourceContents | BlobResourceContents;
-
-/**
- * Embedded resource content block.
- */
-export interface EmbeddedResource {
-  /**
-   * Discriminator for embedded resources.
-   */
-  type: 'resource';
-
-  /**
-   * Inlined resource contents.
-   */
-  resource: ResourceContents;
-}
-
-/**
- * Link to an externally retrievable resource.
- */
-export interface ResourceLink {
-  /**
-   * Discriminator for resource links.
-   */
-  type: 'resource_link';
-
-  /**
-   * Resource URI.
-   */
-  uri: string;
-
-  /**
-   * Optional display name.
-   */
-  name?: string;
-
-  /**
-   * Optional human-readable description.
-   */
-  description?: string;
-
-  /**
-   * Optional MIME type hint.
-   */
-  mimeType?: string;
+  type?: unknown;
+  properties?: Readonly<Record<string, unknown>> | undefined;
+  required?: readonly string[] | undefined;
+  [keyword: string]: unknown;
 }
 
-/**
- * Any content block allowed in tool responses.
- */
-export type ContentBlock =
-  | TextContent
-  | ImageContent
-  | AudioContent
-  | ResourceLink
-  | EmbeddedResource;
-
-/**
- * Looser content block shape accepted by many MCP tool implementations.
- *
- * This keeps tool return typing practical while preserving strict content
- * unions via {@link ContentBlock} for consumers that want discriminated checks.
- */
-export type LooseContentBlock = Record<string, unknown> & {
-  type?: string;
-};
-
-// ============================================================================
-// Result Types
-// ============================================================================
-
-/**
- * The result returned from tool execution.
- *
- * @see {@link https://spec.modelcontextprotocol.io/specification/server/tools/}
- */
-export interface CallToolResult {
-  /**
-   * Ordered content blocks to return to the model.
-   */
-  content: Array<ContentBlock | LooseContentBlock>;
-
-  /**
-   * Optional machine-readable payload.
-   */
-  structuredContent?: JsonValue;
-
-  /**
-   * Marks the result as an error response.
-   */
-  isError?: boolean;
-}
-
-/**
- * Alias for {@link CallToolResult} for API consistency.
- */
-export type ToolResponse = CallToolResult;
-
-// ============================================================================
-// Elicitation Types
-// ============================================================================
-
-/**
- * Form-based elicitation request parameters.
- */
-export interface ElicitationFormParams {
-  /**
-   * Elicitation mode. Omit or set to `'form'` for form input.
-   */
-  mode?: 'form';
-
-  /**
-   * User-facing message.
-   */
-  message: string;
-
-  /**
-   * Requested form schema.
-   */
-  requestedSchema: {
-    /**
-     * Root schema type.
-     */
-    type: 'object';
-
-    /**
-     * Field definitions.
-     */
-    properties: Record<string, InputSchema>;
-
-    /**
-     * Required field names.
-     */
-    required?: readonly string[];
-
-    /**
-     * Additional schema keywords.
-     */
-    [key: string]: unknown;
-  };
-}
-
-/**
- * URL-based elicitation request parameters.
- */
-export interface ElicitationUrlParams {
-  /**
-   * Elicitation mode.
-   */
-  mode: 'url';
-
-  /**
-   * User-facing message.
-   */
-  message: string;
-
-  /**
-   * Unique elicitation identifier.
-   */
-  elicitationId: string;
-
-  /**
-   * URL to open.
-   */
-  url: string;
-}
-
-/**
- * Elicitation request parameters.
- */
-export type ElicitationParams = ElicitationFormParams | ElicitationUrlParams;
-
-/**
- * Result returned by an elicitation request.
- */
-export interface ElicitationResult {
-  /**
-   * User decision.
-   */
-  action: 'accept' | 'decline' | 'cancel';
-
-  /**
-   * Submitted values when `action` is `'accept'`.
-   */
-  content?: Record<string, string | number | boolean | string[]>;
-}
+/** Values accepted by WebMCP tool callbacks. */
+export type WebMcpToolInput = Record<string, unknown> | unknown[];
 
-/**
- * Registration handle returned by registration methods.
- */
+/** Handle returned by MCP-B registration helpers. */
 export interface RegistrationHandle {
-  /**
-   * Unregisters the associated item.
-   */
-  unregister: () => void;
+  unregister(): void;
 }

package/src/index.ts

@@ -1,116 +1,94 @@
 import type { ModelContext, ModelContextTesting } from './model-context.js';
 
-// Re-export all public types
 export type {
-  AudioContent,
-  BlobResourceContents,
   CallToolResult,
   ContentBlock,
-  ElicitationFormParams,
-  ElicitationParams,
-  ElicitationResult,
-  ElicitationUrlParams,
-  EmbeddedResource,
-  ImageContent,
   InputSchema,
-  InputSchemaProperty,
   JsonObject,
-  JsonPrimitive,
   JsonValue,
-  LooseContentBlock,
   RegistrationHandle,
-  ResourceContents,
-  ResourceLink,
   TextContent,
-  TextResourceContents,
-  ToolResponse,
+  WebMcpToolInput,
 } from './common.js';
 export type {
   InferArgsFromInputSchema,
   InferJsonSchema,
-  JsonSchemaArray,
-  JsonSchemaBoolean,
-  JsonSchemaEnumValue,
   JsonSchemaForInference,
-  JsonSchemaMultiType,
-  JsonSchemaNull,
-  JsonSchemaNumber,
-  JsonSchemaObject,
-  JsonSchemaPrimitiveType,
-  JsonSchemaString,
-  JsonSchemaType,
-  JsonSchemaTypeArray,
 } from './json-schema.js';
 export type {
-  AnyToolDescriptor,
-  InferToolArgs,
-  InferToolResult,
+  ChromeModelContext,
+  ChromeModelContextExecuteToolOptions,
+  ChromeModelContextExtensions,
   ModelContext,
-  ModelContextCore,
   ModelContextExtensions,
+  ModelContextGetToolOptions,
   ModelContextRegisterToolOptions,
   ModelContextTesting,
-  ModelContextTestingExecuteToolOptions,
-  ModelContextTestingPolyfillExtensions,
   ModelContextTestingToolInfo,
-  ModelContextToolInfo,
-  ModelContextToolReference,
-  ModelContextToolRegistrationHandle,
   ModelContextWithExtensions,
-  ToolArgsByName,
-  ToolByName,
-  ToolCallEvent,
-  ToolCallParams,
-  ToolName,
-  ToolResultByName,
-  TypedModelContext,
+  RegisteredTool,
 } from './model-context.js';
 export type {
   MaybePromise,
-  ModelContextClient,
+  ModelContextTool,
   ToolAnnotations,
   ToolDescriptor,
   ToolDescriptorFromSchema,
-  ToolExecuteResult,
-  ToolExecutionContext,
   ToolListItem,
-  ToolRawResult,
   ToolResultFromOutputSchema,
+  WebMcpToolAnnotations,
 } from './tool.js';
 
-// ============================================================================
-// Global Augmentation
-// ============================================================================
-
 declare global {
+  /**
+   * Web IDL interface object used for branding and `instanceof`.
+   *
+   * Absent unless the document's realm implements WebMCP, so guard with
+   * `typeof ModelContext !== 'undefined'` before referencing it. A bare
+   * reference to an undeclared global throws `ReferenceError`.
+   */
+  var ModelContext:
+    | (Function & {
+        readonly prototype: ModelContext;
+        [Symbol.hasInstance](value: unknown): value is ModelContext;
+      })
+    | undefined;
+
   interface Document {
     /**
-     * Web Model Context API strict core surface.
+     * Canonical WebMCP API for this document.
      *
-     * Per WebMCP spec PR webmachinelearning/webmcp#184, each Document owns its
-     * associated ModelContext. This is the canonical install location as of
-     * Chrome 150. Prefer `document.modelContext` for new code.
+     * Optional because no browser ships WebMCP unflagged: Chromium exposes it
+     * only under `--enable-features=WebMCP`, and elsewhere the property is
+     * genuinely absent (`'modelContext' in document === false`). Feature-detect
+     * it, or install `@mcp-b/webmcp-polyfill`.
      */
-    readonly modelContext: ModelContext;
+    readonly modelContext?: ModelContext;
   }
 
   interface Navigator {
+    /** @deprecated Use `document.modelContext`. */
+    readonly modelContext?: ModelContext;
+
+    /** @deprecated Compatibility surface for older Chromium previews. */
+    modelContextTesting?: ModelContextTesting;
+  }
+
+  interface SubmitEvent {
     /**
-     * Web Model Context API strict core surface.
+     * True when a declarative WebMCP tool initiated this submission.
      *
-     * @deprecated The modelContext getter moved from Navigator to Document in
-     * Chrome 150 (see webmachinelearning/webmcp#173 / PR #184). Use
-     * `document.modelContext` instead. `navigator.modelContext` is kept as a
-     * backward-compatible alias and will be removed in a future Chrome release.
+     * Optional because declarative forms are explainer-only: this attribute is
+     * in neither the WebMCP specification nor WPT's `webmcp.idl`, and no
+     * browser implements it. `@mcp-b/webmcp-polyfill` installs it.
      */
-    readonly modelContext: ModelContext;
+    readonly agentInvoked?: boolean;
 
     /**
-     * Web Model Context testing API surface (Chromium early preview).
-     * @deprecated Chromium still exposes this API for testing flows. Producer
-     * discovery/execution should prefer document.modelContext.getTools() and
-     * document.modelContext.executeTool(...).
+     * Associates an intercepted form submission result with the invoking agent.
+     *
+     * Optional for the same reason as {@link SubmitEvent.agentInvoked}.
      */
-    modelContextTesting?: ModelContextTesting;
+    respondWith?(agentResponse: Promise<unknown>): void;
   }
 }