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

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@mcp-b/webmcp-types",
+  "version": "0.0.0-beta-20260216200013",
+  "description": "Strict TypeScript type definitions for the WebMCP core API (navigator.modelContext)",
+  "keywords": [
+    "webmcp",
+    "model-context",
+    "navigator-modelcontext",
+    "types",
+    "typescript",
+    "web-standard"
+  ],
+  "homepage": "https://docs.mcp-b.ai/packages/webmcp-types",
+  "bugs": {
+    "url": "https://github.com/WebMCP-org/npm-packages/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/WebMCP-org/npm-packages.git",
+    "directory": "packages/webmcp-types"
+  },
+  "license": "MIT",
+  "author": "Alex Nahas",
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "main": "",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src/common.ts",
+    "src/index.ts",
+    "src/json-schema.ts",
+    "src/model-context.ts",
+    "src/tool.ts"
+  ],
+  "devDependencies": {
+    "@vitest/browser": "^4.0.18",
+    "@vitest/browser-playwright": "^4.0.18",
+    "@vitest/coverage-v8": "^4.0.18",
+    "playwright": "^1.58.0",
+    "typescript": "^5.8.3",
+    "vitest": "^4.0.18"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "check": "biome check --write .",
+    "clean": "rm -rf dist .turbo",
+    "format": "biome format --write .",
+    "lint": "biome lint --write .",
+    "publish:dry": "pnpm publish --access public --dry-run",
+    "publish:npm": "pnpm publish --access public",
+    "test": "vitest run && pnpm run test:conformance",
+    "test:browser": "vitest run --config vitest.browser.config.ts --browser.headless",
+    "test:browser:ui": "vitest --config vitest.browser.config.ts --browser",
+    "test:conformance": "vitest run --config vitest.conformance.config.ts",
+    "typecheck": "tsc --noEmit && vitest run --typecheck --silent"
+  }
+}

package/src/common.ts

@@ -0,0 +1,368 @@
+// ============================================================================
+// 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 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;
+}
+
+/**
+ * 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?: JsonObject;
+
+  /**
+   * 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[]>;
+}
+
+/**
+ * Registration handle returned by registration methods.
+ */
+export interface RegistrationHandle {
+  /**
+   * Unregisters the associated item.
+   */
+  unregister: () => void;
+}

package/src/index.ts

@@ -0,0 +1,95 @@
+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,
+} 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,
+  ModelContext,
+  ModelContextCore,
+  ModelContextExtensions,
+  ModelContextInput,
+  ModelContextOptions,
+  ModelContextTesting,
+  ModelContextTestingExecuteToolOptions,
+  ModelContextTestingPolyfillExtensions,
+  ModelContextTestingToolInfo,
+  ModelContextWithExtensions,
+  ToolArgsByName,
+  ToolByName,
+  ToolCallEvent,
+  ToolCallParams,
+  ToolName,
+  ToolResultByName,
+  TypedModelContext,
+} from './model-context.js';
+export type {
+  MaybePromise,
+  ModelContextClient,
+  ToolAnnotations,
+  ToolDescriptor,
+  ToolDescriptorFromSchema,
+  ToolExecutionContext,
+  ToolListItem,
+  ToolResultFromOutputSchema,
+} from './tool.js';
+
+// ============================================================================
+// Global Augmentation
+// ============================================================================
+
+declare global {
+  interface Navigator {
+    /**
+     * Web Model Context API strict core surface.
+     */
+    modelContext: ModelContext;
+
+    /**
+     * Web Model Context testing API surface (Chromium early preview).
+     * @deprecated Prefer navigator.modelContext.callTool(...) and toolschanged events
+     * for in-page consumers. Chromium still exposes this API for testing flows.
+     */
+    modelContextTesting?: ModelContextTesting;
+  }
+}