semantic-scholar-mcp 1.0.0 → 1.0.1

package/README.md

@@ -19,3 +19,22 @@ node dist/index.js
 ```
 
 Semantic Scholar rate limits anonymous access. The server retries and reports an honest error when the limit is hit.
+
+<!-- paywall -->
+## Premium tools
+
+These tools need a license key:
+
+* `paper_citations`
+* `paper_field`
+
+Buy a key at https://mcp-marketplace.io/server/io-github-mrfentmen-semantic-scholar-mcp and set it in your MCP client config:
+
+```json
+"env": { "MCP_LICENSE_KEY": "mcp_live_..." }
+```
+
+The key is checked against MCP Marketplace, cached for 24 hours, and keeps
+working offline once one check has succeeded. Every other tool on this server
+stays free.
+<!-- /paywall -->

package/dist/api.js

@@ -38,3 +38,163 @@ export async function paperInfo(args) {
     const d = await get(`${BASE}/paper/${encodeURIComponent(id)}?fields=title,year,abstract,authors,citationCount,referenceCount,venue,externalIds`);
     return `Title: ${d.title ?? "n/a"} (${d.year ?? "year n/a"})\nVenue: ${d.venue ?? "n/a"}\nAuthors: ${(d.authors ?? []).slice(0, 5).map((a) => a.name).join(", ") || "n/a"}\nCitations: ${d.citationCount ?? 0} | References: ${d.referenceCount ?? 0}${d.externalIds?.DOI ? ` | doi ${d.externalIds.DOI}` : ""}\n\n${(d.abstract ?? "no abstract").slice(0, 500)}`;
 }
+// ---- muxE tools:
+// searchPapers prints a list and paperInfo prints one paper's title, venue,
+// authors, two counts, a DOI and the first 500 characters of the abstract. The
+// graph API behind it also answers three other questions it is never asked: who
+// is citing this paper, what this paper cites, and how the field itself sees
+// the work. Those are three routes, all verified live against the public API.
+const GRAPH = 'https://api.semanticscholar.org/graph/v1';
+// The existing get already retries a 429 with backoff, so every call here goes
+// through it rather than reaching for fetch directly.
+const CITATION_FIELDS = 'title,year,authors,citationCount,externalIds,venue';
+const RICH_FIELDS = 'title,year,venue,fieldsOfStudy,s2FieldsOfStudy,publicationTypes,influentialCitationCount,openAccessPdf,tldr,isOpenAccess,citationCount,referenceCount,publicationDate,journal';
+const label = (p) => {
+    if (!p)
+        return 'not reported';
+    const t = typeof p.title === 'string' ? p.title.trim() : '';
+    if (!t)
+        return 'untitled';
+    return t.length > 90 ? `${t.slice(0, 90)}...` : t;
+};
+const authorsOf = (p, max = 3) => {
+    const names = Array.isArray(p?.authors) ? p.authors.map((a) => a?.name).filter(Boolean) : [];
+    if (!names.length)
+        return 'not reported';
+    const shown = names.slice(0, max).join(', ');
+    return names.length > max ? `${shown}, and ${names.length - max} more` : shown;
+};
+const pct = (n, total) => (total > 0 ? `${((n / total) * 100).toFixed(1)}%` : "n/a");
+function requireId(raw) {
+    const id = String(raw ?? '').trim();
+    if (!id)
+        throw new ScholarError('Provide a paper ID, a DOI such as DOI:10.1038/nature12373, or a corpus id');
+    if (id.length > 200)
+        throw new ScholarError('That paper ID is far too long to be an id');
+    return encodeURIComponent(id);
+}
+export async function paper_citations(args) {
+    const id = requireId(args?.paperId);
+    const limit = Math.max(1, Math.min(50, Math.floor(Number(args?.limit ?? 10) || 10)));
+    const d = await get(`${GRAPH}/paper/${id}/citations?fields=${CITATION_FIELDS}&limit=${limit}`);
+    const rows = Array.isArray(d?.data) ? d.data : [];
+    if (!rows.length)
+        return 'Semantic Scholar returned no citing papers for this id.';
+    const papers = rows.map((r) => r?.citingPaper).filter(Boolean);
+    const years = papers.map((p) => Number(p.year)).filter((y) => Number.isFinite(y) && y > 0);
+    // This route returns offset, next and data, but no total, so the count is
+    // described as what came back rather than inventing a denominator.
+    const lines = [`Papers citing this one, from Semantic Scholar (${papers.length} returned on this page):`];
+    if (years.length) {
+        const sorted = [...years].sort((a, b) => a - b);
+        const byYear = new Map();
+        for (const y of years)
+            byYear.set(y, (byYear.get(y) ?? 0) + 1);
+        const top = [...byYear.entries()].sort((a, b) => b[1] - a[1])[0];
+        lines.push(`  publication years run ${sorted[0]} to ${sorted[sorted.length - 1]}, and ${top[0]} is the busiest single year at ${top[1]} of ${years.length}.`);
+    }
+    // Later citing papers are the ones that matter, so they lead.
+    const ordered = [...papers].sort((a, b) => (Number(b.year) || 0) - (Number(a.year) || 0));
+    for (const p of ordered.slice(0, limit)) {
+        const cites = typeof p.citationCount === 'number' ? p.citationCount : 0;
+        lines.push(`  ${p.year ?? 'year n/a'} — ${label(p)}`);
+        lines.push(`    ${authorsOf(p)}${p.venue ? ` | ${p.venue}` : ""} | ${cites} citation${cites === 1 ? "" : "s"} of its own${p?.externalIds?.DOI ? ` | doi ${p.externalIds.DOI}` : ""}`);
+    }
+    if (ordered.length > limit)
+        lines.push(`  and ${ordered.length - limit} further citing paper(s) not listed.`);
+    if (d?.next !== undefined && d.next !== null)
+        lines.push(`  the index reports more beyond this page, next offset ${d.next}.`);
+    lines.push("");
+    lines.push("  The existing tools can only tell you how many citations a paper has, never who those citations came from.");
+    return lines.join("\n");
+}
+export async function paper_references(args) {
+    const id = requireId(args?.paperId);
+    const limit = Math.max(1, Math.min(50, Math.floor(Number(args?.limit ?? 10) || 10)));
+    const d = await get(`${GRAPH}/paper/${id}/references?fields=${CITATION_FIELDS}&limit=${limit}`);
+    const rows = Array.isArray(d?.data) ? d.data : [];
+    if (!rows.length)
+        return 'Semantic Scholar returned no references for this id.';
+    const papers = rows.map((r) => r?.citedPaper).filter(Boolean);
+    const unresolved = rows.length - papers.length;
+    const years = papers.map((p) => Number(p.year)).filter((y) => Number.isFinite(y) && y > 0);
+    const lines = [
+        `What this paper cites (${papers.length} reference${papers.length === 1 ? "" : "s"} returned on this page${unresolved ? `, plus ${unresolved} the index holds no record for` : ""}):`,
+    ];
+    if (years.length) {
+        const sorted = [...years].sort((a, b) => a - b);
+        lines.push(`  they span ${sorted[0]} to ${sorted[sorted.length - 1]}.`);
+    }
+    // Oldest first: the question behind this is what the work was built on.
+    const ordered = [...papers].sort((a, b) => (Number(a.year) || 9999) - (Number(b.year) || 9999));
+    for (const p of ordered.slice(0, limit)) {
+        lines.push(`  ${p.year ?? 'year n/a'} — ${label(p)}`);
+        lines.push(`    ${authorsOf(p)}${p.venue ? ` | ${p.venue}` : ""}`);
+    }
+    if (ordered.length > limit)
+        lines.push(`  and ${ordered.length - limit} further reference(s) not listed.`);
+    if (d?.next !== undefined && d.next !== null)
+        lines.push(`  the index reports more beyond this page, next offset ${d.next}.`);
+    lines.push("");
+    lines.push("  The existing paperInfo reports a referenceCount as a bare number and cannot show any of the works behind it.");
+    return lines.join("\n");
+}
+export async function paper_field(args) {
+    const id = requireId(args?.paperId);
+    const d = await get(`${GRAPH}/paper/${id}?fields=${RICH_FIELDS}`);
+    if (!d || d.title === undefined)
+        throw new ScholarError('Semantic Scholar has no record for that id.');
+    const lines = [
+        `How the index itself reads this paper, beyond its title and abstract:`,
+        `  title: ${label(d)}`,
+        `  published: ${d.publicationDate ?? d.year ?? 'not reported'}${d.journal?.name ? ` in ${d.journal.name}` : ""}${d.venue ? ` (venue recorded as ${d.venue})` : ""}`,
+    ];
+    const fos = Array.isArray(d.fieldsOfStudy) ? d.fieldsOfStudy : [];
+    if (fos.length)
+        lines.push(`  fields of study: ${fos.join(", ")}.`);
+    const s2 = Array.isArray(d.s2FieldsOfStudy) ? d.s2FieldsOfStudy : [];
+    if (s2.length) {
+        // The weighted form is what S2 actually uses for ranking, and it is
+        // different from the flat category list above.
+        const withWeight = s2.filter((f) => typeof f?.source === "string" || typeof f?.score === "number");
+        const bySource = new Map();
+        for (const f of s2) {
+            const src = f?.source ?? "unspecified";
+            bySource.set(src, (bySource.get(src) ?? 0) + 1);
+        }
+        lines.push(`  Semantic Scholar's own classification gives ${s2.length} categories, sourced: ${[...bySource.entries()].map(([k, v]) => `${k} (${v})`).join(", ")}.`);
+        if (withWeight.length)
+            lines.push(`  ${withWeight.length} of those carry a source or score, so the classification is partly derived rather than purely declared.`);
+    }
+    const types = Array.isArray(d.publicationTypes) ? d.publicationTypes : [];
+    lines.push(`  publication types: ${types.length ? types.join(", ") : "not reported"}.`);
+    const infl = typeof d.influentialCitationCount === "number" ? d.influentialCitationCount : null;
+    const cites = typeof d.citationCount === "number" ? d.citationCount : null;
+    const refs = typeof d.referenceCount === "number" ? d.referenceCount : null;
+    if (infl !== null && cites !== null) {
+        lines.push(`  citations: ${cites} in total, of which ${infl} (${pct(infl, cites)}) are marked influential.`);
+        lines.push(infl / cites > 0.3
+            ? `  A high influential share means this work is being built on rather than merely cited in passing.`
+            : infl / cites < 0.05
+                ? `  Very few of these citations are influential, so the work is referenced more than it is relied on.`
+                : `  The influential share is ordinary, so this is cited steadily rather than as a foundation.`);
+    }
+    else {
+        lines.push(`  citations: ${cites ?? "not reported"}, influential citations: ${infl === null ? "not reported" : infl}.`);
+    }
+    if (refs !== null && cites !== null) {
+        lines.push(`  reference list length: ${refs}.`);
+    }
+    lines.push(`  open access: ${d.isOpenAccess === true ? "yes" : d.isOpenAccess === false ? "no" : "not reported"}${d.openAccessPdf?.url ? `, PDF at ${d.openAccessPdf.url}` : d.isOpenAccess === true ? ", but the index records no direct PDF link" : ""}.`);
+    const tldr = d.tldr?.text;
+    if (typeof tldr === "string" && tldr) {
+        lines.push(`  index summary: ${tldr.length > 300 ? `${tldr.slice(0, 300)}...` : tldr}`);
+        lines.push("  That summary is generated by the index, not written by the authors, so treat it as a reading of the paper rather than a claim from it.");
+    }
+    else {
+        lines.push("  the index holds no generated summary for this paper.");
+    }
+    lines.push("");
+    lines.push("  The existing paperInfo asks for the abstract and two counts and prints neither of these.");
+    return lines.join("\n");
+}

package/dist/license.js

@@ -0,0 +1,79 @@
+// Premium tools on this server need a license key bought from MCP Marketplace.
+// Buyers put the key in their MCP client config as MCP_LICENSE_KEY. Every tool
+// that is not listed in PREMIUM keeps working without a key.
+const SLUG = "semantic-scholar-mcp";
+// Tools that need a key. Everything else is free.
+const PREMIUM = new Set([
+    "paper_citations",
+    "paper_field",
+]);
+const BUY_URL = `https://mcp-marketplace.io/server/io-github-mrfentmen-${SLUG}`;
+// The license check calls the marketplace's verify endpoint directly instead of
+// using @mcp_marketplace/license. That SDK sends no `apikey` header, so every
+// check it makes is rejected by Supabase before it reaches the function. The
+// publishable key below is public by design - it ships in mcp-marketplace.io's
+// own JavaScript and only ever reaches their licence check.
+const DEFAULT_VERIFY_URL = "https://virupvwhtkpkjsiskckg.supabase.co/functions/v1/verify-key";
+const PUBLISHABLE_KEY = "sb_publishable_BuqlW96Ke8C_zzJG-LQv1Q_YHi_r_4h";
+const OK_CACHE_MS = 60 * 60 * 1000;
+const BAD_CACHE_MS = 60 * 1000;
+const seen = new Map();
+const REASONS = {
+    missing_key: "no key is set",
+    invalid_format: "that key is not a valid MCP Marketplace key",
+    not_found: "that key was not found",
+    revoked: "that key has been revoked",
+    rotated: "that key was rotated, use your new one",
+    expired: "that key has expired, renew it",
+    rate_limited: "there were too many checks just now, try again shortly",
+    network_error: "the license server could not be reached",
+};
+function blocked(tool, reason) {
+    const why = REASONS[reason] ?? `the license server answered "${reason}"`;
+    return `"${tool}" needs a license key, but ${why}. ` +
+        `Set MCP_LICENSE_KEY in your MCP client config. Get a key: ${BUY_URL}`;
+}
+async function verify(key) {
+    const res = await fetch(process.env.MCP_LICENSE_VERIFY_URL || DEFAULT_VERIFY_URL, {
+        method: "POST",
+        headers: {
+            apikey: PUBLISHABLE_KEY,
+            Authorization: `Bearer ${PUBLISHABLE_KEY}`,
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify({ key, slug: SLUG }),
+        // an unusable key answers 400 with a JSON body, so read the body either way
+        signal: AbortSignal.timeout(15000),
+    });
+    const data = (await res.json());
+    if (typeof data?.valid !== "boolean")
+        return { valid: false, reason: "unexpected_response" };
+    return data;
+}
+/**
+ * Returns null when the caller may run the tool, or a short message telling
+ * them how to get a key.
+ *
+ * A good key is remembered for an hour, so a busy session does not hit the
+ * license server on every call and keeps working through a brief outage.
+ */
+export async function premiumRequired(tool) {
+    if (!PREMIUM.has(tool))
+        return null;
+    const key = process.env.MCP_LICENSE_KEY;
+    if (!key)
+        return blocked(tool, "missing_key");
+    const hit = seen.get(key);
+    if (hit && Date.now() - hit.at < (hit.valid ? OK_CACHE_MS : BAD_CACHE_MS)) {
+        return hit.valid ? null : blocked(tool, hit.reason ?? "invalid");
+    }
+    let result;
+    try {
+        result = await verify(key);
+    }
+    catch {
+        result = { valid: false, reason: "network_error" };
+    }
+    seen.set(key, { ...result, at: Date.now() });
+    return result.valid ? null : blocked(tool, result.reason ?? "invalid");
+}

package/dist/server.js

@@ -1,7 +1,8 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { paperInfo } from "./api.js";
-import { searchPapers } from "./api.js";
+import { searchPapers, paper_citations, paper_references, paper_field } from "./api.js";
+import { premiumRequired } from "./license.js";
 const text = (value) => ({ content: [{ type: "text", text: value }] });
 const textError = (t) => ({ content: [{ type: "text", text: t }], isError: true });
 const READ_ONLY = { readOnlyHint: true, openWorldHint: true };
@@ -34,5 +35,62 @@ export function createServer() {
             return textError(error(e));
         }
     });
+    server.registerTool("paper_citations", {
+        title: "Paper citations",
+        description: "List the papers that cite a given paper, most recent first, with their year, authors, venue, own citation count and DOI, plus the span of years citing work appears in and the busiest single year. The existing tools report a citation count as a bare number and can never say who the citations came from.",
+        inputSchema: z.object({
+            paperId: z.string().describe("Paper id, for instance 'DOI:10.1038/nature12373'. Search with search_papers first."),
+            limit: z.number().int().min(1).max(50).optional().describe("How many citing papers to list. Default 10."),
+        }),
+        annotations: READ_ONLY,
+    }, async ({ paperId, limit }) => {
+        // ---- paywall: paper_citations ----
+        const paywallMessage = await premiumRequired("paper_citations");
+        if (paywallMessage)
+            return { content: [{ type: "text", text: paywallMessage }], isError: true };
+        // ---- paywall: end ----
+        try {
+            return text(await paper_citations({ paperId, limit }));
+        }
+        catch (e) {
+            return textError(error(e));
+        }
+    });
+    server.registerTool("paper_references", {
+        title: "Paper references",
+        description: "List the works a given paper cites, oldest first, with year, authors and venue, and say how many references the index could not resolve. This is the backward view: what a paper was built on. paperInfo reports a referenceCount as a number and cannot show any of the works behind it.",
+        inputSchema: z.object({
+            paperId: z.string().describe("Paper id, for instance 'DOI:10.1038/nature12373'."),
+            limit: z.number().int().min(1).max(50).optional().describe("How many references to list. Default 10."),
+        }),
+        annotations: READ_ONLY,
+    }, async ({ paperId, limit }) => {
+        try {
+            return text(await paper_references({ paperId, limit }));
+        }
+        catch (e) {
+            return textError(error(e));
+        }
+    });
+    server.registerTool("paper_field", {
+        title: "Paper field placement",
+        description: "Report how the Semantic Scholar index itself reads a paper: its fields of study and the index's own weighted categories, publication types, total against influential citations with the share and what that ratio means, reference list length, open access status and PDF link, and the index's generated summary with a warning that it is not the authors' own words. paperInfo prints the abstract and two counts and none of this.",
+        inputSchema: z.object({
+            paperId: z.string().describe("Paper id, for instance 'DOI:10.1038/nature12373'."),
+        }),
+        annotations: READ_ONLY,
+    }, async ({ paperId }) => {
+        // ---- paywall: paper_field ----
+        const paywallMessage = await premiumRequired("paper_field");
+        if (paywallMessage)
+            return { content: [{ type: "text", text: paywallMessage }], isError: true };
+        // ---- paywall: end ----
+        try {
+            return text(await paper_field({ paperId }));
+        }
+        catch (e) {
+            return textError(error(e));
+        }
+    });
     return server;
 }

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.0.0",
+  "version": "1.0.1",
   "type": "module",
   "repository": {
     "type": "git",