CLIranks

Instructions

Implementation Reference

• src/index.ts:232-305 (handler)

  The handler for the 'get_api_docs' MCP tool, which fetches API documentation from the CLIRank API and formats it into a markdown string.

  // Tool 3: get_api_docs
  server.tool(
    "get_api_docs",
    "Get agent-friendly documentation for an API, including quickstart guide and documented endpoints. Use this before integrating an API.",
    {
      slug: z.string().describe("API slug, e.g. 'stripe-api', 'openai-api'"),
    },
    async ({ slug }) => {
      try {
        const data = await apiGet<DocsResponse>("/docs", { slug });
  
        const lines = [
          `## ${data.api.name} - Agent Docs`,
          "",
          `Category: ${data.api.category} | Pricing: ${data.api.pricing}`,
          `CLI Score: ${data.api.cliRelevanceScore ?? "N/A"} | Quality: ${data.api.qualityScore ?? "N/A"}`,
          `URL: ${data.api.url}`,
          "",
        ];
  
        if (data.quickstart) {
          const qs = data.quickstart as Record<string, unknown>;
          lines.push("### Quickstart");
          if (qs.baseUrl) lines.push(`Base URL: ${qs.baseUrl}`);
          if (qs.officialDocsUrl) lines.push(`Official docs: ${qs.officialDocsUrl}`);
  
          if (qs.auth && typeof qs.auth === "object") {
            const auth = qs.auth as Record<string, unknown>;
            lines.push(`Auth: ${auth.method}${auth.header ? ` (${auth.header})` : ""}`);
            if (auth.envVar) lines.push(`Env var: ${auth.envVar}`);
          }
  
          if (qs.sdk && typeof qs.sdk === "object") {
            const sdk = qs.sdk as Record<string, unknown>;
            if (sdk.install) lines.push(`\nInstall: \`${sdk.install}\``);
            if (sdk.import) lines.push(`Import: \`${sdk.import}\``);
            if (sdk.init) lines.push(`Init: \`${sdk.init}\``);
          }
  
          if (Array.isArray(qs.requiredEnvVars) && qs.requiredEnvVars.length) {
            lines.push(`\nRequired env vars: ${qs.requiredEnvVars.join(", ")}`);
          }
  
          if (qs.rateLimits && typeof qs.rateLimits === "object") {
            const rl = qs.rateLimits as Record<string, unknown>;
            lines.push(`Rate limits: ${rl.requests ?? "?"} requests per ${rl.window ?? "?"}`);
          }
  
          if (Array.isArray(qs.gotchas) && qs.gotchas.length) {
            lines.push("\nGotchas:");
            for (const g of qs.gotchas) lines.push(`- ${g}`);
          }
  
          lines.push(`\nConfidence: ${qs.confidence ?? "N/A"} | Contributions: ${qs.contributionCount ?? 0}`);
          lines.push("");
        } else {
          lines.push("No quickstart documentation available yet.\n");
        }
  
        if (data.endpoints.length) {
          lines.push(`### Documented Endpoints (${data.totalEndpoints})\n`);
          for (const ep of data.endpoints) {
            lines.push(`- \`${ep.method} ${ep.path}\` - ${ep.summary || "No summary"} (confidence: ${ep.confidence})`);
          }
        } else {
          lines.push("No endpoint documentation available yet.");
        }
  
        return textResult(lines.join("\n"));
      } catch (err) {
        return errorResult(err instanceof Error ? err.message : String(err));
      }
    }
  );