get_ai_visibility_history

Instructions

Implementation Reference

• src/index.ts:16-25 (handler)

  Generic handler function that is used for ALL tools including get_ai_visibility_history. It iterates over all tools and registers them with the MCP server using server.tool(). For each tool call, it constructs the API path from the tool definition and calls apiGet with optional query params. There is no separate handler function for this tool — the generic loop handles it.

  for (const tool of tools) {
    server.tool(tool.name, tool.description, tool.parameters.shape, async (args: Record<string, any>) => {
      const path = tool.path(args);
      const query: Record<string, any> = {};
      for (const key of tool.queryParams ?? []) {
        if (args[key] !== undefined) query[key] = args[key];
      }
      return apiGet(path, Object.keys(query).length ? query : undefined);
    });
  }

• src/tools.ts:262-272 (schema)

  Schema definition for get_ai_visibility_history tool. Defines the Zod schema with projectId (24-char hex ObjectId) and pagination (page, limit) params. The API path is /v1/projects/{projectId}/ai-visibility/history with query params page and limit.

  {
    name: "get_ai_visibility_history",
    description:
      "Get paginated history of AI Visibility checks with completion timestamps. Note: uses checkId (not runId) — AI Visibility has a different data model where each check is one 3-prompt x 3-LLM query cycle. Use this to browse past checks; retrieve full detail with get_ai_visibility_check_detail, or use get_ai_visibility_trend for aggregate time-series. Read-only. Returns paginated JSON array with pagination.hasMore flag.",
    parameters: z.object({
      projectId: objectId("Project ID (from list_projects)"),
      ...pagination,
    }),
    path: (a) => `/v1/projects/${a.projectId}/ai-visibility/history`,
    queryParams: ["page", "limit"],
  },

• src/index.ts:16-25 (registration)

  Registration loop that registers all tools (including get_ai_visibility_history) with the MCP server via server.tool(tool.name, tool.description, tool.parameters.shape, handler). The tool definition from tools.ts is used to wire up name, description, schema, path, and handler.

  for (const tool of tools) {
    server.tool(tool.name, tool.description, tool.parameters.shape, async (args: Record<string, any>) => {
      const path = tool.path(args);
      const query: Record<string, any> = {};
      for (const key of tool.queryParams ?? []) {
        if (args[key] !== undefined) query[key] = args[key];
      }
      return apiGet(path, Object.keys(query).length ? query : undefined);
    });
  }

• src/api-client.ts:3-58 (helper)

  The apiGet helper function that executes the actual HTTP request for all tools. It reads the COMPETLAB_API_KEY env var, builds the full URL from API_BASE (https://api.competlab.com) + path, passes optional query params, and returns JSON content or an error.

  export async function apiGet(
    path: string,
    query?: Record<string, string | number>,
  ): Promise<{ content: Array<{ type: "text"; text: string }>; isError?: true }> {
    const apiKey = process.env.COMPETLAB_API_KEY;
    if (!apiKey) {
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify({
              error: "api_key_missing",
              message: "COMPETLAB_API_KEY environment variable is not set",
            }),
          },
        ],
        isError: true,
      };
    }
  
    const url = new URL(`${API_BASE}${path}`);
    if (query) {
      for (const [k, v] of Object.entries(query)) {
        if (v !== undefined) url.searchParams.set(k, String(v));
      }
    }
  
    try {
      const res = await fetch(url, {
        headers: { "CL-API-Key": apiKey },
      });
  
      const body = await res.text();
  
      if (!res.ok) {
        return { content: [{ type: "text", text: body }], isError: true };
      }
  
      return { content: [{ type: "text", text: body }] };
    } catch (err) {
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify({
              error: "api_unreachable",
              message:
                err instanceof Error ? err.message : "Failed to reach CompetLab API",
              status: 503,
            }),
          },
        ],
        isError: true,
      };
    }
  }