@adityanair98/api-oracle 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 API Oracle contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,216 @@
+# API Oracle
+
+An MCP server that gives Claude Code the ability to find, evaluate, and recommend the best API for any programming task.
+
+When a developer asks *"what should I use to send emails?"* — API Oracle returns a structured recommendation with working code, honest gotchas, pricing details, and everything needed to get started immediately.
+
+[![CI](https://github.com/adityanair/api-oracle/actions/workflows/ci.yml/badge.svg)](https://github.com/adityanair/api-oracle/actions/workflows/ci.yml)
+
+---
+
+## MCP Tools
+
+| Tool | What it does |
+|------|-------------|
+| `find_best_api` | Recommends the best API for a task with quick-start code |
+| `compare_apis` | Side-by-side comparison of 2–5 APIs |
+| `get_api_setup_guide` | Full setup instructions for a specific API |
+| `check_api_freshness` | Staleness report showing which entries need re-verification |
+
+## Knowledge Base — 68 APIs across 23 categories
+
+| Category | APIs |
+|----------|------|
+| AI | Anthropic, OpenAI, Replicate, Resemble AI, Stability AI, ElevenLabs |
+| Analytics | PostHog, Sentry |
+| Auth | Auth0, Clerk |
+| CMS | Contentful, Sanity, Strapi |
+| Commerce | Medusa, Shopify API |
+| Communication | Sendbird, Stream Chat |
+| Database | Firebase, Neon, PlanetScale, Supabase, Upstash |
+| DevOps | Fly.io, Netlify, Railway, Vercel |
+| Email | Mailgun, Postmark, Resend, SendGrid |
+| Forms | Formspark, Typeform |
+| Infrastructure | AWS S3, Cloudflare R2, Cloudflare Workers, DigitalOcean Spaces |
+| Integration | Nango, Zapier |
+| Maps | Google Maps, Mapbox |
+| Media | Deepgram, imgix, Mux |
+| Messaging | Ably, Pusher, Twilio, Vonage |
+| Notifications | Knock, Novu, OneSignal |
+| Payments | LemonSqueezy, Paddle, PayPal, Razorpay, Square, Stripe |
+| Scheduling | Cal.com, Calendly |
+| Search | Algolia |
+| Security | Arcjet, Snyk |
+| Storage | Cloudinary, UploadThing |
+| Testing | BrowserStack, Checkly |
+| Workflow | Inngest, Temporal, Trigger.dev |
+
+---
+
+## Quick Start
+
+### Option A — npx (no install)
+
+```bash
+npx @adityanair98/api-oracle serve
+```
+
+### Option B — global install
+
+```bash
+npm install -g @adityanair98/api-oracle
+api-oracle serve
+```
+
+### Connect to Claude Code
+
+Add to `~/.claude/claude_desktop_config.json` under `mcpServers`:
+
+```json
+{
+  "mcpServers": {
+    "api-oracle": {
+      "command": "npx",
+      "args": ["@adityanair98/api-oracle", "serve"]
+    }
+  }
+}
+```
+
+Restart Claude Code. The `api-oracle` server will appear in your MCP servers list.
+
+---
+
+## Web Dashboard
+
+API Oracle includes a local web dashboard to browse, search, and manage the knowledge base.
+
+```bash
+api-oracle dashboard
+# Opens at http://localhost:3737
+```
+
+Dashboard features:
+- Browse all 68 APIs with search and category filtering
+- Quality scores, staleness indicators, pricing info
+- Detail modal with full entry: code examples, gotchas, rate limits
+- Refresh report — shows which entries need re-verification
+- Quality linter — content quality checks beyond schema validation
+- Search test tool — inspect score breakdowns for any query
+
+---
+
+## From Source
+
+### 1. Clone and install
+
+```bash
+git clone https://github.com/adityanair/api-oracle.git
+cd api-oracle
+npm install
+```
+
+### 2. Build and seed
+
+```bash
+npm run build
+npm run seed
+```
+
+### 3. Run
+
+```bash
+# MCP server (stdio)
+node dist/cli.js serve
+
+# Web dashboard
+node dist/cli.js dashboard
+```
+
+### Development scripts
+
+```bash
+npm run dev            # Run MCP server with tsx (no build needed)
+npm test               # Run all tests (160 tests)
+npm run validate       # Validate all JSON entries + cross-references
+npm run lint-entries   # Content quality linter (0 errors, 15 warnings)
+npm run e2e            # End-to-end query scenarios (43 assertions)
+npm run dashboard      # Start dashboard with tsx
+```
+
+---
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `DB_PATH` | `./data/api-oracle.db` | SQLite database path |
+| `PORT` | `3737` | Dashboard server port |
+| `LOG_LEVEL` | `info` | Log level: debug \| info \| warn \| error |
+
+---
+
+## Adding New APIs
+
+1. Create `src/entries/<category>/<slug>.json`
+2. Fill in all schema fields (see `docs/adding-apis.md`)
+3. `npm run validate` — verify schema and cross-references
+4. `npm run seed` — load into database
+5. `npm test` — run tests
+
+See [docs/adding-apis.md](docs/adding-apis.md) for the full guide and JSON template.
+
+---
+
+## Architecture
+
+```
+src/
+├── cli.ts                # CLI entry point (api-oracle serve|dashboard)
+├── index.ts              # MCP server entry point
+├── server.ts             # McpServer setup + tool registration
+├── tools/                # MCP tool handlers
+│   ├── find-api.ts       # find_best_api
+│   ├── compare-apis.ts   # compare_apis
+│   ├── get-setup-guide.ts# get_api_setup_guide
+│   └── check-freshness.ts# check_api_freshness
+├── knowledge/            # Core logic
+│   ├── schema.ts         # Zod schema + TypeScript types
+│   ├── db.ts             # SQLite CRUD (better-sqlite3)
+│   ├── search.ts         # Search pipeline orchestration
+│   ├── scorer.ts         # Weighted multi-factor ranking engine
+│   ├── synonyms.ts       # Query expansion + category detection
+│   └── tfidf.ts          # TF-IDF in-memory search index
+├── updater/              # Freshness and quality system
+│   ├── staleness.ts      # Staleness level detection
+│   ├── report.ts         # Freshness report builder
+│   ├── linter.ts         # Content quality linter
+│   └── version-tracker.ts# Entry version management
+├── dashboard/            # Web dashboard
+│   ├── server.ts         # Express server
+│   ├── routes/api.ts     # REST API routes
+│   └── public/           # Vanilla HTML/CSS/JS frontend
+├── entries/              # 68 JSON API entries
+│   └── <category>/<slug>.json
+└── utils/
+    ├── logger.ts         # Structured stderr logger
+    └── config.ts         # Environment config
+```
+
+## How Search Works
+
+1. **Phrase detection** — extracts `preferFree`, `preferOpenSource`, etc. from natural language
+2. **Synonym expansion** — "crashes" → error tracking; "log in" → auth; "billing" → payments
+3. **Category detection** — maps query to a category with confidence score
+4. **TF-IDF candidate selection** — field-weighted index pre-ranks all 68 entries
+5. **Multi-factor scoring** — useCaseFit (40%) + quality (25%) + devExperience (20%) + pricingFit (15%)
+6. **Category boost** — entries in the detected category receive up to 12% score boost
+7. **Confidence** — top result gets a 0–1 confidence score
+
+See [docs/scoring-logic.md](docs/scoring-logic.md) for full details.
+
+---
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+/**
+ * API Oracle CLI entry point.
+ *
+ * Usage:
+ *   api-oracle serve       — Start the MCP server (default)
+ *   api-oracle dashboard   — Start the web dashboard
+ *   api-oracle --help      — Print usage
+ *   api-oracle --version   — Print version
+ */
+export {};

package/dist/cli.js

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+/**
+ * API Oracle CLI entry point.
+ *
+ * Usage:
+ *   api-oracle serve       — Start the MCP server (default)
+ *   api-oracle dashboard   — Start the web dashboard
+ *   api-oracle --help      — Print usage
+ *   api-oracle --version   — Print version
+ */
+import { createRequire } from "module";
+import { initDb } from "./knowledge/db.js";
+import { config } from "./utils/config.js";
+const require = createRequire(import.meta.url);
+// eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-require-imports
+const pkg = require("../package.json");
+const HELP = `
+  API Oracle — MCP server for API discovery and recommendations
+
+  Usage:
+    api-oracle [command]
+
+  Commands:
+    serve        Start the MCP server on stdio (default)
+    dashboard    Start the web dashboard at http://localhost:3737
+
+  Options:
+    --help, -h   Show this help message
+    --version    Show version
+
+  Environment variables:
+    DB_PATH      Path to SQLite database (default: ./data/api-oracle.db)
+    PORT         Dashboard port (default: 3737)
+    LOG_LEVEL    Log level: debug | info | warn | error (default: info)
+
+  Example Claude Code configuration (~/.claude/claude_desktop_config.json):
+    {
+      "api-oracle": {
+        "command": "npx",
+        "args": ["@adityanair98/api-oracle", "serve"]
+      }
+    }
+`.trimStart();
+async function main() {
+    const args = process.argv.slice(2);
+    const command = args[0] ?? "serve";
+    if (command === "--help" || command === "-h") {
+        process.stdout.write(HELP);
+        process.exit(0);
+    }
+    if (command === "--version") {
+        process.stdout.write(`${pkg.name} v${pkg.version}\n`);
+        process.exit(0);
+    }
+    if (command === "dashboard") {
+        initDb(config.dbPath);
+        const { startDashboard } = await import("./dashboard/server.js");
+        startDashboard();
+        return;
+    }
+    if (command === "serve" || command === "") {
+        // Default: MCP server on stdio
+        initDb(config.dbPath);
+        const { startServer } = await import("./server.js");
+        await startServer();
+        return;
+    }
+    process.stderr.write(`Unknown command: ${command}\n${HELP}`);
+    process.exit(1);
+}
+main().catch((err) => {
+    process.stderr.write(`Fatal error: ${String(err)}\n`);
+    process.exit(1);
+});