@kak4343/scholar-mcp 0.3.0

package/src/index.ts

@@ -0,0 +1,212 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { PubMedSearcher } from "./sources/pubmed.js";
+import { ArxivSearcher } from "./sources/arxiv.js";
+import { SemanticScholarSearcher } from "./sources/semantic_scholar.js";
+import { SearchCache, buildCacheKey } from "./cache/index.js";
+import { exportResultsToNotion } from "./notion/push.js";
+import type { Source, SearchParams, SearchResult } from "./types.js";
+
+const PUBMED_API_KEY = process.env.PUBMED_API_KEY;
+const SEMANTIC_SCHOLAR_API_KEY = process.env.SEMANTIC_SCHOLAR_API_KEY;
+
+const pubmed = new PubMedSearcher(PUBMED_API_KEY);
+const arxiv = new ArxivSearcher();
+const semantic = new SemanticScholarSearcher(SEMANTIC_SCHOLAR_API_KEY);
+
+interface CachedPayload {
+  query: string;
+  sources_queried: Source[];
+  total_results: number;
+  results: SearchResult[];
+}
+
+const searchCache = new SearchCache<CachedPayload>();
+
+const server = new Server(
+  { name: "scholar-mcp", version: "0.2.0" },
+  { capabilities: { tools: {} } }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [
+    {
+      name: "scholar_search",
+      description:
+        "Search PubMed, arXiv, and Semantic Scholar for scholarly papers. Returns title, authors, abstract, DOI, publication date, and venue. Supports date filtering and per-source filtering. Results are cached in memory (1h TTL) and on disk (7 days, ~/.scholar-mcp/cache/) keyed by sha256 of the request.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          query: {
+            type: "string",
+            description: "Search query (English recommended for accuracy)",
+          },
+          sources: {
+            type: "array",
+            items: { type: "string", enum: ["pubmed", "arxiv", "semantic_scholar"] },
+            description: "Sources to search (default: all three)",
+          },
+          max_results: {
+            type: "number",
+            description: "Maximum results per source (default 10, max 50)",
+          },
+          date_from: { type: "string", description: "Filter by publication date (YYYY-MM-DD)" },
+          date_to: { type: "string", description: "Filter by publication date (YYYY-MM-DD)" },
+        },
+        required: ["query"],
+      },
+    },
+    {
+      name: "scholar_export_to_notion",
+      description:
+        "Push scholar_search results into a Notion database. Compatible with the user's Knowledge DB schema: Title (title), Authors (rich_text), DOI (url), Source (select), Published (date), Venue (rich_text), Citation Count (number), Abstract (rich_text), Japanese Summary (rich_text, optional), Status (select). Reads NOTION_TOKEN from env or ~/.scholar-mcp/config.json. Set dry_run=true to build the page payloads without calling the Notion API.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          results: {
+            type: "array",
+            description: "SearchResult[] from scholar_search",
+            items: { type: "object" },
+          },
+          notion_database_id: {
+            type: "string",
+            description: "Target Notion database id (UUID, with or without dashes)",
+          },
+          notion_token: {
+            type: "string",
+            description: "Optional Notion integration token (else NOTION_TOKEN env / ~/.scholar-mcp/config.json)",
+          },
+          include_japanese_summary: {
+            type: "boolean",
+            description: "Include japanese_summary field if present on the results (default false)",
+          },
+          dry_run: {
+            type: "boolean",
+            description: "If true, return the page payloads without calling Notion (default false)",
+          },
+        },
+        required: ["results", "notion_database_id"],
+      },
+    },
+  ],
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  if (request.params.name === "scholar_search") {
+    return handleSearch(request.params.arguments as unknown as SearchParams);
+  }
+  if (request.params.name === "scholar_export_to_notion") {
+    return handleExportToNotion(request.params.arguments as unknown as {
+      results: SearchResult[];
+      notion_database_id: string;
+      notion_token?: string;
+      include_japanese_summary?: boolean;
+      dry_run?: boolean;
+    });
+  }
+  throw new Error(`Unknown tool: ${request.params.name}`);
+});
+
+async function handleSearch(args: SearchParams) {
+  const sources: Source[] = (args.sources ?? ["pubmed", "arxiv", "semantic_scholar"]) as Source[];
+  const max_results = Math.min(args.max_results ?? 10, 50);
+  const params: SearchParams = {
+    query: args.query,
+    max_results,
+    date_from: args.date_from,
+    date_to: args.date_to,
+  };
+
+  const cacheKey = buildCacheKey({
+    tool: "scholar_search",
+    query: args.query,
+    sources,
+    date_from: args.date_from,
+    date_to: args.date_to,
+    max_results,
+  });
+
+  const cached = searchCache.get(cacheKey);
+  if (cached) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(
+            { ...cached, cache_hit: true, cache_hit_rate: searchCache.hitRate() },
+            null,
+            2,
+          ),
+        },
+      ],
+    };
+  }
+
+  const searchers: Record<Source, () => Promise<SearchResult[]>> = {
+    pubmed: () => pubmed.search(params),
+    arxiv: () => arxiv.search(params),
+    semantic_scholar: () => semantic.search(params),
+  };
+
+  const promises = sources.map(async (s) => {
+    try {
+      return await searchers[s]();
+    } catch (e) {
+      console.error(`[scholar_search] ${s} failed:`, (e as Error).message);
+      return [];
+    }
+  });
+  const resultsArrays = await Promise.all(promises);
+  const allResults = resultsArrays.flat();
+
+  const payload: CachedPayload = {
+    query: args.query,
+    sources_queried: sources,
+    total_results: allResults.length,
+    results: allResults,
+  };
+  searchCache.set(cacheKey, payload);
+
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(
+          { ...payload, cache_hit: false, cache_hit_rate: searchCache.hitRate() },
+          null,
+          2,
+        ),
+      },
+    ],
+  };
+}
+
+async function handleExportToNotion(args: {
+  results: SearchResult[];
+  notion_database_id: string;
+  notion_token?: string;
+  include_japanese_summary?: boolean;
+  dry_run?: boolean;
+}) {
+  const out = await exportResultsToNotion({
+    results: args.results,
+    notion_database_id: args.notion_database_id,
+    notion_token: args.notion_token,
+    include_japanese_summary: args.include_japanese_summary,
+    dry_run: args.dry_run,
+  });
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(out, null, 2),
+      },
+    ],
+  };
+}
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error("[scholar-mcp] v0.2 running on stdio");

package/src/notion/push.ts

@@ -0,0 +1,237 @@
+import { Client } from "@notionhq/client";
+import { readFileSync, existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { SearchResult } from "../types.js";
+
+/**
+ * Notion page schema used by scholar_export_to_notion.
+ *
+ * Compatible with the user's existing Knowledge DB (data_source_id
+ * 0a489d15-83e8-471d-ba1e-f04030473967) and the eye-ophthalmology weekly
+ * review push_to_notion.py helper.
+ *
+ * Properties (must be defined on the target database):
+ *   Title           - title
+ *   Authors         - rich_text
+ *   DOI             - url
+ *   Source          - select (pubmed / arxiv / semantic_scholar)
+ *   Published       - date
+ *   Venue           - rich_text
+ *   Citation Count  - number
+ *   Abstract        - rich_text  (truncated to 2000 chars, full text in body)
+ *   Japanese Summary - rich_text (only when include_japanese_summary)
+ *   Status          - select ("To Read")
+ */
+
+const ABSTRACT_PROPERTY_LIMIT = 2000; // Notion rich_text per-property hard limit
+const BLOCK_TEXT_LIMIT = 2000; // Notion paragraph block hard limit
+
+export interface ExportInput {
+  results: SearchResult[];
+  notion_database_id: string;
+  notion_token?: string;
+  include_japanese_summary?: boolean;
+  dry_run?: boolean;
+}
+
+export interface ExportedPage {
+  result_index: number;
+  title: string;
+  page_id?: string;
+  page_url?: string;
+  status: "created" | "dry_run" | "error";
+  error?: string;
+  /** Page properties payload that was (or would be) sent to Notion. */
+  properties: Record<string, unknown>;
+  /** Children blocks that were (or would be) appended. */
+  children: Array<Record<string, unknown>>;
+}
+
+export interface ExportOutput {
+  database_id: string;
+  total: number;
+  created: number;
+  errors: number;
+  dry_run: boolean;
+  pages: ExportedPage[];
+}
+
+/**
+ * Resolve a Notion token from (in order): explicit arg, NOTION_TOKEN env,
+ * ~/.scholar-mcp/config.json `{ "notion_token": "..." }`. Returns undefined
+ * if nothing matched — callers in dry-run mode can ignore that, but real
+ * exports must fail.
+ */
+export function resolveNotionToken(explicit?: string): string | undefined {
+  if (explicit && explicit.trim()) return explicit.trim();
+  if (process.env.NOTION_TOKEN && process.env.NOTION_TOKEN.trim()) {
+    return process.env.NOTION_TOKEN.trim();
+  }
+  const configPath = join(homedir(), ".scholar-mcp", "config.json");
+  if (existsSync(configPath)) {
+    try {
+      const cfg = JSON.parse(readFileSync(configPath, "utf8")) as { notion_token?: string };
+      if (cfg.notion_token && cfg.notion_token.trim()) return cfg.notion_token.trim();
+    } catch {
+      // ignore malformed config; treat as missing
+    }
+  }
+  return undefined;
+}
+
+function richText(content: string): Array<{ type: "text"; text: { content: string } }> {
+  if (!content) return [];
+  return [{ type: "text", text: { content: content.slice(0, ABSTRACT_PROPERTY_LIMIT) } }];
+}
+
+function chunkParagraphBlocks(content: string): Array<Record<string, unknown>> {
+  if (!content) return [];
+  const blocks: Array<Record<string, unknown>> = [];
+  for (let i = 0; i < content.length; i += BLOCK_TEXT_LIMIT) {
+    const chunk = content.slice(i, i + BLOCK_TEXT_LIMIT);
+    blocks.push({
+      object: "block",
+      type: "paragraph",
+      paragraph: {
+        rich_text: [{ type: "text", text: { content: chunk } }],
+      },
+    });
+  }
+  return blocks;
+}
+
+function buildPagePayload(
+  r: SearchResult,
+  databaseId: string,
+  includeJapaneseSummary: boolean,
+): { properties: Record<string, unknown>; children: Array<Record<string, unknown>> } {
+  const properties: Record<string, unknown> = {
+    Title: { title: richText(r.title || "(untitled)") },
+    Authors: { rich_text: richText(r.authors.join(", ")) },
+    Source: { select: { name: r.source } },
+    Status: { select: { name: "To Read" } },
+  };
+
+  if (r.doi) {
+    properties.DOI = { url: r.doi.startsWith("http") ? r.doi : `https://doi.org/${r.doi}` };
+  }
+  if (r.published_date) {
+    properties.Published = { date: { start: r.published_date } };
+  }
+  if (r.venue) {
+    properties.Venue = { rich_text: richText(r.venue) };
+  }
+  if (typeof r.citation_count === "number") {
+    properties["Citation Count"] = { number: r.citation_count };
+  }
+  if (r.abstract) {
+    properties.Abstract = { rich_text: richText(r.abstract) };
+  }
+  if (includeJapaneseSummary && (r as SearchResult & { japanese_summary?: string }).japanese_summary) {
+    properties["Japanese Summary"] = {
+      rich_text: richText((r as SearchResult & { japanese_summary?: string }).japanese_summary!),
+    };
+  }
+
+  // Mirror the abstract (and full japanese summary) as body blocks so the
+  // 2000-char cap on rich_text properties never truncates the source text.
+  const children: Array<Record<string, unknown>> = [];
+  if (r.abstract && r.abstract.length > ABSTRACT_PROPERTY_LIMIT) {
+    children.push(...chunkParagraphBlocks(r.abstract));
+  }
+
+  // (databaseId is consumed by the caller, not here)
+  void databaseId;
+  return { properties, children };
+}
+
+/**
+ * Push search results to a Notion database.
+ *
+ * Strategy: build per-result page payloads, then either return them
+ * unchanged (dry-run) or POST each one to Notion sequentially. Errors are
+ * captured per result so a single bad row does not abort the batch.
+ */
+export async function exportResultsToNotion(input: ExportInput): Promise<ExportOutput> {
+  const dryRun = input.dry_run ?? false;
+  const includeJp = input.include_japanese_summary ?? false;
+  const databaseId = input.notion_database_id;
+
+  if (!databaseId || !databaseId.trim()) {
+    throw new Error("notion_database_id is required");
+  }
+
+  let client: Client | undefined;
+  if (!dryRun) {
+    const token = resolveNotionToken(input.notion_token);
+    if (!token) {
+      throw new Error(
+        "Notion token not found. Set NOTION_TOKEN env or ~/.scholar-mcp/config.json {\"notion_token\": \"...\"}"
+      );
+    }
+    client = new Client({ auth: token });
+  }
+
+  const pages: ExportedPage[] = [];
+  let created = 0;
+  let errors = 0;
+
+  for (let i = 0; i < input.results.length; i++) {
+    const r = input.results[i];
+    const { properties, children } = buildPagePayload(r, databaseId, includeJp);
+
+    if (dryRun || !client) {
+      pages.push({
+        result_index: i,
+        title: r.title,
+        status: "dry_run",
+        properties,
+        children,
+      });
+      continue;
+    }
+
+    try {
+      const resp = await client.pages.create({
+        parent: { database_id: databaseId },
+        // The Notion SDK's property typings are tighter than our generic
+        // record; the runtime accepts our payload but the type checker
+        // wants the concrete union, so cast at the boundary.
+        properties: properties as Parameters<Client["pages"]["create"]>[0]["properties"],
+        children: children as Parameters<Client["pages"]["create"]>[0]["children"],
+      });
+      const pageRes = resp as { id?: string; url?: string };
+      pages.push({
+        result_index: i,
+        title: r.title,
+        page_id: pageRes.id,
+        page_url: pageRes.url,
+        status: "created",
+        properties,
+        children,
+      });
+      created++;
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e);
+      pages.push({
+        result_index: i,
+        title: r.title,
+        status: "error",
+        error: msg,
+        properties,
+        children,
+      });
+      errors++;
+    }
+  }
+
+  return {
+    database_id: databaseId,
+    total: input.results.length,
+    created,
+    errors,
+    dry_run: dryRun,
+    pages,
+  };
+}

package/src/sources/arxiv.ts

@@ -0,0 +1,61 @@
+import { XMLParser } from "fast-xml-parser";
+import type { SearchParams, SearchResult, SourceSearcher } from "../types.js";
+
+const BASE_URL = "https://export.arxiv.org/api/query";
+const USER_AGENT = "scholar-mcp/0.2.1 (https://github.com/kak4343/scholar-mcp)";
+
+export class ArxivSearcher implements SourceSearcher {
+  async search(params: SearchParams): Promise<SearchResult[]> {
+    const url = new URL(BASE_URL);
+    url.searchParams.set("search_query", `all:${params.query}`);
+    url.searchParams.set("max_results", String(params.max_results ?? 10));
+    url.searchParams.set("sortBy", "submittedDate");
+    url.searchParams.set("sortOrder", "descending");
+
+    const r = await fetch(url, { headers: { "User-Agent": USER_AGENT } });
+    if (!r.ok) throw new Error(`arXiv search failed: ${r.status}`);
+    const xml = await r.text();
+
+    const parser = new XMLParser({ ignoreAttributes: false, attributeNamePrefix: "@_" });
+    const parsed = parser.parse(xml);
+    const entries = parsed.feed?.entry;
+    if (!entries) return [];
+    const entryArray = Array.isArray(entries) ? entries : [entries];
+
+    return entryArray.map((e: any) => this.parseEntry(e)).filter((r): r is SearchResult => {
+      if (r === null) return false;
+      if (params.date_from && r.published_date < params.date_from) return false;
+      if (params.date_to && r.published_date > params.date_to) return false;
+      return true;
+    });
+  }
+
+  private parseEntry(entry: any): SearchResult | null {
+    const id = String(entry.id ?? "");
+    if (!id) return null;
+    const arxiv_id = id.split("/abs/")[1]?.replace(/v\d+$/, "") ?? id;
+
+    const title = String(entry.title ?? "").replace(/\s+/g, " ").trim();
+    const abstract = String(entry.summary ?? "").replace(/\s+/g, " ").trim();
+    const published_date = String(entry.published ?? "").substring(0, 10);
+
+    const authorRaw = entry.author;
+    const authorArray = Array.isArray(authorRaw) ? authorRaw : (authorRaw ? [authorRaw] : []);
+    const authors = authorArray.map((a: any) => String(a.name ?? "")).filter(Boolean);
+
+    const categoryRaw = entry.category;
+    const categoryArray = Array.isArray(categoryRaw) ? categoryRaw : (categoryRaw ? [categoryRaw] : []);
+    const venue = categoryArray.map((c: any) => c["@_term"]).filter(Boolean).join(", ");
+
+    return {
+      source: "arxiv",
+      title,
+      authors,
+      abstract,
+      arxiv_id,
+      published_date,
+      venue: venue || "arXiv preprint",
+      url: id,
+    };
+  }
+}

package/src/sources/pubmed.ts

@@ -0,0 +1,143 @@
+import { XMLParser } from "fast-xml-parser";
+import type { SearchParams, SearchResult, SourceSearcher } from "../types.js";
+
+const BASE_URL = "https://eutils.ncbi.nlm.nih.gov/entrez/eutils";
+const USER_AGENT = "scholar-mcp/0.2.1 (https://github.com/kak4343/scholar-mcp)";
+
+export class PubMedSearcher implements SourceSearcher {
+  private apiKey?: string;
+
+  constructor(apiKey?: string) {
+    this.apiKey = apiKey;
+  }
+
+  async search(params: SearchParams): Promise<SearchResult[]> {
+    const pmids = await this.esearch(params);
+    if (pmids.length === 0) return [];
+    return this.efetch(pmids);
+  }
+
+  private async esearch(params: SearchParams): Promise<string[]> {
+    const url = new URL(`${BASE_URL}/esearch.fcgi`);
+    url.searchParams.set("db", "pubmed");
+    url.searchParams.set("term", this.buildTerm(params));
+    url.searchParams.set("retmax", String(params.max_results ?? 10));
+    url.searchParams.set("retmode", "json");
+    if (this.apiKey) url.searchParams.set("api_key", this.apiKey);
+
+    const r = await fetch(url, { headers: { "User-Agent": USER_AGENT } });
+    if (!r.ok) throw new Error(`PubMed esearch failed: ${r.status}`);
+    const data = await r.json() as { esearchresult?: { idlist?: string[] } };
+    return data.esearchresult?.idlist ?? [];
+  }
+
+  private buildTerm(params: SearchParams): string {
+    let term = params.query;
+    if (params.date_from || params.date_to) {
+      const from = (params.date_from ?? "1900/01/01").replace(/-/g, "/");
+      const to = (params.date_to ?? "3000/01/01").replace(/-/g, "/");
+      term += ` AND (${from}[PDAT] : ${to}[PDAT])`;
+    }
+    return term;
+  }
+
+  private async efetch(pmids: string[]): Promise<SearchResult[]> {
+    const url = new URL(`${BASE_URL}/efetch.fcgi`);
+    url.searchParams.set("db", "pubmed");
+    url.searchParams.set("id", pmids.join(","));
+    url.searchParams.set("retmode", "xml");
+    if (this.apiKey) url.searchParams.set("api_key", this.apiKey);
+
+    const r = await fetch(url, { headers: { "User-Agent": USER_AGENT } });
+    if (!r.ok) throw new Error(`PubMed efetch failed: ${r.status}`);
+    const xml = await r.text();
+
+    const parser = new XMLParser({ ignoreAttributes: false, attributeNamePrefix: "@_" });
+    const parsed = parser.parse(xml);
+    const articles = parsed.PubmedArticleSet?.PubmedArticle;
+    if (!articles) return [];
+    const articleArray = Array.isArray(articles) ? articles : [articles];
+
+    return articleArray.map((a: any) => this.parseArticle(a)).filter((r): r is SearchResult => r !== null);
+  }
+
+  private parseArticle(article: any): SearchResult | null {
+    const medlineCitation = article.MedlineCitation;
+    if (!medlineCitation) return null;
+
+    const pmid = String(medlineCitation.PMID?.["#text"] ?? medlineCitation.PMID ?? "");
+    const articleData = medlineCitation.Article;
+    if (!articleData) return null;
+
+    const title = String(articleData.ArticleTitle?.["#text"] ?? articleData.ArticleTitle ?? "").trim();
+
+    const abstractText = articleData.Abstract?.AbstractText;
+    const abstract = this.flattenAbstract(abstractText);
+
+    const authorList = articleData.AuthorList?.Author;
+    const authors = this.parseAuthors(authorList);
+
+    const journal = articleData.Journal?.Title ?? articleData.Journal?.ISOAbbreviation ?? "";
+    const pubDate = articleData.Journal?.JournalIssue?.PubDate;
+    const published_date = this.parseDate(pubDate);
+
+    const doi = this.extractDoi(article);
+
+    return {
+      source: "pubmed",
+      title,
+      authors,
+      abstract,
+      pmid,
+      doi,
+      published_date,
+      venue: journal,
+      url: `https://pubmed.ncbi.nlm.nih.gov/${pmid}/`,
+    };
+  }
+
+  private flattenAbstract(abstractText: any): string {
+    if (!abstractText) return "";
+    if (typeof abstractText === "string") return abstractText;
+    if (Array.isArray(abstractText)) {
+      return abstractText.map((t: any) => this.flattenAbstract(t)).join(" ");
+    }
+    if (abstractText["#text"]) return String(abstractText["#text"]);
+    return "";
+  }
+
+  private parseAuthors(authorList: any): string[] {
+    if (!authorList) return [];
+    const arr = Array.isArray(authorList) ? authorList : [authorList];
+    return arr.map((a: any) => {
+      const last = a.LastName ?? "";
+      const initials = a.Initials ?? a.ForeName ?? "";
+      return `${last}${initials ? ` ${initials}` : ""}`.trim();
+    }).filter(Boolean);
+  }
+
+  private parseDate(pubDate: any): string {
+    if (!pubDate) return "";
+    const year = pubDate.Year ?? "";
+    const month = pubDate.Month ?? "01";
+    const day = pubDate.Day ?? "01";
+    const monthNum = isNaN(Number(month)) ? this.monthNameToNum(month) : String(month).padStart(2, "0");
+    return year ? `${year}-${monthNum}-${String(day).padStart(2, "0")}` : "";
+  }
+
+  private monthNameToNum(month: string): string {
+    const map: Record<string, string> = {
+      Jan: "01", Feb: "02", Mar: "03", Apr: "04", May: "05", Jun: "06",
+      Jul: "07", Aug: "08", Sep: "09", Oct: "10", Nov: "11", Dec: "12",
+    };
+    return map[month] ?? "01";
+  }
+
+  private extractDoi(article: any): string | undefined {
+    const ids = article.PubmedData?.ArticleIdList?.ArticleId;
+    if (!ids) return undefined;
+    const arr = Array.isArray(ids) ? ids : [ids];
+    const doiEntry = arr.find((i: any) => i["@_IdType"] === "doi");
+    return doiEntry ? String(doiEntry["#text"] ?? doiEntry) : undefined;
+  }
+}