@kak4343/scholar-mcp 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 scholar-mcp 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.ja.md

@@ -0,0 +1,162 @@
+# scholar-mcp (日本語)
+
+> **PubMed + arXiv + Semantic Scholar** を 1 つの MCP tool で横断検索する Claude Code / Claude Desktop 用サーバ。v0.2 で 2 段キャッシュと Notion 直投入を追加。
+
+日本人医師・研究者が Claude Code 上で文献調査を完結できるよう設計した OSS。日常診療で「あの論文どこだっけ」となったとき、Claude に話しかけるだけで 3 ソース横断検索が走り、結果をそのまま Notion Knowledge DB に積めるところまでが射程。
+
+## なぜ作ったか
+
+- 既存 MCP server は単一ソース (PubMed 単独 / arXiv 単独) で、横断検索する場合は tool を 3 回呼び分ける必要がある
+- 横断統合 + キャッシュ + Notion 連携まで揃った OSS が見当たらない
+- 医師 × Claude Code 開発者という二重ドメインからの差別化
+
+## インストール
+
+```bash
+npm install -g @kak4343/scholar-mcp
+```
+
+または `npx` で都度起動:
+
+```bash
+npx @kak4343/scholar-mcp
+```
+
+> **注意:** package は scope 付き (`@kak4343/`)。素の `scholar-mcp` 名は npm 上で別の OSS が既に取得済みのため、scope を必ず付ける。
+
+## Claude Desktop / Claude Code への設定
+
+```json
+{
+  "mcpServers": {
+    "scholar": {
+      "command": "npx",
+      "args": ["@kak4343/scholar-mcp"],
+      "env": {
+        "PUBMED_API_KEY": "任意、NCBI のレート上限を緩和",
+        "SEMANTIC_SCHOLAR_API_KEY": "任意、レート上限を緩和",
+        "NOTION_TOKEN": "任意、scholar_export_to_notion を使う場合のみ必須"
+      }
+    }
+  }
+}
+```
+
+## 提供する Tool
+
+### `scholar_search`
+
+```typescript
+{
+  query: string;                    // 例: "diabetic retinopathy SGLT2"
+  sources?: ("pubmed" | "arxiv" | "semantic_scholar")[];  // 既定: 3 つすべて
+  max_results?: number;             // 既定 10 (1 ソースあたり)、最大 50
+  date_from?: string;               // YYYY-MM-DD
+  date_to?: string;                 // YYYY-MM-DD
+}
+```
+
+戻り値は統一スキーマの JSON。各結果に source / title / authors / abstract / DOI / PMID / arXiv ID / published_date / venue / citation_count (Semantic Scholar のみ) / url が含まれる。あわせて `cache_hit` (boolean) と `cache_hit_rate` (0.0-1.0、プロセス起動以来の累計ヒット率) も返す。
+
+### `scholar_export_to_notion` (v0.2 で追加)
+
+検索結果を Notion DB にそのまま投入する。
+
+```typescript
+{
+  results: SearchResult[];           // scholar_search の戻り値
+  notion_database_id: string;        // UUID (ハイフンあり/なし両方可)
+  notion_token?: string;             // 環境変数より優先
+  include_japanese_summary?: boolean;  // 既定 false
+  dry_run?: boolean;                 // 既定 false。true で API を叩かず payload だけ返す
+}
+```
+
+投入される Notion page のプロパティ (DB 側に定義が必要):
+
+- `Title` (title) — タイトル
+- `Authors` (rich_text) — 著者リスト
+- `DOI` (url) — `https://doi.org/...` 形式に正規化
+- `Source` (select) — `pubmed` / `arxiv` / `semantic_scholar`
+- `Published` (date) — 出版日
+- `Venue` (rich_text) — Journal / conference
+- `Citation Count` (number) — Semantic Scholar の引用数
+- `Abstract` (rich_text、2000 文字でトリム、超過分は body block に書き出し)
+- `Japanese Summary` (rich_text、`include_japanese_summary: true` のときのみ)
+- `Status` (select) — 既定 `To Read`
+
+1 件失敗しても他は投入される (per-result エラーは戻り値の `pages[i].error` に格納)。
+
+## キャッシュ (v0.2 で追加)
+
+`scholar_search` は 2 段キャッシュを持つので、同じクエリを連続で叩いてもネットワークに行かない。
+
+- **Memory cache:** `lru-cache`、1000 entry、TTL 1 時間
+- **Disk cache:** SQLite (`better-sqlite3`)、`~/.scholar-mcp/cache/scholar_cache.db`、TTL 7 日
+- **Cache key:** `sha256(JSON.stringify({tool, query, sources, date_from, date_to, max_results}))`。query は小文字化、sources はソート済なので意味的に同じリクエストは同じキーに正規化される
+- **Promotion:** disk hit は自動で memory に昇格
+- **報告:** 毎回の応答に `cache_hit_rate` を含める
+
+ディスクキャッシュを丸ごと消す場合:
+
+```bash
+rm -rf ~/.scholar-mcp/cache/
+```
+
+## Notion トークンの読み込み順
+
+`scholar_export_to_notion` は以下の順で Notion integration token を解決する。
+
+1. tool 引数の `notion_token`
+2. 環境変数 `NOTION_TOKEN`
+3. `~/.scholar-mcp/config.json` の `{ "notion_token": "secret_..." }`
+
+Notion 側では integration を対象 DB に「接続」する必要がある (Notion DB のページ右上 ・・・ メニュー → Connections)。
+
+スキーマは作者個人の Knowledge DB (`data_source_id: 0a489d15-83e8-471d-ba1e-f04030473967`) と互換にしているので、同じ DB を `scholar-mcp` と既存 Python (例: 眼科週次レビューの `push_to_notion.py`) の両方から書き込める。
+
+## API キー
+
+- **PubMed (任意):** https://www.ncbi.nlm.nih.gov/account/ で無料発行、レート 3 req/s → 10 req/s
+- **Semantic Scholar (強く推奨):** https://www.semanticscholar.org/product/api で無料発行。キー無しだと全世界共有 rate pool で頻繁に HTTP 429 が出る。個人キーで専用 1 req/s が得られる。
+- **arXiv:** API キー不要
+- **Notion:** https://www.notion.so/profile/integrations で無料発行、`scholar_export_to_notion` を使う場合のみ必須
+
+## 開発
+
+```bash
+git clone https://github.com/kak4343/scholar-mcp
+cd scholar-mcp
+npm install
+npm run build
+npm start
+```
+
+簡易スモークテスト (cache hit/miss + Notion dry-run スキーマ確認):
+
+```bash
+node scripts/smoke_test.mjs
+```
+
+## ロードマップ
+
+- **v0.1** (internal): 3 ソース横断 `scholar_search`
+- **v0.2** (internal): 2 段キャッシュ + `scholar_export_to_notion`
+- **v0.3.0** (現行、npm 初公開): `@kak4343/` scope 化、USER_AGENT / clone URL 修正、README 整備
+- **v0.4:** dedup 精度向上 (preprint ↔ 出版済みの紐付け)、日本語要約プロンプトを臨床医 triage 用に調整
+- **v0.5:** `scholar_get_related` (Semantic Scholar の引用グラフ)
+- **v0.6:** open access 論文の全文取得
+
+## 法令・倫理上の注意
+
+- 取得対象は **公開済みのメタデータ + abstract のみ**。全文取得は v0.5 で open access のみ対応予定。
+- すべての結果に出典 URL を含むので、引用時はそちらを参照のこと。
+- **患者情報・症例情報は絶対にクエリに入れないこと。** 作者個人のプロジェクト規約 (患者情報をクラウドに送らない) と整合し、同じ規約を利用者にもお願いしている。
+
+## ライセンス
+
+MIT
+
+## 作者
+
+Claude Code を日常的に診療補助に使っている眼科医。Issue / PR 歓迎。

package/README.md

@@ -0,0 +1,156 @@
+# scholar-mcp
+
+> Unified MCP server for **PubMed + arXiv + Semantic Scholar** scholarly search, with two-tier caching and one-call Notion export.
+
+Search three major scholarly databases from a single MCP tool call, returning unified results (title, authors, abstract, DOI, publication date, citation count, venue, URL). Push any result set straight into a Notion database with a second call.
+
+## Why?
+
+Existing MCP servers cover a single source (PubMed-only, arXiv-only). For clinicians and researchers doing cross-disciplinary literature reviews, calling three separate tools is friction. `scholar-mcp` is one tool, three sources, unified schema, with caching that makes follow-up queries instant.
+
+## Install
+
+```bash
+npm install -g @kak4343/scholar-mcp
+```
+
+Or run via `npx` without install:
+
+```bash
+npx @kak4343/scholar-mcp
+```
+
+> **Note:** the package is scoped (`@kak4343/`) because the unscoped name `scholar-mcp` is already taken on npm by an unrelated package. If you see the wrong tool, double-check the scope.
+
+## Configure in Claude Desktop / Claude Code
+
+```json
+{
+  "mcpServers": {
+    "scholar": {
+      "command": "npx",
+      "args": ["@kak4343/scholar-mcp"],
+      "env": {
+        "PUBMED_API_KEY": "optional, raises NCBI rate limit",
+        "SEMANTIC_SCHOLAR_API_KEY": "optional, raises rate limit",
+        "NOTION_TOKEN": "optional, required only for scholar_export_to_notion"
+      }
+    }
+  }
+}
+```
+
+## Tools
+
+### `scholar_search`
+
+```typescript
+{
+  query: string;                    // e.g. "diabetic retinopathy SGLT2"
+  sources?: ("pubmed" | "arxiv" | "semantic_scholar")[];  // default: all
+  max_results?: number;             // default 10 per source, max 50
+  date_from?: string;               // YYYY-MM-DD
+  date_to?: string;                 // YYYY-MM-DD
+}
+```
+
+Returns a unified JSON object with `results` array containing each paper's source, title, authors, abstract, DOI/PMID/arXiv ID, publication date, venue, citation count (Semantic Scholar only), and URL. Also returns `cache_hit` (boolean) and `cache_hit_rate` (0.0-1.0).
+
+### `scholar_export_to_notion` (v0.2)
+
+Push a result set into a Notion database in one call.
+
+```typescript
+{
+  results: SearchResult[];           // output of scholar_search
+  notion_database_id: string;        // UUID, with or without dashes
+  notion_token?: string;             // overrides NOTION_TOKEN env
+  include_japanese_summary?: boolean;  // default false
+  dry_run?: boolean;                 // default false, build payload only
+}
+```
+
+Each Notion page is created with these properties (the database must define them):
+
+- `Title` (title)
+- `Authors` (rich_text)
+- `DOI` (url, normalised to `https://doi.org/...`)
+- `Source` (select: `pubmed` / `arxiv` / `semantic_scholar`)
+- `Published` (date)
+- `Venue` (rich_text)
+- `Citation Count` (number)
+- `Abstract` (rich_text, truncated at 2000 chars; the full abstract is also written as body blocks)
+- `Japanese Summary` (rich_text, only when `include_japanese_summary: true` and the field exists)
+- `Status` (select: defaults to `To Read`)
+
+Errors are captured per result so a single bad row never aborts the batch.
+
+## Caching (v0.2)
+
+`scholar_search` is backed by a two-tier cache so repeated queries are free.
+
+- **Memory:** `lru-cache`, 1000 entries, 1-hour TTL
+- **Disk:** SQLite (`better-sqlite3`) at `~/.scholar-mcp/cache/scholar_cache.db`, 7-day TTL
+- **Key:** `sha256(JSON.stringify({tool, query, sources, date_from, date_to, max_results}))` — query is lower-cased and sources are sorted, so semantically identical requests share a cache entry
+- **Promotion:** disk hits are promoted back into memory automatically
+- **Reporting:** every response includes `cache_hit_rate` (lifetime hit rate of the running process)
+
+To wipe the on-disk cache: `rm -rf ~/.scholar-mcp/cache/`.
+
+## Notion configuration
+
+`scholar_export_to_notion` looks up the Notion integration token in this order:
+
+1. `notion_token` argument to the tool call
+2. `NOTION_TOKEN` environment variable
+3. `~/.scholar-mcp/config.json` — `{ "notion_token": "secret_..." }`
+
+Your Notion integration must be added to the target database (the integration's "Connections" must include that page). The schema above is intentionally compatible with the maintainer's personal Knowledge database (`data_source_id: 0a489d15-83e8-471d-ba1e-f04030473967`), so the same Notion DB can be populated by either `scholar-mcp` or by Python pipelines built around it.
+
+## API keys
+
+- **PubMed** (optional): free at https://www.ncbi.nlm.nih.gov/account/ — raises rate limit from 3 req/s to 10 req/s
+- **Semantic Scholar** (**strongly recommended**): free at https://www.semanticscholar.org/product/api — without a key, requests share a global rate pool that is frequently saturated (HTTP 429). A personal key gives you a dedicated 1 req/s.
+- **arXiv**: no API key needed
+- **Notion**: free integration token at https://www.notion.so/profile/integrations — required only for `scholar_export_to_notion`
+
+Set them via the environment variables `PUBMED_API_KEY`, `SEMANTIC_SCHOLAR_API_KEY`, and `NOTION_TOKEN`.
+
+## Development
+
+```bash
+git clone https://github.com/kak4343/scholar-mcp
+cd scholar-mcp
+npm install
+npm run build
+npm start
+```
+
+Quick smoke test (cache hit/miss + Notion dry-run schema):
+
+```bash
+node scripts/smoke_test.mjs
+```
+
+## Roadmap
+
+- **v0.1** (internal): `scholar_search` unified across 3 sources
+- **v0.2** (internal): two-tier cache (LRU memory + SQLite disk), `scholar_export_to_notion`
+- **v0.3.0** (current, first public npm release): `@kak4343/` scope rename, USER_AGENT/clone-URL fixes, README polish
+- **v0.4**: dedup precision (preprint ↔ published linking), Japanese summary prompt tuning for clinical triage
+- **v0.5**: `scholar_get_related` tool (Semantic Scholar citation graph)
+- **v0.6**: full-text retrieval for open-access papers
+
+## Legal / ethical notes
+
+- Only publicly indexed paper metadata and abstracts are retrieved (full text is open-access only and reserved for v0.5).
+- Cite the original source in any downstream use; every result includes a canonical URL.
+- Do not paste patient-identifying information into queries — the maintainer's project policy forbids sending such data to any cloud service, and the same applies here.
+
+## License
+
+MIT
+
+## Author
+
+Built by a physician using Claude Code for daily literature review. Issues and PRs welcome.

package/dist/cache/disk_cache.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Persistent SQLite-backed cache for scholar_search results.
+ *
+ * Default location: ~/.scholar-mcp/cache/scholar_cache.db
+ * Default TTL: 7 days
+ *
+ * Schema:
+ *   key      TEXT PRIMARY KEY  -- sha256 of the canonical request
+ *   value    TEXT NOT NULL     -- JSON-serialised payload
+ *   created  INTEGER NOT NULL  -- epoch ms of insertion
+ *   expires  INTEGER NOT NULL  -- epoch ms after which the row is stale
+ */
+export declare class DiskCache<T extends object = object> {
+    private db;
+    private ttlMs;
+    constructor(dbPath?: string, ttlMs?: number);
+    private init;
+    get(key: string): T | undefined;
+    set(key: string, value: T): void;
+    has(key: string): boolean;
+    delete(key: string): void;
+    /** Remove all expired rows. Call periodically to keep the DB small. */
+    prune(): number;
+    clear(): void;
+    get size(): number;
+    close(): void;
+}

package/dist/cache/disk_cache.js

@@ -0,0 +1,82 @@
+import Database from "better-sqlite3";
+import { mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+/**
+ * Persistent SQLite-backed cache for scholar_search results.
+ *
+ * Default location: ~/.scholar-mcp/cache/scholar_cache.db
+ * Default TTL: 7 days
+ *
+ * Schema:
+ *   key      TEXT PRIMARY KEY  -- sha256 of the canonical request
+ *   value    TEXT NOT NULL     -- JSON-serialised payload
+ *   created  INTEGER NOT NULL  -- epoch ms of insertion
+ *   expires  INTEGER NOT NULL  -- epoch ms after which the row is stale
+ */
+export class DiskCache {
+    db;
+    ttlMs;
+    constructor(dbPath, ttlMs = 7 * 24 * 60 * 60 * 1000) {
+        const resolved = dbPath ?? join(homedir(), ".scholar-mcp", "cache", "scholar_cache.db");
+        mkdirSync(dirname(resolved), { recursive: true });
+        this.db = new Database(resolved);
+        this.ttlMs = ttlMs;
+        this.init();
+    }
+    init() {
+        this.db.pragma("journal_mode = WAL");
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS cache (
+        key TEXT PRIMARY KEY,
+        value TEXT NOT NULL,
+        created INTEGER NOT NULL,
+        expires INTEGER NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS idx_cache_expires ON cache(expires);
+    `);
+    }
+    get(key) {
+        const row = this.db
+            .prepare("SELECT value FROM cache WHERE key = ? AND expires > ?")
+            .get(key, Date.now());
+        if (!row)
+            return undefined;
+        try {
+            return JSON.parse(row.value);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    set(key, value) {
+        const now = Date.now();
+        this.db
+            .prepare("INSERT OR REPLACE INTO cache (key, value, created, expires) VALUES (?, ?, ?, ?)")
+            .run(key, JSON.stringify(value), now, now + this.ttlMs);
+    }
+    has(key) {
+        return this.get(key) !== undefined;
+    }
+    delete(key) {
+        this.db.prepare("DELETE FROM cache WHERE key = ?").run(key);
+    }
+    /** Remove all expired rows. Call periodically to keep the DB small. */
+    prune() {
+        const result = this.db.prepare("DELETE FROM cache WHERE expires <= ?").run(Date.now());
+        return Number(result.changes);
+    }
+    clear() {
+        this.db.exec("DELETE FROM cache");
+    }
+    get size() {
+        const row = this.db
+            .prepare("SELECT COUNT(*) AS c FROM cache WHERE expires > ?")
+            .get(Date.now());
+        return row?.c ?? 0;
+    }
+    close() {
+        this.db.close();
+    }
+}
+//# sourceMappingURL=disk_cache.js.map

package/dist/cache/disk_cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"disk_cache.js","sourceRoot":"","sources":["../../src/cache/disk_cache.ts"],"names":[],"mappings":"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"}

package/dist/cache/index.d.ts

@@ -0,0 +1,47 @@
+import type { Source } from "../types.js";
+import { MemoryCache } from "./memory_cache.js";
+import { DiskCache } from "./disk_cache.js";
+export { MemoryCache } from "./memory_cache.js";
+export { DiskCache } from "./disk_cache.js";
+/**
+ * Canonical key inputs. `sources` is sorted before hashing so that
+ * ["arxiv", "pubmed"] and ["pubmed", "arxiv"] map to the same cache entry.
+ */
+export interface CacheKeyInput {
+    tool: string;
+    query: string;
+    sources: Source[];
+    date_from?: string;
+    date_to?: string;
+    max_results?: number;
+}
+export declare function buildCacheKey(input: CacheKeyInput): string;
+/**
+ * Two-tier cache helper: memory first, then disk. On a disk hit the
+ * value is promoted back into memory so subsequent lookups are fast.
+ *
+ * Stats lets the caller report a cache_hit_rate metric.
+ */
+export declare class SearchCache<T extends object = object> {
+    readonly memory: MemoryCache<T>;
+    readonly disk: DiskCache<T>;
+    private hits;
+    private misses;
+    constructor(opts?: {
+        memoryMaxEntries?: number;
+        memoryTtlMs?: number;
+        diskPath?: string;
+        diskTtlMs?: number;
+    });
+    get(key: string): T | undefined;
+    set(key: string, value: T): void;
+    /** Hit rate over the lifetime of this cache instance. */
+    hitRate(): number;
+    stats(): {
+        hits: number;
+        misses: number;
+        rate: number;
+    };
+    resetStats(): void;
+    close(): void;
+}

package/dist/cache/index.js

@@ -0,0 +1,67 @@
+import { createHash } from "node:crypto";
+import { MemoryCache } from "./memory_cache.js";
+import { DiskCache } from "./disk_cache.js";
+export { MemoryCache } from "./memory_cache.js";
+export { DiskCache } from "./disk_cache.js";
+export function buildCacheKey(input) {
+    const canonical = {
+        tool: input.tool,
+        query: input.query.trim().toLowerCase(),
+        sources: [...input.sources].sort(),
+        date_from: input.date_from ?? null,
+        date_to: input.date_to ?? null,
+        max_results: input.max_results ?? null,
+    };
+    return createHash("sha256").update(JSON.stringify(canonical)).digest("hex");
+}
+/**
+ * Two-tier cache helper: memory first, then disk. On a disk hit the
+ * value is promoted back into memory so subsequent lookups are fast.
+ *
+ * Stats lets the caller report a cache_hit_rate metric.
+ */
+export class SearchCache {
+    memory;
+    disk;
+    hits = 0;
+    misses = 0;
+    constructor(opts = {}) {
+        this.memory = new MemoryCache(opts.memoryMaxEntries, opts.memoryTtlMs);
+        this.disk = new DiskCache(opts.diskPath, opts.diskTtlMs);
+    }
+    get(key) {
+        const m = this.memory.get(key);
+        if (m !== undefined) {
+            this.hits++;
+            return m;
+        }
+        const d = this.disk.get(key);
+        if (d !== undefined) {
+            this.memory.set(key, d);
+            this.hits++;
+            return d;
+        }
+        this.misses++;
+        return undefined;
+    }
+    set(key, value) {
+        this.memory.set(key, value);
+        this.disk.set(key, value);
+    }
+    /** Hit rate over the lifetime of this cache instance. */
+    hitRate() {
+        const total = this.hits + this.misses;
+        return total === 0 ? 0 : this.hits / total;
+    }
+    stats() {
+        return { hits: this.hits, misses: this.misses, rate: this.hitRate() };
+    }
+    resetStats() {
+        this.hits = 0;
+        this.misses = 0;
+    }
+    close() {
+        this.disk.close();
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/cache/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cache/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAe5C,MAAM,UAAU,aAAa,CAAC,KAAoB;IAChD,MAAM,SAAS,GAAG;QAChB,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE;QACvC,OAAO,EAAE,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE;QAClC,SAAS,EAAE,KAAK,CAAC,SAAS,IAAI,IAAI;QAClC,OAAO,EAAE,KAAK,CAAC,OAAO,IAAI,IAAI;QAC9B,WAAW,EAAE,KAAK,CAAC,WAAW,IAAI,IAAI;KACvC,CAAC;IACF,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED;;;;;GAKG;AACH,MAAM,OAAO,WAAW;IACb,MAAM,CAAiB;IACvB,IAAI,CAAe;IACpB,IAAI,GAAG,CAAC,CAAC;IACT,MAAM,GAAG,CAAC,CAAC;IAEnB,YAAY,OAKR,EAAE;QACJ,IAAI,CAAC,MAAM,GAAG,IAAI,WAAW,CAAI,IAAI,CAAC,gBAAgB,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;QAC1E,IAAI,CAAC,IAAI,GAAG,IAAI,SAAS,CAAI,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;IAC9D,CAAC;IAED,GAAG,CAAC,GAAW;QACb,MAAM,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC/B,IAAI,CAAC,KAAK,SAAS,EAAE,CAAC;YACpB,IAAI,CAAC,IAAI,EAAE,CAAC;YACZ,OAAO,CAAC,CAAC;QACX,CAAC;QACD,MAAM,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC7B,IAAI,CAAC,KAAK,SAAS,EAAE,CAAC;YACpB,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;YACxB,IAAI,CAAC,IAAI,EAAE,CAAC;YACZ,OAAO,CAAC,CAAC;QACX,CAAC;QACD,IAAI,CAAC,MAAM,EAAE,CAAC;QACd,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,GAAG,CAAC,GAAW,EAAE,KAAQ;QACvB,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAC5B,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAC5B,CAAC;IAED,yDAAyD;IACzD,OAAO;QACL,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC;QACtC,OAAO,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC;IAC7C,CAAC;IAED,KAAK;QACH,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,OAAO,EAAE,EAAE,CAAC;IACxE,CAAC;IAED,UAAU;QACR,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC;QACd,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC;IAClB,CAAC;IAED,KAAK;QACH,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;IACpB,CAAC;CACF"}

package/dist/cache/memory_cache.d.ts

@@ -0,0 +1,17 @@
+/**
+ * In-process LRU cache for scholar_search results.
+ *
+ * - Capacity: 1000 entries
+ * - TTL: 1 hour
+ * - Stores arbitrary JSON-serialisable values keyed by sha256 hash
+ */
+export declare class MemoryCache<T extends object = object> {
+    private cache;
+    constructor(maxEntries?: number, ttlMs?: number);
+    get(key: string): T | undefined;
+    set(key: string, value: T): void;
+    has(key: string): boolean;
+    delete(key: string): boolean;
+    clear(): void;
+    get size(): number;
+}

package/dist/cache/memory_cache.js

@@ -0,0 +1,36 @@
+import { LRUCache } from "lru-cache";
+/**
+ * In-process LRU cache for scholar_search results.
+ *
+ * - Capacity: 1000 entries
+ * - TTL: 1 hour
+ * - Stores arbitrary JSON-serialisable values keyed by sha256 hash
+ */
+export class MemoryCache {
+    cache;
+    constructor(maxEntries = 1000, ttlMs = 60 * 60 * 1000) {
+        this.cache = new LRUCache({
+            max: maxEntries,
+            ttl: ttlMs,
+        });
+    }
+    get(key) {
+        return this.cache.get(key);
+    }
+    set(key, value) {
+        this.cache.set(key, value);
+    }
+    has(key) {
+        return this.cache.has(key);
+    }
+    delete(key) {
+        return this.cache.delete(key);
+    }
+    clear() {
+        this.cache.clear();
+    }
+    get size() {
+        return this.cache.size;
+    }
+}
+//# sourceMappingURL=memory_cache.js.map

package/dist/cache/memory_cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory_cache.js","sourceRoot":"","sources":["../../src/cache/memory_cache.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAErC;;;;;;GAMG;AACH,MAAM,OAAO,WAAW;IACd,KAAK,CAAsB;IAEnC,YAAY,UAAU,GAAG,IAAI,EAAE,KAAK,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI;QACnD,IAAI,CAAC,KAAK,GAAG,IAAI,QAAQ,CAAY;YACnC,GAAG,EAAE,UAAU;YACf,GAAG,EAAE,KAAK;SACX,CAAC,CAAC;IACL,CAAC;IAED,GAAG,CAAC,GAAW;QACb,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC7B,CAAC;IAED,GAAG,CAAC,GAAW,EAAE,KAAQ;QACvB,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAC7B,CAAC;IAED,GAAG,CAAC,GAAW;QACb,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC7B,CAAC;IAED,MAAM,CAAC,GAAW;QAChB,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAChC,CAAC;IAED,KAAK;QACH,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;IAED,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;IACzB,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};