bibtex-reference-manager-mcp 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.1.0
+
+- First release of BibTeX Reference Manager MCP.
+- Added `parse_bibliography`, which reads BibTeX, RIS or CSL JSON and returns normalized entries.
+- Added `convert_bibliography`, which converts between BibTeX, RIS, CSL JSON and plain text.
+- Added `dedupe_entries`, which finds duplicates by DOI, cite key and title similarity.
+- Added `lint_entries`, which flags missing fields, bad page ranges, uncapitalized titles and invalid DOIs.
+- Added `generate_cite_keys`, which makes keys like smith2024deep.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AnonymousOnyx22
+
+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

@@ -1,3 +1,141 @@
-# Temporary Holding Version
+# BibTeX Reference Manager MCP
 
-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.
+[![npm](https://img.shields.io/npm/v/bibtex-reference-manager-mcp.svg)](https://www.npmjs.com/package/bibtex-reference-manager-mcp)
+[![downloads](https://img.shields.io/npm/dm/bibtex-reference-manager-mcp.svg)](https://www.npmjs.com/package/bibtex-reference-manager-mcp)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+BibTeX Reference Manager MCP is a free, open source [MCP](https://modelcontextprotocol.io) server, published on npm as `bibtex-reference-manager-mcp`. It cleans, converts, dedupes and formats BibTeX, RIS and CSL JSON reference lists, so you stop fixing broken `.bib` files by hand. Paste a list into your AI app and ask it to read the entries, convert them to another format, find the duplicates, flag the problems or give every entry a tidy cite key.
+
+Use it with Claude Desktop, Claude Code, Cursor, VS Code Copilot and any other app that supports MCP. It runs on your computer, needs no internet and no login, and your references never leave your machine.
+
+Free forever. No account and no subscription.
+
+## Install
+
+Run it straight from npm with `npx`. You need Node.js 20 or newer, see [Node version](#node-version) for the details. There is nothing else to install, no account, no API key and no config file for the server itself.
+
+```bash
+npx -y bibtex-reference-manager-mcp
+```
+
+Add it to your AI app's MCP config so the app can start it for you:
+
+- [Claude Desktop](#claude-desktop)
+- [Claude Code](#claude-code)
+- [Cursor](#cursor)
+- [VS Code Copilot](#vs-code-copilot)
+
+All of them start the same server the same way. The only difference is where the config goes.
+
+### Claude Desktop
+
+Add this to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "bibtex": {
+      "command": "npx",
+      "args": ["-y", "bibtex-reference-manager-mcp"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop after you save the file.
+
+### Claude Code
+
+Run this in a terminal:
+
+```bash
+claude mcp add bibtex -- npx -y bibtex-reference-manager-mcp
+```
+
+### Cursor
+
+Cursor reads `.cursor/mcp.json` from the project folder, or `~/.cursor/mcp.json` in your home folder if you want the server in every project.
+
+```json
+{
+  "mcpServers": {
+    "bibtex": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "bibtex-reference-manager-mcp"]
+    }
+  }
+}
+```
+
+### VS Code Copilot
+
+Add this to `.vscode/mcp.json` in your workspace:
+
+```json
+{
+  "servers": {
+    "bibtex": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "bibtex-reference-manager-mcp"]
+    }
+  }
+}
+```
+
+## Try these prompts
+
+Paste your reference list into the chat first, or attach the file, then ask:
+
+1. "Here is my references.bib. Lint it and tell me what is broken, entry by entry."
+2. "Find the duplicates in this list and give me back a clean BibTeX file without them."
+3. "Convert these RIS entries from my library export to BibTeX, then rename the keys so they look like smith2024deep."
+
+## Tools
+
+| Tool | What it does |
+| --- | --- |
+| `parse_bibliography` | Reads BibTeX, RIS or CSL JSON text and returns normalized entries: lower case field names, tidy spacing, bare DOIs, the year filled in from a date, and authors split into "Family, Given". |
+| `convert_bibliography` | Converts between BibTeX, RIS, CSL JSON and plain text. The input format is detected unless you pass `from`. Page ranges become `12--15` in BibTeX. |
+| `dedupe_entries` | Finds duplicates by DOI, by the same cite key and by similar titles (the years must not clash). Says which entry to keep and returns a BibTeX list without the extra copies. |
+| `lint_entries` | Flags missing required fields, bad page ranges, uncapitalized titles, invalid DOIs, odd years and repeated keys. |
+| `generate_cite_keys` | Makes keys from the first author, the year and the first useful title word, like `smith2024deep`. Repeats get a letter, like `smith2024deepa`. |
+
+Every tool takes the reference list as `text`, and every tool returns both a readable answer and structured fields. All of them are read only. They never change a file, because you paste the text in and get the result back.
+
+### Formats
+
+- BibTeX: `@string` macros, quoted and braced values, `#` joins, and `@comment` blocks are handled.
+- RIS: the usual tags such as `TY`, `AU`, `TI`, `T2`, `PY`, `SP`, `EP`, `DO` and `KW`.
+- CSL JSON: a list of items, one item, or an object with an `items` list.
+
+## Privacy
+
+Everything runs on your computer. The server reads only the text your AI app passes to it. It makes no network requests, does not look up DOIs online, needs no API key and keeps nothing between calls. DOI checks only look at the shape of the DOI, they do not ask a website whether it exists.
+
+## FAQ
+
+**Does it check that a DOI really exists?** No. It runs offline, so it only checks that the DOI has the right shape, like `10.1000/xyz123`.
+
+**How does it decide two titles are the same?** It lowercases the titles, drops punctuation and accents, and compares pairs of letters. The default match is 0.9 out of 1. Pass `title_threshold` to loosen or tighten that. Two entries with different years are not matched by title.
+
+**Will it change my protected capitals like `{DNA}`?** No. Braces are kept in BibTeX output and only removed when you convert to RIS, CSL JSON or plain text.
+
+## Node version
+
+You need Node.js 20 or newer to run the server. To work on it, use Node.js 22.12 or newer.
+
+## Development
+
+```bash
+npm install
+npm run build
+npm test
+```
+
+The code is in `src`. `src/bib.ts` reads and writes the formats, `src/analyze.ts` finds duplicates and lint problems, and `src/tools.ts` defines the five tools.
+
+## License
+
+MIT, see [LICENSE](LICENSE).

package/build/src/analyze.js

@@ -0,0 +1,169 @@
+import { ascii, cleanDoi, plain } from "./bib.js";
+/* ---------- duplicates ---------- */
+export function normalizeTitle(t) {
+    return ascii(plain(t))
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, " ")
+        .trim();
+}
+function bigrams(s) {
+    const m = new Map();
+    const t = s.replace(/ /g, "");
+    for (let i = 0; i < t.length - 1; i++) {
+        const g = t.slice(i, i + 2);
+        m.set(g, (m.get(g) ?? 0) + 1);
+    }
+    return m;
+}
+/** Dice coefficient on character pairs, from 0 to 1. */
+export function titleSimilarity(a, b) {
+    const x = normalizeTitle(a);
+    const y = normalizeTitle(b);
+    if (!x || !y)
+        return 0;
+    if (x === y)
+        return 1;
+    const bx = bigrams(x);
+    const by = bigrams(y);
+    let overlap = 0;
+    let total = 0;
+    for (const v of bx.values())
+        total += v;
+    for (const v of by.values())
+        total += v;
+    for (const [g, c] of bx)
+        overlap += Math.min(c, by.get(g) ?? 0);
+    return total ? (2 * overlap) / total : 0;
+}
+export function findDuplicates(entries, threshold) {
+    const n = entries.length;
+    const parent = entries.map((_, i) => i);
+    const find = (i) => (parent[i] === i ? i : (parent[i] = find(parent[i])));
+    const reasons = new Map();
+    const link = (a, b, why) => {
+        const ra = find(a);
+        const rb = find(b);
+        if (ra !== rb)
+            parent[rb] = ra;
+        // Record the reason against both members, the root is settled afterwards.
+        for (const i of [a, b]) {
+            if (!reasons.has(i))
+                reasons.set(i, new Set());
+            reasons.get(i).add(why);
+        }
+    };
+    for (let i = 0; i < n; i++) {
+        for (let j = i + 1; j < n; j++) {
+            const a = entries[i];
+            const b = entries[j];
+            const da = a.fields.doi ? cleanDoi(a.fields.doi).toLowerCase() : "";
+            const db = b.fields.doi ? cleanDoi(b.fields.doi).toLowerCase() : "";
+            if (da && da === db)
+                link(i, j, "doi");
+            if (a.key && a.key.toLowerCase() === b.key.toLowerCase())
+                link(i, j, "key");
+            const ya = a.fields.year;
+            const yb = b.fields.year;
+            const yearsClash = ya && yb && ya !== yb;
+            if (!yearsClash && a.fields.title && b.fields.title && titleSimilarity(a.fields.title, b.fields.title) >= threshold)
+                link(i, j, "title");
+        }
+    }
+    const groups = new Map();
+    for (let i = 0; i < n; i++) {
+        const r = find(i);
+        groups.set(r, [...(groups.get(r) ?? []), i]);
+    }
+    const out = [];
+    for (const members of groups.values()) {
+        if (members.length < 2)
+            continue;
+        const why = new Set();
+        for (const i of members)
+            for (const r of reasons.get(i) ?? [])
+                why.add(r);
+        // Keep the entry with the most fields, the earliest one on a tie.
+        const best = members.reduce((p, c) => (Object.keys(entries[c].fields).length > Object.keys(entries[p].fields).length ? c : p), members[0]);
+        out.push({
+            indexes: members,
+            keys: members.map((i) => entries[i].key),
+            reasons: ["doi", "key", "title"].filter((r) => why.has(r)),
+            keepIndex: best,
+            keep: entries[best].key,
+            remove: members.filter((i) => i !== best).map((i) => entries[i].key),
+        });
+    }
+    return out.sort((a, b) => a.indexes[0] - b.indexes[0]);
+}
+const REQUIRED = {
+    article: [["author"], ["title"], ["journal"], ["year"]],
+    book: [["author", "editor"], ["title"], ["publisher"], ["year"]],
+    inproceedings: [["author"], ["title"], ["booktitle"], ["year"]],
+    incollection: [["author"], ["title"], ["booktitle"], ["publisher"], ["year"]],
+    phdthesis: [["author"], ["title"], ["school"], ["year"]],
+    mastersthesis: [["author"], ["title"], ["school"], ["year"]],
+    techreport: [["author"], ["title"], ["institution"], ["year"]],
+    unpublished: [["author"], ["title"], ["note"]],
+    misc: [["title"]],
+    online: [["title"], ["url"]],
+};
+const SMALL_WORDS = new Set(["a", "an", "the", "and", "or", "of", "in", "on", "for", "to", "with", "at", "by", "from", "as", "but", "nor", "vs"]);
+export function pageProblem(pages) {
+    const p = pages.trim();
+    if (/^[A-Za-z]?\d+$/.test(p))
+        return null;
+    if (/^\d+--\d+$/.test(p)) {
+        const [a, b] = p.split("--").map(Number);
+        return b < a ? `the range ${p} ends before it starts` : null;
+    }
+    if (/^\d+\s*[-–—]\s*\d+$/.test(p)) {
+        const [a, b] = p.split(/[-–—]/).map(Number);
+        return b < a ? `the range ${p} ends before it starts` : "use a double hyphen between the pages, like 12--15";
+    }
+    if (/^\d+\s*[-–—]+\s*\d+\s*[-–—]+\s*\d+$/.test(p))
+        return "the range has more than two page numbers";
+    return `"${p}" is not a page number or a range like 12--15`;
+}
+export function lintEntries(entries) {
+    const issues = [];
+    const seen = new Map();
+    for (const e of entries) {
+        const k = e.key.toLowerCase();
+        seen.set(k, (seen.get(k) ?? 0) + 1);
+    }
+    const reportedKeys = new Set();
+    for (const e of entries) {
+        const f = e.fields;
+        const add = (rule, severity, message, field) => issues.push({ key: e.key, rule, severity, message, ...(field ? { field } : {}) });
+        if ((seen.get(e.key.toLowerCase()) ?? 0) > 1 && !reportedKeys.has(e.key.toLowerCase())) {
+            reportedKeys.add(e.key.toLowerCase());
+            add("duplicate-key", "error", `The key ${e.key} is used ${seen.get(e.key.toLowerCase())} times.`);
+        }
+        for (const group of REQUIRED[e.type] ?? [["title"]]) {
+            if (!group.some((g) => f[g])) {
+                add("missing-field", e.type === "misc" || e.type === "online" ? "warning" : "error", `A ${e.type} needs ${group.join(" or ")}, and it is missing.`, group[0]);
+            }
+        }
+        if (f.pages) {
+            const problem = pageProblem(f.pages);
+            if (problem)
+                add("bad-pages", "warning", `Pages: ${problem}.`, "pages");
+        }
+        if (f.title) {
+            const words = plain(f.title).split(" ").filter(Boolean);
+            const raw = f.title.trim();
+            if (/^[a-z]/.test(raw)) {
+                add("uncapitalized-title", "warning", `The title starts with a lower case letter: "${plain(f.title)}".`, "title");
+            }
+            else if (words.length > 3 && words.filter((w) => !SMALL_WORDS.has(w.toLowerCase())).every((w) => w === w.toLowerCase())) {
+                add("uncapitalized-title", "warning", `Every word of the title is lower case: "${plain(f.title)}".`, "title");
+            }
+        }
+        if (f.doi && !/^10\.\d{4,9}\/\S+$/.test(cleanDoi(f.doi))) {
+            add("invalid-doi", "error", `"${f.doi}" is not a valid DOI. A DOI looks like 10.1000/xyz123.`, "doi");
+        }
+        if (f.year && !/^\d{4}$/.test(f.year))
+            add("bad-year", "warning", `The year "${f.year}" is not a four digit year.`, "year");
+    }
+    return issues;
+}

package/build/src/bib.js

@@ -0,0 +1,578 @@
+const MONTHS = {
+    jan: "January", feb: "February", mar: "March", apr: "April", may: "May", jun: "June",
+    jul: "July", aug: "August", sep: "September", oct: "October", nov: "November", dec: "December",
+};
+const STOP_WORDS = new Set([
+    "a", "an", "the", "on", "of", "in", "and", "for", "to", "with", "at", "by", "from", "is", "are", "as", "or", "into", "towards", "toward",
+]);
+const FIELD_ORDER = [
+    "author", "editor", "title", "journal", "booktitle", "year", "month", "volume", "number", "pages",
+    "publisher", "address", "school", "institution", "edition", "series", "issn", "isbn", "doi", "url", "abstract", "keywords", "note",
+];
+/* ---------- small helpers ---------- */
+export function squash(s) {
+    return s.replace(/\s+/g, " ").trim();
+}
+/** Remove BibTeX braces and a few common escapes so the text reads normally. */
+export function plain(s) {
+    return squash(s
+        .replace(/\\([&%$#_])/g, "$1")
+        .replace(/---/g, "—")
+        .replace(/[{}]/g, ""));
+}
+export function cleanDoi(raw) {
+    return squash(raw)
+        .replace(/^(https?:\/\/)?(dx\.)?doi\.org\//i, "")
+        .replace(/^doi:\s*/i, "")
+        .trim();
+}
+export function ascii(s) {
+    return s.normalize("NFD").replace(/[̀-ͯ]/g, "");
+}
+/* ---------- names ---------- */
+function splitTopLevel(s, sep) {
+    // Split on a separator but never inside braces.
+    const parts = [];
+    let depth = 0;
+    let cur = "";
+    for (let i = 0; i < s.length; i++) {
+        const ch = s[i];
+        if (ch === "{")
+            depth++;
+        else if (ch === "}")
+            depth = Math.max(0, depth - 1);
+        if (depth === 0) {
+            const m = s.slice(i).match(sep);
+            if (m && m.index === 0) {
+                parts.push(cur);
+                cur = "";
+                i += m[0].length - 1;
+                continue;
+            }
+        }
+        cur += ch;
+    }
+    parts.push(cur);
+    return parts.map(squash).filter(Boolean);
+}
+export function parseNames(raw) {
+    if (!raw)
+        return [];
+    return splitTopLevel(raw, /^\s+and\s+/i).map((n) => {
+        if (/^\{[^{}]*\}$/.test(n))
+            return { family: n.slice(1, -1), given: "", literal: true };
+        const comma = splitTopLevel(n, /^,/);
+        if (comma.length >= 2)
+            return { family: comma[0], given: comma.slice(1).join(" ") };
+        const words = n.split(" ");
+        if (words.length === 1)
+            return { family: words[0], given: "" };
+        // Lower case particles like "van" or "de" belong to the family name.
+        let i = words.length - 1;
+        while (i > 1 && /^[a-z]/.test(words[i - 1]))
+            i--;
+        return { family: words.slice(i).join(" "), given: words.slice(0, i).join(" ") };
+    });
+}
+export function formatNames(names) {
+    return names.map((n) => (n.literal ? `{${n.family}}` : n.given ? `${n.family}, ${n.given}` : n.family)).join(" and ");
+}
+/* ---------- format detection ---------- */
+export function detectFormat(text) {
+    const t = text.trim();
+    if (/^[\[{]/.test(t))
+        return "csl_json";
+    if (/^TY {2}- /m.test(t))
+        return "ris";
+    if (/@\s*\w+\s*[{(]/.test(t))
+        return "bibtex";
+    throw new Error("Could not tell the format. Pass format as bibtex, ris or csl_json.");
+}
+/* ---------- entry normalizing ---------- */
+const TYPE_ALIASES = {
+    conference: "inproceedings",
+    electronic: "online",
+    www: "online",
+    report: "techreport",
+    thesis: "phdthesis",
+};
+function normalizeEntry(e) {
+    const fields = {};
+    for (const [k, v] of Object.entries(e.fields)) {
+        const val = squash(v);
+        if (val)
+            fields[k.toLowerCase()] = val;
+    }
+    if (fields.doi)
+        fields.doi = cleanDoi(fields.doi);
+    if (!fields.year && fields.date) {
+        const y = fields.date.match(/\b(\d{4})\b/);
+        if (y)
+            fields.year = y[1];
+    }
+    if (!fields.journal && fields.journaltitle)
+        fields.journal = fields.journaltitle;
+    delete fields.journaltitle;
+    if (fields.month && MONTHS[fields.month.toLowerCase()])
+        fields.month = MONTHS[fields.month.toLowerCase()];
+    const type = e.type.toLowerCase();
+    return { type: TYPE_ALIASES[type] ?? type, key: e.key.trim(), fields };
+}
+/* ---------- BibTeX ---------- */
+export function parseBibtex(text) {
+    const entries = [];
+    const macros = {};
+    let i = 0;
+    const n = text.length;
+    const skipWs = () => {
+        while (i < n && /\s/.test(text[i]))
+            i++;
+    };
+    const readBraced = () => {
+        let depth = 0;
+        const start = i + 1;
+        for (; i < n; i++) {
+            if (text[i] === "{")
+                depth++;
+            else if (text[i] === "}" && --depth === 0) {
+                const out = text.slice(start, i);
+                i++;
+                return out;
+            }
+        }
+        return text.slice(start);
+    };
+    const readQuoted = () => {
+        let depth = 0;
+        const start = i + 1;
+        for (i = i + 1; i < n; i++) {
+            if (text[i] === "{")
+                depth++;
+            else if (text[i] === "}")
+                depth--;
+            else if (text[i] === '"' && depth <= 0 && text[i - 1] !== "\\") {
+                const out = text.slice(start, i);
+                i++;
+                return out;
+            }
+        }
+        return text.slice(start);
+    };
+    const readValue = () => {
+        let out = "";
+        for (;;) {
+            skipWs();
+            if (text[i] === "{")
+                out += readBraced();
+            else if (text[i] === '"')
+                out += readQuoted();
+            else {
+                const m = text.slice(i).match(/^[^\s,#={}()"]+/);
+                if (!m)
+                    break;
+                i += m[0].length;
+                const lower = m[0].toLowerCase();
+                out += macros[lower] ?? (MONTHS[lower] ? lower : m[0]);
+            }
+            skipWs();
+            if (text[i] === "#")
+                i++;
+            else
+                break;
+        }
+        return out;
+    };
+    while (i < n) {
+        const at = text.indexOf("@", i);
+        if (at < 0)
+            break;
+        i = at + 1;
+        const head = text.slice(i).match(/^\s*([A-Za-z]+)\s*([{(])/);
+        if (!head)
+            continue;
+        const type = head[1].toLowerCase();
+        i += head[0].length;
+        const close = head[2] === "{" ? "}" : ")";
+        if (type === "comment" || type === "preamble") {
+            i--;
+            if (head[2] === "{")
+                readBraced();
+            continue;
+        }
+        if (type === "string") {
+            skipWs();
+            const name = text.slice(i).match(/^[^\s=]+/);
+            if (name) {
+                i += name[0].length;
+                skipWs();
+                if (text[i] === "=") {
+                    i++;
+                    macros[name[0].toLowerCase()] = readValue();
+                }
+            }
+            skipWs();
+            if (text[i] === close)
+                i++;
+            continue;
+        }
+        skipWs();
+        const keyM = text.slice(i).match(/^[^,\s{}]*/);
+        const key = keyM ? keyM[0] : "";
+        i += key.length;
+        const fields = {};
+        for (;;) {
+            skipWs();
+            if (i >= n)
+                break;
+            if (text[i] === ",") {
+                i++;
+                continue;
+            }
+            if (text[i] === close) {
+                i++;
+                break;
+            }
+            const nameM = text.slice(i).match(/^[A-Za-z][\w:.\-]*/);
+            if (!nameM) {
+                i++;
+                continue;
+            }
+            i += nameM[0].length;
+            skipWs();
+            if (text[i] !== "=")
+                continue;
+            i++;
+            fields[nameM[0].toLowerCase()] = readValue();
+        }
+        entries.push(normalizeEntry({ type, key, fields }));
+    }
+    return entries;
+}
+function bibtexValue(v) {
+    return `{${v}}`;
+}
+function normalizePages(p) {
+    const m = p.match(/^(\w+)\s*[-–—]+\s*(\w+)$/);
+    return m ? `${m[1]}--${m[2]}` : p;
+}
+export function toBibtex(entries) {
+    return entries
+        .map((e) => {
+        const names = Object.keys(e.fields).sort((a, b) => {
+            const ia = FIELD_ORDER.indexOf(a);
+            const ib = FIELD_ORDER.indexOf(b);
+            return (ia < 0 ? 99 : ia) - (ib < 0 ? 99 : ib) || a.localeCompare(b);
+        });
+        const lines = names.map((k) => `  ${k} = ${bibtexValue(k === "pages" ? normalizePages(e.fields[k]) : e.fields[k])},`);
+        return `@${e.type}{${e.key},\n${lines.join("\n")}\n}`;
+    })
+        .join("\n\n");
+}
+/* ---------- RIS ---------- */
+const RIS_TYPES = {
+    JOUR: "article", BOOK: "book", CHAP: "incollection", CONF: "inproceedings", CPAPER: "inproceedings",
+    THES: "phdthesis", RPRT: "techreport", ELEC: "online", ICOMM: "online", UNPB: "unpublished", GEN: "misc", MGZN: "article",
+};
+const RIS_OUT = {
+    article: "JOUR", book: "BOOK", incollection: "CHAP", inbook: "CHAP", inproceedings: "CPAPER", phdthesis: "THES",
+    mastersthesis: "THES", techreport: "RPRT", online: "ELEC", unpublished: "UNPB", misc: "GEN",
+};
+export function parseRis(text) {
+    const entries = [];
+    let tags = [];
+    const flush = () => {
+        if (!tags.length)
+            return;
+        const get = (...t) => tags.find(([k]) => t.includes(k))?.[1];
+        const all = (...t) => tags.filter(([k]) => t.includes(k)).map(([, v]) => v);
+        const ty = get("TY") ?? "GEN";
+        const type = RIS_TYPES[ty] ?? "misc";
+        const fields = {};
+        const authors = all("AU", "A1").map((a) => formatNames(parseNames(a)));
+        if (authors.length)
+            fields.author = authors.join(" and ");
+        const editors = all("ED", "A2");
+        if (editors.length)
+            fields.editor = editors.join(" and ");
+        fields.title = get("TI", "T1") ?? "";
+        const container = get("T2", "JO", "JF", "JA", "BT") ?? "";
+        if (container)
+            fields[type === "article" ? "journal" : type === "book" ? "series" : "booktitle"] = container;
+        const py = get("PY", "Y1", "DA") ?? "";
+        fields.year = py.match(/\d{4}/)?.[0] ?? "";
+        fields.volume = get("VL") ?? "";
+        fields.number = get("IS") ?? "";
+        const sp = get("SP");
+        const ep = get("EP");
+        fields.pages = sp && ep ? `${sp}--${ep}` : sp ?? "";
+        fields.publisher = get("PB") ?? "";
+        fields.address = get("CY") ?? "";
+        fields.doi = get("DO") ?? "";
+        fields.url = get("UR", "L1") ?? "";
+        fields.abstract = get("AB", "N2") ?? "";
+        fields.keywords = all("KW").join(", ");
+        const sn = get("SN") ?? "";
+        if (sn)
+            fields[type === "book" ? "isbn" : "issn"] = sn;
+        entries.push(normalizeEntry({ type, key: get("ID") ?? "", fields }));
+        tags = [];
+    };
+    for (const line of text.split(/\r?\n/)) {
+        const m = line.match(/^([A-Z][A-Z0-9])\s{2}-\s?(.*)$/);
+        if (!m) {
+            // A line that does not start with a tag continues the last value.
+            if (tags.length && line.trim())
+                tags[tags.length - 1][1] += " " + line.trim();
+            continue;
+        }
+        if (m[1] === "ER")
+            flush();
+        else if (m[1] === "TY" && tags.length) {
+            flush();
+            tags.push([m[1], m[2].trim()]);
+        }
+        else
+            tags.push([m[1], m[2].trim()]);
+    }
+    flush();
+    return entries;
+}
+export function toRis(entries) {
+    return entries
+        .map((e) => {
+        const f = e.fields;
+        const out = [`TY  - ${RIS_OUT[e.type] ?? "GEN"}`];
+        if (e.key)
+            out.push(`ID  - ${e.key}`);
+        for (const n of parseNames(f.author))
+            out.push(`AU  - ${plain(n.literal ? n.family : n.given ? `${n.family}, ${n.given}` : n.family)}`);
+        for (const n of parseNames(f.editor))
+            out.push(`ED  - ${plain(n.given ? `${n.family}, ${n.given}` : n.family)}`);
+        if (f.title)
+            out.push(`TI  - ${plain(f.title)}`);
+        const container = f.journal ?? f.booktitle;
+        if (container)
+            out.push(`T2  - ${plain(container)}`);
+        if (f.year)
+            out.push(`PY  - ${f.year}`);
+        if (f.volume)
+            out.push(`VL  - ${f.volume}`);
+        if (f.number)
+            out.push(`IS  - ${f.number}`);
+        if (f.pages) {
+            const m = normalizePages(f.pages).match(/^(\w+)--(\w+)$/);
+            if (m)
+                out.push(`SP  - ${m[1]}`, `EP  - ${m[2]}`);
+            else
+                out.push(`SP  - ${f.pages}`);
+        }
+        if (f.publisher)
+            out.push(`PB  - ${plain(f.publisher)}`);
+        if (f.address)
+            out.push(`CY  - ${plain(f.address)}`);
+        if (f.doi)
+            out.push(`DO  - ${f.doi}`);
+        if (f.url)
+            out.push(`UR  - ${f.url}`);
+        if (f.abstract)
+            out.push(`AB  - ${plain(f.abstract)}`);
+        if (f.keywords)
+            for (const k of f.keywords.split(/[,;]/).map(squash).filter(Boolean))
+                out.push(`KW  - ${k}`);
+        const sn = f.issn ?? f.isbn;
+        if (sn)
+            out.push(`SN  - ${sn}`);
+        out.push("ER  - ");
+        return out.join("\n");
+    })
+        .join("\n\n");
+}
+/* ---------- CSL JSON ---------- */
+const CSL_TYPES = {
+    "article-journal": "article", "article-magazine": "article", "article-newspaper": "article", article: "article",
+    book: "book", chapter: "incollection", "paper-conference": "inproceedings", thesis: "phdthesis",
+    report: "techreport", webpage: "online", "post-weblog": "online", manuscript: "unpublished", dataset: "misc",
+};
+const CSL_OUT = {
+    article: "article-journal", book: "book", incollection: "chapter", inbook: "chapter", inproceedings: "paper-conference",
+    phdthesis: "thesis", mastersthesis: "thesis", techreport: "report", online: "webpage", unpublished: "manuscript", misc: "document",
+};
+export function parseCslJson(text) {
+    let data;
+    try {
+        data = JSON.parse(text);
+    }
+    catch (e) {
+        throw new Error(`The CSL JSON could not be read: ${e.message}`);
+    }
+    const items = Array.isArray(data) ? data : data && typeof data === "object" && "items" in data && Array.isArray(data.items) ? data.items : [data];
+    return items
+        .filter((it) => it && typeof it === "object")
+        .map((it) => {
+        const type = CSL_TYPES[String(it.type ?? "")] ?? "misc";
+        const names = (list) => Array.isArray(list)
+            ? formatNames(list.map((a) => a.literal ? { family: String(a.literal), given: "", literal: true } : { family: String(a.family ?? ""), given: String(a.given ?? "") }))
+            : "";
+        const dp = it.issued?.["date-parts"]?.[0] ?? [];
+        const container = it["container-title"] ? String(it["container-title"]) : "";
+        const fields = {
+            author: names(it.author),
+            editor: names(it.editor),
+            title: it.title ? String(it.title) : "",
+            year: dp[0] ? String(dp[0]) : it.issued?.literal?.match?.(/\d{4}/)?.[0] ?? "",
+            volume: it.volume != null ? String(it.volume) : "",
+            number: it.issue != null ? String(it.issue) : "",
+            pages: it.page ? String(it.page) : "",
+            publisher: it.publisher ? String(it.publisher) : "",
+            address: it["publisher-place"] ? String(it["publisher-place"]) : "",
+            doi: it.DOI ? String(it.DOI) : "",
+            url: it.URL ? String(it.URL) : "",
+            abstract: it.abstract ? String(it.abstract) : "",
+            issn: it.ISSN ? String(it.ISSN) : "",
+            isbn: it.ISBN ? String(it.ISBN) : "",
+        };
+        if (container)
+            fields[type === "article" ? "journal" : "booktitle"] = container;
+        return normalizeEntry({ type, key: it.id != null ? String(it.id) : "", fields });
+    });
+}
+export function toCslJson(entries) {
+    const items = entries.map((e) => {
+        const f = e.fields;
+        const names = (raw) => parseNames(raw).map((n) => (n.literal ? { literal: plain(n.family) } : { family: plain(n.family), given: plain(n.given) }));
+        const item = { id: e.key, type: CSL_OUT[e.type] ?? "document" };
+        if (f.author)
+            item.author = names(f.author);
+        if (f.editor)
+            item.editor = names(f.editor);
+        if (f.title)
+            item.title = plain(f.title);
+        const container = f.journal ?? f.booktitle;
+        if (container)
+            item["container-title"] = plain(container);
+        if (f.year && /^\d{4}$/.test(f.year))
+            item.issued = { "date-parts": [[Number(f.year)]] };
+        if (f.volume)
+            item.volume = f.volume;
+        if (f.number)
+            item.issue = f.number;
+        if (f.pages)
+            item.page = normalizePages(f.pages).replace("--", "-");
+        if (f.publisher)
+            item.publisher = plain(f.publisher);
+        if (f.address)
+            item["publisher-place"] = plain(f.address);
+        if (f.doi)
+            item.DOI = f.doi;
+        if (f.url)
+            item.URL = f.url;
+        if (f.abstract)
+            item.abstract = plain(f.abstract);
+        if (f.issn)
+            item.ISSN = f.issn;
+        if (f.isbn)
+            item.ISBN = f.isbn;
+        return item;
+    });
+    return JSON.stringify(items, null, 2);
+}
+/* ---------- plain text ---------- */
+function initials(given) {
+    return given
+        .split(/[\s]+/)
+        .filter(Boolean)
+        .map((w) => (w.includes("-") ? w.split("-").map((p) => `${p[0].toUpperCase()}.`).join("-") : `${w[0].toUpperCase()}.`))
+        .join(" ");
+}
+export function toText(entries) {
+    return entries
+        .map((e) => {
+        const f = e.fields;
+        const names = parseNames(f.author).map((n) => (n.literal || !n.given ? plain(n.family) : `${plain(n.family)}, ${initials(plain(n.given))}`));
+        let who = "";
+        if (names.length === 1)
+            who = names[0];
+        else if (names.length > 1)
+            who = `${names.slice(0, -1).join(", ")}, & ${names[names.length - 1]}`;
+        const parts = [];
+        if (who)
+            parts.push(who.endsWith(".") ? who : `${who}.`);
+        parts.push(`(${f.year ?? "n.d."}).`);
+        if (f.title)
+            parts.push(/[.?!]$/.test(plain(f.title)) ? plain(f.title) : `${plain(f.title)}.`);
+        const container = f.journal ?? f.booktitle;
+        if (container) {
+            let c = plain(container);
+            if (f.volume)
+                c += `, ${f.volume}`;
+            if (f.number)
+                c += `(${f.number})`;
+            if (f.pages)
+                c += `, ${normalizePages(f.pages).replace("--", "-")}`;
+            parts.push(`${c}.`);
+        }
+        else if (f.publisher)
+            parts.push(`${plain(f.publisher)}.`);
+        if (f.doi)
+            parts.push(`https://doi.org/${f.doi}`);
+        else if (f.url)
+            parts.push(f.url);
+        return parts.join(" ");
+    })
+        .join("\n\n");
+}
+/* ---------- parse and write by name ---------- */
+export function parseAny(text, format = "auto") {
+    if (!text.trim())
+        throw new Error("The text is empty. Paste a BibTeX, RIS or CSL JSON reference list.");
+    const fmt = format === "auto" ? detectFormat(text) : format;
+    const entries = fmt === "bibtex" ? parseBibtex(text) : fmt === "ris" ? parseRis(text) : parseCslJson(text);
+    // Give entries without a key one, so every entry can be named later.
+    const used = new Set(entries.map((e) => e.key).filter(Boolean));
+    for (const e of entries) {
+        if (!e.key) {
+            e.key = uniqueKey(makeKey(e, { titleWord: true }), used);
+            used.add(e.key);
+        }
+    }
+    return { format: fmt, entries };
+}
+export function serialize(entries, format) {
+    switch (format) {
+        case "bibtex":
+            return toBibtex(entries);
+        case "ris":
+            return toRis(entries);
+        case "csl_json":
+            return toCslJson(entries);
+        default:
+            return toText(entries);
+    }
+}
+/* ---------- cite keys ---------- */
+export function makeKey(e, opts) {
+    const first = parseNames(e.fields.author)[0] ?? parseNames(e.fields.editor)[0];
+    let family = first ? plain(first.family).split(" ").pop() ?? "" : "";
+    family = ascii(family).toLowerCase().replace(/[^a-z0-9]/g, "");
+    if (!family)
+        family = "anon";
+    const year = /^\d{4}$/.test(e.fields.year ?? "") ? e.fields.year : "nd";
+    let word = "";
+    if (opts.titleWord && e.fields.title) {
+        const words = ascii(plain(e.fields.title))
+            .toLowerCase()
+            .split(/[^a-z0-9]+/)
+            .filter(Boolean);
+        word = words.find((w) => !STOP_WORDS.has(w)) ?? words[0] ?? "";
+    }
+    return `${family}${year}${word}`;
+}
+export function uniqueKey(base, used) {
+    if (!used.has(base))
+        return base;
+    for (let n = 0;; n++) {
+        const suffix = n < 26 ? String.fromCharCode(97 + n) : `${n}`;
+        if (!used.has(base + suffix))
+            return base + suffix;
+    }
+}

package/build/src/core/tools.js

@@ -0,0 +1,25 @@
+export async function runTool(tool, args, api) {
+    try {
+        const out = await tool.run(args, api);
+        return { content: [{ type: "text", text: out.text }], structuredContent: out.structured };
+    }
+    catch (err) {
+        // Pass the message through as it was written, so the caller can act on it.
+        const msg = err instanceof Error ? err.message : String(err);
+        return { content: [{ type: "text", text: msg }], isError: true };
+    }
+}
+export function registerTools(server, tools, api) {
+    for (const tool of tools) {
+        server.registerTool(tool.name, {
+            title: tool.title,
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+            outputSchema: tool.outputSchema,
+            annotations: { readOnlyHint: true, openWorldHint: false },
+        }, async (args) => runTool(tool, args, api));
+    }
+}
+export function bullets(lines, empty = "Nothing to show.") {
+    return lines.length ? lines.map((l) => `- ${l}`).join("\n") : empty;
+}

package/build/src/index.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createServer, VERSION } from "./server.js";
+function usage() {
+    console.log(`bibtex-reference-manager-mcp ${VERSION}
+
+Clean, convert, dedupe and format BibTeX, RIS and CSL JSON reference lists for AI apps (MCP). Works offline.
+
+Add it to your AI app's MCP config with command "npx" and args ["-y", "bibtex-reference-manager-mcp"].
+
+  --help, --version`);
+}
+async function main() {
+    const cmd = process.argv[2];
+    if (cmd === "--help" || cmd === "-h")
+        return usage();
+    if (cmd === "--version" || cmd === "-v")
+        return console.log(VERSION);
+    await createServer().connect(new StdioServerTransport());
+    console.error(`bibtex-reference-manager-mcp ${VERSION} running`);
+}
+main().catch((e) => {
+    console.error(e);
+    process.exit(1);
+});

package/build/src/server.js

@@ -0,0 +1,9 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { registerTools } from "./core/tools.js";
+import { tools } from "./tools.js";
+export const VERSION = "0.1.0";
+export function createServer() {
+    const server = new McpServer({ name: "bibtex-reference-manager-mcp", version: VERSION });
+    registerTools(server, tools, null);
+    return server;
+}

package/build/src/tools.js

@@ -0,0 +1,180 @@
+import { z } from "zod";
+import { bullets } from "./core/tools.js";
+import { findDuplicates, lintEntries } from "./analyze.js";
+import { makeKey, parseAny, parseNames, plain, serialize, toBibtex, uniqueKey } from "./bib.js";
+const text = z.string().min(1).describe("The reference list as text: BibTeX, RIS or CSL JSON.");
+const format = z
+    .enum(["auto", "bibtex", "ris", "csl_json"])
+    .optional()
+    .describe("The format of the text. Defaults to auto, which looks at the text to decide.");
+const entryShape = z.object({
+    key: z.string(),
+    type: z.string().describe("The BibTeX entry type, like article or book."),
+    authors: z.array(z.string()).describe("Authors as \"Family, Given\"."),
+    fields: z.record(z.string(), z.string()).describe("Every field of the entry, with lower case names."),
+});
+function describeEntry(e) {
+    return {
+        key: e.key,
+        type: e.type,
+        authors: parseNames(e.fields.author).map((n) => (n.literal ? plain(n.family) : n.given ? `${n.family}, ${n.given}` : n.family)),
+        fields: e.fields,
+    };
+}
+function plural(n, word) {
+    if (n === 1)
+        return `${n} ${word}`;
+    return `${n} ${word.endsWith("y") ? `${word.slice(0, -1)}ies` : `${word}s`}`;
+}
+const parseBibliography = {
+    name: "parse_bibliography",
+    title: "Parse a bibliography",
+    description: "Read BibTeX, RIS or CSL JSON text and return the entries in one normalized shape: lower case field names, tidy whitespace, bare DOIs, the year filled in from a date, and authors split into \"Family, Given\". Nothing is sent anywhere.",
+    inputSchema: { text, format },
+    outputSchema: {
+        format: z.string().describe("The format that was read: bibtex, ris or csl_json."),
+        count: z.number().describe("How many entries were found."),
+        entries: z.array(entryShape),
+    },
+    run: async (a) => {
+        const { format: fmt, entries } = parseAny(a.text, a.format ?? "auto");
+        const lines = entries.map((e) => `${e.key} (${e.type}): ${plain(e.fields.title ?? "no title")}${e.fields.year ? `, ${e.fields.year}` : ""}`);
+        return {
+            text: `Read ${plural(entries.length, "entry")} as ${fmt}.\n${bullets(lines, "No entries were found.")}`,
+            structured: { format: fmt, count: entries.length, entries: entries.map(describeEntry) },
+        };
+    },
+};
+const convertBibliography = {
+    name: "convert_bibliography",
+    title: "Convert a bibliography",
+    description: "Convert a reference list between BibTeX, RIS, CSL JSON and plain text (a simple author, year, title style). The input format is detected unless you pass it. Page ranges, DOIs and names are cleaned on the way.",
+    inputSchema: {
+        text,
+        to: z.enum(["bibtex", "ris", "csl_json", "text"]).describe("The format to write."),
+        from: format,
+    },
+    outputSchema: {
+        from: z.string().describe("The format that was read."),
+        to: z.string().describe("The format that was written."),
+        count: z.number().describe("How many entries were converted."),
+        output: z.string().describe("The converted reference list."),
+    },
+    run: async (a) => {
+        const { format: fmt, entries } = parseAny(a.text, a.from ?? "auto");
+        if (!entries.length)
+            throw new Error("No entries were found in the text, so there is nothing to convert.");
+        const output = serialize(entries, a.to);
+        return {
+            text: `Converted ${plural(entries.length, "entry")} from ${fmt} to ${a.to}.\n\n${output}`,
+            structured: { from: fmt, to: a.to, count: entries.length, output },
+        };
+    },
+};
+const dedupeEntries = {
+    name: "dedupe_entries",
+    title: "Find duplicate entries",
+    description: "Find duplicate references by matching DOI, by the same cite key, and by similar titles (the years must not clash). Each group says which entry to keep, the one with the most fields, and which to remove. Also returns the list as BibTeX with the extra copies dropped.",
+    inputSchema: {
+        text,
+        format,
+        title_threshold: z
+            .number()
+            .min(0.5)
+            .max(1)
+            .optional()
+            .describe("How alike two titles must be to count as the same, from 0.5 to 1. Defaults to 0.9."),
+    },
+    outputSchema: {
+        total: z.number().describe("How many entries were read."),
+        unique: z.number().describe("How many entries are left once the duplicates are dropped."),
+        groups: z.array(z.object({
+            keys: z.array(z.string()),
+            reasons: z.array(z.enum(["doi", "key", "title"])),
+            keep: z.string(),
+            remove: z.array(z.string()),
+        })),
+        deduplicated_bibtex: z.string().describe("The list as BibTeX without the removed copies."),
+    },
+    run: async (a) => {
+        const { entries } = parseAny(a.text, a.format ?? "auto");
+        const groups = findDuplicates(entries, a.title_threshold ?? 0.9);
+        const drop = new Set();
+        for (const g of groups) {
+            for (const i of g.indexes)
+                if (i !== g.keepIndex)
+                    drop.add(i);
+        }
+        const kept = entries.filter((_, i) => !drop.has(i));
+        const lines = groups.map((g) => `${g.keys.join(", ")} match by ${g.reasons.join(" and ")}. Keep ${g.keep}.`);
+        return {
+            text: `Read ${plural(entries.length, "entry")} and found ${plural(groups.length, "duplicate group")}. ${kept.length} would be left.\n${bullets(lines, "No duplicates found.")}`,
+            structured: {
+                total: entries.length,
+                unique: kept.length,
+                groups: groups.map(({ keys, reasons, keep, remove }) => ({ keys, reasons, keep, remove })),
+                deduplicated_bibtex: toBibtex(kept),
+            },
+        };
+    },
+};
+const lintEntriesTool = {
+    name: "lint_entries",
+    title: "Lint entries",
+    description: "Check a reference list for problems: missing required fields for the entry type, bad page ranges, titles that are not capitalized, invalid DOIs, odd years and repeated keys. Each issue names the entry key, the field and a plain message.",
+    inputSchema: { text, format },
+    outputSchema: {
+        count: z.number().describe("How many entries were checked."),
+        errors: z.number(),
+        warnings: z.number(),
+        issues: z.array(z.object({
+            key: z.string(),
+            rule: z.enum(["missing-field", "bad-pages", "uncapitalized-title", "invalid-doi", "bad-year", "duplicate-key"]),
+            severity: z.enum(["error", "warning"]),
+            field: z.string().optional(),
+            message: z.string(),
+        })),
+    },
+    run: async (a) => {
+        const { entries } = parseAny(a.text, a.format ?? "auto");
+        const issues = lintEntries(entries);
+        const errors = issues.filter((i) => i.severity === "error").length;
+        const warnings = issues.length - errors;
+        const lines = issues.map((i) => `${i.key}: [${i.rule}] ${i.message}`);
+        return {
+            text: `Checked ${plural(entries.length, "entry")}: ${plural(errors, "error")}, ${plural(warnings, "warning")}.\n${bullets(lines, "No problems found.")}`,
+            structured: { count: entries.length, errors, warnings, issues },
+        };
+    },
+};
+const generateCiteKeys = {
+    name: "generate_cite_keys",
+    title: "Generate cite keys",
+    description: "Create consistent cite keys from the first author's family name, the year and the first meaningful word of the title, like smith2024deep. Repeated keys get a letter added. Returns the old and new key for each entry and the list as BibTeX with the new keys.",
+    inputSchema: {
+        text,
+        format,
+        include_title_word: z.boolean().optional().describe("Add the first meaningful title word, so you get smith2024deep and not smith2024. Defaults to true."),
+    },
+    outputSchema: {
+        count: z.number(),
+        keys: z.array(z.object({ old_key: z.string(), new_key: z.string() })),
+        bibtex: z.string().describe("The list as BibTeX using the new keys."),
+    },
+    run: async (a) => {
+        const { entries } = parseAny(a.text, a.format ?? "auto");
+        const used = new Set();
+        const keys = entries.map((e) => {
+            const nk = uniqueKey(makeKey(e, { titleWord: a.include_title_word ?? true }), used);
+            used.add(nk);
+            return { old_key: e.key, new_key: nk };
+        });
+        const renamed = entries.map((e, i) => ({ ...e, key: keys[i].new_key }));
+        const lines = keys.map((k) => (k.old_key === k.new_key ? `${k.new_key} (unchanged)` : `${k.old_key} becomes ${k.new_key}`));
+        return {
+            text: `Made ${plural(keys.length, "cite key")}.\n${bullets(lines, "No entries were found.")}`,
+            structured: { count: keys.length, keys, bibtex: toBibtex(renamed) },
+        };
+    },
+};
+export const tools = [parseBibliography, convertBibliography, dedupeEntries, lintEntriesTool, generateCiteKeys];

package/llms.txt

@@ -0,0 +1,57 @@
+# BibTeX Reference Manager MCP
+
+> A free, open source MCP server that cleans, converts, dedupes and formats BibTeX, RIS and CSL JSON reference lists. It runs offline on the user's computer with no account and no API key. npm package: bibtex-reference-manager-mcp. Version 0.1.0.
+
+Use this server when a user pastes or attaches a reference list and wants it read, converted, deduplicated, checked or renamed. Pass the list as the `text` argument. The tools do the work in code, so do not rewrite entries by hand when a tool can do it.
+
+## Install
+
+Command: `npx -y bibtex-reference-manager-mcp`
+
+MCP config for Claude Desktop, Cursor and similar apps:
+
+```json
+{
+  "mcpServers": {
+    "bibtex": {
+      "command": "npx",
+      "args": ["-y", "bibtex-reference-manager-mcp"]
+    }
+  }
+}
+```
+
+Needs Node.js 20 or newer.
+
+## Tools
+
+All tools are read only, work offline and take `text` (the reference list). Most take an optional `format` of auto, bibtex, ris or csl_json. The default, auto, looks at the text.
+
+- parse_bibliography: returns normalized entries (key, type, authors as "Family, Given", and all fields). Field names are lower case, DOIs are bare, and the year is filled in from a date when needed.
+- convert_bibliography: takes `to` (bibtex, ris, csl_json or text) and optional `from`. Returns the converted list in `output`. BibTeX page ranges are written as 12--15.
+- dedupe_entries: finds duplicate groups by DOI, same cite key (ignoring case) and title similarity. Optional `title_threshold` from 0.5 to 1, default 0.9. Titles are not matched when both entries have a year and the years differ. Each group gives `keep` (the entry with the most fields) and `remove`. Also returns `deduplicated_bibtex`.
+- lint_entries: returns issues with `key`, `rule`, `severity`, `field` and `message`. Rules: missing-field, bad-pages, uncapitalized-title, invalid-doi, bad-year, duplicate-key.
+- generate_cite_keys: returns old and new keys and `bibtex` with the new keys. Keys look like smith2024deep. Set `include_title_word` to false for smith2024. Repeated keys get a letter, like smith2024deepa.
+
+## Example prompts
+
+- "Lint this .bib file and list what to fix."
+- "Remove the duplicate references and give me the clean BibTeX."
+- "Convert this RIS export to BibTeX and rename the keys."
+- "Turn this CSL JSON into a plain text reference list."
+
+## FAQ
+
+Does it look up DOIs online? No. It checks only that a DOI has the shape 10.xxxx/something.
+
+Does it send data anywhere? No. It makes no network requests and keeps nothing between calls.
+
+What happens with an empty list or text it cannot place? The tool returns an error that says so, and asks for the format to be passed.
+
+Which entry types are checked for required fields? article, book, inproceedings, incollection, phdthesis, mastersthesis, techreport, unpublished, misc and online. Other types need a title.
+
+## Links
+
+- Source: https://github.com/AnonymousOnyx22/bibtex-reference-manager-mcp
+- npm: https://www.npmjs.com/package/bibtex-reference-manager-mcp
+- License: MIT

package/package.json

@@ -1,6 +1,90 @@
 {
   "name": "bibtex-reference-manager-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "BibTeX reference manager MCP server for AI apps. Ask your AI to parse, clean, convert, dedupe, lint and format BibTeX, RIS and CSL JSON reference lists, and to make consistent cite keys. Works offline with no account.",
+  "type": "module",
+  "main": "build/src/index.js",
+  "bin": {
+    "bibtex-reference-manager-mcp": "build/src/index.js"
+  },
+  "files": [
+    "build/src",
+    "README.md",
+    "llms.txt",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "devEngines": {
+    "runtime": {
+      "name": "node",
+      "version": "^22.12.0 || ^24.0.0 || >=26.0.0"
+    }
+  },
+  "scripts": {
+    "build": "tsc && node -e \"require('fs').chmodSync('build/src/index.js', 0o755)\"",
+    "test": "vitest run",
+    "start": "node build/src/index.js",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "keywords": [
+    "bibtex",
+    "bibtex reference manager",
+    "bibtex cleaner",
+    "bibtex converter",
+    "bib file",
+    "ris",
+    "ris converter",
+    "csl json",
+    "citation",
+    "citations",
+    "references",
+    "bibliography",
+    "reference manager",
+    "cite key",
+    "citation key",
+    "dedupe references",
+    "duplicate references",
+    "doi",
+    "doi validator",
+    "latex",
+    "zotero",
+    "endnote",
+    "mendeley",
+    "academic writing",
+    "thesis",
+    "mcp",
+    "mcp server",
+    "mcp-server",
+    "model-context-protocol",
+    "bibtex-reference-manager-mcp",
+    "student",
+    "students",
+    "university",
+    "education",
+    "claude",
+    "cursor"
+  ],
+  "author": "AnonymousOnyx22",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AnonymousOnyx22/bibtex-reference-manager-mcp.git"
+  },
+  "homepage": "https://github.com/AnonymousOnyx22/bibtex-reference-manager-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/AnonymousOnyx22/bibtex-reference-manager-mcp/issues"
+  },
+  "mcpName": "io.github.AnonymousOnyx22/bibtex-reference-manager-mcp",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.1",
+    "zod": "^4.6.7"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.5",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.5"
+  }
+}