CLIranks

Instructions

Implementation Reference

• src/index.ts:127-166 (handler)

  Implementation of the 'discover_apis' tool, which searches for APIs based on a query and optional filters, and returns a formatted list of matches.

  server.tool(
    "discover_apis",
    "Search for APIs by intent or capability. Describe what you need and get ranked matches. Examples: 'send transactional emails', 'process payments', 'image generation'.",
    {
      query: z.string().describe("What you need, e.g. 'send transactional emails'"),
      min_cli_score: z.number().min(1).max(10).optional().describe("Minimum CLI relevance score (1-10)"),
      pricing: z.enum(["free", "freemium", "paid", "pay-per-use", "transaction-based"]).optional().describe("Pricing filter"),
      limit: z.number().min(1).max(50).optional().describe("Max results (default 10, max 50)"),
    },
    async ({ query, min_cli_score, pricing, limit }) => {
      try {
        const params: Record<string, string> = { q: query };
        if (min_cli_score !== undefined) params.min_cli = String(min_cli_score);
        if (pricing) params.pricing = pricing;
        if (limit !== undefined) params.limit = String(limit);
  
        const data = await apiGet<DiscoverResponse>("/discover", params);
  
        if (data.count === 0) {
          return textResult(`No APIs found matching "${query}". Try broader terms or remove filters.`);
        }
  
        const lines = [`Found ${data.count} APIs matching "${query}":\n`];
        for (const r of data.results) {
          lines.push(`## ${r.name}`);
          lines.push(`Slug: ${r.slug} | Category: ${r.category}`);
          lines.push(`CLI Score: ${r.cliRelevanceScore ?? "N/A"} | Quality: ${r.qualityScore ?? "N/A"} | Pricing: ${r.pricing}`);
          lines.push(`${r.description}`);
          if (r.capabilities.length) lines.push(`Capabilities: ${r.capabilities.join(", ")}`);
          if (r.agentDocs.hasQuickstart) lines.push(`Agent docs: quickstart available, ${r.agentDocs.endpointCount} endpoints documented`);
          lines.push(`Details: ${r.detailUrl}`);
          lines.push("");
        }
  
        return textResult(lines.join("\n"));
      } catch (err) {
        return errorResult(err instanceof Error ? err.message : String(err));
      }
    }
  );