bibtex-reference-manager-mcp 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.1.2
+
+- Added `fix_entries`, which applies the safe fixes from `lint_entries` (double hyphen page ranges, capitalized titles, bare DOIs) and returns the cleaned BibTeX with a list of each change.
+
+- `convert_bibliography` takes an optional `style` (`apa`, `mla` or `ieee`) for the plain text output, so a formatted reference list takes one call. Without it the output is the same as before.
+
+## 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.

package/README.md

@@ -6,6 +6,8 @@
 
 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.
@@ -18,6 +20,14 @@ Run it straight from npm with `npx`. You need Node.js 20 or newer, see [Node ver
 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)
@@ -84,22 +94,55 @@ Add this to `.vscode/mcp.json` in your workspace:
 }
 ```
 
-## Try these prompts
+## Why this server
 
-Paste your reference list into the chat first, or attach the file, then ask:
+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.
 
-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."
+- 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. |
+| `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. For plain text, pass `style` as `apa` (the default), `mla` or `ieee` to get a formatted reference list. |
 | `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. |
+| `fix_entries` | Applies the safe fixes from `lint_entries` and returns the cleaned BibTeX: double hyphen page ranges, capitalized titles and bare DOIs. It lists each change and does not guess missing fields. |
 | `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.
@@ -110,6 +153,30 @@ Every tool takes the reference list as `text`, and every tool returns both a rea
 - 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 six 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`, then `fix_entries` to apply the safe fixes it can make.
+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.
@@ -134,7 +201,27 @@ 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.
+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 six 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
 

package/build/src/analyze.js

@@ -167,3 +167,44 @@ export function lintEntries(entries) {
     }
     return issues;
 }
+function capitalizeTitle(title) {
+    const raw = title.trim();
+    if (/^[a-z]/.test(raw))
+        return raw[0].toUpperCase() + raw.slice(1);
+    let depth = 0;
+    return raw
+        .split(/(\s+)/)
+        .map((word) => {
+        const inBraces = depth > 0 || word.startsWith("{");
+        for (const c of word)
+            depth += c === "{" ? 1 : c === "}" ? -1 : 0;
+        if (inBraces || SMALL_WORDS.has(word.toLowerCase()))
+            return word;
+        return word.replace(/^[a-z]/, (c) => c.toUpperCase());
+    })
+        .join("");
+}
+export function fixEntries(entries) {
+    const fixes = [];
+    const fixed = entries.map((e) => {
+        const f = { ...e.fields };
+        const set = (field, to) => {
+            if (to !== f[field])
+                fixes.push({ key: e.key, field, from: f[field], to });
+            f[field] = to;
+        };
+        if (f.pages && pageProblem(f.pages)?.startsWith("use a double hyphen")) {
+            set("pages", f.pages.trim().replace(/\s*[-–—]\s*/, "--"));
+        }
+        if (f.title && lintEntries([{ ...e, fields: f }]).some((i) => i.rule === "uncapitalized-title")) {
+            set("title", capitalizeTitle(f.title));
+        }
+        if (f.doi) {
+            const doi = cleanDoi(f.doi);
+            if (/^10\.\d{4,9}\/\S+$/.test(doi))
+                set("doi", doi);
+        }
+        return { ...e, fields: f };
+    });
+    return { entries: fixed, fixes };
+}

package/build/src/bib.js

@@ -124,6 +124,14 @@ export function parseBibtex(text) {
     const macros = {};
     let i = 0;
     const n = text.length;
+    // The entry being read, so an error can name it and the line it went wrong on.
+    let where = { type: "", key: "", field: "" };
+    const lineAt = (pos) => text.slice(0, pos).split("\n").length;
+    const fail = (what, pos) => {
+        const field = where.field ? ` in field ${where.field}` : "";
+        const entry = where.key ? `entry ${where.key}` : `@${where.type} entry`;
+        throw new Error(`${what}${field} of ${entry}, line ${lineAt(pos)}.`);
+    };
     const skipWs = () => {
         while (i < n && /\s/.test(text[i]))
             i++;
@@ -132,6 +140,9 @@ export function parseBibtex(text) {
         let depth = 0;
         const start = i + 1;
         for (; i < n; i++) {
+            // A new entry starting at the front of a line means this value was never closed.
+            if (text[i] === "\n" && /^\n[ \t]*@[A-Za-z]+\s*[{(]/.test(text.slice(i, i + 80)))
+                break;
             if (text[i] === "{")
                 depth++;
             else if (text[i] === "}" && --depth === 0) {
@@ -140,7 +151,7 @@ export function parseBibtex(text) {
                 return out;
             }
         }
-        return text.slice(start);
+        return fail("Unclosed brace", start - 1);
     };
     const readQuoted = () => {
         let depth = 0;
@@ -156,7 +167,7 @@ export function parseBibtex(text) {
                 return out;
             }
         }
-        return text.slice(start);
+        return fail("Unclosed quote", start - 1);
     };
     const readValue = () => {
         let out = "";
@@ -191,6 +202,8 @@ export function parseBibtex(text) {
         if (!head)
             continue;
         const type = head[1].toLowerCase();
+        const entryLine = lineAt(at);
+        where = { type, key: "", field: "" };
         i += head[0].length;
         const close = head[2] === "{" ? "}" : ")";
         if (type === "comment" || type === "preamble") {
@@ -219,11 +232,13 @@ export function parseBibtex(text) {
         const keyM = text.slice(i).match(/^[^,\s{}]*/);
         const key = keyM ? keyM[0] : "";
         i += key.length;
+        where.key = key;
         const fields = {};
         for (;;) {
             skipWs();
-            if (i >= n)
-                break;
+            if (i >= n) {
+                throw new Error(`Entry ${key || `@${type}`} starting on line ${entryLine} is never closed. Add a closing "${close}" at the end of it.`);
+            }
             if (text[i] === ",") {
                 i++;
                 continue;
@@ -242,7 +257,9 @@ export function parseBibtex(text) {
             if (text[i] !== "=")
                 continue;
             i++;
-            fields[nameM[0].toLowerCase()] = readValue();
+            where.field = nameM[0].toLowerCase();
+            fields[where.field] = readValue();
+            where.field = "";
         }
         entries.push(normalizeEntry({ type, key, fields }));
     }
@@ -280,11 +297,16 @@ const RIS_OUT = {
 export function parseRis(text) {
     const entries = [];
     let tags = [];
+    let startLine = 1;
+    let lineNo = 0;
     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);
+        if (!get("TY")) {
+            throw new Error(`The RIS record starting on line ${startLine} has no TY line. Every record must begin with "TY  - " and a type like JOUR.`);
+        }
         const ty = get("TY") ?? "GEN";
         const type = RIS_TYPES[ty] ?? "misc";
         const fields = {};
@@ -318,7 +340,10 @@ export function parseRis(text) {
         tags = [];
     };
     for (const line of text.split(/\r?\n/)) {
+        lineNo++;
         const m = line.match(/^([A-Z][A-Z0-9])\s{2}-\s?(.*)$/);
+        if (m && !tags.length)
+            startLine = lineNo;
         if (!m) {
             // A line that does not start with a tag continues the last value.
             if (tags.length && line.trim())
@@ -329,6 +354,7 @@ export function parseRis(text) {
             flush();
         else if (m[1] === "TY" && tags.length) {
             flush();
+            startLine = lineNo;
             tags.push([m[1], m[2].trim()]);
         }
         else
@@ -484,9 +510,90 @@ function initials(given) {
         .map((w) => (w.includes("-") ? w.split("-").map((p) => `${p[0].toUpperCase()}.`).join("-") : `${w[0].toUpperCase()}.`))
         .join(" ");
 }
-export function toText(entries) {
+function endWith(s) {
+    return /[.?!]$/.test(s) ? s : `${s}.`;
+}
+function mlaText(e) {
+    const f = e.fields;
+    const people = parseNames(f.author).map((n) => ({
+        first: n.literal || !n.given ? plain(n.family) : `${plain(n.family)}, ${plain(n.given)}`,
+        last: n.literal || !n.given ? plain(n.family) : `${plain(n.given)} ${plain(n.family)}`,
+    }));
+    let who = "";
+    if (people.length === 1)
+        who = people[0].first;
+    else if (people.length === 2)
+        who = `${people[0].first}, and ${people[1].last}`;
+    else if (people.length > 2)
+        who = `${people[0].first}, et al`;
+    const parts = [];
+    if (who)
+        parts.push(endWith(who));
+    const container = f.journal ?? f.booktitle;
+    if (f.title)
+        parts.push(container ? `"${endWith(plain(f.title))}"` : endWith(plain(f.title)));
+    const bits = [];
+    if (container)
+        bits.push(plain(container));
+    else if (f.publisher)
+        bits.push(plain(f.publisher));
+    if (container && f.volume)
+        bits.push(`vol. ${f.volume}`);
+    if (container && f.number)
+        bits.push(`no. ${f.number}`);
+    if (f.year)
+        bits.push(f.year);
+    if (container && f.pages)
+        bits.push(`pp. ${normalizePages(f.pages).replace("--", "-")}`);
+    if (bits.length)
+        parts.push(`${bits.join(", ")}.`);
+    if (f.doi)
+        parts.push(`https://doi.org/${f.doi}.`);
+    else if (f.url)
+        parts.push(`${f.url}.`);
+    return parts.join(" ");
+}
+function ieeeText(e, index) {
+    const f = e.fields;
+    const names = parseNames(f.author).map((n) => (n.literal || !n.given ? plain(n.family) : `${initials(plain(n.given))} ${plain(n.family)}`));
+    let who = "";
+    if (names.length === 1)
+        who = names[0];
+    else if (names.length === 2)
+        who = `${names[0]} and ${names[1]}`;
+    else if (names.length > 2)
+        who = `${names.slice(0, -1).join(", ")}, and ${names[names.length - 1]}`;
+    const container = f.journal ?? f.booktitle;
+    const title = f.title ? plain(f.title).replace(/[.,]$/, "") : "";
+    const bits = [];
+    if (container)
+        bits.push(plain(container));
+    else if (f.publisher)
+        bits.push(plain(f.publisher));
+    if (container && f.volume)
+        bits.push(`vol. ${f.volume}`);
+    if (container && f.number)
+        bits.push(`no. ${f.number}`);
+    if (container && f.pages)
+        bits.push(`pp. ${normalizePages(f.pages).replace("--", "-")}`);
+    if (f.year)
+        bits.push(f.year);
+    const head = [who, container && title ? `"${title},"` : title].filter(Boolean).join(", ");
+    let body = container && title ? `${head} ${bits.join(", ")}` : [head, bits.join(", ")].filter(Boolean).join(", ");
+    body = endWith(body.trim());
+    if (f.doi)
+        body += ` doi: ${f.doi}.`;
+    else if (f.url)
+        body += ` ${f.url}`;
+    return `[${index + 1}] ${body}`;
+}
+export function toText(entries, style = "apa") {
     return entries
-        .map((e) => {
+        .map((e, i) => {
+        if (style === "mla")
+            return mlaText(e);
+        if (style === "ieee")
+            return ieeeText(e, i);
         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 = "";
@@ -537,7 +644,7 @@ export function parseAny(text, format = "auto") {
     }
     return { format: fmt, entries };
 }
-export function serialize(entries, format) {
+export function serialize(entries, format, style = "apa") {
     switch (format) {
         case "bibtex":
             return toBibtex(entries);
@@ -546,7 +653,7 @@ export function serialize(entries, format) {
         case "csl_json":
             return toCslJson(entries);
         default:
-            return toText(entries);
+            return toText(entries, style);
     }
 }
 /* ---------- cite keys ---------- */

package/build/src/server.js

@@ -1,7 +1,7 @@
 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 const VERSION = "0.1.2";
 export function createServer() {
     const server = new McpServer({ name: "bibtex-reference-manager-mcp", version: VERSION });
     registerTools(server, tools, null);

package/build/src/tools.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { bullets } from "./core/tools.js";
-import { findDuplicates, lintEntries } from "./analyze.js";
+import { findDuplicates, fixEntries, 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
@@ -29,7 +29,7 @@ function plural(n, word) {
 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.",
+    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. Example: text \"@article{k1, AUTHOR = {John Smith and Jane Doe}, title={Deep Learning for Graphs}, year={2024}}\" returns one entry with authors [\"Smith, John\", \"Doe, Jane\"] and lower case field names. Leave format out unless auto picks the wrong one.",
     inputSchema: { text, format },
     outputSchema: {
         format: z.string().describe("The format that was read: bibtex, ris or csl_json."),
@@ -48,11 +48,15 @@ const parseBibliography = {
 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.",
+    description: "Convert a reference list between BibTeX, RIS, CSL JSON and plain text (a simple reference list style, APA by default, or MLA or IEEE when you pass style). The input format is detected unless you pass it. Page ranges, DOIs and names are cleaned on the way. Example: text is a BibTeX entry and to is \"ris\", and output is the same reference as RIS. Set from only to override detection.",
     inputSchema: {
         text,
         to: z.enum(["bibtex", "ris", "csl_json", "text"]).describe("The format to write."),
         from: format,
+        style: z
+            .enum(["apa", "mla", "ieee"])
+            .optional()
+            .describe("The citation style for the text output: apa, mla or ieee. Defaults to apa. Ignored for the other formats."),
     },
     outputSchema: {
         from: z.string().describe("The format that was read."),
@@ -64,7 +68,7 @@ const convertBibliography = {
         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);
+        const output = serialize(entries, a.to, a.style ?? "apa");
         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 },
@@ -74,7 +78,7 @@ const convertBibliography = {
 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.",
+    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. Example: two entries with the same DOI, one with 3 fields and one with 6, give one group that keeps the entry with 6 fields and lists the other under remove. Your files are not changed.",
     inputSchema: {
         text,
         format,
@@ -121,7 +125,7 @@ const dedupeEntries = {
 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.",
+    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. Example: an @article with no journal field gives an issue with the rule missing-field and the field journal. Pass the whole list as text so repeated keys can be found.",
     inputSchema: { text, format },
     outputSchema: {
         count: z.number().describe("How many entries were checked."),
@@ -147,10 +151,39 @@ const lintEntriesTool = {
         };
     },
 };
+const fixEntriesTool = {
+    name: "fix_entries",
+    title: "Fix entries",
+    description: "Apply the safe fixes that lint_entries points to and return the cleaned list as BibTeX: page ranges with one hyphen get a double hyphen, titles that start with a lower case letter or are all lower case get capitals (words inside braces are left alone), and DOIs written as a link or with a doi: prefix become bare DOIs. Missing fields, backwards page ranges and DOIs that are not valid are not guessed, so run lint_entries on the result. Example: pages \"12-15\" becomes \"12--15\". Your files are not changed.",
+    inputSchema: { text, format },
+    outputSchema: {
+        count: z.number().describe("How many entries were read."),
+        fixed: z.number().describe("How many changes were made."),
+        fixes: z.array(z.object({
+            key: z.string(),
+            field: z.enum(["pages", "title", "doi"]),
+            from: z.string(),
+            to: z.string(),
+        })),
+        bibtex: z.string().describe("The cleaned list as BibTeX."),
+    },
+    run: async (a) => {
+        const { entries } = parseAny(a.text, a.format ?? "auto");
+        if (!entries.length)
+            throw new Error("No entries were found in the text, so there is nothing to fix.");
+        const { entries: cleaned, fixes } = fixEntries(entries);
+        const bibtex = toBibtex(cleaned);
+        const lines = fixes.map((f) => `${f.key}: ${f.field} "${f.from}" becomes "${f.to}"`);
+        return {
+            text: `Checked ${plural(entries.length, "entry")} and made ${plural(fixes.length, "change")}.\n${bullets(lines, "Nothing needed fixing.")}\n\n${bibtex}`,
+            structured: { count: entries.length, fixed: fixes.length, fixes, bibtex },
+        };
+    },
+};
 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.",
+    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. Example: an entry with key old1, author \"Smith, John\", year 2024 and title \"Deep Learning for Graphs\" gives old_key old1 and new_key smith2024deep, or smith2024 when include_title_word is false.",
     inputSchema: {
         text,
         format,
@@ -177,4 +210,4 @@ const generateCiteKeys = {
         };
     },
 };
-export const tools = [parseBibliography, convertBibliography, dedupeEntries, lintEntriesTool, generateCiteKeys];
+export const tools = [parseBibliography, convertBibliography, dedupeEntries, lintEntriesTool, fixEntriesTool, generateCiteKeys];

package/llms.txt

@@ -1,6 +1,6 @@
 # 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.
+> 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.2.
 
 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.
 
@@ -23,22 +23,181 @@ MCP config for Claude Desktop, Cursor and similar apps:
 
 Needs Node.js 20 or newer.
 
+## Why this server
+
+It works on pasted text, not on a live library. It needs no account, API key or internet, and sends nothing anywhere. It does not connect to Zotero or Mendeley; the user exports a file and pastes it in, so any reference manager that writes BibTeX, RIS or CSL JSON works. The work is done by code, so results are the same each time. All tools are read only.
+
+## Exporting from Zotero or Mendeley
+
+1. In Zotero, right click a collection or select items, choose the export option and pick BibTeX or RIS. In Mendeley, select references, choose Export and pick BibTeX or RIS.
+2. Copy the contents of the saved .bib or .ris file, or attach the file.
+3. Pass it as the `text` argument. The format is detected, or pass `format`.
+4. Return the result to the user. To get it back into their reference manager, they save it as .bib or .ris and import it.
+
 ## 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.
+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. Every tool returns both a readable answer and structured fields.
 
-- 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.
+### parse_bibliography
+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".
 
-## Example prompts
+Inputs:
+- text (required): the reference list
+- format (optional): auto, bibtex, ris, or csl_json
+
+Example input (BibTeX):
+```bibtex
+@article{smith2024,
+  AUTHOR = {John Smith and Jane Doe},
+  title={Deep Learning for Graphs},
+  year={2024},
+  doi = {https://doi.org/10.1000/abc123},
+  journal = {J Graph Learn}
+}
+```
+
+Example result:
+- format: bibtex
+- count: 1
+- entries[0].authors: ["Smith, John", "Doe, Jane"]
+- entries[0].fields.doi: "10.1000/abc123"
+- entries[0].fields.year: "2024"
+
+Notes: leave format out unless auto picks the wrong one. If the text cannot be read, the tool returns an error asking for the format to be passed.
 
+### convert_bibliography
+Convert between BibTeX, RIS, CSL JSON and plain text. For plain text, pass style as apa (the default), mla or ieee to get a formatted reference list. Input format is detected unless passed. Page ranges become 12--15 in BibTeX. DOIs and names are cleaned on the way.
+
+Inputs:
+- text (required): the reference list
+- to (required): bibtex, ris, csl_json, or text
+- from (optional): auto, bibtex, ris, or csl_json
+
+Example 1: BibTeX to RIS
+Input text is BibTeX. to: "ris". Output contains RIS tags like TY, AU, TI, PY, DO and ER  - .
+
+Example 2: RIS to BibTeX
+RIS entries convert to BibTeX. Page ranges like 100-112 become pages = {100--112}.
+
+Example 3: CSL JSON to plain text
+Produces lines like "Garcia, L., & World Health Organization. (2022). Remote learning outcomes."
+
+Example 4: BibTeX to CSL JSON
+Returns a JSON array of items.
+
+If there are no entries, the tool returns an error that says so.
+
+### dedupe_entries
+Find duplicate references by matching DOI, by the same cite key, and by similar titles (years must not clash). For each group it 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.
+
+Inputs:
+- text (required): the reference list
+- format (optional): auto, bibtex, ris, or csl_json
+- title_threshold (optional): 0.5 to 1, default 0.9
+
+How matching works:
+- DOI match: normalizes DOI (strips https://doi.org/) and matches case insensitively
+- key match: matches cite keys ignoring case
+- title match: lowercases, drops punctuation and accents, compares pairs of letters. Two entries with different years are not matched by title
+
+Example: two entries with the same DOI, one with 3 fields and one with 6. The group keeps the entry with 6 fields and lists the other under remove. The deduplicated_bibtex omits the removed copy.
+
+If loose titles should match, lower title_threshold (e.g. 0.8). If there are no duplicates, the tool reports no duplicates found and returns the full list.
+
+### lint_entries
+Check a reference list for problems. Each issue gives key, rule, severity, field (if any), and message.
+
+Inputs:
+- text (required): the reference list
+- format (optional): auto, bibtex, ris, or csl_json
+
+Rules:
+- missing-field: required fields missing for the entry type. Checked types: article, book, inproceedings, incollection, phdthesis, mastersthesis, techreport, unpublished, misc, online. Other types need a title. For example @article needs journal; @book needs author.
+- bad-pages: page ranges that run backwards, use one hyphen, or are not numbers. Use double hyphen for ranges.
+- uncapitalized-title: titles that start with a lower case letter (protected capitals in {DNA} are allowed)
+- invalid-doi: DOI does not look like 10.xxxx/something (DOIs are not looked up online)
+- bad-year: year is not a normal year value
+- duplicate-key: the same cite key appears more than once
+
+Example issues:
+- bad1: missing-field on journal (error)
+- bad1: uncapitalized-title (warning)
+- bad1: invalid-doi (warning)
+- bad1: bad-year (warning)
+- bad2: bad-pages because single hyphen (warning)
+- bad3: missing-field on author and bad-pages (errors/warnings)
+- dup: duplicate-key (error)
+
+Pass the whole list so repeated keys can be found. A clean list returns no problems found.
+
+### fix_entries
+Apply the safe fixes that lint_entries points to and return the cleaned list as BibTeX, plus a list of each change (key, field, from, to).
+
+Inputs:
+- text (required): the reference list
+- format (optional): auto, bibtex, ris, or csl_json
+
+Fixes:
+- pages: a single hyphen range like 12-15 becomes 12--15
+- title: a title that starts with a lower case letter gets a capital; a title with every word in lower case gets capitals on the main words. Text inside braces is left alone
+- doi: a link or doi: prefix is removed, leaving the bare DOI
+
+Not fixed: missing fields, backwards page ranges, bad years, repeated keys and DOIs that are not valid. Run lint_entries on the result to see what is left. The list is returned as text, no file is changed.
+
+### generate_cite_keys
+Create consistent cite keys from the first author's family name, the year, and the first meaningful word of the title. Repeated keys get a letter added.
+
+Inputs:
+- text (required): the reference list
+- format (optional): auto, bibtex, ris, or csl_json
+- include_title_word (optional): add the first meaningful title word (default true)
+
+Behavior:
+- Uses first author's family name, normalized (accents removed)
+- Uses year if present
+- If include_title_word is true, uses first meaningful title word
+- If no author, uses anon plus year and title word
+- Repeats get a letter: smith2024, smith2024a, smith2024b
+- Returns old and new keys for each entry and the list as BibTeX with new keys
+
+Examples:
+- Smith, John, 2024, "Deep learning for sequencing" -> smith2024deep
+- Same author/year/title start -> smith2024deepa
+- Muller with umlaut -> muller2019art
+- No author -> keys based on anon and title
+
+## Workflows
+
+### Clean up a Zotero or Mendeley export
+1. Export from Zotero or Mendeley as BibTeX or RIS
+2. Pass to lint_entries to find problems
+3. Pass to dedupe_entries to remove duplicates
+4. Pass to generate_cite_keys to make consistent keys
+5. Use convert_bibliography if the target format differs
+
+Example sequence with text from an export:
+- lint_entries on the raw list shows missing fields and bad page ranges
+- dedupe_entries returns deduplicated_bibtex with duplicates removed
+- generate_cite_keys on the cleaned list returns bibtex with new keys
+
+### Convert between formats
+1. parse_bibliography to inspect normalized entries
+2. convert_bibliography with to set to target format (bibtex, ris, csl_json, or text)
+3. Page ranges become 12--15 in BibTeX. Protected capitals in braces are kept in BibTeX output
+
+### Check before submitting
+1. Run lint_entries to catch missing required fields, bad pages, bad DOIs, bad years, repeated keys
+2. Fix issues in the source or regenerate
+3. Run dedupe_entries to ensure no duplicates remain
+4. Optionally rename keys with generate_cite_keys
+
+## 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."
+- "Parse this list and show me normalized authors and DOIs."
+- "Deduplicate this mixed list using a looser title match."
 
 ## FAQ
 
@@ -50,6 +209,10 @@ What happens with an empty list or text it cannot place? The tool returns an err
 
 Which entry types are checked for required fields? article, book, inproceedings, incollection, phdthesis, mastersthesis, techreport, unpublished, misc and online. Other types need a 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.
+
+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.
+
 ## Links
 
 - Source: https://github.com/AnonymousOnyx22/bibtex-reference-manager-mcp

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "bibtex-reference-manager-mcp",
-  "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.",
+  "version": "0.1.2",
+  "description": "BibTeX reference manager MCP server for students writing LaTeX theses and papers. Ask your AI app to fix a broken .bib file, clean a Zotero export or Mendeley export, convert EndNote RIS to BibTeX, remove duplicates, check DOIs and make consistent cite keys for your thesis bibliography. Also reads CSL JSON. Works offline with no account.",
   "type": "module",
   "main": "build/src/index.js",
   "bin": {
@@ -35,11 +35,17 @@
     "bibtex cleaner",
     "bibtex converter",
     "bib file",
+    "fix bib file",
+    "latex bibliography",
+    "thesis bibliography",
+    "zotero export",
+    "mendeley export",
+    "endnote ris",
+    "ris to bibtex",
     "ris",
     "ris converter",
     "csl json",
     "citation",
-    "citations",
     "references",
     "bibliography",
     "reference manager",
@@ -61,11 +67,19 @@
     "model-context-protocol",
     "bibtex-reference-manager-mcp",
     "student",
-    "students",
     "university",
-    "education",
     "claude",
-    "cursor"
+    "cursor",
+    "bibtex reference manager mcp",
+    "master thesis bibtex",
+    "phd thesis bibliography",
+    "thesis citations",
+    "references for thesis",
+    "literature review bibtex",
+    "research paper citations",
+    "cite references latex",
+    "bibliography for thesis",
+    "academic references"
   ],
   "author": "AnonymousOnyx22",
   "license": "MIT",