Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 33 additions & 18 deletions index.d.ts
Original file line number Diff line number Diff line change
Expand Up @@ -176,46 +176,61 @@ namespace WebMCP {
}

/**
* Represents a tool that has been registered and is available for execution.
* Represents a tool that has been registered and exposed to a document for execution.
* It is obtained by `getTools()`, and executed with `executeTool()`.
* A `Tool` is a snapshot of the tool at the time `getTools()` discovered it, and identifies that specific registration of the tool:
* if that tool is unregistered, executing the `Tool` fails, even if a new tool is later registered under the same name.
*/
interface RegisteredTool {
interface Tool {
/**
* A unique identifier for the tool.
* The name of the tool. It is the same value provided at tool registration, via `ModelContextTool.name`.
*/
name: string;
readonly name: string;
/**
* A human-readable label for the tool.
* A human-readable label for the tool. It is the same value provided at tool registration, via `ModelContextTool.title`.
*/
title: string;
readonly title: string;
/**
* Natural-language description of what the tool does.
*/
description: string;
readonly description: string;
/**
* A JSON Schema object describing the expected input parameters for the tool.
* A JSON Schema object describing the expected input parameters for the tool, or `null` if the tool was registered without one.
* It is a deep copy of the schema provided at tool registration, via `ModelContextTool.inputSchema`.
*/
inputSchema?: object;
readonly inputSchema: object | null;
/**
* A JSON Schema object describing the expected output structure for the tool.
* A JSON Schema object describing the expected output structure for the tool, or `null` if the tool was registered without one.
* Tool output is expected to conform to the provided schema, and agents may reject outputs that do not validate.
* It is a deep copy of the schema provided at tool registration, via `ModelContextTool.outputSchema`.
*/
outputSchema?: object;
readonly outputSchema: object | null;
/**
* The WindowProxy of the document that registered the tool, or `null` if that document is no longer fully active, e.g., because it was navigated away from.
*/
readonly source: WindowProxy | null;
/**
* The Window of the document that registered the tool.
* @deprecated Use `source` instead. Only present in Chrome versions before 160.
*/
window: Window;
// TODO: Remove once Chrome 160 reaches the stable channel.
readonly window?: Window;
/**
* The origin of the document that registered the tool.
*/
origin: string;
readonly origin: string;
/**
* Metadata about the tool's behavior.
* Metadata about the tool's behavior, matching `ModelContextTool.annotations`, or `null` if the tool was registered without any.
*/
annotations?: ToolAnnotations;
readonly annotations: ToolAnnotations | null;
}

/**
* @deprecated Use `Tool` instead.
*/
// TODO: Remove once Chrome 160 reaches the stable channel.
type RegisteredTool = Tool;

/**
* Initialization options for a `ToolActivatedEvent`.
*/
Expand Down Expand Up @@ -261,14 +276,14 @@ namespace WebMCP {
* Returns a list of registered tools exposed to this document.
* @param options Filtering options.
*/
getTools(options?: ModelContextGetToolOptions): Promise<RegisteredTool[]>;
getTools(options?: ModelContextGetToolOptions): Promise<Tool[]>;
/**
* Executes a tool on the document it was registered on.
* @param tool The tool to execute.
* @param tool The tool to execute, as returned by `getTools()`.
* @param inputObject The input parameters for the tool.
* @param options Execution options.
*/
executeTool(tool: RegisteredTool, inputObject?: object, options?: ModelContextExecuteToolOptions): Promise<string>;
executeTool(tool: Tool, inputObject?: object, options?: ModelContextExecuteToolOptions): Promise<string>;
/**
* Event handler for the toolchange event.
*/
Expand Down
41 changes: 32 additions & 9 deletions index.test-d.ts
Original file line number Diff line number Diff line change
Expand Up @@ -189,7 +189,7 @@ test('supports tool annotations', () => {
debugging?: boolean;
}>();
expectTypeOf<WebMCP.ModelContextTool['annotations']>().toEqualTypeOf<WebMCP.ToolAnnotations | undefined>();
expectTypeOf<WebMCP.RegisteredTool['annotations']>().toEqualTypeOf<WebMCP.ToolAnnotations | undefined>();
expectTypeOf<WebMCP.Tool['annotations']>().toEqualTypeOf<WebMCP.ToolAnnotations | null>();
});

test('infers execute output from an output schema', () => {
Expand Down Expand Up @@ -236,7 +236,7 @@ test('infers execute output from an output schema', () => {
});

expectTypeOf<WebMCP.ModelContextTool['outputSchema']>().toEqualTypeOf<object | undefined>();
expectTypeOf<WebMCP.RegisteredTool['outputSchema']>().toEqualTypeOf<object | undefined>();
expectTypeOf<WebMCP.Tool['outputSchema']>().toEqualTypeOf<object | null>();
});

test('rejects an invalid output schema or a return value that disagrees with it', () => {
Expand Down Expand Up @@ -277,23 +277,46 @@ test('rejects an invalid output schema or a return value that disagrees with it'
});
});

declare const registeredTool: WebMCP.RegisteredTool;
declare const tool: WebMCP.Tool;

test('exposes discovered tools as read-only Tool objects', async () => {
if (document.modelContext) {
const tools = await document.modelContext.getTools();
expectTypeOf(tools).toEqualTypeOf<WebMCP.Tool[]>();
}

expectTypeOf(tool.name).toEqualTypeOf<string>();
expectTypeOf(tool.title).toEqualTypeOf<string>();
expectTypeOf(tool.description).toEqualTypeOf<string>();
expectTypeOf(tool.inputSchema).toEqualTypeOf<object | null>();
expectTypeOf(tool.outputSchema).toEqualTypeOf<object | null>();
expectTypeOf(tool.source).toEqualTypeOf<WindowProxy | null>();
expectTypeOf(tool.origin).toEqualTypeOf<string>();
expectTypeOf(tool.annotations).toEqualTypeOf<WebMCP.ToolAnnotations | null>();

// @ts-expect-error Tool attributes are read-only.
tool.name = 'renamed';
// Kept for compatibility with Chrome versions before 160.
expectTypeOf(tool.window).toEqualTypeOf<Window | undefined>();

expectTypeOf<WebMCP.RegisteredTool>().toEqualTypeOf<WebMCP.Tool>();
});

test('supports executeTool', async () => {
const controller = new AbortController();

if (document.modelContext) {
const result = await document.modelContext.executeTool(registeredTool);
const result = await document.modelContext.executeTool(tool);
expectTypeOf(result).toEqualTypeOf<string>();

await document.modelContext.executeTool(registeredTool, { query: 'test' });
await document.modelContext.executeTool(registeredTool, [1, 2, 3]);
await document.modelContext.executeTool(registeredTool, {}, { signal: controller.signal });
await document.modelContext.executeTool(tool, { query: 'test' });
await document.modelContext.executeTool(tool, [1, 2, 3]);
await document.modelContext.executeTool(tool, {}, { signal: controller.signal });

// @ts-expect-error inputObject must be an object.
await document.modelContext.executeTool(registeredTool, 'invalid');
await document.modelContext.executeTool(tool, 'invalid');
// @ts-expect-error inputObject must be an object.
await document.modelContext.executeTool(registeredTool, 123);
await document.modelContext.executeTool(tool, 123);
}

expectTypeOf<WebMCP.ModelContextExecuteToolOptions>().toEqualTypeOf<{
Expand Down