CLIranks

Instructions

Implementation Reference

• src/index.ts:307-391 (handler)

  The `compare_apis` tool implementation, including its registration, input schema, and the handler function that fetches and compares multiple APIs side by side.

  // Tool 4: compare_apis
  server.tool(
    "compare_apis",
    "Compare two or more APIs side by side. Returns a comparison table with scores, pricing, auth, and capabilities.",
    {
      slugs: z.array(z.string()).min(2).max(5).describe("Array of API slugs to compare, e.g. ['stripe-api', 'paypal-api']"),
    },
    async ({ slugs }) => {
      try {
        // Fetch all APIs in parallel
        const results = await Promise.all(
          slugs.map(async (slug) => {
            const data = await apiGet<ApisResponse>("/apis", { q: slug, limit: "5" });
            const api = data.apis.find(a => slugify(a.name) === slug) || data.apis[0];
            return { slug, api: api || null };
          })
        );
  
        const missing = results.filter(r => !r.api).map(r => r.slug);
        if (missing.length) {
          return errorResult(`APIs not found: ${missing.join(", ")}. Use discover_apis to find valid slugs.`);
        }
  
        const apis = results.map(r => r.api!);
        const names = apis.map(a => a.name);
  
        // Build comparison table
        const header = `| | ${names.join(" | ")} |`;
        const separator = `|---|${names.map(() => "---").join("|")}|`;
  
        const rows = [
          `| Category | ${apis.map(a => a.category).join(" | ")} |`,
          `| Pricing | ${apis.map(a => a.pricing).join(" | ")} |`,
          `| CLI Score | ${apis.map(a => a.cliRelevanceScore ?? "N/A").join(" | ")} |`,
          `| Quality | ${apis.map(a => a.qualityScore ?? "N/A").join(" | ")} |`,
          `| Overall | ${apis.map(a => a.overallScore ?? "N/A").join(" | ")} |`,
          `| npm | ${apis.map(a => a.npmPackage || "N/A").join(" | ")} |`,
          `| Downloads/wk | ${apis.map(a => a.weeklyDownloads?.toLocaleString() ?? "N/A").join(" | ")} |`,
        ];
  
        // CLI breakdown comparison if available
        const hasBreakdown = apis.some(a => a.cliBreakdown);
        if (hasBreakdown) {
          const keys = ["hasOfficialSdk", "envVarAuth", "headlessCompatible", "hasCli", "jsonResponse"];
          for (const key of keys) {
            rows.push(`| ${formatKey(key)} | ${apis.map(a => a.cliBreakdown?.[key] ? "Yes" : "No").join(" | ")} |`);
          }
        }
  
        // Capabilities
        rows.push(`| Capabilities | ${apis.map(a => a.capabilities.length ? a.capabilities.slice(0, 5).join(", ") : "N/A").join(" | ")} |`);
  
        const lines = [
          `## API Comparison`,
          "",
          header,
          separator,
          ...rows,
          "",
        ];
  
        // Add descriptions
        for (const api of apis) {
          lines.push(`### ${api.name}`);
          lines.push(api.description);
          lines.push("");
        }
  
        // Recommendation
        const scored = apis
          .map(a => ({ name: a.name, score: (a.cliRelevanceScore ?? 0) + (a.qualityScore ?? 0) }))
          .sort((a, b) => b.score - a.score);
  
        if (scored[0].score > scored[1].score) {
          lines.push(`**Recommendation:** ${scored[0].name} scores highest (${scored[0].score} combined CLI + quality).`);
        } else {
          lines.push(`**Recommendation:** ${scored[0].name} and ${scored[1].name} score equally. Choose based on your specific requirements.`);
        }
  
        return textResult(lines.join("\n"));
      } catch (err) {
        return errorResult(err instanceof Error ? err.message : String(err));
      }
    }
  );