@mcp-b/webmcp-polyfill 0.2.0 → 0.2.1

package/README.md

@@ -11,6 +11,21 @@ Strict WebMCP core runtime polyfill for `navigator.modelContext`.
 
 It does not install MCP bridge extensions like `callTool`, resources, or prompts.
 
+Important:
+
+- `navigator.modelContext` in this package does not provide `listTools()` or `callTool(...)`.
+- For list/execute test flows, use `navigator.modelContextTesting` (when `installTestingShim` is enabled).
+
+## Type Safety First
+
+`@mcp-b/webmcp-polyfill` is runtime-focused. For compile-time safety, pair it with
+`@mcp-b/webmcp-types`.
+
+Recommended setup:
+
+- `@mcp-b/webmcp-polyfill` for strict runtime behavior
+- `@mcp-b/webmcp-types` for schema-driven TypeScript inference
+
 ## Package Selection
 
 | Package | Use When |
@@ -59,6 +74,45 @@ navigator.modelContext.registerTool({
 
 The IIFE auto-initializes by default.
 
+## Type Inference (with `@mcp-b/webmcp-types`)
+
+The polyfill provides runtime behavior. For strict compile-time inference, pair it with `@mcp-b/webmcp-types`.
+
+```ts
+import type { JsonSchemaForInference } from '@mcp-b/webmcp-types';
+import { initializeWebMCPPolyfill } from '@mcp-b/webmcp-polyfill';
+
+initializeWebMCPPolyfill();
+
+const inputSchema = {
+  type: 'object',
+  properties: {
+    query: { type: 'string' },
+    limit: { type: 'integer', minimum: 1, maximum: 50 },
+  },
+  required: ['query'],
+  additionalProperties: false,
+} as const satisfies JsonSchemaForInference;
+
+navigator.modelContext.registerTool({
+  name: 'search',
+  description: 'Search indexed docs',
+  inputSchema,
+  async execute(args) {
+    // Inferred type:
+    // { query: string; limit?: number }
+    return {
+      content: [{ type: 'text', text: `Searching for ${args.query} (${args.limit ?? 10})` }],
+    };
+  },
+});
+```
+
+Inference notes:
+
+- Best results come from literal schemas (`as const satisfies JsonSchemaForInference`).
+- Widened/runtime schemas fall back to `Record<string, unknown>` for safety.
+
 ## API
 
 ### `initializeWebMCPPolyfill(options?)`
@@ -107,6 +161,29 @@ Restores previous `navigator.modelContext` and `navigator.modelContextTesting` d
 
 - Removes all registered tools.
 
+## Listing and Executing Tools
+
+In `@mcp-b/webmcp-polyfill`, listing and execution helpers are exposed on
+`navigator.modelContextTesting` (not `navigator.modelContext`) when the testing shim is enabled.
+
+```ts
+import { initializeWebMCPPolyfill } from '@mcp-b/webmcp-polyfill';
+
+initializeWebMCPPolyfill({ installTestingShim: true });
+
+const tools = navigator.modelContextTesting?.listTools();
+const result = await navigator.modelContextTesting?.executeTool(
+  'search',
+  JSON.stringify({ query: 'webmcp' })
+);
+
+void tools;
+void result;
+```
+
+If you want `callTool(...)` / extension-style runtime methods on `navigator.modelContext`, use
+`@mcp-b/global`.
+
 ## Input Schema Support
 
 `inputSchema` accepts:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcp-b/webmcp-polyfill",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Strict WebMCP core runtime polyfill for navigator.modelContext",
   "keywords": [
     "webmcp",
@@ -43,7 +43,7 @@
   "dependencies": {
     "@cfworker/json-schema": "^4.1.1",
     "@standard-schema/spec": "^1.1.0",
-    "@mcp-b/webmcp-types": "0.2.0"
+    "@mcp-b/webmcp-types": "0.2.1"
   },
   "devDependencies": {
     "@vitest/browser": "^4.0.18",