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

package/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+## 0.1.1
+
+- The README now has a Common workflows section showing how the five tools work together in a typical thesis or cleaning workflow.
+
+- The README now has a competitor comparison table showing how it differs from servers that connect to online accounts or web APIs.
+
+- The README and llms.txt now have a Why this server section and steps for exporting a Zotero or Mendeley library to .bib or RIS and pasting it in.
+
+- The README intro, the npm description and the npm keywords now use the words students search for, such as LaTeX, Zotero export, Mendeley export, EndNote RIS, thesis bibliography and fix .bib file.
+
+- BibTeX and RIS parse errors now name the entry, the field and the line that failed, for example an unclosed brace, an unclosed quote, an entry that is never closed, or a RIS record without a TY line. Before, the parser guessed and returned a damaged entry.
+
+## 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,227 @@
-# 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.
+
+It is made with students in mind. Writing a thesis in LaTeX? Ask it to fix a broken `.bib` file, clean up a Zotero export or a Mendeley export, turn an EndNote RIS file into BibTeX, and tidy your thesis bibliography before you hand it in.
+
+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
+```
+
+## 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."
+
+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"]
+    }
+  }
+}
+```
+
+## Why this server
+
+Some MCP servers connect to a reference manager account and read your library online. This one does not. It works on text you paste in, so it is a different tool for a different job.
+
+- It needs no account, no API key and no internet. Nothing is sent anywhere.
+- It does not connect to Zotero or Mendeley. You export a file and paste it in, so it works with any reference manager that can write BibTeX, RIS or CSL JSON.
+- The work is done by code, not by the AI guessing. Converting, deduping, linting and renaming keys give the same result every time.
+- It is read only. It never edits your library or your files. You get the result back and decide what to keep.
+
+If you want an assistant to search or change a live online library, you need a server that connects to that service. This one is for cleaning up an exported list.
+
+## Competitor comparison
+
+Other MCP servers work with reference libraries too. Most connect to an online account or a web API, so your data leaves your computer and you need an account or an API key. This server works on text you paste in, so it needs no account, no API key and no internet, and nothing is sent anywhere.
+
+| Server | Works offline | Needs account or key | Reads a live library | Read only | Formats |
+| --- | --- | --- | --- | --- | --- |
+| BibTeX Reference Manager MCP | Yes | No | No | Yes | BibTeX, RIS, CSL JSON |
+| zotero-mcp | No | Yes | Yes | No | Zotero, BibTeX |
+| mendeley-mcp | No | Yes | Yes | No | Mendeley, BibTeX |
+| bibtex-mcp | No | Optional | No | Yes | BibTeX |
+| reference-mcp | No | No | No | Yes | BibTeX |
+| CrossRef-MCP | No | No | No | Yes | BibTeX |
+| mcp_doi2bib | No | No | No | Yes | BibTeX |
+| Local-Zotero-MCP | No | No | Yes | Yes | Zotero |
+| jabref-mcp | No | No | Yes | No | BibTeX |
+
+zotero-mcp and mendeley-mcp connect to your online Zotero or Mendeley library and can change it. bibtex-mcp, reference-mcp, CrossRef-MCP and mcp_doi2bib fetch citations from web sources such as Semantic Scholar, OpenAlex, CiteAs, Google Scholar and CrossRef. Local-Zotero-MCP reads your local Zotero library through the Zotero desktop app. jabref-mcp reads a JabRef .bib file and can add entries through JabRef.
+
+Pick this server when you want to clean, convert, dedupe, lint and rename an exported list without sending it anywhere. Pick one of the others when you want to search or change a live online library.
+
+## Export from Zotero or Mendeley
+
+1. In Zotero, right click a collection (or select some items), choose the export option and pick BibTeX or RIS. In Mendeley, select your references, choose Export and pick BibTeX or RIS. Menu names change between versions, so look for Export.
+2. Open the saved `.bib` or `.ris` file in any text editor and copy everything, or attach the file in an app that accepts attachments.
+3. Paste it into your AI app and ask, for example: "Lint this list, remove the duplicates and give me back clean BibTeX with tidy cite keys."
+4. Copy the result into your `.bib` file. To get it back into your reference manager, save it as a `.bib` or `.ris` file and import it.
+
+The format is detected for you. If a file is not recognized, say which format it is.
+
+## 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.
+
+## Common workflows
+
+These show how the five tools fit together. All of them take the reference list as `text` and are read only.
+
+### Clean a Zotero or Mendeley export
+
+1. Run `parse_bibliography` to normalize the entries and fill in missing years.
+2. Run `dedupe_entries` to remove duplicates by DOI, cite key or title.
+3. Run `lint_entries` to see missing fields, bad page ranges and odd years.
+4. Run `generate_cite_keys` to give every entry a tidy key like `smith2024deep`.
+5. Run `convert_bibliography` to get back a clean BibTeX file.
+
+### Turn an EndNote RIS export into BibTeX
+
+1. Run `parse_bibliography` on the RIS text to check it parses.
+2. Run `convert_bibliography` with `to` set to BibTeX.
+3. Run `generate_cite_keys` if you want keys like `smith2024deep`.
+
+### Check a finished .bib before you hand it in
+
+1. Run `parse_bibliography` to normalize.
+2. Run `lint_entries` and fix what it flags.
+3. Run `dedupe_entries` to make sure nothing is listed twice.
+
+## 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.
+
+## More free student MCP servers
+
+All free, open source and read only where they touch your accounts. Browse the full list at [brightspacemcp.com/more-mcps](https://brightspacemcp.com/more-mcps/).
+
+| Server | What it does |
+| --- | --- |
+| [Brightspace MCP](https://github.com/AnonymousOnyx22/brightspace-d2l-mcp) | D2L Brightspace for AI. Due dates with real submission status, grades, a target grade calculator and course files. |
+| [Canvas MCP](https://github.com/AnonymousOnyx22/canvas-lms-student-mcp) | Canvas LMS for AI, read only. Due dates, missing work, grades and announcements. |
+| [Moodle MCP](https://github.com/AnonymousOnyx22/moodle-student-mcp) | Moodle for AI, read only. Due dates, overdue work, grades and announcements. |
+| [Google Classroom MCP](https://github.com/AnonymousOnyx22/google-classroom-student-mcp) | Google Classroom for AI, read only. Todos, due dates, missing work and grades. |
+| [GPA Calculator MCP](https://github.com/AnonymousOnyx22/gpa-calculator-mcp) | GPA, grade conversion and the grade you need on the final, for AI. Works offline, no account. |
+| [Citations MCP](https://github.com/AnonymousOnyx22/student-citations-mcp) | APA, MLA and Chicago citations from a DOI, an ISBN or typed details. No account. |
+| [Study Planner MCP](https://github.com/AnonymousOnyx22/study-planner-mcp) | Exam study schedules, spaced repetition dates, pomodoro plans and assignment milestones. Works offline. |
+| [Paper Finder MCP](https://github.com/AnonymousOnyx22/paper-finder-student-mcp) | Search scholarly papers, find open access copies and related work through OpenAlex. No key needed. |
+| [Open Textbook Finder MCP](https://github.com/AnonymousOnyx22/open-textbook-finder-mcp) | Find free legal copies of textbooks on OpenStax, DOAB and Open Library, look up editions by ISBN and suggest cheaper older ones. |
+| [STEM Calculator MCP](https://github.com/AnonymousOnyx22/stem-calc-student-mcp) | Chemistry and physics homework math: molar mass, balancing equations, grams to moles, unit conversion and significant figures. Works offline. |
+| [Essay Stats MCP](https://github.com/AnonymousOnyx22/essay-stats-mcp) | Offline writing metrics for essays. Word and page counts, readability scores, passive voice, repeated openers, filler words, long sentences and word limit checks, so students can check their work against assignment requirements. No account, no network. |
+| [Syllabus to Calendar MCP](https://github.com/AnonymousOnyx22/syllabus-calendar-mcp) | Syllabus to calendar MCP server. Extract dates from syllabus text, build an ics calendar, expand recurring classes and merge calendars. Works offline, no account. |
+| [Job Application Tracker MCP](https://github.com/AnonymousOnyx22/job-tracker-student-mcp) | Job application tracker MCP server. Track internships, jobs, interviews and deadlines offline, see what is coming up, and export your list as CSV or Markdown. No account and no API keys. |
+
+## 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;
+}