ai4l-library-dev 0.0.0-stage → 0.1.1

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,11 @@
-# Temporary Holding Version
+# ai4l-library-dev
 
-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.
+**Internal development build. Not for public use.**
+
+This package is used for internal testing of the ai4l-library MCP server. It may
+change or break at any time.
+
+The public release lives at:
+
+- npm: [`ai4l-library`](https://www.npmjs.com/package/ai4l-library)
+- GitHub: [forever-healthy/AI4L-library](https://github.com/forever-healthy/AI4L-library)

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,22 @@
 {
   "name": "ai4l-library-dev",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Internal development build of ai4l-library. Not for public use.",
+  "type": "module",
+  "bin": {
+    "ai4l-library-dev": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "fast-xml-parser": "^5.11.2",
+    "zod": "^3.0.0"
+  },
+  "license": "MIT",
+  "private": false
+}