ai4l-library 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# AI4L Library - Change Log
+
+
+### v0.1.1 — 2026-10-26
+
+* `library_add(id)` and `library_status(id)` for `pmid:` IDs: the `pubmed` tier fetches the efetch XML and writes `-abstract.xml`, `-abstract.md` and `-meta.md` under `<type>/<L1>/<L2>/<number>/`; entries are level `abstract` and idempotent
+* Status JSON per call; invalid IDs, unsupported types, unknown PMIDs and fetch failures are returned as `error`, never thrown
+* Library directory: `LIBRARY_DIR`, else `/library` when mounted, else `./library`
+* Unit tests (`npm test`) and an opt-in live PubMed test (`LIVE=1`)
+
+### v0.0.1 — 2026-10-26
+
+* Project skeleton: stdio MCP server with `get_version`; publishing scaffold (dev/public npm, MCP registry, GitHub release)

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Forever Healthy Foundation
+
+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, sub-license, 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

@@ -1,3 +1,49 @@
-# Temporary Holding Version
+![Version](https://img.shields.io/badge/Version-0.1.1-green.svg)
+[![Forever Healthy](https://img.shields.io/badge/(c)_2026-Forever_Healthy-573D7D.svg)](https://forever-healthy.org)
+[![npm](https://img.shields.io/badge/npm-ai4l--library-cb3837.svg)](https://www.npmjs.com/package/ai4l-library)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# AI4L Library MCP Server
+
+A [Model Context Protocol](https://modelcontextprotocol.io) server that builds a local library of the scientific papers an evidence review cites. Given a paper ID (`type:value`, e.g. `pmid:30955454`), it fetches the paper's metadata, abstract and — where obtainable — full text through a configurable cascade of retrieval services (PubMed, PMC, Europe PMC, Unpaywall, OpenAlex, …), converts everything to Markdown, and stores it under a mounted `library/` directory. Nothing flows through the model's context: the server writes to disk itself and returns only a small status per call.
+
+**Status: v0.1, early development.** `library_add` and `library_status` work for `pmid:` IDs through the PubMed tier only, so every entry is level `abstract`. The full-text cascade and `library_read` are next.
+
+
+## Tools
+
+* `library_add(id, url?)` → build or complete the library entry for one ID; returns its status (level `full_text` / `abstract`, retrieving tier, retraction flag, files). Idempotent. One ID per call.
+* `library_status(id)` → read-only check of presence and level
+* `library_read(id, section | query)` → one passage of a stored paper's Markdown — the deliberate, small flow through context for claim verification (planned)
+
+IDs follow the `type:value` form (`pmid:`, `pmc:`, `doi:`, `nct:`); bare digits count as `pmid:`. v0.1 supports `pmid:` only.
+* `get_version()` → the running server's package name, version and library directory
+
+
+## Install
+
+The server is published to npm as **[`ai4l-library`](https://www.npmjs.com/package/ai4l-library)** and runs over stdio via `npx` — no global install needed (requires Node.js ≥ 18):
+
+```
+npx -y ai4l-library
+```
+
+Client config (`.mcp.json` for Claude Code, `claude_desktop_config.json` for Claude Desktop, or your client's MCP settings):
+
+```json
+{
+  "mcpServers": {
+    "d-library": {
+      "command": "npx",
+      "args": ["-y", "ai4l-library"]
+    }
+  }
+}
+```
+
+Planned: a Docker image with the converters and a headless browser built in, the library mounted as a volume —
+`docker run --rm -i --env-file .env -v "$PWD/library:/library" ghcr.io/forever-healthy/ai4l-library`
+
+
+## License
+
+MIT — © 2026 Forever Healthy Foundation

package/dist/index.js

@@ -0,0 +1,334 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// src/tools.ts
+import { readFileSync as readFileSync2 } from "fs";
+import { z } from "zod";
+
+// src/entry.ts
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { basename } from "path";
+function emptyStatus(requested, type, id, libraryDir) {
+  return {
+    requested,
+    type,
+    id,
+    entry: null,
+    entry_dir: null,
+    library_dir: libraryDir,
+    pmid: null,
+    pmcid: null,
+    doi: null,
+    title: null,
+    first_author: null,
+    year: null,
+    publication_types: [],
+    retracted: false,
+    level: null,
+    version: null,
+    retrieved_by: null,
+    retrieved_date: null,
+    attempts: [],
+    files: []
+  };
+}
+function renderAbstractMd(r) {
+  const line = [
+    r.authors.join(", ") || null,
+    r.journal,
+    r.year,
+    `PMID ${r.pmid}`,
+    r.doi ? `DOI ${r.doi}` : null,
+    r.pmcid ? `PMCID ${r.pmcid}` : null
+  ].filter(Boolean).join(" \xB7 ");
+  const body = r.abstract.length ? r.abstract.map((a) => a.label ? `**${a.label}.** ${a.text}` : a.text).join("\n\n") : "_No abstract available._";
+  return `# ${r.title}
+
+${line}
+
+## Abstract
+
+${body}
+`;
+}
+function renderMeta(r, files, retrievedDate, converter) {
+  const lines = [
+    ["pmid", r.pmid],
+    ["pmcid", r.pmcid ?? ""],
+    ["doi", r.doi ?? ""],
+    ["title", JSON.stringify(r.title)],
+    ["first_author", r.firstAuthor ?? ""],
+    ["year", r.year ?? ""],
+    ["publication_types", r.publicationTypes.join(", ")],
+    ["retracted", r.publicationTypes.includes("Retracted Publication") ? "yes" : "no"],
+    ["level", "abstract"],
+    ["version", ""],
+    ["files", files.join(", ")],
+    ["retrieved_by", "pubmed"],
+    ["retrieved_date", retrievedDate],
+    ["converted_by", converter],
+    ["attempts", ""]
+  ];
+  return "---\n" + lines.map(([k, v]) => v === "" ? `${k}:` : `${k}: ${v}`).join("\n") + "\n---\n";
+}
+function entryExists(p) {
+  return existsSync(p.meta);
+}
+function writeEntry(p, r, xml, converter) {
+  mkdirSync(p.entryDir, { recursive: true });
+  const files = [basename(p.xml), basename(p.md)];
+  const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+  writeFileSync(p.xml, xml);
+  writeFileSync(p.md, renderAbstractMd(r));
+  writeFileSync(p.meta, renderMeta(r, files, today, converter));
+}
+function parseFrontmatter(md) {
+  const m = /^---\n([\s\S]*?)\n---/.exec(md);
+  const out = {};
+  for (const line of (m?.[1] ?? "").split("\n")) {
+    const i = line.indexOf(":");
+    if (i > 0) out[line.slice(0, i).trim()] = line.slice(i + 1).trim();
+  }
+  return out;
+}
+var list = (v) => v ? v.split(",").map((s) => s.trim()).filter(Boolean) : [];
+var opt = (v) => v ? v : null;
+function readStatus(p, base) {
+  const fm = parseFrontmatter(readFileSync(p.meta, "utf8"));
+  let title = opt(fm.title);
+  if (title?.startsWith('"')) {
+    try {
+      title = JSON.parse(title);
+    } catch {
+    }
+  }
+  return {
+    ...base,
+    entry: p.entry,
+    entry_dir: p.entryDir,
+    pmid: opt(fm.pmid),
+    pmcid: opt(fm.pmcid),
+    doi: opt(fm.doi),
+    title,
+    first_author: opt(fm.first_author),
+    year: opt(fm.year),
+    publication_types: list(fm.publication_types),
+    retracted: fm.retracted === "yes",
+    level: opt(fm.level) ?? null,
+    version: opt(fm.version),
+    retrieved_by: opt(fm.retrieved_by),
+    retrieved_date: opt(fm.retrieved_date),
+    attempts: list(fm.attempts),
+    files: list(fm.files)
+  };
+}
+
+// src/ids.ts
+var SUPPORTED = /* @__PURE__ */ new Set(["pmid"]);
+var KNOWN = /* @__PURE__ */ new Set(["pmid", "pmc", "doi", "nct"]);
+function parseId(raw) {
+  const requested = String(raw ?? "").trim();
+  const bare = /^\d+$/.test(requested);
+  const m = bare ? null : /^([A-Za-z][A-Za-z0-9_-]*):(.+)$/.exec(requested);
+  if (!bare && !m) return { requested, type: null, id: null, error: "invalid id" };
+  const type = bare ? "pmid" : m[1].toLowerCase();
+  const value = bare ? requested : m[2].trim();
+  if (!KNOWN.has(type)) return { requested, type, id: value, error: "invalid id" };
+  if (!SUPPORTED.has(type)) return { requested, type, id: value, error: "type not supported yet" };
+  if (!/^[1-9]\d*$/.test(value)) return { requested, type, id: value, error: "invalid id" };
+  return { requested, type, id: value };
+}
+
+// src/layout.ts
+import { existsSync as existsSync2 } from "fs";
+import { join, resolve } from "path";
+var LIBRARY_DIR = (() => {
+  const env = process.env.LIBRARY_DIR;
+  if (env && env.trim()) return resolve(env.trim());
+  if (existsSync2("/library")) return "/library";
+  return resolve("library");
+})();
+function entryDirRel(type, num) {
+  const l1 = num.length > 6 ? num.slice(0, -6) : "0";
+  const l2 = num.length > 4 ? num.slice(0, -4) : "0";
+  return `${type}/${l1}/${l2}/${num}`;
+}
+function entryPaths(libraryDir, type, num) {
+  const entry = `${type}-${num}`;
+  const entryDir = join(libraryDir, entryDirRel(type, num));
+  return {
+    entry,
+    entryDir,
+    xml: join(entryDir, `${entry}-abstract.xml`),
+    md: join(entryDir, `${entry}-abstract.md`),
+    meta: join(entryDir, `${entry}-meta.md`)
+  };
+}
+
+// src/pubmed.ts
+import { XMLParser } from "fast-xml-parser";
+var EFETCH = "https://eutils.ncbi.nlm.nih.gov/entrez/eutils/efetch.fcgi";
+var TIMEOUT_MS = 3e4;
+function efetchUrl(pmid) {
+  const u = new URL(EFETCH);
+  u.searchParams.set("db", "pubmed");
+  u.searchParams.set("id", pmid);
+  u.searchParams.set("retmode", "xml");
+  if (process.env.NCBI_API_KEY) u.searchParams.set("api_key", process.env.NCBI_API_KEY);
+  if (process.env.CONTACT_EMAIL) {
+    u.searchParams.set("tool", "ai4l-library");
+    u.searchParams.set("email", process.env.CONTACT_EMAIL);
+  }
+  return u.toString();
+}
+async function fetchPubmedXml(pmid) {
+  const url = efetchUrl(pmid);
+  let last;
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      const res = await fetch(url, { signal: AbortSignal.timeout(TIMEOUT_MS) });
+      if (res.ok) return await res.text();
+      last = new Error(`HTTP ${res.status}`);
+      if (res.status !== 429 && res.status < 500) break;
+    } catch (e) {
+      last = e;
+    }
+  }
+  const msg = last instanceof Error ? last.message : String(last);
+  throw new Error(`pubmed fetch failed: ${msg}`);
+}
+var parser = new XMLParser({
+  ignoreAttributes: false,
+  attributeNamePrefix: "@_",
+  parseTagValue: false,
+  processEntities: true,
+  stopNodes: ["*.ArticleTitle", "*.AbstractText"],
+  isArray: (name) => ["PubmedArticle", "AbstractText", "Author", "ArticleId", "PublicationType"].includes(name)
+});
+function text(n) {
+  if (n == null) return "";
+  if (typeof n === "object") return text(n["#text"]);
+  return String(n);
+}
+function inlineText(raw) {
+  return decodeEntities(raw.replace(/<[^>]+>/g, "")).replace(/\s+/g, " ").trim();
+}
+function decodeEntities(s) {
+  return s.replace(/&#x([0-9a-f]+);/gi, (_, h) => String.fromCodePoint(parseInt(h, 16))).replace(/&#(\d+);/g, (_, d) => String.fromCodePoint(parseInt(d, 10))).replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&apos;/g, "'").replace(/&amp;/g, "&");
+}
+function parsePubmedXml(xml) {
+  const doc = parser.parse(xml);
+  const article = doc?.PubmedArticleSet?.PubmedArticle?.[0];
+  if (!article) return null;
+  const cit = article.MedlineCitation ?? {};
+  const art = cit.Article ?? {};
+  const ids = article.PubmedData?.ArticleIdList?.ArticleId ?? [];
+  const idOf = (t) => {
+    const hit = ids.find((i) => i["@_IdType"] === t);
+    return hit ? text(hit).trim() || null : null;
+  };
+  const authorList = art.AuthorList?.Author ?? [];
+  const authors = authorList.map((a) => {
+    if (a.CollectiveName) return text(a.CollectiveName).trim();
+    const last = text(a.LastName).trim();
+    const ini = text(a.Initials).trim();
+    return [last, ini].filter(Boolean).join(" ");
+  }).filter(Boolean);
+  const first = authorList[0];
+  const firstAuthor = first ? text(first.CollectiveName ?? first.LastName).trim() || null : null;
+  const pub = art.Journal?.JournalIssue?.PubDate ?? {};
+  let year = text(pub.Year).trim() || null;
+  if (!year) year = /\d{4}/.exec(text(pub.MedlineDate))?.[0] ?? null;
+  const abstract = (art.Abstract?.AbstractText ?? []).map((a) => ({
+    label: typeof a === "object" ? a["@_Label"] ?? null : null,
+    text: inlineText(text(a))
+  })).filter((a) => a.text);
+  return {
+    pmid: text(cit.PMID).trim() || idOf("pubmed") || "",
+    pmcid: idOf("pmc"),
+    doi: idOf("doi"),
+    title: inlineText(text(art.ArticleTitle)),
+    authors,
+    firstAuthor,
+    journal: text(art.Journal?.Title).trim() || null,
+    year,
+    publicationTypes: (art.PublicationTypeList?.PublicationType ?? []).map((p) => text(p).trim()).filter(Boolean),
+    abstract
+  };
+}
+
+// src/tools.ts
+var pkg = (() => {
+  try {
+    return JSON.parse(readFileSync2(new URL("../package.json", import.meta.url), "utf8"));
+  } catch {
+    return { name: "ai4l-library", version: "0.0.0" };
+  }
+})();
+var INSTRUCTIONS = `ai4l-library builds a local library of the scientific papers cited by evidence reviews. Given a paper ID ("type:value", e.g. pmid:30955454; bare digits count as pmid) it fetches the paper's record and stores it as files under the library directory. Nothing flows through your context: the server writes to disk itself and returns only a small JSON status per call. One ID per call \u2014 no batches.
+
+Tools:
+- library_add(id, url?) \u2014 build the entry for one ID and return its status. Idempotent: an existing entry is returned without any network call.
+- library_status(id) \u2014 read-only: the entry's status, or level "missing".
+- get_version() \u2014 package name, version and the resolved library directory.
+
+Status JSON fields: requested, type, id, entry, entry_dir, library_dir, pmid, pmcid, doi, title, first_author, year, publication_types, retracted, level, version, retrieved_by, retrieved_date, attempts, files, and error when the call could not produce an entry ("invalid id", "type not supported yet", "pmid not found", or a fetch failure).
+
+v0.1: pmid: IDs only (other types return error "type not supported yet"); the pubmed tier only, so every entry is level "abstract" (efetch XML, abstract Markdown, meta); url is accepted but ignored.`;
+var idSchema = z.string().describe('Paper ID as "type:value", e.g. "pmid:30955454"; bare digits count as pmid.');
+var json = (s) => ({ content: [{ type: "text", text: JSON.stringify(s, null, 2) }] });
+function registerTools(server2) {
+  server2.tool(
+    "library_add",
+    "Build the library entry for one paper ID and return its status JSON. v0.1: pmid: only, pubmed tier only (level abstract). Idempotent \u2014 an existing entry is returned without refetching.",
+    { id: idSchema, url: z.string().optional().describe("A download location obtained elsewhere (ignored in v0.1).") },
+    async ({ id }) => {
+      const parsed = parseId(id);
+      const status = emptyStatus(parsed.requested, parsed.type, parsed.id, LIBRARY_DIR);
+      if (parsed.error) return json({ ...status, error: parsed.error });
+      const paths = entryPaths(LIBRARY_DIR, parsed.type, parsed.id);
+      if (entryExists(paths)) return json(readStatus(paths, status));
+      let xml;
+      try {
+        xml = await fetchPubmedXml(parsed.id);
+      } catch (e) {
+        return json({ ...status, error: e instanceof Error ? e.message : String(e) });
+      }
+      const record = parsePubmedXml(xml);
+      if (!record) return json({ ...status, error: "pmid not found" });
+      writeEntry(paths, record, xml, `${pkg.name} ${pkg.version}`);
+      return json(readStatus(paths, status));
+    }
+  );
+  server2.tool(
+    "library_status",
+    'Read-only status of the library entry for one paper ID: the same status JSON as library_add, or level "missing" when there is no entry. Never fetches.',
+    { id: idSchema },
+    async ({ id }) => {
+      const parsed = parseId(id);
+      const status = emptyStatus(parsed.requested, parsed.type, parsed.id, LIBRARY_DIR);
+      if (parsed.error) return json({ ...status, error: parsed.error });
+      const paths = entryPaths(LIBRARY_DIR, parsed.type, parsed.id);
+      if (entryExists(paths)) return json(readStatus(paths, status));
+      return json({ ...status, entry: paths.entry, entry_dir: paths.entryDir, level: "missing" });
+    }
+  );
+  server2.tool(
+    "get_version",
+    "Get the running ai4l-library MCP server's package name and version, and the resolved library directory. Useful to confirm which build is loaded.",
+    {},
+    async () => ({ content: [{ type: "text", text: `${pkg.name} v${pkg.version} \xB7 library_dir: ${LIBRARY_DIR}` }] })
+  );
+}
+
+// src/index.ts
+var server = new McpServer(
+  { name: pkg.name, version: pkg.version },
+  { instructions: INSTRUCTIONS }
+);
+registerTools(server);
+var transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "ai4l-library",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "mcpName": "io.github.forever-healthy/ai4l-library",
+  "description": "MCP Server that builds a local Markdown library of the scientific papers cited by evidence reviews — fetches metadata, abstract and full text per PubMed ID through a configurable cascade of retrieval services",
+  "type": "module",
+  "bin": {
+    "ai4l-library": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "fast-xml-parser": "^5.11.2",
+    "zod": "^3.0.0"
+  },
+  "keywords": [
+    "mcp",
+    "ai4l",
+    "pubmed",
+    "papers",
+    "library",
+    "evidence-review"
+  ],
+  "author": "Forever Healthy Foundation",
+  "license": "MIT",
+  "homepage": "https://github.com/forever-healthy/AI4L-library",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/forever-healthy/AI4L-library.git"
+  },
+  "private": false
+}