@automatelab/citation-intelligence 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 automatelab
+
+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,302 @@
+# Citation Intelligence MCP
+
+**A free, self-hosted MCP server that tells your agent what LLMs cite - across Perplexity, Google AI Overviews, ChatGPT, Claude, Gemini, and Bing.**
+
+[![npm version](https://img.shields.io/npm/v/@automatelab/citation-intelligence.svg)](https://www.npmjs.com/package/@automatelab/citation-intelligence)
+[![license](https://img.shields.io/npm/l/@automatelab/citation-intelligence.svg)](./LICENSE)
+[![node](https://img.shields.io/node/v/@automatelab/citation-intelligence.svg)](https://nodejs.org)
+
+## What this is
+
+An MCP server for agents and developers who need to know which URLs get cited by AI search engines for any query. Install once, query from any MCP-compatible client (Claude Desktop, Cursor, Claude Code, Continue, Cline, n8n, LangGraph). Self-hosted, no account, no centralized backend. Bring your own API keys; nothing is stored on a remote server.
+
+## Who this is for
+
+Install this if you're:
+
+- Building an agent that does research and want it to cite sources LLMs already trust
+- A solo dev or indie hacker checking whether your SaaS is showing up in AI search
+- A content creator confirming your articles are being cited by ChatGPT, Claude, or Perplexity
+- An SEO or GEO practitioner who wants programmatic citation data without a $295-$499/mo dashboard
+- Running an editorial pipeline and want citation-deficit-driven topic selection
+- Comparing competitor visibility across AI engines for any niche
+
+Do NOT install this if you want:
+
+- A polished marketing dashboard with charts and team seats - try Profound, AthenaHQ, or Otterly.AI
+- A hosted service with SLAs - this is self-hosted by design
+- Citation tracking for academic papers - try citecheck
+- 350M+ pre-modeled prompts - that's Ahrefs Brand Radar
+
+## Why this exists
+
+The AI citation tracking market is dominated by VC-funded dashboards starting at $295/mo. None ships MCP-first. If you're an agent or developer who wants citation data piped directly into your workflow - not into a SaaS login - there isn't a tool for you. This is that tool.
+
+---
+
+## Tools
+
+| Tool | Purpose |
+|---|---|
+| `check_citations` | URLs cited by Perplexity / Claude / ChatGPT / Gemini / Bing for a query |
+| `am_i_cited` | Presence + rank for a domain across a query cluster |
+| `ai_overview` | Google AI Overview presence + cited sources |
+| `cited_for` | Queries the domain has been cited for, from local cache |
+| `predict_citation` | Citation likelihood from public signals - no LLM fired |
+| `track_queries` | Save / load / list named query panels (editorial watchlists) |
+| `run_panel` | Run a panel through `am_i_cited` and snapshot to disk |
+| `citation_trend` | Time-series report of citation rate + per-query gained/lost deltas |
+| `compare_domains` | Side-by-side `predict_citation` across 2-10 URLs |
+| `wikipedia_mentions` | List Wikipedia articles referencing a domain (zero keys) |
+| `audit_sitemap` | Bulk `predict_citation` across every URL in a sitemap, worst-first |
+| `gsc_citation_gap` | Join Google Search Console performance with AI citation status |
+
+## Quick start
+
+```bash
+npx -y @automatelab/citation-intelligence
+```
+
+Requires Node 20 or later.
+
+### Claude Desktop
+
+Add to `%APPDATA%\Claude\claude_desktop_config.json` (Windows) or `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):
+
+```json
+{
+  "mcpServers": {
+    "citation-intelligence": {
+      "command": "npx",
+      "args": ["-y", "@automatelab/citation-intelligence"],
+      "env": {
+        "PERPLEXITY_API_KEY": "pplx-...",
+        "SERPAPI_KEY": "...",
+        "ANTHROPIC_API_KEY": "sk-ant-...",
+        "OPENAI_API_KEY": "sk-...",
+        "GEMINI_API_KEY": "..."
+      }
+    }
+  }
+}
+```
+
+Set only the keys you have. Any MCP client that supports stdio transport works - same `command` / `args` pattern.
+
+## How it stays free
+
+- **No central backend.** The server runs on your machine. Nothing is uploaded.
+- **Free tier first.** SerpAPI gives 100 free Google AI Overview lookups/month. Bing Web Search has a free tier. Perplexity offers free Sonar access on signup.
+- **Bring your own paid keys** if you want the premium engines (Claude, ChatGPT, Gemini). Keys pass through to the vendor and never touch any third party.
+- **Local cache** at `~/.config/citation-intelligence/cache.json`. Repeated queries hit cache, not API. Default TTL: 7 days.
+- **predict_citation runs with zero keys** - it scores citation likelihood from public signals (Wikipedia, schema.org, llms.txt, GitHub) without firing any LLM.
+
+## Privacy
+
+- All API calls go from your machine directly to the vendor (Anthropic, OpenAI, Google, Perplexity, Bing, SerpAPI).
+- No proxy. No analytics. No telemetry by default.
+- API keys are read from environment variables on the MCP process - never logged, never persisted.
+- Cache file lives at `~/.config/citation-intelligence/cache.json`. Delete it any time.
+
+## Environment variables
+
+| Var | Purpose | Free tier? |
+|---|---|---|
+| `PERPLEXITY_API_KEY` | check_citations (Perplexity) | Yes |
+| `SERPAPI_KEY` | ai_overview | 100/month free |
+| `BING_API_KEY` | check_citations (Bing) | Yes |
+| `ANTHROPIC_API_KEY` | check_citations (Claude) | Paid only |
+| `OPENAI_API_KEY` | check_citations (ChatGPT) | Paid only |
+| `GEMINI_API_KEY` | check_citations (Gemini) | Yes |
+| `CITATION_CACHE_TTL_DAYS` | Cache TTL for citation_check entries (default 7) | n/a |
+| `CITATION_AI_OVERVIEW_TTL_DAYS` | Cache TTL for ai_overview entries (default 1) | n/a |
+| `CITATION_CONFIG_DIR` | Override config dir (default `~/.config/citation-intelligence`) | n/a |
+
+## Example: am I cited?
+
+```
+You: For the queries "best AI citation tracker", "MCP for AI search", "self-hosted GEO tool",
+     is automatelab.tech cited?
+
+(agent invokes am_i_cited)
+
+Result:
+{
+  "domain": "automatelab.tech",
+  "engine": "perplexity",
+  "results": [
+    { "query": "best AI citation tracker",   "cited": true,  "rank": 4 },
+    { "query": "MCP for AI search",          "cited": true,  "rank": 1 },
+    { "query": "self-hosted GEO tool",       "cited": false, "matching_urls": [] }
+  ],
+  "summary": {
+    "queries_total": 3,
+    "queries_cited": 2,
+    "citation_rate": 0.67,
+    "average_rank": 2.5
+  }
+}
+```
+
+## Example: predict citation likelihood (no key required)
+
+```
+You: How likely is https://example.com/blog/post to be cited by AI?
+
+(agent invokes predict_citation)
+
+Result:
+{
+  "url": "https://example.com/blog/post",
+  "score": 62,
+  "grade": "C",
+  "signals": {
+    "wikipedia_linked": false,
+    "github_referenced": false,
+    "reddit_referenced": true,
+    "llms_txt_present": true,
+    "https": true,
+    "has_article_schema": true,
+    "has_faq_schema": false,
+    "has_breadcrumb_schema": true,
+    "canonical_clean": true,
+    "word_count": 1850,
+    "reading_time_minutes": 8,
+    "h2_count": 7,
+    "h2_question_count": 1,
+    "authority_link_count": 2,
+    "external_link_count": 6,
+    "internal_link_count": 11,
+    "last_modified_days_ago": 42,
+    "has_open_graph": true
+  },
+  "fixes": [
+    { "signal": "has_faq_schema", "suggestion": "Page already has question-style H2s. Wrap them in FAQPage JSON-LD - high-leverage win.", "estimated_lift": "high" },
+    { "signal": "h2_question_count", "suggestion": "Reframe at least 2 H2s as questions users actually ask...", "estimated_lift": "medium" }
+  ]
+}
+```
+
+The Wikipedia signal is measured (it correlates with citation) but no "go get a Wikipedia article" suggestion is emitted - the advice would be non-actionable. Scoring is split across six buckets - domain authority, structured data, content depth, link graph, freshness, metadata - so a thin page and a deep page on the same domain get meaningfully different scores.
+
+---
+
+## Workflow recipes
+
+Concrete patterns that compose the 12 tools into something useful. Costs assume ChatGPT or Perplexity at ~$0.01-0.03/query.
+
+### 1. Weekly citation tracker
+
+The single highest-ROI pattern. Pick 20-30 queries from your editorial backlog, snapshot weekly, watch the rate trend.
+
+```
+# One-time setup
+track_queries name="editorial-watchlist" domain="example.com" action="save"
+              queries=["best widget tutorial", "how to set up X", ...]
+
+# Weekly cron (5 min, ~$0.20-0.60 per run)
+run_panel name="editorial-watchlist"
+
+# Anytime
+citation_trend panel="editorial-watchlist"
+```
+
+`citation_trend` returns per-query deltas: which queries flipped from `cited: false` to `cited: true` since the first snapshot. That's your real editorial-impact metric.
+
+### 2. Pre-publish gate
+
+Before publishing a post, find out who owns the citation slot and whether the slot is worth competing for.
+
+```
+# 1. Is there an AI Overview to compete for?
+ai_overview query="<target query>"
+
+# 2. Who is cited today?
+check_citations query="<target query>"
+
+# 3. After publish + 14 days: did the post break in?
+am_i_cited domain="example.com" queries=["<target query>"]
+```
+
+If `check_citations` returns 5+ strong incumbents on a low-volume query, pick a different angle. If `ai_overview_present: false`, the query has no AI surface - reconsider.
+
+### 3. Bulk site audit
+
+Catch site-wide structural issues across every page in one pass. Zero API spend.
+
+```
+audit_sitemap sitemap_url="https://example.com/sitemap.xml" limit=200
+```
+
+Returns `worst_first` sorted by citation-likelihood score. Surfaces missing schema, conflicting canonicals, missing `/llms.txt`, broken HTTPS.
+
+### 4. Competitor signal gap
+
+You're not cited; they are. Why?
+
+```
+# 1. Find the top-cited URLs for your target query
+check_citations query="<query>"
+
+# 2. Compare your URL to theirs signal-by-signal
+compare_domains urls=[
+  "https://example.com/your-post",
+  "https://competitor-1.com/their-post",
+  "https://competitor-2.com/their-post"
+]
+```
+
+`diverging_signals` is the list of where you're losing. Usually obvious once you see it - they have FAQ schema, GitHub references, Wikipedia links - you don't.
+
+### 5. Google-rank vs AI-citation gap
+
+The closest editorial wins are queries where you already rank in Google's top 10 but are invisible to AI. Requires a GCP service account with `webmasters.readonly` scope.
+
+```
+gsc_citation_gap
+  domain="example.com"
+  queries=["...editorial watchlist..."]
+  start_date="2026-04-01"
+  end_date="2026-05-01"
+```
+
+`closest_wins` returns queries with `position <= 10` and `ai_cited: false`, sorted by impressions desc. Push citation signals on those specific URLs first.
+
+### 6. Wikipedia mention monitor
+
+Wikipedia is the top-correlation signal but the advice "get on Wikipedia" is useless. So instead: watch when it happens organically.
+
+```
+wikipedia_mentions domain="example.com" limit=50
+```
+
+Returns Wikipedia article URLs that already link to the domain. Re-run quarterly; the diff is your "we got a Wikipedia citation" alert.
+
+## Schema.org
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "SoftwareApplication",
+  "name": "Citation Intelligence MCP",
+  "applicationCategory": "DeveloperApplication",
+  "operatingSystem": "Cross-platform",
+  "description": "Self-hosted MCP server for querying AI citation data from Perplexity, Claude, ChatGPT, Gemini, Bing, and Google AI Overviews.",
+  "offers": { "@type": "Offer", "price": "0" },
+  "url": "https://github.com/AutomateLab-tech/citation-intelligence"
+}
+```
+
+## Contributing
+
+Bug reports, feature ideas, and PRs welcome. See [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+## Security
+
+Report a vulnerability via [SECURITY.md](./SECURITY.md).
+
+## License
+
+MIT - see [LICENSE](./LICENSE).
+
+Built by [automatelab.tech](https://automatelab.tech)

package/dist/adapters/anthropic.d.ts

@@ -0,0 +1,3 @@
+import type { AdapterResult } from "../types.js";
+export declare function claudeSearch(query: string, maxResults: number): Promise<AdapterResult>;
+//# sourceMappingURL=anthropic.d.ts.map

package/dist/adapters/anthropic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"anthropic.d.ts","sourceRoot":"","sources":["../../src/adapters/anthropic.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAY,MAAM,aAAa,CAAC;AAa3D,wBAAsB,YAAY,CAChC,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,aAAa,CAAC,CAsDxB"}

package/dist/adapters/anthropic.js

@@ -0,0 +1,52 @@
+import { envKey } from "../lib/config.js";
+import { fetchJson, ToolFetchError } from "../lib/fetch.js";
+export async function claudeSearch(query, maxResults) {
+    const key = envKey("ANTHROPIC_API_KEY");
+    if (!key) {
+        throw new ToolFetchError({
+            type: "missing_key",
+            engine: "claude",
+            env_var: "ANTHROPIC_API_KEY",
+            message: "Set ANTHROPIC_API_KEY to use the Claude engine. Get a key at https://console.anthropic.com.",
+        });
+    }
+    const body = JSON.stringify({
+        model: "claude-sonnet-4-6",
+        max_tokens: 1024,
+        tools: [{ type: "web_search_20250305", name: "web_search", max_uses: 3 }],
+        messages: [{ role: "user", content: query }],
+    });
+    const res = await fetchJson("https://api.anthropic.com/v1/messages", {
+        method: "POST",
+        headers: {
+            "x-api-key": key,
+            "anthropic-version": "2023-06-01",
+            "content-type": "application/json",
+        },
+        body,
+    });
+    const citations = [];
+    const seen = new Set();
+    const textParts = [];
+    for (const block of res.content ?? []) {
+        if (block.type === "text") {
+            textParts.push(block.text);
+        }
+        else if (block.type === "web_search_tool_result") {
+            for (const r of block.content ?? []) {
+                if (!r.url || seen.has(r.url))
+                    continue;
+                seen.add(r.url);
+                citations.push({
+                    url: r.url,
+                    title: r.title,
+                    rank: citations.length + 1,
+                });
+                if (citations.length >= maxResults)
+                    break;
+            }
+        }
+    }
+    return { citations, raw_answer: textParts.join("\n") || undefined };
+}
+//# sourceMappingURL=anthropic.js.map

package/dist/adapters/anthropic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"anthropic.js","sourceRoot":"","sources":["../../src/adapters/anthropic.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAc5D,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,KAAa,EACb,UAAkB;IAElB,MAAM,GAAG,GAAG,MAAM,CAAC,mBAAmB,CAAC,CAAC;IACxC,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,MAAM,IAAI,cAAc,CAAC;YACvB,IAAI,EAAE,aAAa;YACnB,MAAM,EAAE,QAAQ;YAChB,OAAO,EAAE,mBAAmB;YAC5B,OAAO,EACL,6FAA6F;SAChG,CAAC,CAAC;IACL,CAAC;IAED,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC;QAC1B,KAAK,EAAE,mBAAmB;QAC1B,UAAU,EAAE,IAAI;QAChB,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,qBAAqB,EAAE,IAAI,EAAE,YAAY,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC;QACzE,QAAQ,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;KAC7C,CAAC,CAAC;IAEH,MAAM,GAAG,GAAG,MAAM,SAAS,CACzB,uCAAuC,EACvC;QACE,MAAM,EAAE,MAAM;QACd,OAAO,EAAE;YACP,WAAW,EAAE,GAAG;YAChB,mBAAmB,EAAE,YAAY;YACjC,cAAc,EAAE,kBAAkB;SACnC;QACD,IAAI;KACL,CACF,CAAC;IAEF,MAAM,SAAS,GAAe,EAAE,CAAC;IACjC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,SAAS,GAAa,EAAE,CAAC;IAE/B,KAAK,MAAM,KAAK,IAAI,GAAG,CAAC,OAAO,IAAI,EAAE,EAAE,CAAC;QACtC,IAAI,KAAK,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;YAC1B,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC7B,CAAC;aAAM,IAAI,KAAK,CAAC,IAAI,KAAK,wBAAwB,EAAE,CAAC;YACnD,KAAK,MAAM,CAAC,IAAI,KAAK,CAAC,OAAO,IAAI,EAAE,EAAE,CAAC;gBACpC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC;oBAAE,SAAS;gBACxC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;gBAChB,SAAS,CAAC,IAAI,CAAC;oBACb,GAAG,EAAE,CAAC,CAAC,GAAG;oBACV,KAAK,EAAE,CAAC,CAAC,KAAK;oBACd,IAAI,EAAE,SAAS,CAAC,MAAM,GAAG,CAAC;iBAC3B,CAAC,CAAC;gBACH,IAAI,SAAS,CAAC,MAAM,IAAI,UAAU;oBAAE,MAAM;YAC5C,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,SAAS,EAAE,CAAC;AACtE,CAAC"}

package/dist/adapters/bing.d.ts

@@ -0,0 +1,3 @@
+import type { AdapterResult } from "../types.js";
+export declare function bingSearch(query: string, maxResults: number): Promise<AdapterResult>;
+//# sourceMappingURL=bing.d.ts.map

package/dist/adapters/bing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bing.d.ts","sourceRoot":"","sources":["../../src/adapters/bing.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAY,MAAM,aAAa,CAAC;AAQ3D,wBAAsB,UAAU,CAC9B,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,aAAa,CAAC,CAgCxB"}

package/dist/adapters/bing.js

@@ -0,0 +1,31 @@
+import { envKey } from "../lib/config.js";
+import { fetchJson, ToolFetchError } from "../lib/fetch.js";
+export async function bingSearch(query, maxResults) {
+    const key = envKey("BING_API_KEY");
+    if (!key) {
+        throw new ToolFetchError({
+            type: "missing_key",
+            engine: "bing",
+            env_var: "BING_API_KEY",
+            message: "Set BING_API_KEY to use the Bing engine. Free tier at https://www.microsoft.com/en-us/bing/apis/bing-web-search-api.",
+        });
+    }
+    const params = new URLSearchParams({ q: query, count: String(maxResults) });
+    const res = await fetchJson(`https://api.bing.microsoft.com/v7.0/search?${params.toString()}`, { headers: { "ocp-apim-subscription-key": key } });
+    const citations = [];
+    let rank = 1;
+    for (const v of res.webPages?.value ?? []) {
+        if (!v.url)
+            continue;
+        citations.push({
+            url: v.url,
+            title: v.name,
+            snippet: v.snippet,
+            rank: rank++,
+        });
+        if (citations.length >= maxResults)
+            break;
+    }
+    return { citations };
+}
+//# sourceMappingURL=bing.js.map

package/dist/adapters/bing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bing.js","sourceRoot":"","sources":["../../src/adapters/bing.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAS5D,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,KAAa,EACb,UAAkB;IAElB,MAAM,GAAG,GAAG,MAAM,CAAC,cAAc,CAAC,CAAC;IACnC,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,MAAM,IAAI,cAAc,CAAC;YACvB,IAAI,EAAE,aAAa;YACnB,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,cAAc;YACvB,OAAO,EACL,sHAAsH;SACzH,CAAC,CAAC;IACL,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,eAAe,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;IAC5E,MAAM,GAAG,GAAG,MAAM,SAAS,CACzB,8CAA8C,MAAM,CAAC,QAAQ,EAAE,EAAE,EACjE,EAAE,OAAO,EAAE,EAAE,2BAA2B,EAAE,GAAG,EAAE,EAAE,CAClD,CAAC;IAEF,MAAM,SAAS,GAAe,EAAE,CAAC;IACjC,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,KAAK,MAAM,CAAC,IAAI,GAAG,CAAC,QAAQ,EAAE,KAAK,IAAI,EAAE,EAAE,CAAC;QAC1C,IAAI,CAAC,CAAC,CAAC,GAAG;YAAE,SAAS;QACrB,SAAS,CAAC,IAAI,CAAC;YACb,GAAG,EAAE,CAAC,CAAC,GAAG;YACV,KAAK,EAAE,CAAC,CAAC,IAAI;YACb,OAAO,EAAE,CAAC,CAAC,OAAO;YAClB,IAAI,EAAE,IAAI,EAAE;SACb,CAAC,CAAC;QACH,IAAI,SAAS,CAAC,MAAM,IAAI,UAAU;YAAE,MAAM;IAC5C,CAAC;IAED,OAAO,EAAE,SAAS,EAAE,CAAC;AACvB,CAAC"}

package/dist/adapters/gemini.d.ts

@@ -0,0 +1,3 @@
+import type { AdapterResult } from "../types.js";
+export declare function geminiSearch(query: string, maxResults: number): Promise<AdapterResult>;
+//# sourceMappingURL=gemini.d.ts.map

package/dist/adapters/gemini.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gemini.d.ts","sourceRoot":"","sources":["../../src/adapters/gemini.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAY,MAAM,aAAa,CAAC;AAW3D,wBAAsB,YAAY,CAChC,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,aAAa,CAAC,CA+CxB"}

package/dist/adapters/gemini.js

@@ -0,0 +1,47 @@
+import { envKey } from "../lib/config.js";
+import { fetchJson, ToolFetchError } from "../lib/fetch.js";
+export async function geminiSearch(query, maxResults) {
+    const key = envKey("GEMINI_API_KEY");
+    if (!key) {
+        throw new ToolFetchError({
+            type: "missing_key",
+            engine: "gemini",
+            env_var: "GEMINI_API_KEY",
+            message: "Set GEMINI_API_KEY to use the Gemini engine. Get a key at https://aistudio.google.com/apikey.",
+        });
+    }
+    const body = JSON.stringify({
+        contents: [{ parts: [{ text: query }] }],
+        tools: [{ google_search: {} }],
+    });
+    const url = `https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent?key=${encodeURIComponent(key)}`;
+    const res = await fetchJson(url, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body,
+    });
+    const citations = [];
+    const seen = new Set();
+    const textParts = [];
+    for (const cand of res.candidates ?? []) {
+        for (const p of cand.content?.parts ?? []) {
+            if (p.text)
+                textParts.push(p.text);
+        }
+        for (const chunk of cand.groundingMetadata?.groundingChunks ?? []) {
+            const u = chunk.web?.uri;
+            if (!u || seen.has(u))
+                continue;
+            seen.add(u);
+            citations.push({
+                url: u,
+                title: chunk.web?.title,
+                rank: citations.length + 1,
+            });
+            if (citations.length >= maxResults)
+                break;
+        }
+    }
+    return { citations, raw_answer: textParts.join("\n") || undefined };
+}
+//# sourceMappingURL=gemini.js.map

package/dist/adapters/gemini.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gemini.js","sourceRoot":"","sources":["../../src/adapters/gemini.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAY5D,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,KAAa,EACb,UAAkB;IAElB,MAAM,GAAG,GAAG,MAAM,CAAC,gBAAgB,CAAC,CAAC;IACrC,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,MAAM,IAAI,cAAc,CAAC;YACvB,IAAI,EAAE,aAAa;YACnB,MAAM,EAAE,QAAQ;YAChB,OAAO,EAAE,gBAAgB;YACzB,OAAO,EACL,+FAA+F;SAClG,CAAC,CAAC;IACL,CAAC;IAED,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC;QAC1B,QAAQ,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;QACxC,KAAK,EAAE,CAAC,EAAE,aAAa,EAAE,EAAE,EAAE,CAAC;KAC/B,CAAC,CAAC;IAEH,MAAM,GAAG,GAAG,gGAAgG,kBAAkB,CAAC,GAAG,CAAC,EAAE,CAAC;IAEtI,MAAM,GAAG,GAAG,MAAM,SAAS,CAAiB,GAAG,EAAE;QAC/C,MAAM,EAAE,MAAM;QACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;QAC/C,IAAI;KACL,CAAC,CAAC;IAEH,MAAM,SAAS,GAAe,EAAE,CAAC;IACjC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,SAAS,GAAa,EAAE,CAAC;IAE/B,KAAK,MAAM,IAAI,IAAI,GAAG,CAAC,UAAU,IAAI,EAAE,EAAE,CAAC;QACxC,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,OAAO,EAAE,KAAK,IAAI,EAAE,EAAE,CAAC;YAC1C,IAAI,CAAC,CAAC,IAAI;gBAAE,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QACrC,CAAC;QACD,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,iBAAiB,EAAE,eAAe,IAAI,EAAE,EAAE,CAAC;YAClE,MAAM,CAAC,GAAG,KAAK,CAAC,GAAG,EAAE,GAAG,CAAC;YACzB,IAAI,CAAC,CAAC,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;gBAAE,SAAS;YAChC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;YACZ,SAAS,CAAC,IAAI,CAAC;gBACb,GAAG,EAAE,CAAC;gBACN,KAAK,EAAE,KAAK,CAAC,GAAG,EAAE,KAAK;gBACvB,IAAI,EAAE,SAAS,CAAC,MAAM,GAAG,CAAC;aAC3B,CAAC,CAAC;YACH,IAAI,SAAS,CAAC,MAAM,IAAI,UAAU;gBAAE,MAAM;QAC5C,CAAC;IACH,CAAC;IAED,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,SAAS,EAAE,CAAC;AACtE,CAAC"}

package/dist/adapters/openai.d.ts

@@ -0,0 +1,3 @@
+import type { AdapterResult } from "../types.js";
+export declare function openaiSearch(query: string, maxResults: number): Promise<AdapterResult>;
+//# sourceMappingURL=openai.d.ts.map

package/dist/adapters/openai.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai.d.ts","sourceRoot":"","sources":["../../src/adapters/openai.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAY,MAAM,aAAa,CAAC;AAiB3D,wBAAsB,YAAY,CAChC,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,aAAa,CAAC,CAoDxB"}

package/dist/adapters/openai.js

@@ -0,0 +1,49 @@
+import { envKey } from "../lib/config.js";
+import { fetchJson, ToolFetchError } from "../lib/fetch.js";
+export async function openaiSearch(query, maxResults) {
+    const key = envKey("OPENAI_API_KEY");
+    if (!key) {
+        throw new ToolFetchError({
+            type: "missing_key",
+            engine: "openai",
+            env_var: "OPENAI_API_KEY",
+            message: "Set OPENAI_API_KEY to use the ChatGPT engine. Get a key at https://platform.openai.com.",
+        });
+    }
+    const body = JSON.stringify({
+        model: "gpt-4.1",
+        tools: [{ type: "web_search_preview" }],
+        input: query,
+    });
+    const res = await fetchJson("https://api.openai.com/v1/responses", {
+        method: "POST",
+        headers: {
+            authorization: `Bearer ${key}`,
+            "content-type": "application/json",
+        },
+        body,
+    });
+    const citations = [];
+    const seen = new Set();
+    const textParts = [];
+    for (const out of res.output ?? []) {
+        for (const c of out.content ?? []) {
+            if (c.type === "output_text" && c.text)
+                textParts.push(c.text);
+            for (const ann of c.annotations ?? []) {
+                if (ann.type !== "url_citation" || !ann.url || seen.has(ann.url))
+                    continue;
+                seen.add(ann.url);
+                citations.push({
+                    url: ann.url,
+                    title: ann.title,
+                    rank: citations.length + 1,
+                });
+                if (citations.length >= maxResults)
+                    break;
+            }
+        }
+    }
+    return { citations, raw_answer: textParts.join("\n") || undefined };
+}
+//# sourceMappingURL=openai.js.map

package/dist/adapters/openai.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai.js","sourceRoot":"","sources":["../../src/adapters/openai.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAkB5D,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,KAAa,EACb,UAAkB;IAElB,MAAM,GAAG,GAAG,MAAM,CAAC,gBAAgB,CAAC,CAAC;IACrC,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,MAAM,IAAI,cAAc,CAAC;YACvB,IAAI,EAAE,aAAa;YACnB,MAAM,EAAE,QAAQ;YAChB,OAAO,EAAE,gBAAgB;YACzB,OAAO,EACL,yFAAyF;SAC5F,CAAC,CAAC;IACL,CAAC;IAED,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC;QAC1B,KAAK,EAAE,SAAS;QAChB,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,oBAAoB,EAAE,CAAC;QACvC,KAAK,EAAE,KAAK;KACb,CAAC,CAAC;IAEH,MAAM,GAAG,GAAG,MAAM,SAAS,CACzB,qCAAqC,EACrC;QACE,MAAM,EAAE,MAAM;QACd,OAAO,EAAE;YACP,aAAa,EAAE,UAAU,GAAG,EAAE;YAC9B,cAAc,EAAE,kBAAkB;SACnC;QACD,IAAI;KACL,CACF,CAAC;IAEF,MAAM,SAAS,GAAe,EAAE,CAAC;IACjC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,SAAS,GAAa,EAAE,CAAC;IAE/B,KAAK,MAAM,GAAG,IAAI,GAAG,CAAC,MAAM,IAAI,EAAE,EAAE,CAAC;QACnC,KAAK,MAAM,CAAC,IAAI,GAAG,CAAC,OAAO,IAAI,EAAE,EAAE,CAAC;YAClC,IAAI,CAAC,CAAC,IAAI,KAAK,aAAa,IAAI,CAAC,CAAC,IAAI;gBAAE,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;YAC/D,KAAK,MAAM,GAAG,IAAI,CAAC,CAAC,WAAW,IAAI,EAAE,EAAE,CAAC;gBACtC,IAAI,GAAG,CAAC,IAAI,KAAK,cAAc,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC;oBAC9D,SAAS;gBACX,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;gBAClB,SAAS,CAAC,IAAI,CAAC;oBACb,GAAG,EAAE,GAAG,CAAC,GAAG;oBACZ,KAAK,EAAE,GAAG,CAAC,KAAK;oBAChB,IAAI,EAAE,SAAS,CAAC,MAAM,GAAG,CAAC;iBAC3B,CAAC,CAAC;gBACH,IAAI,SAAS,CAAC,MAAM,IAAI,UAAU;oBAAE,MAAM;YAC5C,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,SAAS,EAAE,CAAC;AACtE,CAAC"}

package/dist/adapters/perplexity.d.ts

@@ -0,0 +1,3 @@
+import type { AdapterResult } from "../types.js";
+export declare function perplexitySearch(query: string, maxResults: number): Promise<AdapterResult>;
+//# sourceMappingURL=perplexity.d.ts.map

package/dist/adapters/perplexity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"perplexity.d.ts","sourceRoot":"","sources":["../../src/adapters/perplexity.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAY,MAAM,aAAa,CAAC;AAU3D,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,aAAa,CAAC,CAwDxB"}

package/dist/adapters/perplexity.js

@@ -0,0 +1,55 @@
+import { envKey } from "../lib/config.js";
+import { fetchJson, ToolFetchError } from "../lib/fetch.js";
+export async function perplexitySearch(query, maxResults) {
+    const key = envKey("PERPLEXITY_API_KEY");
+    if (!key) {
+        throw new ToolFetchError({
+            type: "missing_key",
+            engine: "perplexity",
+            env_var: "PERPLEXITY_API_KEY",
+            message: "Set PERPLEXITY_API_KEY to use the Perplexity engine. Sign up at https://www.perplexity.ai/settings/api",
+        });
+    }
+    const body = JSON.stringify({
+        model: "sonar",
+        messages: [{ role: "user", content: query }],
+        return_citations: true,
+    });
+    const res = await fetchJson("https://api.perplexity.ai/chat/completions", {
+        method: "POST",
+        headers: {
+            authorization: `Bearer ${key}`,
+            "content-type": "application/json",
+        },
+        body,
+    });
+    const citations = [];
+    const seen = new Set();
+    if (res.search_results) {
+        for (const r of res.search_results) {
+            if (!r.url || seen.has(r.url))
+                continue;
+            seen.add(r.url);
+            citations.push({
+                url: r.url,
+                title: r.title,
+                rank: citations.length + 1,
+            });
+            if (citations.length >= maxResults)
+                break;
+        }
+    }
+    if (citations.length < maxResults && res.citations) {
+        for (const url of res.citations) {
+            if (!url || seen.has(url))
+                continue;
+            seen.add(url);
+            citations.push({ url, rank: citations.length + 1 });
+            if (citations.length >= maxResults)
+                break;
+        }
+    }
+    const raw_answer = res.choices?.[0]?.message?.content;
+    return { citations, raw_answer };
+}
+//# sourceMappingURL=perplexity.js.map

package/dist/adapters/perplexity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"perplexity.js","sourceRoot":"","sources":["../../src/adapters/perplexity.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAW5D,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,KAAa,EACb,UAAkB;IAElB,MAAM,GAAG,GAAG,MAAM,CAAC,oBAAoB,CAAC,CAAC;IACzC,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,MAAM,IAAI,cAAc,CAAC;YACvB,IAAI,EAAE,aAAa;YACnB,MAAM,EAAE,YAAY;YACpB,OAAO,EAAE,oBAAoB;YAC7B,OAAO,EACL,wGAAwG;SAC3G,CAAC,CAAC;IACL,CAAC;IAED,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC;QAC1B,KAAK,EAAE,OAAO;QACd,QAAQ,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;QAC5C,gBAAgB,EAAE,IAAI;KACvB,CAAC,CAAC;IAEH,MAAM,GAAG,GAAG,MAAM,SAAS,CACzB,4CAA4C,EAC5C;QACE,MAAM,EAAE,MAAM;QACd,OAAO,EAAE;YACP,aAAa,EAAE,UAAU,GAAG,EAAE;YAC9B,cAAc,EAAE,kBAAkB;SACnC;QACD,IAAI;KACL,CACF,CAAC;IAEF,MAAM,SAAS,GAAe,EAAE,CAAC;IACjC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAE/B,IAAI,GAAG,CAAC,cAAc,EAAE,CAAC;QACvB,KAAK,MAAM,CAAC,IAAI,GAAG,CAAC,cAAc,EAAE,CAAC;YACnC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC;gBAAE,SAAS;YACxC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;YAChB,SAAS,CAAC,IAAI,CAAC;gBACb,GAAG,EAAE,CAAC,CAAC,GAAG;gBACV,KAAK,EAAE,CAAC,CAAC,KAAK;gBACd,IAAI,EAAE,SAAS,CAAC,MAAM,GAAG,CAAC;aAC3B,CAAC,CAAC;YACH,IAAI,SAAS,CAAC,MAAM,IAAI,UAAU;gBAAE,MAAM;QAC5C,CAAC;IACH,CAAC;IACD,IAAI,SAAS,CAAC,MAAM,GAAG,UAAU,IAAI,GAAG,CAAC,SAAS,EAAE,CAAC;QACnD,KAAK,MAAM,GAAG,IAAI,GAAG,CAAC,SAAS,EAAE,CAAC;YAChC,IAAI,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;gBAAE,SAAS;YACpC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACd,SAAS,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,CAAC;YACpD,IAAI,SAAS,CAAC,MAAM,IAAI,UAAU;gBAAE,MAAM;QAC5C,CAAC;IACH,CAAC;IAED,MAAM,UAAU,GAAG,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC;IACtD,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,CAAC;AACnC,CAAC"}