Navigate

Instructions

Implementation Reference

• src/tools/navigation.ts:36-51 (handler)

  The handler function that executes the pinchtab_navigate tool logic. It sends a POST to /navigate (or /tab with new) via the pinch client, optionally waits for a snapshot, and returns the result.

  async ({ url, newTab, waitMs }) => {
    try {
      if (newTab) {
        await pinch("POST", "/tab", { action: "new", url });
      } else {
        await pinch("POST", "/navigate", { url });
      }
      if (waitMs && waitMs > 0) {
        const snap = await waitAndSnapshot(waitMs);
        return toolResult(`Navigated to ${url}\n\n${snap}`);
      }
      return toolResult({ navigated: url });
    } catch (error) {
      return toolError(error);
    }
  },

• src/tools/navigation.ts:18-35 (schema)

  Input schema definition for pinchtab_navigate: url (string, required), newTab (boolean, optional), waitMs (number, optional, max 10000ms).

  {
    description:
      "Navigate the browser to a URL. Set waitMs to wait for page load and get a snapshot back automatically.",
    inputSchema: z.object({
      newTab: z
        .boolean()
        .optional()
        .describe("Open the URL in a new tab instead of navigating the current one."),
      url: z.string().describe("URL to navigate to"),
      waitMs: z
        .number()
        .optional()
        .describe(
          "Wait this many ms after navigation, then return a compact page snapshot (max 10000).",
        ),
    }),
    title: "Navigate",
  },

• src/tools/navigation.ts:15-52 (registration)

  Tool registration: registerNavigationTools calls server.registerTool('pinchtab_navigate', ...) with the schema and handler.

  export function registerNavigationTools(server: McpServer) {
    server.registerTool(
      "pinchtab_navigate",
      {
        description:
          "Navigate the browser to a URL. Set waitMs to wait for page load and get a snapshot back automatically.",
        inputSchema: z.object({
          newTab: z
            .boolean()
            .optional()
            .describe("Open the URL in a new tab instead of navigating the current one."),
          url: z.string().describe("URL to navigate to"),
          waitMs: z
            .number()
            .optional()
            .describe(
              "Wait this many ms after navigation, then return a compact page snapshot (max 10000).",
            ),
        }),
        title: "Navigate",
      },
      async ({ url, newTab, waitMs }) => {
        try {
          if (newTab) {
            await pinch("POST", "/tab", { action: "new", url });
          } else {
            await pinch("POST", "/navigate", { url });
          }
          if (waitMs && waitMs > 0) {
            const snap = await waitAndSnapshot(waitMs);
            return toolResult(`Navigated to ${url}\n\n${snap}`);
          }
          return toolResult({ navigated: url });
        } catch (error) {
          return toolError(error);
        }
      },
    );

• src/tools/index.ts:7-12 (registration)

  registerAllTools calls registerNavigationTools(server) to wire up the tool.

  export function registerAllTools(server: McpServer) {
    registerInstanceTools(server);
    registerNavigationTools(server);
    registerInteractionTools(server);
    registerContentTools(server);
  }

• src/tools/shared.ts:6-11 (helper)

  waitAndSnapshot helper used by the handler when waitMs is provided: waits the specified ms (clamped to 10s) and returns a compact snapshot.

  export async function waitAndSnapshot(ms: number): Promise<string> {
    const clamped = Math.min(ms, MAX_WAIT_MS);
    await new Promise((resolve) => setTimeout(resolve, clamped));
    const snapshot = await pinch("GET", "/snapshot?format=compact");
    return typeof snapshot === "string" ? snapshot : JSON.stringify(snapshot, undefined, 2);
  }