ToolDefinition.ts•3.46 kB
/**
* @license
* Copyright 2025 Google LLC
* SPDX-License-Identifier: Apache-2.0
*/
import type {TextSnapshotNode} from '../McpContext.js';
import {zod} from '../third_party/index.js';
import type {Dialog, ElementHandle, Page} from '../third_party/index.js';
import type {TraceResult} from '../trace-processing/parse.js';
import type {PaginationOptions} from '../utils/types.js';
import type {ToolCategory} from './categories.js';
export interface ToolDefinition<
Schema extends zod.ZodRawShape = zod.ZodRawShape,
> {
name: string;
description: string;
annotations: {
title?: string;
category: ToolCategory;
/**
* If true, the tool does not modify its environment.
*/
readOnlyHint: boolean;
};
schema: Schema;
handler: (
request: Request<Schema>,
response: Response,
context: Context,
) => Promise<void>;
}
export interface Request<Schema extends zod.ZodRawShape> {
params: zod.objectOutputType<Schema, zod.ZodTypeAny>;
}
export interface ImageContentData {
data: string;
mimeType: string;
}
export interface SnapshotParams {
verbose?: boolean;
filePath?: string;
}
export interface Response {
appendResponseLine(value: string): void;
setIncludePages(value: boolean): void;
setIncludeNetworkRequests(
value: boolean,
options?: PaginationOptions & {
resourceTypes?: string[];
includePreservedRequests?: boolean;
},
): void;
setIncludeConsoleData(
value: boolean,
options?: PaginationOptions & {
types?: string[];
includePreservedMessages?: boolean;
},
): void;
includeSnapshot(params?: SnapshotParams): void;
attachImage(value: ImageContentData): void;
attachNetworkRequest(reqid: number): void;
attachConsoleMessage(msgid: number): void;
}
/**
* Only add methods required by tools/*.
*/
export type Context = Readonly<{
isRunningPerformanceTrace(): boolean;
setIsRunningPerformanceTrace(x: boolean): void;
recordedTraces(): TraceResult[];
storeTraceRecording(result: TraceResult): void;
getSelectedPage(): Page;
getDialog(): Dialog | undefined;
clearDialog(): void;
getPageByIdx(idx: number): Page;
newPage(): Promise<Page>;
closePage(pageIdx: number): Promise<void>;
setSelectedPageIdx(idx: number): void;
getElementByUid(uid: string): Promise<ElementHandle<Element>>;
getAXNodeByUid(uid: string): TextSnapshotNode | undefined;
setNetworkConditions(conditions: string | null): void;
setCpuThrottlingRate(rate: number): void;
saveTemporaryFile(
data: Uint8Array<ArrayBufferLike>,
mimeType: 'image/png' | 'image/jpeg' | 'image/webp',
): Promise<{filename: string}>;
saveFile(
data: Uint8Array<ArrayBufferLike>,
filename: string,
): Promise<{filename: string}>;
waitForEventsAfterAction(action: () => Promise<unknown>): Promise<void>;
waitForTextOnPage(params: {
text: string;
timeout?: number | undefined;
}): Promise<Element>;
}>;
export function defineTool<Schema extends zod.ZodRawShape>(
definition: ToolDefinition<Schema>,
) {
return definition;
}
export const CLOSE_PAGE_ERROR =
'The last open page cannot be closed. It is fine to keep it open.';
export const timeoutSchema = {
timeout: zod
.number()
.int()
.optional()
.describe(
`Maximum wait time in milliseconds. If set to 0, the default timeout will be used.`,
)
.transform(value => {
return value && value <= 0 ? undefined : value;
}),
};