CLIranks

Instructions

Implementation Reference

• src/index.ts:426-504 (handler)

  The get_reviews tool registration and handler implementation. It validates input parameters, calls an external API, formats the response, and handles errors.

  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));
      }
    }
  );