{"_id":"@adityanair98/api-oracle","name":"@adityanair98/api-oracle","dist-tags":{"latest":"0.5.0"},"versions":{"0.5.0":{"name":"@adityanair98/api-oracle","version":"0.5.0","description":"MCP server that finds, evaluates, and recommends the best API for any programming task","type":"module","main":"dist/index.js","bin":{"api-oracle":"dist/cli.js"},"keywords":["mcp","claude","api","recommendation","developer-tools","ai-tools"],"engines":{"node":">=20.0.0"},"license":"MIT","scripts":{"build":"tsc && cp -r src/dashboard/public dist/dashboard/public","dev":"tsx src/index.ts","test":"vitest run","test:watch":"vitest","validate":"tsx scripts/validate-entries.ts","seed":"tsx scripts/seed-db.ts","e2e":"tsx scripts/e2e-test.ts","analyze":"tsx scripts/scoring-analysis.ts","refresh-report":"tsx scripts/refresh-report.ts","lint-entries":"tsx scripts/lint-entries.ts","dashboard":"tsx src/dashboard/server.ts","dashboard:dev":"tsx watch src/dashboard/server.ts","prepublishOnly":"npm run build && npm test"},"dependencies":{"@modelcontextprotocol/sdk":"1.27.1","better-sqlite3":"12.6.2","express":"5.1.0","zod":"4.3.6"},"devDependencies":{"@types/better-sqlite3":"7.6.13","@types/express":"5.0.3","@types/node":"25.3.0","tsx":"4.21.0","typescript":"5.9.3","vitest":"4.0.18"},"_id":"@adityanair98/api-oracle@0.5.0","gitHead":"53253967823a7652944f9a798cbff95ff2c5a964","types":"./dist/index.d.ts","_nodeVersion":"20.20.0","_npmVersion":"10.8.2","dist":{"integrity":"sha512-Ra3TjYn4lpta+gcpSTkMf7Zw6RXBIC/ErBuO7s54Vvnw4zmh0uLzepqfyV1S/AN/pu97R5CANveAshtPsyNG5Q==","shasum":"88e98a7cd37543579de506b7e69373d87bd0a336","tarball":"https://registry.npmjs.org/@adityanair98/api-oracle/-/api-oracle-0.5.0.tgz","fileCount":119,"unpackedSize":785178,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDnCPPTo9NboEknVUFWJWeDml7oRmqJIDR6GjAJ8D0MLAIhAIqn/it9ij4T0D94yVnChKOSS51Y/Hfo1PueY2c+JLMF"}]},"_npmUser":{"name":"adityanair98","email":"adityanair98@gmail.com"},"directories":{},"maintainers":[{"name":"adityanair98","email":"adityanair98@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/api-oracle_0.5.0_1772150762918_0.1917017287006737"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-27T00:06:02.781Z","0.5.0":"2026-02-27T00:06:03.159Z","modified":"2026-02-27T00:06:03.445Z"},"maintainers":[{"name":"adityanair98","email":"adityanair98@gmail.com"}],"description":"MCP server that finds, evaluates, and recommends the best API for any programming task","keywords":["mcp","claude","api","recommendation","developer-tools","ai-tools"],"license":"MIT","readme":"# API Oracle\n\nAn MCP server that gives Claude Code the ability to find, evaluate, and recommend the best API for any programming task.\n\nWhen 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.\n\n[![CI](https://github.com/adityanair/api-oracle/actions/workflows/ci.yml/badge.svg)](https://github.com/adityanair/api-oracle/actions/workflows/ci.yml)\n\n---\n\n## MCP Tools\n\n| Tool | What it does |\n|------|-------------|\n| `find_best_api` | Recommends the best API for a task with quick-start code |\n| `compare_apis` | Side-by-side comparison of 2–5 APIs |\n| `get_api_setup_guide` | Full setup instructions for a specific API |\n| `check_api_freshness` | Staleness report showing which entries need re-verification |\n\n## Knowledge Base — 68 APIs across 23 categories\n\n| Category | APIs |\n|----------|------|\n| AI | Anthropic, OpenAI, Replicate, Resemble AI, Stability AI, ElevenLabs |\n| Analytics | PostHog, Sentry |\n| Auth | Auth0, Clerk |\n| CMS | Contentful, Sanity, Strapi |\n| Commerce | Medusa, Shopify API |\n| Communication | Sendbird, Stream Chat |\n| Database | Firebase, Neon, PlanetScale, Supabase, Upstash |\n| DevOps | Fly.io, Netlify, Railway, Vercel |\n| Email | Mailgun, Postmark, Resend, SendGrid |\n| Forms | Formspark, Typeform |\n| Infrastructure | AWS S3, Cloudflare R2, Cloudflare Workers, DigitalOcean Spaces |\n| Integration | Nango, Zapier |\n| Maps | Google Maps, Mapbox |\n| Media | Deepgram, imgix, Mux |\n| Messaging | Ably, Pusher, Twilio, Vonage |\n| Notifications | Knock, Novu, OneSignal |\n| Payments | LemonSqueezy, Paddle, PayPal, Razorpay, Square, Stripe |\n| Scheduling | Cal.com, Calendly |\n| Search | Algolia |\n| Security | Arcjet, Snyk |\n| Storage | Cloudinary, UploadThing |\n| Testing | BrowserStack, Checkly |\n| Workflow | Inngest, Temporal, Trigger.dev |\n\n---\n\n## Quick Start\n\n### Option A — npx (no install)\n\n```bash\nnpx @adityanair98/api-oracle serve\n```\n\n### Option B — global install\n\n```bash\nnpm install -g @adityanair98/api-oracle\napi-oracle serve\n```\n\n### Connect to Claude Code\n\nAdd to `~/.claude/claude_desktop_config.json` under `mcpServers`:\n\n```json\n{\n  \"mcpServers\": {\n    \"api-oracle\": {\n      \"command\": \"npx\",\n      \"args\": [\"@adityanair98/api-oracle\", \"serve\"]\n    }\n  }\n}\n```\n\nRestart Claude Code. The `api-oracle` server will appear in your MCP servers list.\n\n---\n\n## Web Dashboard\n\nAPI Oracle includes a local web dashboard to browse, search, and manage the knowledge base.\n\n```bash\napi-oracle dashboard\n# Opens at http://localhost:3737\n```\n\nDashboard features:\n- Browse all 68 APIs with search and category filtering\n- Quality scores, staleness indicators, pricing info\n- Detail modal with full entry: code examples, gotchas, rate limits\n- Refresh report — shows which entries need re-verification\n- Quality linter — content quality checks beyond schema validation\n- Search test tool — inspect score breakdowns for any query\n\n---\n\n## From Source\n\n### 1. Clone and install\n\n```bash\ngit clone https://github.com/adityanair/api-oracle.git\ncd api-oracle\nnpm install\n```\n\n### 2. Build and seed\n\n```bash\nnpm run build\nnpm run seed\n```\n\n### 3. Run\n\n```bash\n# MCP server (stdio)\nnode dist/cli.js serve\n\n# Web dashboard\nnode dist/cli.js dashboard\n```\n\n### Development scripts\n\n```bash\nnpm run dev            # Run MCP server with tsx (no build needed)\nnpm test               # Run all tests (160 tests)\nnpm run validate       # Validate all JSON entries + cross-references\nnpm run lint-entries   # Content quality linter (0 errors, 15 warnings)\nnpm run e2e            # End-to-end query scenarios (43 assertions)\nnpm run dashboard      # Start dashboard with tsx\n```\n\n---\n\n## Environment Variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `DB_PATH` | `./data/api-oracle.db` | SQLite database path |\n| `PORT` | `3737` | Dashboard server port |\n| `LOG_LEVEL` | `info` | Log level: debug \\| info \\| warn \\| error |\n\n---\n\n## Adding New APIs\n\n1. Create `src/entries/<category>/<slug>.json`\n2. Fill in all schema fields (see `docs/adding-apis.md`)\n3. `npm run validate` — verify schema and cross-references\n4. `npm run seed` — load into database\n5. `npm test` — run tests\n\nSee [docs/adding-apis.md](docs/adding-apis.md) for the full guide and JSON template.\n\n---\n\n## Architecture\n\n```\nsrc/\n├── cli.ts                # CLI entry point (api-oracle serve|dashboard)\n├── index.ts              # MCP server entry point\n├── server.ts             # McpServer setup + tool registration\n├── tools/                # MCP tool handlers\n│   ├── find-api.ts       # find_best_api\n│   ├── compare-apis.ts   # compare_apis\n│   ├── get-setup-guide.ts# get_api_setup_guide\n│   └── check-freshness.ts# check_api_freshness\n├── knowledge/            # Core logic\n│   ├── schema.ts         # Zod schema + TypeScript types\n│   ├── db.ts             # SQLite CRUD (better-sqlite3)\n│   ├── search.ts         # Search pipeline orchestration\n│   ├── scorer.ts         # Weighted multi-factor ranking engine\n│   ├── synonyms.ts       # Query expansion + category detection\n│   └── tfidf.ts          # TF-IDF in-memory search index\n├── updater/              # Freshness and quality system\n│   ├── staleness.ts      # Staleness level detection\n│   ├── report.ts         # Freshness report builder\n│   ├── linter.ts         # Content quality linter\n│   └── version-tracker.ts# Entry version management\n├── dashboard/            # Web dashboard\n│   ├── server.ts         # Express server\n│   ├── routes/api.ts     # REST API routes\n│   └── public/           # Vanilla HTML/CSS/JS frontend\n├── entries/              # 68 JSON API entries\n│   └── <category>/<slug>.json\n└── utils/\n    ├── logger.ts         # Structured stderr logger\n    └── config.ts         # Environment config\n```\n\n## How Search Works\n\n1. **Phrase detection** — extracts `preferFree`, `preferOpenSource`, etc. from natural language\n2. **Synonym expansion** — \"crashes\" → error tracking; \"log in\" → auth; \"billing\" → payments\n3. **Category detection** — maps query to a category with confidence score\n4. **TF-IDF candidate selection** — field-weighted index pre-ranks all 68 entries\n5. **Multi-factor scoring** — useCaseFit (40%) + quality (25%) + devExperience (20%) + pricingFit (15%)\n6. **Category boost** — entries in the detected category receive up to 12% score boost\n7. **Confidence** — top result gets a 0–1 confidence score\n\nSee [docs/scoring-logic.md](docs/scoring-logic.md) for full details.\n\n---\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-66861bad8e2826f8d96bf4b00fe55e1d"}