@mcp-b/webmcp-polyfill 2.3.2 → 3.0.0-beta.20260702171253

package/dist/index.js

@@ -1,61 +1,47 @@
-import { Validator } from "@cfworker/json-schema";
+import { isPlainObject, normalizeInputSchema, toJsonValue, validateValueWithSchema } from "./schema.js";
 
 //#region src/index.ts
 const FAILED_TO_PARSE_INPUT_ARGUMENTS_MESSAGE = "Failed to parse input arguments";
 const TOOL_INVOCATION_FAILED_MESSAGE = "Tool was executed but the invocation failed. For example, the script function threw an error";
 const TOOL_CANCELLED_MESSAGE = "Tool was cancelled";
-const DEFAULT_INPUT_SCHEMA = {
-	type: "object",
-	properties: {}
-};
-const STANDARD_JSON_SCHEMA_TARGETS = ["draft-2020-12", "draft-07"];
+/** WebMCP §4.2 tool name: ASCII alnum, underscore, hyphen, period; 1–128 code points. */
+const VALID_TOOL_NAME_RE = /^[A-Za-z0-9_\-.]{1,128}$/u;
 const POLYFILL_MARKER_PROPERTY = "__isWebMCPPolyfill";
 const STANDARD_VALIDATOR_SYMBOL = Symbol("standardValidator");
+function createAbortError() {
+	return new DOMException("signal is aborted without reason", "AbortError");
+}
 const installState = {
 	installed: false,
-	previousModelContextDescriptor: void 0,
-	previousModelContextTestingDescriptor: void 0
+	previousNavigatorModelContextDescriptor: void 0,
+	previousNavigatorModelContextTestingDescriptor: void 0,
+	previousDocumentModelContextDescriptor: void 0,
+	installedNavigatorModelContext: false,
+	installedNavigatorModelContextTesting: false,
+	installedDocumentModelContext: false
 };
 var StrictWebMCPContext = class extends EventTarget {
 	tools = /* @__PURE__ */ new Map();
 	testingShim = null;
 	_ontoolchange = null;
-	provideContextDeprecationWarned = false;
-	clearContextDeprecationWarned = false;
 	unregisterToolDeprecationWarned = false;
+	toolsChangedQueued = false;
 	get ontoolchange() {
 		return this._ontoolchange;
 	}
 	set ontoolchange(handler) {
 		this._ontoolchange = handler;
 	}
-	provideContext(options = {}) {
-		this.warnProvideContextDeprecationOnce();
-		const nextTools = /* @__PURE__ */ new Map();
-		for (const tool of options.tools ?? []) {
-			const normalized = normalizeToolDescriptor(tool, nextTools);
-			nextTools.set(normalized.name, normalized);
-		}
-		this.tools = nextTools;
-		this.notifyToolsChanged();
-	}
-	clearContext() {
-		this.warnClearContextDeprecationOnce();
-		this.tools.clear();
-		this.notifyToolsChanged();
-	}
 	registerTool(tool, options) {
 		const signal = options?.signal;
-		if (signal?.aborted) {
-			console.warn(`[WebMCPPolyfill] registerTool("${tool?.name ?? "<unknown>"}") skipped: options.signal was already aborted.`);
-			return;
-		}
+		if (signal?.aborted) return Promise.reject(createAbortError());
 		const normalized = normalizeToolDescriptor(tool, this.tools);
 		this.tools.set(normalized.name, normalized);
 		this.notifyToolsChanged();
 		if (signal) signal.addEventListener("abort", () => {
 			if (this.tools.delete(normalized.name)) this.notifyToolsChanged();
 		}, { once: true });
+		return Promise.resolve();
 	}
 	unregisterTool(nameOrTool) {
 		this.warnUnregisterToolDeprecationOnce();
@@ -63,7 +49,10 @@ var StrictWebMCPContext = class extends EventTarget {
 		if (this.tools.delete(name)) this.notifyToolsChanged();
 	}
 	getTools() {
-		return this.getToolInfos();
+		return Promise.resolve(this.getRegisteredToolInfos());
+	}
+	executeTool(tool, inputArgsJson, options) {
+		return this.executeToolByName(tool.name, inputArgsJson, options, false);
 	}
 	getTestingShim() {
 		if (!this.testingShim) this.testingShim = new PolyfillTestingShim(this);
@@ -85,8 +74,23 @@ var StrictWebMCPContext = class extends EventTarget {
 			};
 		});
 	}
+	/** @internal Used by getTools() */
+	getRegisteredToolInfos() {
+		return this.getToolInfos().map((toolInfo) => {
+			const tool = this.tools.get(toolInfo.name);
+			return {
+				...toolInfo,
+				title: tool?.title ?? "",
+				origin: globalThis.location?.origin ?? "",
+				window: globalThis.window
+			};
+		});
+	}
 	/** @internal Used by PolyfillTestingShim */
 	async executeToolForTesting(toolName, inputArgsJson, options) {
+		return this.executeToolByName(toolName, inputArgsJson, options, true);
+	}
+	async executeToolByName(toolName, inputArgsJson, options, normalizeResult) {
 		if (options?.signal?.aborted) throw createUnknownError(TOOL_CANCELLED_MESSAGE);
 		const tool = this.tools.get(toolName);
 		if (!tool) throw createUnknownError(`Tool not found: ${toolName}`);
@@ -101,7 +105,13 @@ var StrictWebMCPContext = class extends EventTarget {
 		} };
 		try {
 			const execution = tool.execute(args, client);
-			return toSerializedTestingResult(normalizeToolResponse(await withAbortSignal(Promise.resolve(execution), options?.signal)));
+			const rawResult = await withAbortSignal(Promise.resolve(execution), options?.signal);
+			const normalizedResult = normalizeToolResponse(rawResult);
+			const outputValidationError = validateOutputForTool(normalizedResult, tool);
+			if (outputValidationError) throw new Error(outputValidationError);
+			if (normalizeResult) return toSerializedTestingResult(normalizedResult);
+			const serialized = JSON.stringify(rawResult);
+			return serialized === void 0 ? null : serialized;
 		} catch (error) {
 			throw createUnknownError(error instanceof Error ? `${TOOL_INVOCATION_FAILED_MESSAGE}: ${error.message}` : TOOL_INVOCATION_FAILED_MESSAGE);
 		} finally {
@@ -109,7 +119,10 @@ var StrictWebMCPContext = class extends EventTarget {
 		}
 	}
 	notifyToolsChanged() {
+		if (this.toolsChangedQueued) return;
+		this.toolsChangedQueued = true;
 		queueMicrotask(() => {
+			this.toolsChangedQueued = false;
 			const event = new Event("toolchange");
 			try {
 				this._ontoolchange?.call(this, event);
@@ -120,16 +133,6 @@ var StrictWebMCPContext = class extends EventTarget {
 			this.testingShim?.dispatchToolChange();
 		});
 	}
-	warnProvideContextDeprecationOnce() {
-		if (this.provideContextDeprecationWarned) return;
-		this.provideContextDeprecationWarned = true;
-		console.warn("[WebMCPPolyfill] navigator.modelContext.provideContext() is deprecated and will be removed in the next major version. Register tools individually with registerTool() instead.");
-	}
-	warnClearContextDeprecationOnce() {
-		if (this.clearContextDeprecationWarned) return;
-		this.clearContextDeprecationWarned = true;
-		console.warn("[WebMCPPolyfill] navigator.modelContext.clearContext() is deprecated and will be removed in the next major version. Unregister individual tools instead.");
-	}
 	warnUnregisterToolDeprecationOnce() {
 		if (this.unregisterToolDeprecationWarned) return;
 		this.unregisterToolDeprecationWarned = true;
@@ -194,6 +197,15 @@ function createUnknownError(message) {
 		return error;
 	}
 }
+function createInvalidStateError(message) {
+	try {
+		return new DOMException(message, "InvalidStateError");
+	} catch {
+		const error = new Error(message);
+		error.name = "InvalidStateError";
+		return error;
+	}
+}
 function parseInputArgsJson(inputArgsJson) {
 	let parsed;
 	try {
@@ -209,131 +221,11 @@ function getToolNameForUnregister(nameOrTool) {
 	if (isPlainObject(nameOrTool) && typeof nameOrTool.name === "string") return nameOrTool.name;
 	throw new TypeError("Failed to execute 'unregisterTool' on 'ModelContext': parameter 1 must be a string or an object with a string name.");
 }
-function isPlainObject(value) {
-	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
-}
-function getStandardProps(value) {
-	if (!isPlainObject(value)) return null;
-	const standard = value["~standard"];
-	if (!isPlainObject(standard)) return null;
-	return standard;
-}
-function isStandardInputValidatorSchema(value) {
-	const standard = getStandardProps(value);
-	return Boolean(standard && standard.version === 1 && typeof standard.validate === "function");
-}
-function isStandardInputJsonSchema(value) {
-	const standard = getStandardProps(value);
-	if (!standard || standard.version !== 1 || !isPlainObject(standard.jsonSchema)) return false;
-	return typeof standard.jsonSchema.input === "function";
-}
-function createStandardValidatorFromJsonSchema(schema) {
-	return { "~standard": {
-		version: 1,
-		vendor: "@mcp-b/webmcp-polyfill-json-schema",
-		validate(value) {
-			if (!isPlainObject(value)) return { issues: [{ message: "expected object arguments" }] };
-			const issue = validateArgsWithSchema(value, schema);
-			if (issue) return { issues: [issue] };
-			return { value };
-		}
-	} };
-}
-function convertStandardInputSchema(schema) {
-	for (const target of STANDARD_JSON_SCHEMA_TARGETS) try {
-		const converted = schema["~standard"].jsonSchema.input({ target });
-		validateInputSchema(converted);
-		return converted;
-	} catch (error) {
-		console.warn(`[WebMCPPolyfill] Standard JSON Schema conversion failed for target "${target}":`, error);
-	}
-	throw new Error("Failed to convert Standard JSON Schema inputSchema to a JSON Schema object");
-}
-function normalizeInputSchema(inputSchema) {
-	if (inputSchema === void 0) {
-		const normalized = DEFAULT_INPUT_SCHEMA;
-		return {
-			inputSchema: normalized,
-			standardValidator: createStandardValidatorFromJsonSchema(normalized)
-		};
-	}
-	if (isStandardInputJsonSchema(inputSchema)) {
-		const converted = convertStandardInputSchema(inputSchema);
-		return {
-			inputSchema: converted,
-			standardValidator: createStandardValidatorFromJsonSchema(converted)
-		};
-	}
-	if (isStandardInputValidatorSchema(inputSchema)) return {
-		inputSchema: DEFAULT_INPUT_SCHEMA,
-		standardValidator: inputSchema
-	};
-	validateInputSchema(inputSchema);
-	if (Object.keys(inputSchema).length === 0) return {
-		inputSchema: DEFAULT_INPUT_SCHEMA,
-		standardValidator: createStandardValidatorFromJsonSchema(DEFAULT_INPUT_SCHEMA)
-	};
-	const normalizedSchema = inputSchema.type === void 0 ? {
-		type: "object",
-		...inputSchema
-	} : inputSchema;
-	return {
-		inputSchema: normalizedSchema,
-		standardValidator: createStandardValidatorFromJsonSchema(normalizedSchema)
-	};
-}
-function validateInputSchema(schema) {
-	if (!isPlainObject(schema)) throw new Error("inputSchema must be a JSON Schema object");
-	validateJsonSchemaNode(schema, "$");
-}
-function validateJsonSchemaNode(node, path) {
-	const typeValue = node.type;
-	if (typeValue !== void 0 && typeof typeValue !== "string" && !(Array.isArray(typeValue) && typeValue.every((entry) => typeof entry === "string" && entry.length > 0))) throw new Error(`Invalid JSON Schema at ${path}: "type" must be a string or string[]`);
-	const requiredValue = node.required;
-	if (requiredValue !== void 0 && !(Array.isArray(requiredValue) && requiredValue.every((entry) => typeof entry === "string"))) throw new Error(`Invalid JSON Schema at ${path}: "required" must be an array of strings`);
-	const propertiesValue = node.properties;
-	if (propertiesValue !== void 0) {
-		if (!isPlainObject(propertiesValue)) throw new Error(`Invalid JSON Schema at ${path}: "properties" must be an object`);
-		for (const [key, value] of Object.entries(propertiesValue)) {
-			if (!isPlainObject(value)) throw new Error(`Invalid JSON Schema at ${path}.properties.${key}: expected object schema`);
-			validateJsonSchemaNode(value, `${path}.properties.${key}`);
-		}
-	}
-	const itemsValue = node.items;
-	if (itemsValue !== void 0) if (Array.isArray(itemsValue)) for (const [index, value] of itemsValue.entries()) {
-		if (!isPlainObject(value)) throw new Error(`Invalid JSON Schema at ${path}.items[${index}]: expected object schema`);
-		validateJsonSchemaNode(value, `${path}.items[${index}]`);
-	}
-	else if (isPlainObject(itemsValue)) validateJsonSchemaNode(itemsValue, `${path}.items`);
-	else throw new Error(`Invalid JSON Schema at ${path}: "items" must be an object or object[]`);
-	for (const keyword of [
-		"allOf",
-		"anyOf",
-		"oneOf"
-	]) {
-		const value = node[keyword];
-		if (value === void 0) continue;
-		if (!Array.isArray(value)) throw new Error(`Invalid JSON Schema at ${path}: "${keyword}" must be an array`);
-		for (const [index, entry] of value.entries()) {
-			if (!isPlainObject(entry)) throw new Error(`Invalid JSON Schema at ${path}.${keyword}[${index}]: expected object schema`);
-			validateJsonSchemaNode(entry, `${path}.${keyword}[${index}]`);
-		}
-	}
-	const notValue = node.not;
-	if (notValue !== void 0) {
-		if (!isPlainObject(notValue)) throw new Error(`Invalid JSON Schema at ${path}: "not" must be an object schema`);
-		validateJsonSchemaNode(notValue, `${path}.not`);
-	}
-	try {
-		JSON.stringify(node);
-	} catch {
-		throw new Error(`Invalid JSON Schema at ${path}: schema must be JSON-serializable`);
-	}
-}
 function normalizeToolDescriptor(tool, existing) {
 	if (!tool || typeof tool !== "object") throw new TypeError("registerTool(tool) requires a tool object");
-	if (typeof tool.name !== "string" || tool.name.length === 0) throw new TypeError("Tool \"name\" must be a non-empty string");
-	if (typeof tool.description !== "string" || tool.description.length === 0) throw new TypeError("Tool \"description\" must be a non-empty string");
+	if (typeof tool.name !== "string" || tool.name.length === 0) throw createInvalidStateError("Tool \"name\" must be a non-empty string");
+	if (!VALID_TOOL_NAME_RE.test(tool.name) || Array.from(tool.name).length > 128) throw createInvalidStateError("Tool \"name\" must be 1–128 characters and contain only ASCII alphanumeric, underscore, hyphen, or period");
+	if (typeof tool.description !== "string" || tool.description.length === 0) throw createInvalidStateError("Tool \"description\" must be a non-empty string");
 	if (typeof tool.execute !== "function") throw new TypeError("Tool \"execute\" must be a function");
 	if (existing.has(tool.name)) throw new Error(`Tool already registered: ${tool.name}`);
 	const normalizedInputSchema = normalizeInputSchema(tool.inputSchema);
@@ -352,13 +244,6 @@ function normalizeToolDescriptor(tool, existing) {
 		[STANDARD_VALIDATOR_SYMBOL]: normalizedInputSchema.standardValidator
 	};
 }
-function validateArgsWithSchema(args, schema) {
-	const result = new Validator(schema, "2020-12", true).validate(args);
-	if (result.valid) return null;
-	const error = result.errors[result.errors.length - 1];
-	if (!error) return { message: "Input validation failed" };
-	return { message: error.error };
-}
 function formatStandardIssuePath(path) {
 	if (!path || path.length === 0) return null;
 	const segments = path.map((segment) => {
@@ -387,22 +272,15 @@ async function validateArgsWithStandardSchema(args, schema) {
 async function validateArgsForTool(args, tool) {
 	return validateArgsWithStandardSchema(args, tool[STANDARD_VALIDATOR_SYMBOL]);
 }
+function validateOutputForTool(result, tool) {
+	if (!tool.outputSchema || result.isError) return null;
+	if (result.structuredContent === void 0) return `Output validation error: Tool ${tool.name} has an output schema but no structured content was provided`;
+	const issue = validateValueWithSchema(result.structuredContent, tool.outputSchema);
+	return issue ? `Output validation error: ${issue.message}` : null;
+}
 function isCallToolResult(value) {
 	return isPlainObject(value) && Array.isArray(value.content);
 }
-function isJsonPrimitive(value) {
-	return value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean";
-}
-function isJsonValue(value) {
-	if (isJsonPrimitive(value)) return Number.isFinite(value) || typeof value !== "number";
-	if (Array.isArray(value)) return value.every((entry) => isJsonValue(entry));
-	if (!isPlainObject(value)) return false;
-	return Object.values(value).every((entry) => isJsonValue(entry));
-}
-function toStructuredContent(value) {
-	if (!isPlainObject(value) || !isJsonValue(value)) return;
-	return value;
-}
 function serializeTextContent(value) {
 	if (typeof value === "string") return value;
 	try {
@@ -413,13 +291,13 @@ function serializeTextContent(value) {
 }
 function normalizeToolResponse(value) {
 	if (isCallToolResult(value)) return value;
-	const structuredContent = toStructuredContent(value);
+	const structuredContent = toJsonValue(value);
 	return {
 		content: [{
 			type: "text",
 			text: serializeTextContent(value)
 		}],
-		...structuredContent ? { structuredContent } : {},
+		...structuredContent !== void 0 ? { structuredContent } : {},
 		isError: false
 	};
 }
@@ -462,6 +340,10 @@ function getNavigator() {
 	if (typeof navigator !== "undefined") return navigator;
 	return null;
 }
+function getDocument() {
+	if (typeof document !== "undefined") return document;
+	return null;
+}
 function defineNavigatorProperty(target, key, value) {
 	Object.defineProperty(target, key, {
 		configurable: true,
@@ -470,37 +352,90 @@ function defineNavigatorProperty(target, key, value) {
 		value
 	});
 }
+function defineDocumentModelContextProperty(target, value) {
+	Object.defineProperty(target, "modelContext", {
+		configurable: true,
+		enumerable: true,
+		writable: false,
+		value
+	});
+}
+let navigatorModelContextDeprecationWarned = false;
+function defineDeprecatedNavigatorModelContext(target, value) {
+	Object.defineProperty(target, "modelContext", {
+		configurable: true,
+		enumerable: true,
+		get() {
+			if (!navigatorModelContextDeprecationWarned) {
+				navigatorModelContextDeprecationWarned = true;
+				console.warn("[WebMCPPolyfill] navigator.modelContext is deprecated. The May 27, 2026 WebMCP draft moved the modelContext getter from Navigator to Document — use document.modelContext instead. See https://github.com/webmachinelearning/webmcp/pull/184.");
+			}
+			return value;
+		}
+	});
+}
 function initializeWebMCPPolyfill(options) {
 	const nav = getNavigator();
-	if (!nav) return;
-	if (Boolean(nav.modelContext)) return;
+	const doc = getDocument();
+	if (!nav && !doc) return;
+	const documentModelContext = doc?.modelContext;
+	if (Boolean(documentModelContext)) return;
+	const navigatorModelContext = nav?.modelContext;
+	const hasNavigatorModelContext = Boolean(navigatorModelContext);
 	if (installState.installed) cleanupWebMCPPolyfill();
+	if (doc && navigatorModelContext) {
+		installState.previousDocumentModelContextDescriptor = Object.getOwnPropertyDescriptor(doc, "modelContext");
+		defineDocumentModelContextProperty(doc, navigatorModelContext);
+		installState.installedDocumentModelContext = true;
+		installState.installed = true;
+		return;
+	}
+	if (hasNavigatorModelContext) return;
 	const context = new StrictWebMCPContext();
 	const modelContext = context;
 	modelContext[POLYFILL_MARKER_PROPERTY] = true;
-	installState.previousModelContextDescriptor = Object.getOwnPropertyDescriptor(nav, "modelContext");
-	installState.previousModelContextTestingDescriptor = Object.getOwnPropertyDescriptor(nav, "modelContextTesting");
-	defineNavigatorProperty(nav, "modelContext", modelContext);
-	const installTestingShim = options?.installTestingShim ?? "if-missing";
-	const hasModelContextTesting = Boolean(nav.modelContextTesting);
-	if (installTestingShim === "always" || (installTestingShim === true || installTestingShim === "if-missing") && !hasModelContextTesting) defineNavigatorProperty(nav, "modelContextTesting", context.getTestingShim());
+	if (doc) {
+		installState.previousDocumentModelContextDescriptor = Object.getOwnPropertyDescriptor(doc, "modelContext");
+		defineDocumentModelContextProperty(doc, modelContext);
+		installState.installedDocumentModelContext = true;
+	}
+	if (nav) {
+		installState.previousNavigatorModelContextDescriptor = Object.getOwnPropertyDescriptor(nav, "modelContext");
+		installState.previousNavigatorModelContextTestingDescriptor = Object.getOwnPropertyDescriptor(nav, "modelContextTesting");
+		navigatorModelContextDeprecationWarned = false;
+		defineDeprecatedNavigatorModelContext(nav, modelContext);
+		installState.installedNavigatorModelContext = true;
+		const installTestingShim = options?.installTestingShim ?? "if-missing";
+		const hasModelContextTesting = Boolean(nav.modelContextTesting);
+		if (installTestingShim === "always" || (installTestingShim === true || installTestingShim === "if-missing") && !hasModelContextTesting) {
+			defineNavigatorProperty(nav, "modelContextTesting", context.getTestingShim());
+			installState.installedNavigatorModelContextTesting = true;
+		}
+	}
 	installState.installed = true;
 }
 function cleanupWebMCPPolyfill() {
-	const nav = getNavigator();
-	if (!nav || !installState.installed) return;
-	const restore = (key, previousDescriptor) => {
+	if (!installState.installed) return;
+	const restore = (target, key, previousDescriptor) => {
 		if (previousDescriptor) {
-			Object.defineProperty(nav, key, previousDescriptor);
+			Object.defineProperty(target, key, previousDescriptor);
 			return;
 		}
-		delete nav[key];
+		delete target[key];
 	};
-	restore("modelContext", installState.previousModelContextDescriptor);
-	restore("modelContextTesting", installState.previousModelContextTestingDescriptor);
+	const nav = getNavigator();
+	const doc = getDocument();
+	if (doc && installState.installedDocumentModelContext) restore(doc, "modelContext", installState.previousDocumentModelContextDescriptor);
+	if (nav && installState.installedNavigatorModelContext) restore(nav, "modelContext", installState.previousNavigatorModelContextDescriptor);
+	if (nav && installState.installedNavigatorModelContextTesting) restore(nav, "modelContextTesting", installState.previousNavigatorModelContextTestingDescriptor);
 	installState.installed = false;
-	installState.previousModelContextDescriptor = void 0;
-	installState.previousModelContextTestingDescriptor = void 0;
+	installState.previousDocumentModelContextDescriptor = void 0;
+	installState.previousNavigatorModelContextDescriptor = void 0;
+	installState.previousNavigatorModelContextTestingDescriptor = void 0;
+	installState.installedDocumentModelContext = false;
+	installState.installedNavigatorModelContext = false;
+	installState.installedNavigatorModelContextTesting = false;
+	navigatorModelContextDeprecationWarned = false;
 }
 if (typeof window !== "undefined" && typeof document !== "undefined") {
 	const options = window.__webMCPPolyfillOptions;
@@ -512,5 +447,5 @@ if (typeof window !== "undefined" && typeof document !== "undefined") {
 }
 
 //#endregion
-export { cleanupWebMCPPolyfill, initializeWebMCPPolyfill, initializeWebMCPPolyfill as initializeWebModelContextPolyfill, isPlainObject, validateArgsWithSchema };
+export { cleanupWebMCPPolyfill, initializeWebMCPPolyfill, initializeWebMCPPolyfill as initializeWebModelContextPolyfill, isPlainObject, normalizeInputSchema, toJsonValue, validateValueWithSchema };
 //# sourceMappingURL=index.js.map