navigate

Instructions

Implementation Reference

• src/tools/navigation.ts:8-28 (registration)

  Registration of the 'navigate' tool via server.tool() call inside registerNavigationTools()

  export function registerNavigationTools(server: McpServer, deps: ToolDeps): void {
    server.tool(
      "navigate",
      "Navigate a tab to a URL. Waits for page load. Use create_tab first, then navigate. Returns final URL (may differ due to redirects).",
      {
        tabId: z.string().min(1).describe("Tab ID from create_tab"),
        url: z.string().url().describe("Full URL including protocol (e.g. 'https://example.com')")
      },
      async (input: unknown) => {
        try {
          const parsed = z.object({ tabId: z.string().min(1).describe("Tab ID from create_tab"), url: z.string().url().describe("Full URL including protocol (e.g. 'https://example.com')") }).parse(input);
          const tracked = getTrackedTab(parsed.tabId);
          const result = await deps.client.navigate(parsed.tabId, parsed.url, tracked.userId);
          incrementToolCall(parsed.tabId);
          updateTabUrl(parsed.tabId, result.url);
          return okResult({ url: result.url, title: result.title ?? "", refsAvailable: result.refsAvailable });
        } catch (error) {
          return toErrorResult(error);
        }
      }
    );

• src/tools/navigation.ts:16-27 (handler)

  Handler function that parses input, calls client.navigate(), and returns the result

  async (input: unknown) => {
    try {
      const parsed = z.object({ tabId: z.string().min(1).describe("Tab ID from create_tab"), url: z.string().url().describe("Full URL including protocol (e.g. 'https://example.com')") }).parse(input);
      const tracked = getTrackedTab(parsed.tabId);
      const result = await deps.client.navigate(parsed.tabId, parsed.url, tracked.userId);
      incrementToolCall(parsed.tabId);
      updateTabUrl(parsed.tabId, result.url);
      return okResult({ url: result.url, title: result.title ?? "", refsAvailable: result.refsAvailable });
    } catch (error) {
      return toErrorResult(error);
    }
  }

• src/tools/navigation.ts:12-15 (schema)

  Zod schema for input validation: tabId (string) and url (string, url format)

  {
    tabId: z.string().min(1).describe("Tab ID from create_tab"),
    url: z.string().url().describe("Full URL including protocol (e.g. 'https://example.com')")
  },

• src/client.ts:342-353 (helper)

  Client helper method that sends the HTTP POST request to the /tabs/{tabId}/navigate endpoint

  async navigate(tabId: string, url: string, userId: string): Promise<NavigateResponse> {
    const response = await this.requestJson(`/tabs/${encodeURIComponent(tabId)}/navigate`, {
      method: "POST",
      body: JSON.stringify({ url, userId })
    }, NavigateRawResponseSchema);
  
    return {
      url: response.url ?? url,
      title: response.title,
      refsAvailable: response.refsAvailable
    };
  }

• src/client.ts:78-84 (schema)

  Zod schema for parsing the raw navigate API response (NavigateRawResponseSchema)

  const NavigateRawResponseSchema = z
    .object({
      url: z.string().optional(),
      title: z.string().optional(),
      refsAvailable: z.boolean().optional()
    })
    .passthrough();