Focus

Instructions

Implementation Reference

• src/tools/interaction.ts:157-169 (handler)

  The handler function for pinchtab_focus: sends a POST /action request with kind:'focus' and the ref ID to the PinchTab server. Returns the result or error.

    async ({ ref }) => {
      try {
        return toolResult(
          await pinch("POST", "/action", {
            kind: "focus",
            ref,
          }),
        );
      } catch (error) {
        return toolError(error);
      }
    },
  );

• src/tools/interaction.ts:149-155 (schema)

  Input schema for pinchtab_focus: requires a 'ref' string describing the element reference ID (e.g. 'e3').

  {
    description:
      "Focus an element by its ref ID. Useful for triggering focus-dependent UI (e.g. autocomplete dropdowns) without clicking.",
    inputSchema: z.object({
      ref: z.string().describe("Element reference ID (e.g. 'e3')"),
    }),
    title: "Focus",

• src/tools/interaction.ts:147-169 (registration)

  Registration of the 'pinchtab_focus' tool via server.registerTool() with title 'Focus' and description about focusing elements.

  server.registerTool(
    "pinchtab_focus",
    {
      description:
        "Focus an element by its ref ID. Useful for triggering focus-dependent UI (e.g. autocomplete dropdowns) without clicking.",
      inputSchema: z.object({
        ref: z.string().describe("Element reference ID (e.g. 'e3')"),
      }),
      title: "Focus",
    },
    async ({ ref }) => {
      try {
        return toolResult(
          await pinch("POST", "/action", {
            kind: "focus",
            ref,
          }),
        );
      } catch (error) {
        return toolError(error);
      }
    },
  );

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

  registerAllTools() calls registerInteractionTools(server) which registers pinchtab_focus along with other interaction tools.

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

• src/pinchtab/client.ts:6-49 (helper)

  The pinch() helper function used by the handler to make HTTP POST requests to the PinchTab server's /action endpoint.

  export async function pinch(
    method: string,
    path: string,
    body?: Record<string, unknown>,
  ): Promise<unknown> {
    if (!(await isPinchtabRunning())) {
      await ensurePinchtabRunning();
    }
  
    const headers: Record<string, string> = {
      "Content-Type": "application/json",
    };
    if (PINCHTAB_TOKEN) {
      headers["Authorization"] = `Bearer ${PINCHTAB_TOKEN}`;
    }
  
    const url = `${PINCHTAB_URL}${path}`;
  
    let res: Response;
    try {
      res = await fetch(url, {
        body: body ? JSON.stringify(body) : undefined,
        headers,
        method,
        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
      });
    } catch (error) {
      if (error instanceof DOMException && error.name === "TimeoutError") {
        throw new Error(`PinchTab ${method} ${path} timed out after ${REQUEST_TIMEOUT_MS / 1000}s`);
      }
      throw error;
    }
  
    if (!res.ok) {
      const text = await res.text();
      throw new Error(`PinchTab ${method} ${path} → ${res.status}: ${text}`);
    }
  
    const contentType = (res.headers.get("content-type") ?? "").split(";")[0].toLowerCase().trim();
    if (contentType === "application/json") {
      return res.json();
    }
    return res.text();
  }