@mcp-b/webmcp-types 0.0.0-beta-20260216200013

package/src/json-schema.ts

@@ -0,0 +1,290 @@
+import type { JsonPrimitive, JsonValue } from './common.js';
+
+/**
+ * Primitive JSON Schema `type` values supported by the MVP inference layer.
+ */
+export type JsonSchemaPrimitiveType = 'string' | 'number' | 'integer' | 'boolean' | 'null';
+
+/**
+ * JSON Schema `type` values supported by the MVP inference layer.
+ */
+export type JsonSchemaType = JsonSchemaPrimitiveType | 'object' | 'array';
+
+/**
+ * JSON Schema multi-type tuple (for example `["string", "null"]`).
+ */
+export type JsonSchemaTypeArray = readonly [JsonSchemaType, ...JsonSchemaType[]];
+
+/**
+ * Literal values supported in JSON Schema `enum`/`const`.
+ */
+export type JsonSchemaEnumValue = JsonPrimitive | JsonValue;
+
+/**
+ * Extra JSON Schema keywords tolerated by the inference layer.
+ *
+ * These keys are intentionally accepted as opaque metadata. Inference only uses
+ * the core MVP keywords and ignores these fields.
+ */
+interface SupplementalJsonSchemaKeywords {
+  $defs?: unknown;
+  $ref?: unknown;
+  additionalItems?: unknown;
+  allOf?: unknown;
+  anyOf?: unknown;
+  contains?: unknown;
+  definitions?: unknown;
+  dependentRequired?: unknown;
+  dependentSchemas?: unknown;
+  format?: unknown;
+  if?: unknown;
+  maxContains?: unknown;
+  minContains?: unknown;
+  not?: unknown;
+  oneOf?: unknown;
+  patternProperties?: unknown;
+  prefixItems?: unknown;
+  propertyNames?: unknown;
+  then?: unknown;
+  unevaluatedItems?: unknown;
+  unevaluatedProperties?: unknown;
+}
+
+/**
+ * Non-validation metadata accepted by the MVP inference subset.
+ */
+interface JsonSchemaMetadata extends SupplementalJsonSchemaKeywords {
+  default?: JsonValue;
+  description?: string;
+  examples?: readonly JsonValue[];
+  /**
+   * OpenAPI-compatible nullability marker.
+   */
+  nullable?: boolean;
+  title?: string;
+}
+
+/**
+ * JSON Schema for `type: "string"`.
+ */
+export interface JsonSchemaString extends JsonSchemaMetadata {
+  const?: string;
+  enum?: readonly string[];
+  maxLength?: number;
+  minLength?: number;
+  pattern?: string;
+  type: 'string';
+}
+
+/**
+ * JSON Schema for `type: "number"` and `type: "integer"`.
+ */
+export interface JsonSchemaNumber extends JsonSchemaMetadata {
+  const?: number;
+  enum?: readonly number[];
+  exclusiveMaximum?: number;
+  exclusiveMinimum?: number;
+  maximum?: number;
+  minimum?: number;
+  multipleOf?: number;
+  type: 'number' | 'integer';
+}
+
+/**
+ * JSON Schema for `type: "boolean"`.
+ */
+export interface JsonSchemaBoolean extends JsonSchemaMetadata {
+  const?: boolean;
+  enum?: readonly boolean[];
+  type: 'boolean';
+}
+
+/**
+ * JSON Schema for `type: "null"`.
+ */
+export interface JsonSchemaNull extends JsonSchemaMetadata {
+  const?: null;
+  enum?: readonly null[];
+  type: 'null';
+}
+
+/**
+ * JSON Schema for `type: "array"`.
+ */
+export interface JsonSchemaArray extends JsonSchemaMetadata {
+  items: JsonSchemaForInference;
+  maxItems?: number;
+  minItems?: number;
+  type: 'array';
+  uniqueItems?: boolean;
+}
+
+/**
+ * JSON Schema for `type: "object"`.
+ */
+export interface JsonSchemaObject extends JsonSchemaMetadata {
+  additionalProperties?: boolean | JsonSchemaForInference;
+  maxProperties?: number;
+  minProperties?: number;
+  properties?: Readonly<Record<string, JsonSchemaForInference>>;
+  required?: readonly string[];
+  type: 'object';
+}
+
+/**
+ * JSON Schema for multi-type unions via `type: [...]`.
+ */
+export interface JsonSchemaMultiType extends JsonSchemaMetadata {
+  additionalProperties?: boolean | JsonSchemaForInference;
+  const?: JsonSchemaEnumValue;
+  enum?: readonly JsonSchemaEnumValue[];
+  items?: JsonSchemaForInference;
+  properties?: Readonly<Record<string, JsonSchemaForInference>>;
+  required?: readonly string[];
+  type: JsonSchemaTypeArray;
+}
+
+/**
+ * JSON Schema subset supported by the MVP type inference layer.
+ */
+export type JsonSchemaForInference =
+  | JsonSchemaArray
+  | JsonSchemaBoolean
+  | JsonSchemaMultiType
+  | JsonSchemaNull
+  | JsonSchemaNumber
+  | JsonSchemaObject
+  | JsonSchemaString;
+
+type Simplify<T> = { [K in keyof T]: T[K] } & {};
+
+type EmptyObject = Record<never, never>;
+
+type EnumLiteral<TSchema> = TSchema extends { enum: infer TEnum extends readonly unknown[] }
+  ? Extract<TEnum[number], JsonSchemaEnumValue>
+  : never;
+
+type ConstLiteral<TSchema> = TSchema extends { const: infer TConst }
+  ? Extract<TConst, JsonSchemaEnumValue>
+  : never;
+
+type PropertiesOf<TSchema> = TSchema extends {
+  properties: infer TProperties extends Readonly<Record<string, JsonSchemaForInference>>;
+}
+  ? TProperties
+  : EmptyObject;
+
+type RequiredKeysOf<TSchema, TProperties extends Record<string, unknown>> = TSchema extends {
+  required: readonly (infer TRequired)[];
+}
+  ? string extends TRequired
+    ? never
+    : Extract<TRequired, keyof TProperties & string>
+  : never;
+
+type RequiredProps<
+  TProperties extends Record<string, JsonSchemaForInference>,
+  TRequiredKeys extends string,
+> = {
+  [K in keyof TProperties as K extends TRequiredKeys ? K : never]-?: InferJsonSchema<
+    TProperties[K]
+  >;
+};
+
+type OptionalProps<
+  TProperties extends Record<string, JsonSchemaForInference>,
+  TRequiredKeys extends string,
+> = {
+  [K in keyof TProperties as K extends TRequiredKeys ? never : K]?: InferJsonSchema<TProperties[K]>;
+};
+
+type PropertyKeysOf<TSchema> = keyof PropertiesOf<TSchema> & string;
+
+type AdditionalSchemaOf<TSchema> = TSchema extends { additionalProperties: infer TAdditional }
+  ? TAdditional
+  : undefined;
+
+type AdditionalPropsValue<TSchema> = AdditionalSchemaOf<TSchema> extends JsonSchemaForInference
+  ? InferJsonSchema<AdditionalSchemaOf<TSchema>>
+  : unknown;
+
+type AdditionalPropsOf<TSchema> = TSchema extends { additionalProperties: false }
+  ? EmptyObject
+  : AdditionalSchemaOf<TSchema> extends JsonSchemaForInference
+    ? PropertyKeysOf<TSchema> extends never
+      ? Record<string, AdditionalPropsValue<TSchema>>
+      : Record<string, unknown>
+    : Record<string, unknown>;
+
+type InferObject<TSchema> = Simplify<
+  RequiredProps<PropertiesOf<TSchema>, RequiredKeysOf<TSchema, PropertiesOf<TSchema>>> &
+    OptionalProps<PropertiesOf<TSchema>, RequiredKeysOf<TSchema, PropertiesOf<TSchema>>> &
+    AdditionalPropsOf<TSchema>
+>;
+
+type TypeKeywordOf<TSchema> = TSchema extends { type: infer TType } ? TType : never;
+
+type TypeOptionsOf<TSchema> = TypeKeywordOf<TSchema> extends readonly unknown[]
+  ? Extract<TypeKeywordOf<TSchema>[number], JsonSchemaType>
+  : Extract<TypeKeywordOf<TSchema>, JsonSchemaType>;
+
+type InferFromTypeOption<TSchema, TType extends JsonSchemaType> = 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;
+
+type InferFromTypeKeyword<TSchema> = TypeOptionsOf<TSchema> extends never
+  ? unknown
+  : InferFromTypeOption<TSchema, TypeOptionsOf<TSchema>>;
+
+type ApplyNullable<TSchema, TValue> = TSchema extends { nullable: true } ? TValue | null : TValue;
+
+/**
+ * Infers a TypeScript type from the supported JSON Schema subset.
+ *
+ * `const` and `enum` take precedence when present.
+ */
+export type InferJsonSchema<TSchema> = [ConstLiteral<TSchema>] extends [never]
+  ? [EnumLiteral<TSchema>] extends [never]
+    ? ApplyNullable<TSchema, InferFromTypeKeyword<TSchema>>
+    : ApplyNullable<TSchema, EnumLiteral<TSchema>>
+  : ApplyNullable<TSchema, ConstLiteral<TSchema>>;
+
+type IsWidenedTypeKeyword<TTypeKeyword> = string extends TTypeKeyword
+  ? true
+  : TTypeKeyword extends readonly unknown[]
+    ? string extends TTypeKeyword[number]
+      ? true
+      : false
+    : false;
+
+type IncludesObjectType<TSchema> = TypeOptionsOf<TSchema> extends never
+  ? false
+  : 'object' extends TypeOptionsOf<TSchema>
+    ? true
+    : false;
+
+/**
+ * Infers tool argument types from a root `InputSchema`.
+ *
+ * If the schema is not a literal object schema (for example a widened
+ * `InputSchema` loaded at runtime), this intentionally falls back to
+ * `Record<string, unknown>`.
+ */
+export type InferArgsFromInputSchema<TSchema extends { type: string | readonly string[] }> =
+  IsWidenedTypeKeyword<TSchema['type']> extends true
+    ? Record<string, unknown>
+    : IncludesObjectType<TSchema> extends true
+      ? InferObject<TSchema>
+      : Record<string, unknown>;

package/src/model-context.ts

@@ -0,0 +1,346 @@
+import type { CallToolResult, InputSchema, ToolResponse } from './common.js';
+import type { JsonSchemaForInference, JsonSchemaObject } from './json-schema.js';
+import type { ToolDescriptor, ToolDescriptorFromSchema, ToolListItem } from './tool.js';
+
+// ============================================================================
+// Model Context Input
+// ============================================================================
+
+/**
+ * Context provided to models via provideContext().
+ */
+export interface ModelContextInput<TTools extends readonly ToolDescriptor[] = ToolDescriptor[]> {
+  /**
+   * Base tool descriptors to expose.
+   */
+  tools?: TTools;
+}
+
+/**
+ * Public options accepted by provideContext().
+ */
+export type ModelContextOptions = ModelContextInput;
+
+// ============================================================================
+// Model Context Testing
+// ============================================================================
+
+/**
+ * Tool info returned by ModelContextTesting.listTools().
+ */
+export interface ModelContextTestingToolInfo {
+  name: string;
+  description: string;
+  inputSchema?: string;
+}
+
+/**
+ * Options supported by ModelContextTesting.executeTool().
+ */
+export interface ModelContextTestingExecuteToolOptions {
+  signal?: AbortSignal;
+}
+
+/**
+ * Chromium early-preview testing API on navigator.modelContextTesting.
+ */
+export interface ModelContextTesting {
+  listTools(): ModelContextTestingToolInfo[];
+  executeTool(
+    toolName: string,
+    inputArgsJson: string,
+    options?: ModelContextTestingExecuteToolOptions
+  ): Promise<string | null>;
+  registerToolsChangedCallback(callback: () => void): void;
+  getCrossDocumentScriptToolResult(): Promise<string>;
+}
+
+/**
+ * Polyfill-only testing extensions layered on top of ModelContextTesting.
+ */
+export interface ModelContextTestingPolyfillExtensions {
+  getToolCalls(): Array<{
+    toolName: string;
+    arguments: Record<string, unknown>;
+    timestamp: number;
+  }>;
+  clearToolCalls(): void;
+  setMockToolResponse(toolName: string, response: ToolResponse): void;
+  clearMockToolResponse(toolName: string): void;
+  clearAllMockToolResponses(): void;
+  getRegisteredTools(): ReturnType<ModelContextExtensions['listTools']>;
+  reset(): void;
+}
+
+// ============================================================================
+// Type Inference Helpers
+// ============================================================================
+
+/**
+ * Any supported tool descriptor.
+ *
+ * Uses `never` for args so descriptors with stricter argument objects remain assignable.
+ */
+export type AnyToolDescriptor = ToolDescriptor<never, CallToolResult, string>;
+
+/**
+ * Infers argument shape from a tool descriptor.
+ */
+export type InferToolArgs<TTool> = TTool extends ToolDescriptor<
+  infer TArgs,
+  infer _TResult,
+  infer _TName
+>
+  ? TArgs
+  : never;
+
+/**
+ * Infers result shape from a tool descriptor.
+ */
+export type InferToolResult<TTool> = TTool extends ToolDescriptor<
+  infer _TArgs,
+  infer TResult,
+  infer _TName
+>
+  ? TResult
+  : never;
+
+/**
+ * Union of tool names from a tuple/array of descriptors.
+ */
+export type ToolName<TTools extends readonly { name: string }[]> = TTools[number]['name'];
+
+/**
+ * Extracts a tool descriptor by name from a tuple/array.
+ */
+export type ToolByName<
+  TTools extends readonly { name: string }[],
+  TName extends ToolName<TTools>,
+> = Extract<TTools[number], { name: TName }>;
+
+/**
+ * Tool argument type by tool name from a tuple/array.
+ */
+export type ToolArgsByName<
+  TTools extends readonly { name: string }[],
+  TName extends ToolName<TTools>,
+> = InferToolArgs<ToolByName<TTools, TName>>;
+
+/**
+ * Tool result type by tool name from a tuple/array.
+ */
+export type ToolResultByName<
+  TTools extends readonly { name: string }[],
+  TName extends ToolName<TTools>,
+> = InferToolResult<ToolByName<TTools, TName>>;
+
+/**
+ * Typed parameters for `callTool`.
+ *
+ * When a tool has no args (`Record<string, never>`), `arguments` becomes optional.
+ */
+export type ToolCallParams<
+  TName extends string = string,
+  TArgs extends Record<string, unknown> = Record<string, never>,
+> = { name: TName } & (TArgs extends Record<string, never>
+  ? { arguments?: TArgs }
+  : { arguments: TArgs });
+
+// ============================================================================
+// Tool Call Event
+// ============================================================================
+
+/**
+ * Event dispatched when a tool is called.
+ */
+export interface ToolCallEvent extends Event {
+  /**
+   * Tool name being invoked.
+   */
+  name: string;
+
+  /**
+   * Tool arguments supplied by the caller.
+   */
+  arguments: Record<string, unknown>;
+
+  /**
+   * Intercepts execution with a custom tool response.
+   */
+  respondWith: (response: ToolResponse) => void;
+}
+
+// ============================================================================
+// Model Context
+// ============================================================================
+
+/**
+ * Strict WebMCP core interface on navigator.modelContext.
+ */
+export interface ModelContextCore {
+  // ==================== CONTEXT ====================
+
+  /**
+   * Replaces base context with provided tools.
+   */
+  provideContext(options?: ModelContextOptions): void;
+
+  // ==================== TOOLS ====================
+
+  /**
+   * Registers a dynamic tool with JSON Schema-driven inference.
+   *
+   * `execute(args)` is inferred from `inputSchema`, and when a literal object
+   * `outputSchema` is provided, `execute(...).structuredContent` is inferred too.
+   */
+  registerTool<
+    TInputSchema extends JsonSchemaForInference,
+    TOutputSchema extends JsonSchemaObject | undefined = undefined,
+    TName extends string = string,
+  >(tool: ToolDescriptorFromSchema<TInputSchema, TOutputSchema, TName>): void;
+
+  /**
+   * Registers a dynamic tool with explicitly typed args/result.
+   */
+  registerTool<
+    TInputSchema extends InputSchema,
+    TArgs extends Record<string, unknown> = Record<string, unknown>,
+    TResult extends CallToolResult = CallToolResult,
+    TName extends string = string,
+  >(
+    tool: ToolDescriptor<TArgs, TResult, TName> & {
+      inputSchema: TInputSchema;
+    } & (TInputSchema extends InputSchema
+        ? string extends TInputSchema['type']
+          ? unknown
+          : never
+        : unknown)
+  ): void;
+
+  /**
+   * Registers a dynamic tool without an explicit inputSchema.
+   * Runtime defaults this to an empty object schema.
+   */
+  registerTool<
+    TArgs extends Record<string, unknown> = Record<string, unknown>,
+    TResult extends CallToolResult = CallToolResult,
+    TName extends string = string,
+  >(
+    tool: Omit<ToolDescriptor<TArgs, TResult, TName>, 'inputSchema'> & {
+      inputSchema?: undefined;
+    }
+  ): void;
+
+  /**
+   * Unregisters a dynamic tool by name.
+   */
+  unregisterTool(name: string): void;
+
+  /**
+   * Clears all context (base + dynamic registrations).
+   */
+  clearContext(): void;
+}
+
+/**
+ * MCPB extension surface layered on top of strict WebMCP core.
+ * These members are intentionally non-standard.
+ */
+export interface ModelContextExtensions {
+  /**
+   * Lists currently registered tools.
+   */
+  listTools(): ToolListItem[];
+
+  /**
+   * Executes a registered tool.
+   */
+  callTool<
+    TName extends string = string,
+    TArgs extends Record<string, unknown> = Record<string, unknown>,
+  >(params: { name: TName; arguments?: TArgs }): Promise<ToolResponse>;
+
+  // ==================== EVENTS ====================
+
+  /**
+   * Adds a listener for tool invocation events.
+   */
+  addEventListener(
+    type: 'toolcall',
+    listener: (event: ToolCallEvent) => void | Promise<void>,
+    options?: boolean | AddEventListenerOptions
+  ): void;
+
+  /**
+   * Adds a listener for tool list changes.
+   */
+  addEventListener(
+    type: 'toolschanged',
+    listener: () => void,
+    options?: boolean | AddEventListenerOptions
+  ): void;
+
+  /**
+   * Removes a listener for tool invocation events.
+   */
+  removeEventListener(
+    type: 'toolcall',
+    listener: (event: ToolCallEvent) => void | Promise<void>,
+    options?: boolean | EventListenerOptions
+  ): void;
+
+  /**
+   * Removes a listener for tool list changes.
+   */
+  removeEventListener(
+    type: 'toolschanged',
+    listener: () => void,
+    options?: boolean | EventListenerOptions
+  ): void;
+
+  /**
+   * Dispatches an event.
+   */
+  dispatchEvent(event: Event): boolean;
+}
+
+/**
+ * Public navigator.modelContext type (strict core only).
+ */
+export type ModelContext = ModelContextCore;
+
+/**
+ * Full runtime shape including MCPB extensions.
+ */
+export type ModelContextWithExtensions = ModelContextCore & ModelContextExtensions;
+
+// ============================================================================
+// Typed Model Context
+// ============================================================================
+
+/**
+ * Strongly-typed `ModelContext` view derived from known tool descriptors.
+ *
+ * This is useful when your project has a static tool registry and you want
+ * name-aware inference for `callTool`.
+ */
+export type TypedModelContext<
+  TTools extends readonly { name: string }[] = readonly ToolDescriptor[],
+> = ModelContextWithExtensions & {
+  /**
+   * Executes a known tool with name-aware argument and response inference.
+   */
+  callTool<TName extends ToolName<TTools>>(
+    params: ToolCallParams<TName, ToolArgsByName<TTools, TName>>
+  ): Promise<ToolResultByName<TTools, TName>>;
+
+  /**
+   * Fallback call signature for unknown or dynamically-discovered tools.
+   */
+  callTool(params: { name: string; arguments?: Record<string, unknown> }): Promise<ToolResponse>;
+
+  /**
+   * Lists tools with a narrowed name union.
+   */
+  listTools(): Array<ToolListItem<ToolName<TTools>>>;
+};