@mcp-b/webmcp-types 0.1.0 → 0.2.1

package/README.md

@@ -2,34 +2,46 @@
 
 Strict TypeScript type definitions for the WebMCP core API (`navigator.modelContext`).
 
-Zero dependencies. Zero runtime. Just `.d.ts` declarations.
+Zero runtime. Zero side effects. Just `.d.ts` types.
 
-## What's included
+## Type Safety First
 
-- Global `Navigator` augmentation (`navigator.modelContext`)
-- Core descriptors: tools
-- Content and result payload types (`ContentBlock`, `CallToolResult`, `ResourceContents`)
-- MCPB extension API types (`ModelContextExtensions`, including `callTool`)
-- Tool execution client types (`ModelContextClient`, `ToolExecutionContext`)
-- Typed event surface (`ToolCallEvent`)
-- Pure JSON Schema inference helpers (`JsonSchemaForInference`, `InferArgsFromInputSchema`, `ToolDescriptorFromSchema`, `ToolResultFromOutputSchema`)
+This package is the type-safety source of truth for WebMCP.
+
+- Infer tool input args from literal `inputSchema`
+- Infer `structuredContent` from literal `outputSchema`
+- Keep safe fallbacks (`Record<string, unknown>`) when schemas are widened/runtime-defined
+- Provide name-aware typed registries with `TypedModelContext`
+
+## Why This Package
+
+- Global `Navigator` augmentation for `navigator.modelContext`
+- Strongly typed tool descriptors and tool responses
+- Literal JSON Schema inference for tool args and `structuredContent`
+- Name-aware helper types for typed tool registries
+- Runtime-agnostic: works with native implementations, polyfills, or adapters
+
+## Package Selection
+
+| Package | Use When |
+| --- | --- |
+| `@mcp-b/webmcp-types` | You only need compile-time types |
+| `@mcp-b/webmcp-polyfill` | You need strict WebMCP core runtime behavior |
+| `@mcp-b/global` | You want core + MCPB bridge extensions (`callTool`, prompts, resources, etc.) |
 
 ## Install
 
 ```bash
-npm install --save-dev @mcp-b/webmcp-types
-# or
 pnpm add -D @mcp-b/webmcp-types
+# or
+npm install --save-dev @mcp-b/webmcp-types
 ```
 
-If your published library exposes `@mcp-b/webmcp-types` in its own `.d.ts` surface, install it as a production dependency instead of a dev dependency.
-
-## Usage
+If your published library exposes these types in its public declarations, install as a production dependency instead of a dev dependency.
 
-### Enable global types
+## Activate Global Types
 
-TypeScript does not always include global declarations from regular npm packages automatically.
-Use one of the following activation methods:
+TypeScript may not automatically include global declarations from npm packages. Use one of these:
 
 1. Add to `tsconfig.json`:
 
@@ -43,145 +55,19 @@ Use one of the following activation methods:
 
 2. Add a triple-slash reference in a global `.d.ts` file:
 
-```typescript
+```ts
 /// <reference types="@mcp-b/webmcp-types" />
 ```
 
-3. Add a type-only import in your app/library entry:
+3. Add a type-only import:
 
-```typescript
+```ts
 import type {} from '@mcp-b/webmcp-types';
 ```
 
-### Global API example
-
-After activating the types, `navigator.modelContext` is available on `Navigator`:
-
-```typescript
-// No import needed - types are globally augmented
-navigator.modelContext.registerTool({
-  name: 'search',
-  description: 'Search the web',
-  inputSchema: {
-    type: 'object',
-    properties: { query: { type: 'string' } },
-    required: ['query'],
-  },
-  execute: async ({ query }) => ({
-    content: [{ type: 'text', text: `Results for: ${query}` }],
-  }),
-});
-```
-
-### Individual imports
-
-```typescript
-import type {
-  ElicitationParams,
-  ElicitationResult,
-  InferArgsFromInputSchema,
-  JsonSchemaForInference,
-  LooseContentBlock,
-  MaybePromise,
-  ModelContext,
-  ModelContextClient,
-  ModelContextExtensions,
-  ToolExecutionContext,
-  ToolDescriptor,
-  ToolDescriptorFromSchema,
-  ToolResultFromOutputSchema,
-  TypedModelContext,
-  CallToolResult,
-} from '@mcp-b/webmcp-types';
-```
-
-### Sync or async execute handlers
-
-`execute` can return a plain result or a `Promise`.
-
-```typescript
-import type { CallToolResult, ToolDescriptor } from '@mcp-b/webmcp-types';
-
-const syncTool: ToolDescriptor<{ message: string }, CallToolResult, 'sync_echo'> = {
-  name: 'sync_echo',
-  description: 'Synchronous echo',
-  inputSchema: {
-    type: 'object',
-    properties: { message: { type: 'string' } },
-    required: ['message'],
-  },
-  execute(args) {
-    return {
-      content: [{ type: 'text', text: args.message }],
-    };
-  },
-};
-```
-
-### Strict and loose content blocks
-
-`CallToolResult.content` accepts strict MCP content blocks and pragmatic loose objects.
-
-```typescript
-import type { CallToolResult } from '@mcp-b/webmcp-types';
-
-const result: CallToolResult = {
-  content: [
-    { type: 'text', text: 'strict block' },
-    { text: 'loose block', data: 'opaque payload' },
-  ],
-};
-```
-
-### Typed tool descriptors
-
-```typescript
-import type { ToolDescriptor } from '@mcp-b/webmcp-types';
-
-type SearchArgs = {
-  query: string;
-  limit?: number;
-};
-
-const searchTool: ToolDescriptor<SearchArgs> = {
-  name: 'search',
-  description: 'Search indexed docs',
-  inputSchema: {
-    type: 'object',
-    properties: {
-      query: { type: 'string' },
-      limit: { type: 'number' },
-    },
-    required: ['query'],
-  },
-  execute: async ({ query, limit }, context) => {
-    const approval = await context.requestUserInteraction(async () => ({
-      confirmed: true,
-    }));
-
-    if (
-      typeof approval !== 'object' ||
-      !approval ||
-      !('confirmed' in approval) ||
-      !approval.confirmed
-    ) {
-      return {
-        content: [{ type: 'text', text: 'Search cancelled by user.' }],
-      };
-    }
+## Quick Start
 
-    return {
-      content: [{ type: 'text', text: `Searching for "${query}" (limit: ${limit ?? 10})` }],
-    };
-  },
-};
-```
-
-### Pure JSON Schema inference (input + output)
-
-Inference focuses on core keywords (`type`, `properties`, `required`, `items`, `enum`, `const`) and tolerates additional schema metadata.
-
-```typescript
+```ts
 import type { JsonSchemaForInference } from '@mcp-b/webmcp-types';
 
 const inputSchema = {
@@ -198,10 +84,7 @@ const outputSchema = {
   type: 'object',
   properties: {
     total: { type: 'integer' },
-    items: {
-      type: 'array',
-      items: { type: 'string' },
-    },
+    items: { type: 'array', items: { type: 'string' } },
   },
   required: ['total'],
   additionalProperties: false,
@@ -213,13 +96,11 @@ navigator.modelContext.registerTool({
   inputSchema,
   outputSchema,
   async execute(args) {
-    // args is inferred as:
-    // { query: string; limit?: number }
+    // args is inferred as: { query: string; limit?: number }
     return {
       content: [{ type: 'text', text: `Searching for ${args.query}` }],
-      // structuredContent is inferred from outputSchema as:
-      // { total: number; items?: string[] }
       structuredContent: {
+        // inferred from outputSchema
         total: 1,
         items: [args.query],
       },
@@ -228,79 +109,123 @@ navigator.modelContext.registerTool({
 });
 ```
 
-If your schema is not a literal (for example loaded from runtime config), inference safely falls back to `Record<string, unknown>`.
+## Strict Type Inference Deep Dive
 
-### Tool-scoped elicitation
+### 1. Inference works best with literal schemas
 
-```typescript
-import type { ModelContextExtensions } from '@mcp-b/webmcp-types';
-
-const modelContext = navigator.modelContext as Navigator['modelContext'] & ModelContextExtensions;
+Use `as const satisfies JsonSchemaForInference` so TypeScript preserves literal schema information.
 
-modelContext.registerTool({
-  name: 'deploy',
-  description: 'Deploy current build',
-  inputSchema: {
-    type: 'object',
-    properties: {
-      environment: { type: 'string' },
-    },
-    required: ['environment'],
-  },
-  async execute({ environment }, context) {
-    const confirmation = await context.requestUserInteraction(async () => ({
-      action: 'accept',
-      content: { confirm: true },
-    }));
-
-    if (confirmation.action !== 'accept' || !confirmation.content?.confirm) {
-      return {
-        content: [{ type: 'text', text: 'Deployment cancelled.' }],
-      };
-    }
+If schema types are widened (for example `InputSchema` loaded at runtime), inference intentionally falls back to:
 
-    return {
-      content: [{ type: 'text', text: `Deployment started for ${environment}.` }],
-    };
-  },
-};
+```ts
+Record<string, unknown>
 ```
 
-### Name-aware typed context (advanced)
+### 2. Input inference rules
+
+`InferArgsFromInputSchema<T>` and schema-driven `registerTool(...)` inference use a focused subset:
+
+- `type`
+- `properties`
+- `required`
+- `items`
+- `enum`
+- `const`
+- `nullable`
+- `additionalProperties`
+
+Other schema keywords are accepted as metadata but do not add new inferred structure.
+
+### 3. `additionalProperties` behavior
+
+| Schema shape | Inferred extras |
+| --- | --- |
+| `additionalProperties: false` | No extra keys |
+| `additionalProperties` omitted/`true` | Extra keys allowed as `unknown` |
+| `additionalProperties: { ... }` with no named `properties` | Map-like `Record<string, ...>` |
+| `additionalProperties: { ... }` with named `properties` | Named properties inferred, extras remain `unknown` |
+
+### 4. Required keys depend on literal `required`
 
-```typescript
+If `required` is widened (for example a runtime `string[]`), fields are treated as optional by design.
+
+### 5. Output inference from `outputSchema`
+
+When `outputSchema` is a literal object schema, `structuredContent` is inferred automatically via `ToolResultFromOutputSchema`.
+
+This catches enum/type mismatches at compile time.
+
+### 6. Explicit typing is still available
+
+You can always provide explicit generic args/results with `ToolDescriptor<TArgs, TResult, TName>` when schema inference is not enough for your use case.
+
+## Name-Aware Typed Context (Advanced)
+
+`TypedModelContext<TTools>` gives literal-name-aware `callTool(...)` typing for known registries.
+
+```ts
 import type { CallToolResult, ToolDescriptor, TypedModelContext } from '@mcp-b/webmcp-types';
 
 type SearchTool = ToolDescriptor<
-  { query: string },
+  { query: string; limit?: number },
   CallToolResult & { structuredContent: { total: number } },
   'search'
 >;
 
 type PingTool = ToolDescriptor<Record<string, never>, CallToolResult, 'ping'>;
-
 type AppModelContext = TypedModelContext<readonly [SearchTool, PingTool]>;
+
 declare const modelContext: AppModelContext;
 
-const searchResult = await modelContext.callTool({
+await modelContext.callTool({
   name: 'search',
   arguments: { query: 'webmcp' },
 });
-// searchResult is inferred from the 'search' tool result type.
 
 await modelContext.callTool({ name: 'ping' });
-// 'ping' arguments are optional because the args type is Record<string, never>.
+// arguments are optional for Record<string, never> tools
 ```
 
-## Relationship to Runtime Packages
+## Core and Extension Surfaces
 
-| Package | Purpose |
-|---------|---------|
-| `@mcp-b/webmcp-types` | Type definitions only - for libraries that need to type-check against the API |
-| `@mcp-b/webmcp-polyfill` | Strict core runtime polyfill for `navigator.modelContext` |
-| `@mcp-b/global` | Full MCPB runtime (core + bridge extensions like `callTool`, prompts, resources) |
+`Navigator['modelContext']` is typed as strict core WebMCP methods only.
+
+Extension methods are available via `ModelContextExtensions` and `ModelContextWithExtensions`:
+
+```ts
+import type { ModelContextExtensions } from '@mcp-b/webmcp-types';
+
+const modelContext = navigator.modelContext as Navigator['modelContext'] & ModelContextExtensions;
+const tools = modelContext.listTools();
+const result = await modelContext.callTool({
+  name: 'search',
+  arguments: { query: 'docs' },
+});
+
+void tools;
+void result;
+```
 
-Use `@mcp-b/webmcp-types` when you only need types (e.g., building a library that accepts `ToolDescriptor`). Use `@mcp-b/webmcp-polyfill` for strict core runtime behavior, or `@mcp-b/global` for extension-heavy bridge workflows.
+## Commonly Used Exports
+
+| Export | Purpose |
+| --- | --- |
+| `ModelContext` | Strict core `navigator.modelContext` type |
+| `ToolDescriptor` | Explicitly typed tool descriptor |
+| `ToolDescriptorFromSchema` | Schema-driven descriptor with inferred args/result |
+| `JsonSchemaForInference` | Supported JSON Schema subset for inference |
+| `InferArgsFromInputSchema` | Derive args shape from a schema type |
+| `ToolResultFromOutputSchema` | Derive `structuredContent` type from output schema |
+| `TypedModelContext` | Name-aware typed `callTool`/`listTools` for known registries |
+| `CallToolResult` | Tool response type |
+| `ContentBlock` / `LooseContentBlock` | Strict and pragmatic content block typing |
+| `ModelContextClient` | Tool execution client (`requestUserInteraction`) |
+
+## Important Notes
+
+- This package does not install any runtime behavior.
+- Runtime validation/execution behavior depends on your WebMCP runtime package.
+- `navigator.modelContextTesting` is typed as optional for compatibility with Chromium preview/testing surfaces.
 
 ## License
 

package/dist/model-context.d.ts

@@ -142,7 +142,7 @@ export interface ModelContextCore {
      */
     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;
-    } & (string extends TInputSchema['type'] ? unknown : never)): void;
+    } & (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.

package/dist/model-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"model-context.d.ts","sourceRoot":"","sources":["../src/model-context.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"model-context.d.ts","sourceRoot":"","sources":["../src/model-context.ts"],"names":[],"mappings":"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"}

package/dist/standard-schema.d.ts

@@ -0,0 +1,32 @@
+import type { StandardJSONSchemaV1 as BaseStandardJSONSchemaV1, StandardSchemaV1 as BaseStandardSchemaV1, StandardTypedV1 } from '@standard-schema/spec';
+import type { InputSchema } from './common.js';
+/**
+ * Re-export of the official Standard Schema spec types.
+ */
+export type { BaseStandardJSONSchemaV1 as StandardJSONSchemaV1, BaseStandardSchemaV1 as StandardSchemaV1, StandardTypedV1, };
+/**
+ * Standard Schema validator constrained to object-like tool args.
+ */
+export type StandardInputValidatorSchema = BaseStandardSchemaV1<Record<string, unknown>, Record<string, unknown>>;
+/**
+ * Standard JSON Schema converter constrained to object-like tool args.
+ */
+export type StandardInputJsonSchema = BaseStandardJSONSchemaV1<Record<string, unknown>, Record<string, unknown>>;
+/**
+ * Schema that supports both Standard Schema validation and JSON Schema conversion.
+ */
+export type StandardInputSchemaWithJson = StandardInputValidatorSchema & StandardInputJsonSchema;
+/**
+ * Any input schema accepted by tool descriptors.
+ *
+ * Runtime adapters may normalize all inputs to a Standard Schema validator.
+ * When a schema implements both Standard Schema validation and Standard JSON
+ * Schema conversion, adapters may prefer JSON conversion to keep validation
+ * errors consistent across plain JSON Schema and Standard-compatible inputs.
+ */
+export type ToolInputSchema = InputSchema | StandardInputValidatorSchema | StandardInputJsonSchema;
+/**
+ * Any output schema accepted by tool descriptors.
+ */
+export type ToolOutputSchema = InputSchema | StandardInputJsonSchema;
+//# sourceMappingURL=standard-schema.d.ts.map

package/dist/standard-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"standard-schema.d.ts","sourceRoot":"","sources":["../src/standard-schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,oBAAoB,IAAI,wBAAwB,EAChD,gBAAgB,IAAI,oBAAoB,EACxC,eAAe,EAChB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C;;GAEG;AACH,YAAY,EACV,wBAAwB,IAAI,oBAAoB,EAChD,oBAAoB,IAAI,gBAAgB,EACxC,eAAe,GAChB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,4BAA4B,GAAG,oBAAoB,CAC7D,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACvB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CACxB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,uBAAuB,GAAG,wBAAwB,CAC5D,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACvB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CACxB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,2BAA2B,GAAG,4BAA4B,GAAG,uBAAuB,CAAC;AAEjG;;;;;;;GAOG;AACH,MAAM,MAAM,eAAe,GAAG,WAAW,GAAG,4BAA4B,GAAG,uBAAuB,CAAC;AAEnG;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,WAAW,GAAG,uBAAuB,CAAC"}

package/dist/tool.d.ts

@@ -56,7 +56,7 @@ export type MaybePromise<T> = T | Promise<T>;
  * Tool descriptor for the Web Model Context API.
  *
  * Tools are functions that AI models can call to perform actions or retrieve
- * information. This interface uses JSON Schema for input validation.
+ * information. This interface uses JSON Schema for input/output typing.
  *
  * @template TArgs - Tool input arguments.
  * @template TResult - Tool execution result shape.
@@ -74,11 +74,11 @@ export interface ToolDescriptor<TArgs extends Record<string, unknown> = Record<s
      */
     description: string;
     /**
-     * JSON Schema describing accepted input arguments.
+     * Schema describing accepted input arguments.
      */
     inputSchema?: InputSchema;
     /**
-     * Optional JSON Schema describing output payload shape.
+     * Optional schema describing output payload shape.
      */
     outputSchema?: InputSchema;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcp-b/webmcp-types",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Strict TypeScript type definitions for the WebMCP core API (navigator.modelContext)",
   "keywords": [
     "webmcp",
@@ -39,7 +39,10 @@
     "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"
   },
@@ -56,6 +59,8 @@
     "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/model-context.ts

@@ -210,7 +210,11 @@ export interface ModelContextCore {
   >(
     tool: ToolDescriptor<TArgs, TResult, TName> & {
       inputSchema: TInputSchema;
-    } & (string extends TInputSchema['type'] ? unknown : never)
+    } & (TInputSchema extends InputSchema
+        ? string extends TInputSchema['type']
+          ? unknown
+          : never
+        : unknown)
   ): void;
 
   /**

package/src/tool.ts

@@ -78,7 +78,7 @@ export type MaybePromise<T> = T | Promise<T>;
  * Tool descriptor for the Web Model Context API.
  *
  * Tools are functions that AI models can call to perform actions or retrieve
- * information. This interface uses JSON Schema for input validation.
+ * information. This interface uses JSON Schema for input/output typing.
  *
  * @template TArgs - Tool input arguments.
  * @template TResult - Tool execution result shape.
@@ -102,12 +102,12 @@ export interface ToolDescriptor<
   description: string;
 
   /**
-   * JSON Schema describing accepted input arguments.
+   * Schema describing accepted input arguments.
    */
   inputSchema?: InputSchema;
 
   /**
-   * Optional JSON Schema describing output payload shape.
+   * Optional schema describing output payload shape.
    */
   outputSchema?: InputSchema;