@research-copilot/mcp-scholar 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ldm2060
+
+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,112 @@
+# @research-copilot/mcp-scholar
+
+MCP server for scholarly paper search, aggregating results from multiple academic search backends.
+
+## Installation
+
+```bash
+npx @research-copilot/mcp-scholar
+```
+
+Or via MCP configuration:
+
+```json
+{
+  "mcpServers": {
+    "research-scholar": {
+      "command": "npx",
+      "args": ["-y", "@research-copilot/mcp-scholar"]
+    }
+  }
+}
+```
+
+## Tools
+
+### `scholar_search`
+
+Search for academic papers across multiple backends.
+
+**Inputs:**
+- `query` (string, required) - Search query
+- `limit` (number, optional) - Max results per backend (default: 10)
+- `backends` (string[], optional) - Backends to query (default: ["arxiv", "dblp"])
+
+**Backends:**
+- `arxiv` - arXiv.org (full backend, reliable)
+- `dblp` - DBLP Computer Science Bibliography (full backend, reliable)
+- `scholar` - Google Scholar via SerpAPI (best-effort, requires API key)
+- `arxivsub` - arXiv submission tracker (best-effort)
+
+**Returns:** Array of paper objects with fields:
+- `title` (string)
+- `authors` (string[])
+- `year` (number)
+- `venue` (string)
+- `url` (string)
+- `abstract` (string, if available)
+- `citations` (number, if available)
+- `source` (string) - Backend that provided this result
+
+### `scholar_metadata`
+
+Get detailed metadata for a specific arXiv paper.
+
+**Inputs:**
+- `arxiv_id` (string, required) - arXiv ID (e.g., "2401.12345")
+
+**Returns:** Paper metadata with full details from arXiv API.
+
+### `scholar_bibtex`
+
+Get BibTeX citation for a paper from DBLP.
+
+**Inputs:**
+- `dblp_key` (string, required) - DBLP key (e.g., "conf/icml/SmithJ23")
+
+**Returns:**
+- `bibtex` (string) - BibTeX entry, or empty string if not found
+
+## Backend Details
+
+**arXiv** (full backend):
+- Atom XML API
+- Reliable, no rate limits for reasonable use
+- Returns: title, authors, year, abstract, arXiv URL
+
+**DBLP** (full backend):
+- JSON API + BibTeX fetching
+- Reliable, no API key required
+- Returns: title, authors, year, venue, DBLP URL, BibTeX
+
+**Google Scholar** (best-effort):
+- Via SerpAPI (requires `SERP_API_KEY` environment variable)
+- Rate-limited by SerpAPI plan
+- Returns: title, authors, year, citations, URL
+- Errors are logged but don't fail the overall search
+
+**arXiv Submission** (best-effort):
+- Tracks recent arXiv submissions
+- May be unstable
+- Errors are logged but don't fail the overall search
+
+## Multi-Backend Aggregation
+
+The `scholar_search` tool runs queries against all enabled backends in parallel and aggregates results. Per-backend failures are isolated (one backend error doesn't fail the entire search). Each result is tagged with its `source` backend.
+
+**Default backends:** `["arxiv", "dblp"]` (reliable, no API keys required)
+
+**To use Google Scholar:** Set `SERP_API_KEY` environment variable and include `"scholar"` in backends array.
+
+## Architecture
+
+- `src/facade.ts` - Multi-backend orchestration with failure isolation
+- `src/backends/arxiv.ts` - arXiv API client (Atom XML)
+- `src/backends/dblp.ts` - DBLP API client (JSON + BibTeX)
+- `src/backends/scholar.ts` - Google Scholar via SerpAPI
+- `src/backends/arxivsub.ts` - arXiv submission tracker
+- `src/server.ts` - MCP server implementation
+
+## License
+
+MIT

package/dist/mcp-scholar.js

@@ -0,0 +1,361 @@
+#!/usr/bin/env node
+
+// bin/mcp-scholar.ts
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// src/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+
+// src/backends/arxiv.ts
+import { XMLParser } from "fast-xml-parser";
+var ENDPOINT = "http://export.arxiv.org/api/query";
+var parser = new XMLParser({
+  ignoreAttributes: true,
+  trimValues: true
+});
+function toArray(value) {
+  if (value === void 0 || value === null) return [];
+  return Array.isArray(value) ? value : [value];
+}
+function arxivIdFromUrl(idUrl) {
+  const match = idUrl.match(/abs\/(.+)$/);
+  return match ? match[1] : idUrl;
+}
+async function arxivSearch(query, limit, fetchImpl = fetch) {
+  const url = `${ENDPOINT}?search_query=all:${encodeURIComponent(query)}&max_results=${limit}`;
+  const res = await fetchImpl(url);
+  const xml = await res.text();
+  const doc = parser.parse(xml);
+  const entries = toArray(doc.feed?.entry);
+  return entries.map((entry) => {
+    const idUrl = typeof entry.id === "string" ? entry.id : "";
+    const authors = toArray(entry.author).map((a) => typeof a?.name === "string" ? a.name : "").filter((n) => n.length > 0);
+    const published = typeof entry.published === "string" ? entry.published : void 0;
+    const year = published ? Number(published.slice(0, 4)) : void 0;
+    const title = typeof entry.title === "string" ? entry.title.trim() : "";
+    const abstract = typeof entry.summary === "string" ? entry.summary.trim() : void 0;
+    return {
+      id: arxivIdFromUrl(idUrl),
+      title,
+      authors,
+      year: Number.isFinite(year) ? year : void 0,
+      abstract,
+      url: idUrl || void 0,
+      source: "arxiv"
+    };
+  });
+}
+async function arxivMetadata(id, fetchImpl = fetch) {
+  const url = `${ENDPOINT}?id_list=${encodeURIComponent(id)}&max_results=1`;
+  const res = await fetchImpl(url);
+  const xml = await res.text();
+  const doc = parser.parse(xml);
+  const entries = toArray(doc.feed?.entry);
+  if (entries.length === 0) return void 0;
+  const entry = entries[0];
+  const idUrl = typeof entry.id === "string" ? entry.id : "";
+  const authors = toArray(entry.author).map((a) => typeof a?.name === "string" ? a.name : "").filter((n) => n.length > 0);
+  const published = typeof entry.published === "string" ? entry.published : void 0;
+  const year = published ? Number(published.slice(0, 4)) : void 0;
+  return {
+    id: arxivIdFromUrl(idUrl),
+    title: typeof entry.title === "string" ? entry.title.trim() : "",
+    authors,
+    year: Number.isFinite(year) ? year : void 0,
+    abstract: typeof entry.summary === "string" ? entry.summary.trim() : void 0,
+    url: idUrl || void 0,
+    source: "arxiv"
+  };
+}
+
+// src/backends/dblp.ts
+var SEARCH_ENDPOINT = "https://dblp.org/search/publ/api";
+function toArray2(value) {
+  if (value === void 0 || value === null) return [];
+  return Array.isArray(value) ? value : [value];
+}
+async function dblpSearch(query, limit, fetchImpl = fetch) {
+  const url = `${SEARCH_ENDPOINT}?q=${encodeURIComponent(query)}&format=json&h=${limit}`;
+  const res = await fetchImpl(url);
+  const json = await res.json();
+  const hits = toArray2(json.result?.hits?.hit);
+  return hits.map((hit) => {
+    const info = hit.info ?? {};
+    const authors = toArray2(info.authors?.author).map((a) => typeof a?.text === "string" ? a.text : "").filter((n) => n.length > 0);
+    const yearNum = info.year !== void 0 ? Number(info.year) : void 0;
+    return {
+      id: typeof info.key === "string" ? info.key : info.url ?? "",
+      title: typeof info.title === "string" ? info.title : "",
+      authors,
+      year: yearNum !== void 0 && Number.isFinite(yearNum) ? yearNum : void 0,
+      url: typeof info.url === "string" ? info.url : void 0,
+      source: "dblp"
+    };
+  });
+}
+async function dblpBibtex(keyOrUrl, fetchImpl = fetch) {
+  try {
+    const url = bibtexUrl(keyOrUrl);
+    const res = await fetchImpl(url);
+    if (!res.ok) return "";
+    const text = await res.text();
+    return text;
+  } catch (err) {
+    process.stderr.write(
+      `mcp-scholar: dblpBibtex failed for "${keyOrUrl}": ${errMsg(err)}
+`
+    );
+    return "";
+  }
+}
+function bibtexUrl(keyOrUrl) {
+  if (/^https?:\/\//.test(keyOrUrl)) {
+    return keyOrUrl.endsWith(".bib") ? keyOrUrl : `${keyOrUrl}.bib`;
+  }
+  return `https://dblp.org/rec/${keyOrUrl}.bib`;
+}
+function errMsg(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+
+// src/backends/scholar.ts
+var ENDPOINT2 = "https://scholar.google.com/scholar";
+async function scholarSearch(query, limit, fetchImpl = fetch) {
+  try {
+    const url = `${ENDPOINT2}?q=${encodeURIComponent(query)}&hl=en&num=${limit}`;
+    const res = await fetchImpl(url, {
+      headers: {
+        // A desktop UA reduces (does not eliminate) bot blocking.
+        "user-agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0 Safari/537.36",
+        "accept-language": "en-US,en;q=0.9"
+      }
+    });
+    if (!res.ok) return [];
+    const html = await res.text();
+    if (/captcha|unusual traffic|not a robot/i.test(html)) return [];
+    return parseScholarHtml(html, limit);
+  } catch (err) {
+    process.stderr.write(
+      `mcp-scholar: scholar backend degraded to []: ${errMsg2(err)}
+`
+    );
+    return [];
+  }
+}
+function parseScholarHtml(html, limit) {
+  const papers = [];
+  const h3Re = /<h3[^>]*class="[^"]*gs_rt[^"]*"[^>]*>([\s\S]*?)<\/h3>/gi;
+  let m;
+  while ((m = h3Re.exec(html)) !== null && papers.length < limit) {
+    const inner = m[1];
+    const anchor = inner.match(/<a[^>]*>([\s\S]*?)<\/a>/i);
+    const rawTitle = anchor ? anchor[1] : inner;
+    const title = stripTags(rawTitle).trim();
+    if (!title) continue;
+    const href = inner.match(/<a[^>]*href="([^"]+)"/i)?.[1];
+    papers.push({
+      id: href ?? title,
+      title,
+      authors: [],
+      url: href,
+      source: "scholar"
+    });
+  }
+  return papers;
+}
+function stripTags(s) {
+  return s.replace(/<[^>]+>/g, "").replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&#39;/g, "'").replace(/&quot;/g, '"');
+}
+function errMsg2(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+
+// src/backends/arxivsub.ts
+var ENDPOINT3 = "https://arxivsub.com/api/search";
+async function arxivsubSearch(query, limit, fetchImpl = fetch, env = process.env) {
+  const key = env.ARXIVSUB_SKILL_KEY;
+  if (!key) {
+    return [];
+  }
+  try {
+    const url = `${ENDPOINT3}?q=${encodeURIComponent(query)}&limit=${limit}`;
+    const res = await fetchImpl(url, {
+      headers: { authorization: `Bearer ${key}`, accept: "application/json" }
+    });
+    if (!res.ok) return [];
+    const json = await res.json();
+    const items = json.results ?? json.items ?? json.data ?? [];
+    if (!Array.isArray(items)) return [];
+    return items.slice(0, limit).map((item) => {
+      const authors = Array.isArray(item.authors) ? item.authors : typeof item.authors === "string" ? [item.authors] : [];
+      const yearNum = item.year !== void 0 ? Number(item.year) : void 0;
+      return {
+        id: String(item.id ?? item.arxiv_id ?? item.url ?? item.title ?? ""),
+        title: typeof item.title === "string" ? item.title : "",
+        authors,
+        year: yearNum !== void 0 && Number.isFinite(yearNum) ? yearNum : void 0,
+        abstract: item.abstract ?? item.summary,
+        url: typeof item.url === "string" ? item.url : void 0,
+        source: "arxivsub"
+      };
+    });
+  } catch (err) {
+    process.stderr.write(
+      `mcp-scholar: arxivsub backend degraded to []: ${errMsg3(err)}
+`
+    );
+    return [];
+  }
+}
+function errMsg3(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+
+// src/facade.ts
+var DEFAULT_BACKENDS = ["arxiv", "dblp"];
+var DEFAULT_LIMIT = 10;
+async function searchScholar(query, opts = {}) {
+  const limit = opts.limit ?? DEFAULT_LIMIT;
+  const backends = opts.backends ?? DEFAULT_BACKENDS;
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const tasks = backends.map((name) => runBackend(name, query, limit, fetchImpl));
+  const results = await Promise.all(tasks);
+  return results.flat();
+}
+async function runBackend(name, query, limit, fetchImpl) {
+  try {
+    switch (name) {
+      case "arxiv":
+        return await arxivSearch(query, limit, fetchImpl);
+      case "dblp":
+        return await dblpSearch(query, limit, fetchImpl);
+      case "scholar":
+        return await scholarSearch(query, limit, fetchImpl);
+      case "arxivsub":
+        return await arxivsubSearch(query, limit, fetchImpl);
+      default:
+        process.stderr.write(`mcp-scholar: unknown backend "${name}" ignored
+`);
+        return [];
+    }
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    process.stderr.write(
+      `mcp-scholar: backend "${name}" failed (isolated): ${message}
+`
+    );
+    return [];
+  }
+}
+
+// src/server.ts
+function createServer() {
+  const server = new McpServer({
+    name: "mcp-scholar",
+    version: "0.0.0"
+  });
+  server.registerTool(
+    "scholar_search",
+    {
+      title: "Search scholarly literature",
+      description: "Search literature across multiple backends (default: arxiv + dblp; scholar and arxivsub are opt-in best-effort). Per-backend failures are isolated and every result is tagged with its source.",
+      inputSchema: {
+        query: z.string().describe("Free-text search query"),
+        limit: z.number().int().positive().optional().describe("Max results per backend (default 10)"),
+        backends: z.array(z.enum(["arxiv", "dblp", "scholar", "arxivsub"])).optional().describe('Backends to query (default ["arxiv","dblp"])')
+      }
+    },
+    async ({ query, limit, backends }) => {
+      try {
+        const papers = await searchScholar(query, { limit, backends });
+        return {
+          content: [{ type: "text", text: JSON.stringify(papers, null, 2) }],
+          structuredContent: { papers }
+        };
+      } catch (err) {
+        return errorResult("scholar_search", err);
+      }
+    }
+  );
+  server.registerTool(
+    "scholar_metadata",
+    {
+      title: "Look up arXiv paper metadata",
+      description: 'Fetch metadata (title, authors, year, abstract, url) for a single arXiv id (e.g. "1706.03762").',
+      inputSchema: {
+        id: z.string().describe("arXiv id, e.g. 1706.03762 or 2005.14165v4")
+      }
+    },
+    async ({ id }) => {
+      try {
+        const paper = await arxivMetadata(id);
+        if (!paper) {
+          return {
+            content: [{ type: "text", text: `No arXiv metadata found for id "${id}"` }],
+            structuredContent: { paper: null }
+          };
+        }
+        return {
+          content: [{ type: "text", text: JSON.stringify(paper, null, 2) }],
+          structuredContent: { paper }
+        };
+      } catch (err) {
+        return errorResult("scholar_metadata", err);
+      }
+    }
+  );
+  server.registerTool(
+    "bibtex",
+    {
+      title: "Get a BibTeX entry",
+      description: "Return a BibTeX entry for a query. Resolves the top DBLP hit and fetches its .bib export. Returns an empty string when nothing is found.",
+      inputSchema: {
+        query: z.string().describe("Search query or DBLP record key")
+      }
+    },
+    async ({ query }) => {
+      try {
+        let key = query;
+        if (!looksLikeDblpKeyOrUrl(query)) {
+          const hits = await dblpSearch(query, 1);
+          if (hits.length > 0 && hits[0].id) {
+            key = hits[0].id;
+          }
+        }
+        const bib = await dblpBibtex(key);
+        return {
+          content: [{ type: "text", text: bib }],
+          structuredContent: { bibtex: bib }
+        };
+      } catch (err) {
+        return errorResult("bibtex", err);
+      }
+    }
+  );
+  return server;
+}
+function looksLikeDblpKeyOrUrl(s) {
+  return /^https?:\/\//.test(s) || /^[a-z]+\/[^\s]+\/[^\s]+$/i.test(s);
+}
+function errorResult(tool, err) {
+  const message = err instanceof Error ? err.message : String(err);
+  return {
+    isError: true,
+    content: [{ type: "text", text: `${tool} failed: ${message}` }]
+  };
+}
+
+// bin/mcp-scholar.ts
+async function main() {
+  const server = createServer();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+main().catch((err) => {
+  process.stderr.write(
+    `mcp-scholar: fatal: ${err instanceof Error ? err.stack ?? err.message : String(err)}
+`
+  );
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@research-copilot/mcp-scholar",
+  "version": "1.0.0",
+  "description": "MCP server for scholarly paper search",
+  "type": "module",
+  "bin": {
+    "mcp-scholar": "./dist/mcp-scholar.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "keywords": [
+    "mcp",
+    "scholar",
+    "arxiv",
+    "dblp",
+    "research"
+  ],
+  "author": "ldm2060",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ldm2060/research_copilot.git",
+    "directory": "packages/mcp-scholar"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "fast-xml-parser": "^4.5.0",
+    "zod": "^3.25.0"
+  },
+  "scripts": {
+    "build": "tsup bin/mcp-scholar.ts --format esm"
+  }
+}