navigate
Directs a browser to load a specific webpage, allowing automation of web navigation tasks with configurable loading conditions and timeouts.
Instructions
Navigate to a URL in the browser
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | URL to navigate to | |
| waitUntil | No | When to consider navigation complete | |
| timeout | No | Timeout in milliseconds | |
| tabId | No | Tab ID to operate on (uses active tab if not specified) |
Implementation Reference
- src/tools/navigation.ts:24-59 (handler)The handler function for the 'navigate' tool. It retrieves the page for the given tabId, navigates to the URL using page.goto(), handles navigation responses, errors like timeouts and failed HTTP statuses, and returns the final URL, title, and status.
async ({ url, waitUntil, timeout, tabId }) => { const pageResult = await getPageForOperation(tabId); if (!pageResult.success) { return handleResult(pageResult); } const page = pageResult.data; const timeoutMs = timeout ?? getDefaultTimeout(); try { const response = await page.goto(url, { waitUntil: (waitUntil ?? 'load') as WaitUntilOption, timeout: timeoutMs, }); if (!response) { return handleResult(err(navigationFailed(url, 'No response received'))); } const status = response.status(); if (status >= 400) { return handleResult(err(navigationFailed(url, `HTTP ${status}`))); } return handleResult(ok({ url: page.url(), title: await page.title(), status, })); } catch (error) { if (error instanceof Error && error.message.includes('timeout')) { return handleResult(err(navigationTimeout(url, timeoutMs))); } return handleResult(err(normalizeError(error))); } } - src/schemas.ts:25-30 (schema)Zod schema defining the input parameters for the 'navigate' tool: required URL, optional waitUntil, timeout, and tabId.
export const navigateSchema = z.object({ url: z.string().url().describe('URL to navigate to'), waitUntil: waitUntilSchema.describe('When to consider navigation complete'), timeout: timeoutSchema, tabId: tabIdSchema, }); - src/tools/navigation.ts:20-60 (registration)Registration of the 'navigate' tool on the MCP server, specifying name, description, input schema, and handler function.
server.tool( 'navigate', 'Navigate to a URL in the browser', navigateSchema.shape, async ({ url, waitUntil, timeout, tabId }) => { const pageResult = await getPageForOperation(tabId); if (!pageResult.success) { return handleResult(pageResult); } const page = pageResult.data; const timeoutMs = timeout ?? getDefaultTimeout(); try { const response = await page.goto(url, { waitUntil: (waitUntil ?? 'load') as WaitUntilOption, timeout: timeoutMs, }); if (!response) { return handleResult(err(navigationFailed(url, 'No response received'))); } const status = response.status(); if (status >= 400) { return handleResult(err(navigationFailed(url, `HTTP ${status}`))); } return handleResult(ok({ url: page.url(), title: await page.title(), status, })); } catch (error) { if (error instanceof Error && error.message.includes('timeout')) { return handleResult(err(navigationTimeout(url, timeoutMs))); } return handleResult(err(normalizeError(error))); } } ); - src/server.ts:23-23 (registration)High-level registration call that includes the 'navigate' tool among navigation tools.
registerNavigationTools(server);