{
  "markdown": "<div align=\"center\">\n\n# ⚡ Annolux\n\n**Curated English & Chinese Search API and MCP for AI Agents & RAG Systems**\n\n*Search that can show its work. Every result carries an explicit `fetched_at` timestamp and provenance.*\n\n[![Go Version](https://img.shields.io/github/go-mod/go-version/eason4kim-rocket/annolux?style=flat-square&logo=go)](https://golang.org)\n[![NPM Version](https://img.shields.io/npm/v/annolux-mcp?style=flat-square&logo=npm&color=CB3837)](https://www.npmjs.com/package/annolux-mcp)\n[![Smithery Badge](https://smithery.ai/badge/@eason4kim/annolux)](https://smithery.ai/server/@eason4kim/annolux)\n[![Glama MCP](https://glama.ai/mcp/servers/eason4kim-rocket/annolux/badge)](https://glama.ai/mcp/servers/eason4kim-rocket/annolux)\n[![Add to Cursor](https://img.shields.io/badge/Add%20to-Cursor-000000?style=flat-square&logo=cursor&logoColor=white)](cursor://anysphere.cursor-deeplink/mcp/install?name=annolux&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImFubm9sdXgtbWNwIl19)\n[![MCP Protocol](https://img.shields.io/badge/MCP-2025--12--11-000000?style=flat-square&logo=anthropic)](https://modelcontextprotocol.io/)\n[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg?style=flat-square)](LICENSE)\n[![Free Tier](https://img.shields.io/badge/Free_Tier-1%2C000_Credits-brightgreen?style=flat-square)](https://annolux.com)\n\n[🌐 Website](https://annolux.com) • [📖 API Docs](https://annolux.com/docs) • [⚡ MCP Quickstart](#-mcp-integration) • [📊 Frozen Benchmarks](#-search-quality--frozen-benchmarks) • [📁 Examples](examples/) • [🇨🇳 中文文档](README_zh.md)\n\n</div>\n\n---\n\n## 💡 Why Annolux?\n\nCurrent web search APIs for AI agents suffer from three fatal flaws:\n1. **Garbage in, garbage out**: Commercial search engines index millions of SEO farms, scraped spam, and auto-generated noise that pollute LLM context windows.\n2. **Missing time-provenance**: LLMs hallucinate current state because search APIs omit the exact snapshot timestamp (`fetched_at`).\n3. **Predatory billing**: Paying full price for failed requests, empty outputs, or rate-limited retries.\n\n**Annolux solves this with an agent-first curated approach:**\n- 🛡️ **Curated Bilingual Technical Index**: High-signal English & Chinese corpus (Rust, Go, Python, AI/ML, Official Docs, RFCs, GitHub, arXiv).\n- 🕒 **Explicit `fetched_at` Timestamp**: Every ranked hit reveals the exact second it was ingested—enabling grounded citations and temporal reasoning.\n- 🎯 **Predictable Ledger Billing**: Exactly **1 credit per successful 2xx response**. Errors, timeouts (504), rate limits (429), and bad requests cost **0 credits**.\n- 🧩 **Native Model Context Protocol (MCP)**: Zero setup across Claude Code, Cursor, Windsurf, Cline, Zed, and Claude Desktop.\n- 🚀 **1,000 Free Credits Every Month**: Sign in with GitHub or Google at [annolux.com](https://annolux.com) and start querying in 30 seconds.\n\n---\n\n## 🥊 Comparison: Annolux vs. Generic Search APIs\n\n| Feature / Metric | **Annolux** | **Exa (Metaphor)** | **Tavily** | **Serper / Google** |\n| :--- | :--- | :--- | :--- | :--- |\n| **Index Quality** | **Curated Tech & Knowledge (EN/ZH)** | Web-wide neural | Web-wide aggregator | Entire Web (noisy SEO) |\n| **Chinese (ZH) Tech Corpus** | **First-class native bilingual FTS** | Moderate | Weak / Translated | Mixed with content farms |\n| **Explicit Snapshot Timestamp** | **✅ `fetched_at` on every result** | ❌ Inconsistent | ❌ Omitted | ❌ Snippet approximate only |\n| **Billing Guarantee** | **✅ 1 credit only on 2xx success** | Request-based | Request-based | Request-based |\n| **Failed / Timeout Queries** | **🆓 0 Credits charged** | ❌ Billed | ❌ Billed | ❌ Billed |\n| **MCP Tool Surface** | **Single lean `search_web` (Minimal token waste)** | Multiple bulky tools | Multi-step tools | Needs custom bridge |\n| **Domain Restriction** | **✅ Exact hostname filtering (`domains`)** | ✅ Supported | ✅ Supported | Limited `site:` query |\n| **Free Starter Tier** | **1,000 credits / month** | Limited trial | 1,000 / mo | 2,500 one-time |\n\n---\n\n## 📦 Quick Installation\n\nNode.js 18+ is the only prerequisite. Start in the zero-config sandbox—no account or API key is required:\n\n```bash\nnpx -y annolux-mcp\n```\n\nFor the full monthly allowance, create a free key at [annolux.com](https://annolux.com) and pass it through the process environment:\n\n```bash\nANNOLUX_API_KEY=ann_live_YOUR_API_KEY npx -y annolux-mcp\n```\n\n---\n\n## 🔌 MCP Integration\n\nAnnolux implements the official [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) specification with a single, high-efficiency tool: `search_web`.\n\n### ⚡ 1-Click Installation (Cursor & Smithery)\n\n- **Cursor**: Click [![Add to Cursor](https://img.shields.io/badge/Add%20to-Cursor-000000?style=flat-square&logo=cursor&logoColor=white)](cursor://anysphere.cursor-deeplink/mcp/install?name=annolux&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImFubm9sdXgtbWNwIl19) to install natively via deep link.\n- **Smithery CLI**:\n  ```bash\n  npx -y @smithery/cli install annolux-mcp --client claude\n  npx -y @smithery/cli install annolux-mcp --client cursor\n  ```\n- **Glama Online Playground**: Test queries instantly without local setup on [Glama.ai](https://glama.ai/mcp/servers/eason4kim-rocket/annolux).\n\n### 1. Claude Code\n```bash\nclaude mcp add annolux -- npx -y annolux-mcp\n```\n\nThis starts in sandbox mode. To use an account key, add it with `-e ANNOLUX_API_KEY=ann_live_YOUR_API_KEY` before `--`.\n\n### 2. Cursor / Windsurf\nAdd to your project `.cursor/mcp.json` or global configuration:\n```json\n{\n  \"mcpServers\": {\n    \"annolux\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"annolux-mcp\"],\n      \"env\": {\n        \"ANNOLUX_API_KEY\": \"ann_live_YOUR_API_KEY\"\n      }\n    }\n  }\n}\n```\n\n### 3. Claude Desktop\nAdd to `claude_desktop_config.json`:\n```json\n{\n  \"mcpServers\": {\n    \"annolux\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"annolux-mcp\"],\n      \"env\": {\n        \"ANNOLUX_API_URL\": \"https://api.annolux.com\",\n        \"ANNOLUX_API_KEY\": \"ann_live_YOUR_API_KEY\"\n      }\n    }\n  }\n}\n```\n\n---\n\n## 🚀 HTTP API Quickstart\n\n### Standard Search Endpoint\n```http\nPOST https://api.annolux.com/api/v1/search\nAuthorization: Bearer ann_live_YOUR_API_KEY\nContent-Type: application/json\n```\n\n```json\n{\n  \"query\": \"tokio async runtime memory model\",\n  \"domains\": [\"tokio.rs\", \"docs.rs\", \"github.com\"],\n  \"deduplicate\": true,\n  \"limit\": 5,\n  \"timeout\": 10,\n  \"ranking\": \"default\"\n}\n```\n\n### Python\n```python\nimport os\nimport requests\n\nresponse = requests.post(\n    \"https://api.annolux.com/api/v1/search\",\n    headers={\"Authorization\": f\"Bearer {os.environ.get('ANNOLUX_API_KEY')}\"},\n    json={\n        \"query\": \"DeepSeek R1 architecture reinforcement learning\",\n        \"limit\": 5,\n        \"deduplicate\": True\n    },\n    timeout=15\n)\n\ndata = response.json()\nfor result in data.get(\"results\", []):\n    print(f\"[{result['fetched_at']}] {result['title']} -> {result['url']}\")\n```\n\n### TypeScript / Node.js\n```typescript\nconst res = await fetch(\"https://api.annolux.com/api/v1/search\", {\n  method: \"POST\",\n  headers: {\n    \"Authorization\": `Bearer ${process.env.ANNOLUX_API_KEY}`,\n    \"Content-Type\": \"application/json\"\n  },\n  body: JSON.stringify({\n    query: \"vLLM PagedAttention implementation details\",\n    limit: 5,\n    deduplicate: true\n  })\n});\n\nconst data = await res.json();\nconsole.log(`Credits Remaining: ${res.headers.get(\"X-Annolux-Credits-Remaining\")}`);\nconsole.log(data.results);\n```\n\n### cURL\n```bash\ncurl -s -X POST https://api.annolux.com/api/v1/search \\\n  -H \"Authorization: Bearer ann_live_YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"query\": \"Go sync.Pool benchmark best practices\",\n    \"limit\": 3\n  }' | jq .\n```\n\n---\n\n## 🏛️ Architecture & Mechanics\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│                 AI Agent / RAG Application                  │\n│       (Claude Code / Cursor / LangChain / Custom LLM)       │\n└──────────────────────────────┬──────────────────────────────┘\n                               │\n               Stdio MCP / HTTPS REST Request\n                               │\n                               ▼\n┌─────────────────────────────────────────────────────────────┐\n│                  Annolux Gateway API Engine                 │\n│  ┌─────────────────────────┐     ┌───────────────────────┐  │\n│  │ 1. Account & Rate Limit │ ──► │ Reserve 1 Credit      │  │\n│  │    (5 RPS, Burst 10)    │     │ in /data/accounts.db  │  │\n│  └─────────────────────────┘     └───────────────────────┘  │\n│                                              │              │\n│                                              ▼              │\n│  ┌───────────────────────────────────────────────────────┐  │\n│  │ 2. Bilingual FTS Ranker (/data/index.db)              │  │\n│  │    • Curated English & Chinese Corpus                 │  │\n│  │    • SimHash Content-Deduplication Engine             │  │\n│  │    • Domain Filter & Exact Substring Match            │  │\n│  └───────────────────────────────────────────────────────┘  │\n│                                              │              │\n│                                              ▼              │\n│  ┌───────────────────────────────────────────────────────┐  │\n│  │ 3. Atomic Response & Ledger Settlement                │  │\n│  │    • 2xx Success ──► Commit 1 Credit & Attach Timing  │  │\n│  │    • 4xx/5xx Err ──► Release Reservation (0 Cost)     │  │\n│  └───────────────────────────────────────────────────────┘  │\n└──────────────────────────────┬──────────────────────────────┘\n                               │\n          JSON with exact `fetched_at` & verified URL\n                               │\n                               ▼\n                     [ Grounded LLM Response ]\n```\n\n---\n\n## 📊 Search Quality & Frozen Benchmarks\n\nAnnolux evaluates search retrieval performance against an immutable, frozen blind set of 40 complex bilingual queries. The ranking weights are never tuned on the test set.\n\n| Metric | First Gate Baseline | Prelaunch Verification Gate |\n| :--- | :---:| :---:|\n| **Hit@1** | `72.5%` | **`72.5%`** |\n| **Hit@3** | `82.5%` | **`82.5%`** |\n| **Hit@10** | `85.0%` | **`85.0%`** |\n| **MRR@10** | `0.78125` | **`0.78125`** |\n| **P95 Latency** | `532 ms` | **`356 ms`** |\n| **5xx Error Rate** | `0.00%` | **`0.00%`** |\n\n*All benchmarks are evaluated client-side under full concurrency load.*\n\n---\n\n## 💳 Transparent Pricing\n\n| Plan | Price | Credits | Rate Limits | Billing Rules |\n| :--- | :--- | :--- | :--- | :--- |\n| **Free** | **$0** | **1,000 / month** | 5 RPS / Burst 10 | Free forever, no credit card required |\n| **Pro** | **$29 / mo** | **20,000 / mo** | 5 RPS / Burst 10 | 1 success = 1 credit, no rollover |\n| **Scale** | **$99 / mo** | **100,000 / mo** | 5 RPS / Burst 10 | 1 success = 1 credit, no rollover |\n\n- No overage charges.\n- Errors, rate-limits, and timeouts are 100% free (0 credit charged).\n- Up to 3 active API keys per account.\n\n---\n\n## 📁 Examples & Recipes\n\nCheck the [`examples/`](examples/) directory for production-ready starters:\n- [`01-claude-code-literature-research`](examples/01-claude-code-literature-research/): Automated technical survey agent with timestamped citations.\n- [`02-cursor-authority-domain-refactor`](examples/02-cursor-authority-domain-refactor/): Restrict search to official doc domains (`react.dev`, `go.dev`) for zero-hallucination refactoring.\n- [`03-production-rag-temporal-pipeline`](examples/03-production-rag-temporal-pipeline/): Production RAG hybrid search pipeline with fallback retrieval.\n- [`04-n8n-ai-research-agent`](examples/04-n8n-ai-research-agent/): Ready-to-import n8n AI Agent workflow with community node (`n8n-nodes-annolux`) and temporal citations.\n\n---\n\n## 🤝 Community & Support\n\n- File bug reports or feature requests on [GitHub Issues](https://github.com/eason4kim-rocket/annolux/issues).\n- Review [SECURITY.md](SECURITY.md) for private vulnerability reporting.\n- Public OpenAPI specification: [annolux.com/openapi.json](https://annolux.com/openapi.json).\n\n---\n\n## 📄 License\n\nAnnolux is open-source software licensed under the [Apache License, Version 2.0](LICENSE).\n",
  "bytes": 12131,
  "sha": "ae495093327b9d2d6248bd5460683e7d5c95ebe98ab192de9b9b570f82d34d31",
  "repo_slug": "eason4kim-rocket/annolux",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_eason4kim_rocket_annolux_87b35814/readme"
}