@adityanair98/api-oracle 0.5.0

package/dist/knowledge/tfidf.js

@@ -0,0 +1,138 @@
+/**
+ * TF-IDF text search engine for API entries.
+ *
+ * Builds an in-memory index from entries and provides relevance-ranked search
+ * without requiring any external API calls or embedding models. Uses weighted
+ * multi-field document construction to boost precision:
+ *   name (x4) > bestFor/subcategory (x3) > useCases (x2) > description (x1)
+ *
+ * TF-IDF formula:
+ *   score(doc, query) = sum_t( TF(t, doc) * IDF(t) ) for each query term t
+ *   IDF(t) = log((N + 1) / (df(t) + 1)) + 1   (Laplace smoothing)
+ *
+ * Exports: TfIdfEngine, getTfIdfEngine, resetTfIdfEngine
+ */
+import { tokenize } from "./scorer.js";
+// ─── Field weights for document construction ──────────────────────────────────
+const FIELD_WEIGHTS = {
+    name: 4, // API name is the strongest identity signal
+    subcategory: 3, // e.g. "transactional-email", "push-notification"
+    bestFor: 3, // Concise purpose statement written for discoverability
+    useCases: 2, // Task-oriented descriptions — close to real queries
+    description: 1, // Full prose description (lower weight — can be noisy)
+    category: 1, // Broad category (broad signal only)
+};
+// ─── TF-IDF Engine ────────────────────────────────────────────────────────────
+export class TfIdfEngine {
+    vectors = [];
+    idf = new Map();
+    entryBySlug = new Map();
+    _built = false;
+    /**
+     * Build the TF-IDF index from a list of entries.
+     * Can be called again to rebuild with updated entries.
+     */
+    build(entries) {
+        this.vectors = [];
+        this.idf = new Map();
+        this.entryBySlug = new Map();
+        this._built = false;
+        const N = entries.length;
+        if (N === 0)
+            return;
+        // Document frequency: how many documents contain each term
+        const df = new Map();
+        for (const entry of entries) {
+            this.entryBySlug.set(entry.slug, entry);
+            const termCounts = new Map();
+            const addTokens = (text, weight) => {
+                for (const token of tokenize(text)) {
+                    termCounts.set(token, (termCounts.get(token) ?? 0) + weight);
+                }
+            };
+            addTokens(entry.name, FIELD_WEIGHTS.name);
+            addTokens(entry.subcategory.replace(/-/g, " "), FIELD_WEIGHTS.subcategory);
+            addTokens(entry.bestFor, FIELD_WEIGHTS.bestFor);
+            addTokens(entry.category, FIELD_WEIGHTS.category);
+            addTokens(entry.description.slice(0, 300), FIELD_WEIGHTS.description);
+            for (const uc of entry.useCases) {
+                addTokens(uc.task, FIELD_WEIGHTS.useCases);
+            }
+            // Document length = sum of all weighted counts (for TF normalization)
+            let totalWeight = 0;
+            for (const count of termCounts.values())
+                totalWeight += count;
+            this.vectors.push({ slug: entry.slug, termCounts, totalWeight });
+            // Update document frequency (count each term once per document)
+            for (const term of termCounts.keys()) {
+                df.set(term, (df.get(term) ?? 0) + 1);
+            }
+        }
+        // Compute IDF with Laplace smoothing to avoid division-by-zero
+        // log((N+1)/(df+1)) + 1 ensures unknown terms get IDF ≈ 1
+        for (const [term, count] of df) {
+            this.idf.set(term, Math.log((N + 1) / (count + 1)) + 1);
+        }
+        this._built = true;
+    }
+    /**
+     * Search the index for entries most relevant to the query.
+     * Returns up to topN entries sorted by TF-IDF score descending.
+     * Entries with zero score are excluded.
+     */
+    search(query, topN = 10) {
+        if (!this._built || this.vectors.length === 0)
+            return [];
+        const queryTokens = tokenize(query);
+        if (queryTokens.size === 0)
+            return [];
+        const scores = [];
+        for (const doc of this.vectors) {
+            let score = 0;
+            for (const term of queryTokens) {
+                const rawCount = doc.termCounts.get(term) ?? 0;
+                if (rawCount === 0)
+                    continue;
+                // TF = count / document_length (normalized by total weighted length)
+                const tf = rawCount / Math.max(doc.totalWeight, 1);
+                // IDF: terms not in any document get default IDF=1 (unknown query term)
+                const idf = this.idf.get(term) ?? 1;
+                score += tf * idf;
+            }
+            if (score > 0) {
+                scores.push({ slug: doc.slug, score });
+            }
+        }
+        scores.sort((a, b) => b.score - a.score);
+        const results = [];
+        for (const { slug } of scores.slice(0, topN)) {
+            const entry = this.entryBySlug.get(slug);
+            if (entry)
+                results.push(entry);
+        }
+        return results;
+    }
+    get isBuilt() {
+        return this._built;
+    }
+    /** Number of indexed documents */
+    get size() {
+        return this.vectors.length;
+    }
+}
+// ─── Module-level singleton ────────────────────────────────────────────────────
+let _engine = null;
+/** Get the shared engine instance (lazily created) */
+export function getTfIdfEngine() {
+    if (!_engine) {
+        _engine = new TfIdfEngine();
+    }
+    return _engine;
+}
+/**
+ * Reset the shared engine (forces rebuild on next search).
+ * Must be called in test afterEach when the DB is replaced.
+ */
+export function resetTfIdfEngine() {
+    _engine = null;
+}

package/dist/server.d.ts

@@ -0,0 +1,9 @@
+/**
+ * MCP server setup — creates the server, registers all tools, and handles protocol.
+ * Uses @modelcontextprotocol/sdk McpServer (high-level API).
+ *
+ * Exports: createServer
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function createServer(): McpServer;
+export declare function startServer(): Promise<void>;

package/dist/server.js

@@ -0,0 +1,40 @@
+/**
+ * MCP server setup — creates the server, registers all tools, and handles protocol.
+ * Uses @modelcontextprotocol/sdk McpServer (high-level API).
+ *
+ * Exports: createServer
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { registerFindBestApi } from "./tools/find-api.js";
+import { registerCompareApis } from "./tools/compare-apis.js";
+import { registerGetSetupGuide } from "./tools/get-setup-guide.js";
+import { registerCheckApiFreshness } from "./tools/check-freshness.js";
+import { createLogger } from "./utils/logger.js";
+const logger = createLogger("server");
+export function createServer() {
+    const server = new McpServer({
+        name: "api-oracle",
+        version: "0.1.0",
+    }, {
+        capabilities: {
+            tools: {},
+        },
+        instructions: "API Oracle helps developers find, evaluate, and use the best API for any programming task. " +
+            "Use find_best_api to get a recommendation, compare_apis to compare specific options, " +
+            "and get_api_setup_guide for complete setup instructions.",
+    });
+    // Register all tools
+    registerFindBestApi(server);
+    registerCompareApis(server);
+    registerGetSetupGuide(server);
+    registerCheckApiFreshness(server);
+    logger.info("Server created with 4 tools registered");
+    return server;
+}
+export async function startServer() {
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    logger.info("API Oracle MCP server running on stdio");
+}

package/dist/tools/check-freshness.d.ts

@@ -0,0 +1,9 @@
+/**
+ * MCP Tool: check_api_freshness
+ * Reports how up-to-date the API Oracle knowledge base entries are.
+ * Returns a staleness summary — useful before making API recommendations.
+ *
+ * Exports: registerCheckApiFreshness
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerCheckApiFreshness(server: McpServer): void;

package/dist/tools/check-freshness.js

@@ -0,0 +1,95 @@
+/**
+ * MCP Tool: check_api_freshness
+ * Reports how up-to-date the API Oracle knowledge base entries are.
+ * Returns a staleness summary — useful before making API recommendations.
+ *
+ * Exports: registerCheckApiFreshness
+ */
+import { z } from "zod";
+import { getAllEntries } from "../knowledge/db.js";
+import { checkAllEntries } from "../updater/staleness.js";
+import { buildFreshnessReport, formatReport, formatBriefSummary } from "../updater/report.js";
+import { createLogger } from "../utils/logger.js";
+const logger = createLogger("tool:check-freshness");
+const inputSchema = {
+    slug: z
+        .string()
+        .optional()
+        .describe("Optional: check freshness for a specific API by slug (e.g. 'stripe'). " +
+        "If omitted, returns a summary for all entries."),
+    level: z
+        .enum(["aging", "stale", "critical"])
+        .optional()
+        .describe("Optional: filter to only show entries at this staleness level or worse. " +
+        "Values: 'aging' (3–6 months), 'stale' (6–12 months), 'critical' (>12 months)."),
+    brief: z
+        .boolean()
+        .optional()
+        .describe("Optional: return a one-line summary instead of a full report (default: false)."),
+};
+export function registerCheckApiFreshness(server) {
+    server.tool("check_api_freshness", "Check how up-to-date the API Oracle knowledge base is. Returns a freshness report showing which entries need review based on their lastVerified date.", inputSchema, async ({ slug, level, brief }) => {
+        logger.info("check_api_freshness called", { slug, level, brief });
+        try {
+            const entries = getAllEntries();
+            if (entries.length === 0) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: "No entries found in the database. Run `npm run seed` first.",
+                        },
+                    ],
+                };
+            }
+            // Single-entry lookup
+            if (slug) {
+                const entry = entries.find((e) => e.slug === slug);
+                if (!entry) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `No entry found with slug: ${slug}`,
+                            },
+                        ],
+                    };
+                }
+                const [info] = checkAllEntries([entry]);
+                if (!info) {
+                    return {
+                        content: [{ type: "text", text: "Error computing staleness." }],
+                    };
+                }
+                const text = `**${entry.name}** (${entry.slug})\n` +
+                    `Last verified: ${info.lastVerified}\n` +
+                    `Age: ${info.daysSinceVerified} days\n` +
+                    `Status: ${info.level}`;
+                return { content: [{ type: "text", text }] };
+            }
+            // Full report
+            let allInfos = checkAllEntries(entries);
+            if (level) {
+                const levelOrder = { fresh: 0, aging: 1, stale: 2, critical: 3 };
+                const minLevel = levelOrder[level] ?? 0;
+                allInfos = allInfos.filter((i) => (levelOrder[i.level] ?? 0) >= minLevel);
+            }
+            const report = buildFreshnessReport(allInfos);
+            if (brief) {
+                return {
+                    content: [{ type: "text", text: formatBriefSummary(report) }],
+                };
+            }
+            return {
+                content: [{ type: "text", text: formatReport(report) }],
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            logger.error("check_api_freshness error", { error: message });
+            return {
+                content: [{ type: "text", text: `Error: ${message}` }],
+            };
+        }
+    });
+}

package/dist/tools/compare-apis.d.ts

@@ -0,0 +1,8 @@
+/**
+ * MCP Tool: compare_apis
+ * Side-by-side comparison of multiple APIs by their slugs.
+ *
+ * Exports: registerCompareApis
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerCompareApis(server: McpServer): void;

package/dist/tools/compare-apis.js

@@ -0,0 +1,149 @@
+/**
+ * MCP Tool: compare_apis
+ * Side-by-side comparison of multiple APIs by their slugs.
+ *
+ * Exports: registerCompareApis
+ */
+import { z } from "zod";
+import { getApiBySlug } from "../knowledge/search.js";
+import { createLogger } from "../utils/logger.js";
+const logger = createLogger("tool:compare-apis");
+const inputSchema = {
+    slugs: z
+        .array(z.string().min(1))
+        .min(2)
+        .max(5)
+        .describe("Slugs of APIs to compare, e.g. ['resend', 'sendgrid', 'postmark']"),
+    criteria: z
+        .string()
+        .optional()
+        .describe("Optional focus area for the comparison, e.g. 'pricing', 'deliverability', 'developer experience'"),
+};
+export function registerCompareApis(server) {
+    server.tool("compare_apis", "Compare multiple APIs side-by-side. Provide 2-5 API slugs and an optional criteria focus.", inputSchema, async ({ slugs, criteria }) => {
+        logger.info("compare_apis called", { slugs, criteria });
+        try {
+            // Look up all requested APIs
+            const entries = slugs.map((slug) => {
+                const entry = getApiBySlug(slug);
+                return { slug, entry };
+            });
+            // Report any not found
+            const notFound = entries.filter((e) => !e.entry).map((e) => e.slug);
+            const found = entries.filter((e) => e.entry !== null);
+            if (found.length < 2) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                error: "Not enough valid APIs to compare",
+                                notFound,
+                                suggestion: "Use find_best_api to discover valid API slugs.",
+                            }),
+                        },
+                    ],
+                };
+            }
+            // Build comparison entries
+            const comparison = found.map(({ entry }) => {
+                const pricingSummary = [
+                    entry.pricing.freeTier ? `Free: ${entry.pricing.freeTier}` : null,
+                    entry.pricing.startingPrice
+                        ? `Paid from ${entry.pricing.startingPrice}`
+                        : null,
+                ]
+                    .filter(Boolean)
+                    .join(" | ") || entry.pricing.model;
+                // Derive strengths from quality justification + best use cases
+                const perfectFits = entry.useCases
+                    .filter((uc) => uc.fit === "perfect")
+                    .map((uc) => uc.task);
+                const partialFits = entry.useCases
+                    .filter((uc) => uc.fit === "partial")
+                    .map((uc) => uc.task);
+                const strengths = [
+                    ...perfectFits.slice(0, 2),
+                    entry.sdk.primaryLanguage === "typescript"
+                        ? "First-class TypeScript SDK"
+                        : null,
+                    entry.reliability.uptimeGuarantee
+                        ? `${entry.reliability.uptimeGuarantee} uptime guarantee`
+                        : null,
+                ].filter((s) => s !== null);
+                const weaknesses = [
+                    ...partialFits.slice(0, 1).map((t) => `Limited support for: ${t}`),
+                    ...entry.gotchas.slice(0, 1),
+                ].filter(Boolean);
+                return {
+                    name: entry.name,
+                    slug: entry.slug,
+                    qualityScore: entry.qualityScore,
+                    strengths: strengths.slice(0, 4),
+                    weaknesses: weaknesses.slice(0, 3),
+                    bestFor: entry.bestFor,
+                    pricing: pricingSummary,
+                    pricingModel: entry.pricing.model,
+                    freeTier: entry.pricing.freeTier ?? "None",
+                    rateLimits: `${entry.rateLimits.tier}: ${entry.rateLimits.limit}`,
+                    sdkLanguages: [
+                        entry.sdk.primaryLanguage,
+                        ...entry.sdk.otherLanguages,
+                    ]
+                        .slice(0, 5)
+                        .join(", "),
+                    website: entry.website,
+                };
+            });
+            // Build verdict
+            const best = comparison.reduce((a, b) => a.qualityScore >= b.qualityScore ? a : b);
+            let verdict;
+            if (criteria) {
+                const criteriaLower = criteria.toLowerCase();
+                // Pricing-focused verdict
+                if (criteriaLower.includes("price") ||
+                    criteriaLower.includes("cost") ||
+                    criteriaLower.includes("free")) {
+                    const withFree = comparison.filter((c) => c.freeTier !== "None");
+                    const cheapest = withFree[0] ?? best;
+                    verdict = `For ${criteria}, ${cheapest.name} offers the best value with "${cheapest.freeTier}" free tier. ${cheapest.name} is best if staying on a free tier matters most.`;
+                }
+                else {
+                    // Generic criteria verdict — defer to quality score
+                    verdict = `For ${criteria}, ${best.name} (score: ${best.qualityScore}/10) comes out ahead. ${best.bestFor}.`;
+                }
+            }
+            else {
+                const names = comparison.map((c) => c.name).join(", ");
+                verdict = `Of ${names}: ${best.name} scores highest at ${best.qualityScore}/10 — ${best.bestFor}.`;
+            }
+            const response = {
+                comparison,
+                verdict,
+                notFound: notFound.length > 0 ? notFound : undefined,
+            };
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(response, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            logger.error("compare_apis error", err);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: "Internal error while comparing APIs",
+                            details: String(err),
+                        }),
+                    },
+                ],
+            };
+        }
+    });
+}

package/dist/tools/find-api.d.ts

@@ -0,0 +1,9 @@
+/**
+ * MCP Tool: find_best_api
+ * Finds and recommends the best API for a given task description.
+ * Returns a structured recommendation with quick-start code.
+ *
+ * Exports: registerFindBestApi
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerFindBestApi(server: McpServer): void;

package/dist/tools/find-api.js

@@ -0,0 +1,120 @@
+/**
+ * MCP Tool: find_best_api
+ * Finds and recommends the best API for a given task description.
+ * Returns a structured recommendation with quick-start code.
+ *
+ * Exports: registerFindBestApi
+ */
+import { z } from "zod";
+import { findApis } from "../knowledge/search.js";
+import { createLogger } from "../utils/logger.js";
+const logger = createLogger("tool:find-api");
+const inputSchema = {
+    task: z.string().min(1).describe("Describe what you need the API to do, e.g. 'send transactional emails with templates'"),
+    constraints: z
+        .object({
+        maxPrice: z
+            .string()
+            .optional()
+            .describe("Maximum acceptable price, e.g. '$50/month'"),
+        requiredLanguage: z
+            .string()
+            .optional()
+            .describe("Required SDK language, e.g. 'typescript', 'python'"),
+        preferFree: z
+            .boolean()
+            .optional()
+            .describe("Prefer APIs with free tiers"),
+    })
+        .optional()
+        .describe("Optional constraints to filter recommendations"),
+};
+export function registerFindBestApi(server) {
+    server.tool("find_best_api", "Find and recommend the best API for a programming task. Returns top recommendation with quick-start code, gotchas, and alternatives.", inputSchema, async ({ task, constraints }) => {
+        logger.info("find_best_api called", { task, constraints });
+        try {
+            const results = findApis(task, constraints, 3);
+            if (results.length === 0) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                error: "No matching APIs found",
+                                suggestion: "Try a broader task description, or the API category may not be in the database yet.",
+                                totalEvaluated: 0,
+                            }),
+                        },
+                    ],
+                };
+            }
+            const [top, ...alternatives] = results;
+            const entry = top.entry;
+            // Build a one-line pricing summary
+            const pricingSummary = [
+                entry.pricing.freeTier ? `Free: ${entry.pricing.freeTier}` : null,
+                entry.pricing.startingPrice
+                    ? `Paid from ${entry.pricing.startingPrice}`
+                    : null,
+                entry.pricing.model === "usage_based" ? "Usage-based (no monthly fee)" : null,
+            ]
+                .filter(Boolean)
+                .join(" | ") || entry.pricing.model;
+            // Select best code example — prefer the first one
+            const bestExample = entry.codeExamples[0];
+            const response = {
+                recommendation: {
+                    name: entry.name,
+                    slug: entry.slug,
+                    why: `${entry.bestFor}. ${entry.qualityJustification}`,
+                    qualityScore: entry.qualityScore,
+                    confidence: top.confidence ?? null,
+                    confidenceLabel: top.confidenceLabel ?? null,
+                    scoreBreakdown: top.scoreBreakdown,
+                    quickStart: {
+                        install: entry.sdk.installCommand,
+                        envVar: `${entry.auth.envVarName}=your_key_here`,
+                        authSnippet: entry.auth.codeSnippet,
+                        codeExample: bestExample?.code ?? "See documentation",
+                        codeExampleTitle: bestExample?.title ?? "",
+                        notes: bestExample?.notes ?? "",
+                    },
+                    gotchas: entry.gotchas,
+                    pricing: pricingSummary,
+                    website: entry.website,
+                    rateLimitNote: `${entry.rateLimits.tier}: ${entry.rateLimits.limit}`,
+                },
+                alternatives: alternatives.map((r) => ({
+                    name: r.entry.name,
+                    slug: r.entry.slug,
+                    why: r.entry.bestFor,
+                    qualityScore: r.entry.qualityScore,
+                    score: Math.round(r.score * 100) / 100,
+                })),
+                totalEvaluated: results.length + alternatives.length,
+            };
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(response, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            logger.error("find_best_api error", err);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: "Internal error while searching for APIs",
+                            details: String(err),
+                        }),
+                    },
+                ],
+            };
+        }
+    });
+}

package/dist/tools/get-setup-guide.d.ts

@@ -0,0 +1,8 @@
+/**
+ * MCP Tool: get_api_setup_guide
+ * Returns detailed, step-by-step setup instructions for a specific API.
+ *
+ * Exports: registerGetSetupGuide
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerGetSetupGuide(server: McpServer): void;