scholar-sidekick-mcp 0.3.4 → 0.4.1

package/README.md

@@ -1,14 +1,24 @@
 # Scholar Sidekick MCP Server
 
-[MCP](https://modelcontextprotocol.io) server for [Scholar Sidekick](https://scholar-sidekick.com) — resolve, format, and export academic citations from any AI assistant.
+[MCP](https://modelcontextprotocol.io) server for [Scholar Sidekick](https://scholar-sidekick.com) — resolve any scholarly identifier (DOI, PMID, PMCID, ISBN, arXiv, ISSN, NASA ADS bibcode, WHO IRIS URL) into 10,000+ CSL styles or nine export formats, single or batch, from any AI assistant.
+
+## Highlights
+
+- **Eight identifier types out of the box** — DOIs, PMIDs, PMCIDs, ISBNs, arXiv IDs, ISSNs, NASA ADS bibcodes, and WHO IRIS URLs (rare in citation tooling).
+- **Batch-friendly** — every tool accepts a single identifier or a comma- or newline-separated list; the server normalises the list and resolves them in one round trip.
+- **10,000+ citation styles** — five hand-tuned builtins (Vancouver, AMA, APA, IEEE, CSE) plus any [CSL style ID](https://github.com/citation-style-language/styles), with alias and dependent-style resolution.
+- **Nine export formats** — BibTeX, RIS, CSL JSON, EndNote (XML/Refer), RefWorks, MEDLINE, Zotero RDF, CSV, plain text.
+- **Composable workflow** — chain `resolveIdentifier` → `formatCitation` → `exportCitation` in one prompt for an end-to-end "raw IDs → exportable bibliography" pipeline.
+- **Provenance metadata on every response** — formatted output is followed by a metadata block (`requestId`, `formatter`, `styleUsed`, `warnings`) so the assistant can show users *which* engine produced each citation.
+- **REST API twin** — the same RapidAPI key works against the [Scholar Sidekick REST API](https://rapidapi.com/scholar-sidekick-scholar-sidekick-api/api/scholar-sidekick) for non-MCP integrations.
 
 ## Tools
 
 | Tool | Description |
 | --- | --- |
-| **resolveIdentifier** | Resolve DOIs, PMIDs, PMCIDs, ISBNs, arXiv IDs, ISSNs, ADS bibcodes to structured bibliographic metadata |
-| **formatCitation** | Format identifiers into Vancouver, AMA, APA, IEEE, CSE, or 10,000+ CSL styles. Output as text, HTML, or JSON |
-| **exportCitation** | Export to BibTeX, RIS, CSL JSON, EndNote (XML/Refer), RefWorks, MEDLINE, Zotero RDF, CSV, or plain text |
+| **resolveIdentifier** | Resolve DOIs, PMIDs, PMCIDs, ISBNs, arXiv IDs, ISSNs, ADS bibcodes, and WHO IRIS URLs to structured bibliographic metadata (CSL JSON). Accepts a single identifier or a comma/newline-separated batch. |
+| **formatCitation** | Format one or many identifiers into Vancouver, AMA, APA, IEEE, CSE, or any of 10,000+ CSL styles. Output as text, HTML, or JSON. Returns formatted citations plus a provenance metadata block. |
+| **exportCitation** | Export one or many identifiers to BibTeX, RIS, CSL JSON, EndNote (XML/Refer), RefWorks, MEDLINE, Zotero RDF, CSV, or plain text — ready to write to disk or hand to a reference manager. |
 
 ## Setup
 
@@ -94,11 +104,22 @@ Any [CSL style ID](https://github.com/citation-style-language/styles) can be pas
 
 Once connected, ask your AI assistant:
 
+**Single identifier**
+
 - "Format 10.1056/NEJMoa2033700 in Vancouver style"
 - "Resolve PMID:30049270 and export as BibTeX"
-- "Format these as APA: 10.1056/NEJMoa2033700, PMID:30049270, ISBN:9780192854087"
 - "Give me a Chicago citation for arXiv:2301.08745"
 
+**Batch input** (comma- or newline-separated — every tool handles it)
+
+- "Format these as APA: 10.1056/NEJMoa2033700, PMID:30049270, ISBN:9780192854087"
+- "Resolve all of these and tell me which are journal articles vs books: 10.1056/NEJMoa2033700, ISBN:9780192854087, PMC7793608"
+
+**End-to-end workflow** (the assistant chains `resolveIdentifier` → `formatCitation` → `exportCitation` in one prompt)
+
+- "Resolve these three identifiers, format each in AMA, and export the set as BibTeX: 10.1056/NEJMoa2033700, PMID:30049270, ISBN:9780192854087"
+- "Build me a Nature-style bibliography from this list and give me a `.bib` file at the end: PMID:30049270, arXiv:2301.08745, 10.1038/s41586-021-03819-2"
+
 ## Supported Identifiers
 
 - DOIs (e.g. `10.1056/NEJMoa2033700`)
@@ -110,6 +131,17 @@ Once connected, ask your AI assistant:
 - NASA ADS bibcodes
 - WHO IRIS URLs
 
+## Provenance & Determinism
+
+Every `formatCitation` and `exportCitation` response is followed by a metadata block so the assistant — and the user — can see exactly which engine produced each citation:
+
+- `formatter` — `builtin` (one of Vancouver, AMA, APA, IEEE, CSE — hand-tuned in TypeScript) or `csl` (citeproc-js with a CSL stylesheet).
+- `styleUsed` — the canonical style ID after alias and dependent-style resolution (e.g. asking for `harvard` resolves to `harvard-cite-them-right`).
+- `requestId` — for support, reproducibility, and log correlation.
+- `warnings` — populated when a fallback was used or the requested style was a dependent of another.
+
+Identifier resolution is deterministic given the same inputs and pinned upstream metadata. Repeated identical requests are cache-hit on the underlying REST API and surface that via the `x-scholar-cache` header.
+
 ## REST API
 
 For programmatic access outside of MCP clients, Scholar Sidekick is also available as a REST API on [RapidAPI](https://rapidapi.com/scholar-sidekick-scholar-sidekick-api/api/scholar-sidekick). Your same RapidAPI key works for both.

package/dist/mcp-server.mjs

@@ -30087,6 +30087,22 @@ function errorResult(result) {
     isError: true
   };
 }
+var MISSING_KEY_MESSAGE = [
+  "Scholar Sidekick is not configured. Set the RAPIDAPI_KEY environment variable to use this tool.",
+  "",
+  "Get a free key:",
+  "  1. Sign up at https://rapidapi.com/scholar-sidekick-scholar-sidekick-api/api/scholar-sidekick",
+  "  2. Subscribe to the free tier and copy your RapidAPI key",
+  "  3. Restart this MCP server with RAPIDAPI_KEY set",
+  "",
+  "If you installed via Claude Desktop, open the Scholar Sidekick extension settings and paste the key there."
+].join("\n");
+function missingKeyResult() {
+  return {
+    content: [{ type: "text", text: MISSING_KEY_MESSAGE }],
+    isError: true
+  };
+}
 function buildMetadata(result) {
   const meta3 = {};
   if (result.requestId) meta3.requestId = result.requestId;
@@ -30104,10 +30120,11 @@ function registerExportTool(server, config2) {
     "exportCitation",
     {
       title: "Export Citation",
-      description: "Export academic citations to bibliography file formats: BibTeX (.bib), RIS, CSV, CSL-JSON, EndNote XML, EndNote Refer, RefWorks, MEDLINE/NBIB, Zotero RDF, or plain text.",
+      description: "Export academic citations from identifiers (DOIs, PMIDs, PMCIDs, ISBNs, arXiv IDs, ISSNs, ADS bibcodes, WHO IRIS URLs) to bibliography file formats: BibTeX (.bib), RIS, CSV, CSL-JSON, EndNote XML, EndNote Refer, RefWorks, MEDLINE/NBIB, Zotero RDF, or plain text. Accepts a single identifier or a comma/newline-separated batch.",
       inputSchema: ExportCitationInput
     },
     async (input) => {
+      if (!config2.rapidApiKey) return missingKeyResult();
       const result = await exportCitation(config2, {
         text: normalizeIdentifiers(input.text),
         format: input.format,
@@ -30130,10 +30147,11 @@ function registerFormatTool(server, config2) {
     "formatCitation",
     {
       title: "Format Citation",
-      description: "Format academic citations from identifiers (DOIs, PMIDs, ISBNs, arXiv IDs, etc.) into a specific citation style. Returns formatted text, HTML, or structured JSON. Supports Vancouver, AMA, APA, IEEE, CSE, and 10,000+ CSL styles.",
+      description: "Format academic citations from identifiers (DOIs, PMIDs, PMCIDs, ISBNs, arXiv IDs, ISSNs, ADS bibcodes, WHO IRIS URLs) into a specific citation style. Accepts a single identifier or a comma/newline-separated batch. Returns formatted text, HTML, or structured JSON, plus a provenance metadata block (formatter, styleUsed, requestId, warnings). Supports Vancouver, AMA, APA, IEEE, CSE, and 10,000+ CSL styles.",
       inputSchema: FormatCitationInput
     },
     async (input) => {
+      if (!config2.rapidApiKey) return missingKeyResult();
       const result = await formatCitation(config2, {
         text: normalizeIdentifiers(input.text),
         style: input.style ?? void 0,
@@ -30166,10 +30184,11 @@ function registerResolveTool(server, config2) {
     "resolveIdentifier",
     {
       title: "Resolve Identifier",
-      description: "Resolve academic identifiers (DOIs, PMIDs, PMCIDs, ISBNs, arXiv IDs, ISSNs, ADS bibcodes) to structured bibliographic metadata (title, authors, journal, year, identifiers, etc.) without formatting. Returns JSON objects.",
+      description: "Resolve academic identifiers (DOIs, PMIDs, PMCIDs, ISBNs, arXiv IDs, ISSNs, ADS bibcodes, WHO IRIS URLs) to structured bibliographic metadata (title, authors, journal, year, identifiers, etc.) without formatting. Accepts a single identifier or a comma/newline-separated batch. Returns JSON objects.",
       inputSchema: ResolveIdentifierInput
     },
     async (input) => {
+      if (!config2.rapidApiKey) return missingKeyResult();
       const result = await formatCitation(config2, {
         text: normalizeIdentifiers(input.text),
         output: "json"
@@ -30194,13 +30213,34 @@ function registerResolveTool(server, config2) {
 
 // src/server.ts
 var SERVER_NAME = "scholar-sidekick";
-var SERVER_VERSION = "0.3.0";
+var SERVER_VERSION = "0.4.1";
+var SERVER_INSTRUCTIONS = `Scholar Sidekick MCP turns academic identifiers into clean citations.
+
+When to use this server:
+- The user mentions a bibliographic identifier \u2014 DOI, PMID, PMCID, ISBN, arXiv ID, ISSN, ADS bibcode, or WHO IRIS URL
+- The user asks to format references in a citation style (Vancouver, APA, AMA, IEEE, Chicago, Harvard, MLA, Nature, BMJ, Lancet, or any of 10,000+ CSL styles)
+- The user asks to export a bibliography to BibTeX, RIS, EndNote, RefWorks, MEDLINE, Zotero RDF, CSL JSON, or CSV
+
+Tool selection:
+- resolveIdentifier \u2014 when the user wants raw structured metadata (returns CSL JSON: title, authors, journal, year, identifiers)
+- formatCitation \u2014 when the user wants a human-readable citation in a specific style (returns text, HTML, or JSON)
+- exportCitation \u2014 when the user wants a downloadable bibliography file (returns the file contents as a string)
+
+Tips:
+- All tools accept multiple identifiers separated by newlines or commas \u2014 batch when possible to save calls
+- Pass identifiers verbatim. The server tolerates DOI URLs (https://doi.org/...), "PMID:" / "PMC" prefixes, "arXiv:" prefixes, and ISBN hyphens
+- Default style for formatCitation is Vancouver. If the user does not name a style, ask before defaulting`;
 function createMcpServer(config2) {
   const cfg = config2 ?? createConfig();
-  const server = new McpServer({
-    name: SERVER_NAME,
-    version: SERVER_VERSION
-  });
+  const server = new McpServer(
+    {
+      name: SERVER_NAME,
+      version: SERVER_VERSION
+    },
+    {
+      instructions: SERVER_INSTRUCTIONS
+    }
+  );
   registerFormatTool(server, cfg);
   registerExportTool(server, cfg);
   registerResolveTool(server, cfg);
@@ -30230,7 +30270,13 @@ async function checkConnection(baseUrl) {
 }
 async function main() {
   const config2 = createConfig();
-  await checkConnection(config2.baseUrl);
+  if (config2.rapidApiKey) {
+    await checkConnection(config2.baseUrl);
+  } else {
+    process.stderr.write(
+      "Scholar Sidekick MCP started without RAPIDAPI_KEY \u2014 tools will return a configuration message until a key is set. Get one at https://rapidapi.com/scholar-sidekick-scholar-sidekick-api/api/scholar-sidekick\n"
+    );
+  }
   const server = createMcpServer(config2);
   const transport = new StdioServerTransport();
   await server.connect(transport);

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "scholar-sidekick-mcp",
-  "version": "0.3.4",
+  "version": "0.4.1",
   "mcpName": "io.github.mlava/scholar-sidekick-mcp",
-  "description": "MCP server for Scholar Sidekick — resolve, format, and export academic citations from any AI assistant",
+  "description": "MCP server for Scholar Sidekick — resolve any scholarly identifier (DOI, PMID, PMCID, ISBN, arXiv, ISSN, ADS, WHO IRIS) into 10,000+ CSL styles or nine export formats, single or batch.",
   "license": "MIT",
   "author": "Scholar Sidekick",
   "repository": {
@@ -15,13 +15,24 @@
     "model-context-protocol",
     "citations",
     "bibliography",
+    "academic",
+    "scholar",
     "doi",
     "pmid",
+    "pmcid",
+    "isbn",
+    "arxiv",
+    "issn",
+    "ads-bibcode",
+    "who-iris",
     "bibtex",
     "ris",
-    "scholar",
-    "academic",
-    "reference-manager"
+    "csl",
+    "endnote",
+    "zotero",
+    "crossref",
+    "reference-manager",
+    "claude"
   ],
   "type": "module",
   "engines": {