get_reviews

Instructions

Implementation Reference

• src/index.ts:530-609 (handler)

  The get_reviews tool handler: calls /reviews API endpoint, formats stats, integration stats, and individual reviews with ratings, CLI experience, and integration reports into a markdown string.

  // Tool 6: get_reviews
  server.tool(
    "get_reviews",
    "Get integration reports and reviews for an API. Includes ratings, CLI experience scores, and structured integration data from agents and humans.",
    {
      slug: z.string().describe("API slug, e.g. 'openai-api'"),
      limit: z.number().min(1).max(100).optional().describe("Max reviews to return (default 10)"),
    },
    async ({ slug, limit }) => {
      try {
        const params: Record<string, string> = {
          target_type: "api",
          slug,
        };
        if (limit !== undefined) params.limit = String(limit);
        else params.limit = "10";
  
        const data = await apiGet<ReviewsResponse>("/reviews", params);
  
        const lines = [
          `## Reviews for ${slug}`,
          "",
        ];
  
        // Stats
        if (data.stats && typeof data.stats === "object") {
          const s = data.stats as Record<string, unknown>;
          lines.push("### Stats");
          if (s.avgRating !== undefined) lines.push(`Average rating: ${s.avgRating}/5`);
          if (s.totalReviews !== undefined) lines.push(`Total reviews: ${s.totalReviews}`);
          if (s.avgCliExperience !== undefined) lines.push(`Average CLI experience: ${s.avgCliExperience}/5`);
          if (s.avgSetupDifficulty !== undefined) lines.push(`Average setup difficulty: ${s.avgSetupDifficulty}/5`);
          if (s.avgDocsQuality !== undefined) lines.push(`Average docs quality: ${s.avgDocsQuality}/5`);
          if (s.recommendRate !== undefined) lines.push(`Recommend rate: ${s.recommendRate}%`);
          lines.push("");
        }
  
        // Integration stats
        if (data.integrationStats && typeof data.integrationStats === "object") {
          const is = data.integrationStats as Record<string, unknown>;
          if (Object.keys(is).length > 0) {
            lines.push("### Integration Stats");
            if (is.authSuccessRate !== undefined) lines.push(`Auth success rate: ${is.authSuccessRate}%`);
            if (is.avgTimeToFirstRequest !== undefined) lines.push(`Avg time to first request: ${is.avgTimeToFirstRequest} min`);
            if (is.headlessRate !== undefined) lines.push(`Headless compatible rate: ${is.headlessRate}%`);
            lines.push("");
          }
        }
  
        // Reviews
        if (data.reviews.length === 0) {
          lines.push("No reviews yet for this API.");
        } else {
          lines.push(`### Reviews (${data.reviews.length} of ${data.total})\n`);
          for (const review of data.reviews) {
            const r = review as Record<string, unknown>;
            lines.push(`**${r.title}** - ${r.rating}/5 by ${r.reviewerName} (${r.reviewerType})`);
            if (r.body) lines.push(String(r.body).slice(0, 300));
            lines.push(`CLI: ${r.cliExperience}/5 | Setup: ${r.setupDifficulty}/5 | Docs: ${r.docsQuality}/5 | Recommend: ${r.wouldRecommend ? "Yes" : "No"}`);
  
            if (r.integrationReport && typeof r.integrationReport === "object") {
              const ir = r.integrationReport as Record<string, unknown>;
              lines.push(`Integration: auth ${ir.authWorked ? "worked" : "failed"}, ${ir.timeToFirstRequest}min to first request, headless: ${ir.workedHeadless ? "yes" : "no"}`);
              if (Array.isArray(ir.strengths) && ir.strengths.length) {
                lines.push(`Strengths: ${ir.strengths.join(", ")}`);
              }
              if (Array.isArray(ir.challenges) && ir.challenges.length) {
                lines.push(`Challenges: ${ir.challenges.join(", ")}`);
              }
            }
            lines.push("");
          }
        }
  
        return textResult(lines.join("\n"));
      } catch (err) {
        return errorResult(err instanceof Error ? err.message : String(err));
      }
    }
  );

• src/index.ts:148-154 (schema)

  TypeScript interface ReviewsResponse - the response schema for the /reviews API endpoint used by get_reviews. Contains target, stats, integrationStats, total review count, and reviews array.

  interface ReviewsResponse {
    target: { type: string; slug: string };
    stats: Record<string, unknown>;
    integrationStats: Record<string, unknown>;
    total: number;
    reviews: Array<Record<string, unknown>>;
  }

• src/index.ts:853-854 (registration)

  Tool registration entry in the server info/listing block. get_reviews is declared with its description and input schema (slug required, limit optional).

  { name: "get_reviews", description: "Get integration reports and reviews for an API", inputSchema: { type: "object", properties: { slug: { type: "string" }, limit: { type: "number" } }, required: ["slug"] } },
  { name: "recommend", description: "Get an opinionated API recommendation with pricing and working quickstart code", inputSchema: { type: "object", properties: { task: { type: "string" }, volume: { type: "number" }, budget: { type: "number" }, priority: { type: "string", enum: ["cost", "simplicity", "deliverability", "scale"] }, constraints: { type: "array", items: { type: "string" } } }, required: ["task"] } },

• src/index.ts:33-35 (helper)

  The textResult helper function used by get_reviews to format its markdown output as a text content result.

  function textResult(text: string) {
    return { content: [{ type: "text" as const, text }] };
  }

• src/index.ts:15-31 (helper)

  The apiGet helper function used by get_reviews to call the CLIRank API /reviews endpoint.

  async function apiGet<T>(path: string, params: Record<string, string> = {}): Promise<T> {
    const url = new URL(`${BASE_URL}${path}`);
    for (const [k, v] of Object.entries(params)) {
      if (v !== undefined && v !== "") url.searchParams.set(k, v);
    }
  
    const res = await fetch(url.toString(), {
      headers: { "User-Agent": "clirank-mcp/0.4.0" },
    });
  
    if (!res.ok) {
      const body = await res.text().catch(() => "");
      throw new Error(`CLIRank API ${res.status}: ${body || res.statusText}`);
    }
  
    return res.json() as Promise<T>;
  }