check_history

Instructions

Implementation Reference

• src/tools/history.ts:38-48 (handler)

  The handler function that executes the check_history tool logic. It calls api.history(page, limit) and returns the result, with error handling for auth, API errors, and unknown errors.

  async ({ page, limit }) => {
    if (!api.hasApiKey) return authError();
  
    try {
      const result = await api.history(page, limit);
      return successResult(result);
    } catch (err) {
      if (err instanceof ApiRequestError) return apiErrorToResult(err);
      return errorResult(err instanceof Error ? err.message : "Unknown error");
    }
  }

• src/tools/history.ts:21-36 (schema)

  Input schema for check_history tool: optional page (int >= 1) and limit (int 1-100, default 20) parameters with descriptions.

      {
        description: `View recent URL check history. Shows what URLs have been checked, their scores, phishing status, and whether each check was free or used a pipeline credit.
  
  Results are paginated. Use page and limit parameters to navigate. Default is 20 results per page, maximum 100.
  
  History is retained for 90 days. Account-level stats (total credits, balance) never expire.`,
        inputSchema: {
          page: z.number().int().min(1).optional().describe("Page number (default 1)"),
          limit: z
            .number()
            .int()
            .min(1)
            .max(100)
            .optional()
            .describe("Results per page, max 100 (default 20)"),
        },

• src/tools/history.ts:15-49 (registration)

  The registerHistoryTool function that registers 'check_history' on the MCP server via server.registerTool().

  export function registerHistoryTool(
    server: McpServer,
    api: UnphurlAPI
  ): void {
    server.registerTool(
      "check_history",
      {
        description: `View recent URL check history. Shows what URLs have been checked, their scores, phishing status, and whether each check was free or used a pipeline credit.
  
  Results are paginated. Use page and limit parameters to navigate. Default is 20 results per page, maximum 100.
  
  History is retained for 90 days. Account-level stats (total credits, balance) never expire.`,
        inputSchema: {
          page: z.number().int().min(1).optional().describe("Page number (default 1)"),
          limit: z
            .number()
            .int()
            .min(1)
            .max(100)
            .optional()
            .describe("Results per page, max 100 (default 20)"),
        },
      },
      async ({ page, limit }) => {
        if (!api.hasApiKey) return authError();
  
        try {
          const result = await api.history(page, limit);
          return successResult(result);
        } catch (err) {
          if (err instanceof ApiRequestError) return apiErrorToResult(err);
          return errorResult(err instanceof Error ? err.message : "Unknown error");
        }
      }
    );

• src/index.ts:39-41 (registration)

  Top-level invocation of registerHistoryTool(server, api) to wire up the tool in the MCP server.

  registerHistoryTool(server, api);
  registerStatsTool(server, api);
  registerAllowlistTools(server, api); // list_allowlist, add_to_allowlist, remove_from_allowlist

• src/api.ts:180-189 (helper)

  The api.history() method that makes the actual HTTP GET request to /v1/history with optional page and limit query params.

  async history(page?: number, limit?: number): Promise<HistoryResponse> {
    const params = new URLSearchParams();
    if (page) params.set("page", String(page));
    if (limit) params.set("limit", String(limit));
    const qs = params.toString();
    return this.doRequest<HistoryResponse>(
      "GET",
      `/v1/history${qs ? "?" + qs : ""}`
    );
  }