bibtex-reference-manager-mcp 0.1.1 → 0.1.3

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 0.1.3
+
+- `lint_entries` now flags a raw `&`, `%`, `_` or `#` in titles, journal names and similar text fields, with the new rule `unescaped-character`, since these often stop a .bib file from compiling. Existing rules are unchanged.
+
+- `generate_cite_keys` takes an optional `show_bibtex`. When true, the text reply also lists the full entries with the new keys, so you can paste them into your .bib file. The existing output is unchanged.
+
+- `convert_bibliography` now accepts `chicago` and `harvard` for `style`, next to `apa`, `mla` and `ieee`. Chicago is the bibliography form with the author first. The existing styles are unchanged.
+
+- `fix_entries` now wraps acronyms like DNA, NASA and iOS in braces, as in `{DNA}`, when it fixes the capitalization of a title, so BibTeX styles keep their case. The new `protected_titles` list shows which words were wrapped. The existing output is unchanged.
+
+- `dedupe_entries` takes an optional `merge_duplicates`. When true, the result has a `merged` list that shows the fields only the removed copies had (like doi or pages) next to the kept entry. The existing output is unchanged.
+
+- When the format cannot be detected, the error now lists the accepted formats with a small BibTeX, RIS and CSL JSON example, and says so when the text is only a list of DOIs or URLs.
+
+## 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.

package/README.md

@@ -139,9 +139,10 @@ The format is detected for you. If a file is not recognized, say which format it
 | 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`, `ieee`, `chicago` or `harvard` 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. |
+| `lint_entries` | Flags missing required fields, bad page ranges, uncapitalized titles, invalid DOIs, odd years, repeated keys and unescaped `&`, `%`, `_` or `#` in titles and journal names. |
+| `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.
@@ -154,7 +155,7 @@ Every tool takes the reference list as `text`, and every tool returns both a rea
 
 ## Common workflows
 
-These show how the five tools fit together. All of them take the reference list as `text` and are read only.
+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
 
@@ -173,7 +174,7 @@ These show how the five tools fit together. All of them take the reference list
 ### Check a finished .bib before you hand it in
 
 1. Run `parse_bibliography` to normalize.
-2. Run `lint_entries` and fix what it flags.
+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
@@ -200,7 +201,7 @@ 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
 

package/build/src/analyze.js

@@ -124,6 +124,17 @@ export function pageProblem(pages) {
         return "the range has more than two page numbers";
     return `"${p}" is not a page number or a range like 12--15`;
 }
+const TEXT_FIELDS = ["title", "booktitle", "journal", "publisher", "series", "school", "institution", "address"];
+// Characters LaTeX stops on when they are not written as \&, \%, \_ or \#. Math between $ signs is skipped.
+function unescapedChars(value) {
+    const text = value.replace(/\\\\/g, "").replace(/\$[^$]*\$/g, "");
+    const found = [];
+    for (const c of ["&", "%", "_", "#"]) {
+        if (new RegExp(`(?<!\\\\)\\${c}`).test(text))
+            found.push(c);
+    }
+    return found;
+}
 export function lintEntries(entries) {
     const issues = [];
     const seen = new Map();
@@ -159,6 +170,15 @@ export function lintEntries(entries) {
                 add("uncapitalized-title", "warning", `Every word of the title is lower case: "${plain(f.title)}".`, "title");
             }
         }
+        for (const name of TEXT_FIELDS) {
+            const value = f[name];
+            if (!value)
+                continue;
+            const found = unescapedChars(value);
+            if (found.length) {
+                add("unescaped-character", "error", `The ${name} has ${found.map((c) => `an unescaped ${c}`).join(" and ")}. Write \\${found.join(" and \\")} so LaTeX can compile it.`, name);
+            }
+        }
         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");
         }
@@ -167,3 +187,65 @@ export function lintEntries(entries) {
     }
     return issues;
 }
+// Words like DNA, NASA, iOS or mRNA: BibTeX styles would lower case them without braces.
+const ACRONYM = /^([("'[]*)([A-Z]{2,}s?|[a-z]+[A-Z][A-Za-z]*)([)"'\].,;:!?]*)$/;
+function capitalizeTitle(title) {
+    const raw = title.trim();
+    const protectedWords = [];
+    const firstOnly = /^[a-z]/.test(raw);
+    let depth = 0;
+    let first = true;
+    const out = raw
+        .split(/(\s+)/)
+        .map((word) => {
+        const inBraces = depth > 0 || word.startsWith("{");
+        for (const c of word)
+            depth += c === "{" ? 1 : c === "}" ? -1 : 0;
+        const isWord = word.trim() !== "";
+        const wasFirst = isWord && first;
+        if (isWord)
+            first = false;
+        if (inBraces)
+            return word;
+        const m = ACRONYM.exec(word);
+        if (m) {
+            protectedWords.push(m[2]);
+            return `${m[1]}{${m[2]}}${m[3]}`;
+        }
+        if (firstOnly)
+            return wasFirst ? word.replace(/^[a-z]/, (c) => c.toUpperCase()) : word;
+        if (SMALL_WORDS.has(word.toLowerCase()))
+            return word;
+        return word.replace(/^[a-z]/, (c) => c.toUpperCase());
+    })
+        .join("");
+    return { title: out, protectedWords };
+}
+export function fixEntries(entries) {
+    const fixes = [];
+    const protectedTitles = [];
+    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")) {
+            const cap = capitalizeTitle(f.title);
+            set("title", cap.title);
+            if (cap.protectedWords.length)
+                protectedTitles.push({ key: e.key, words: cap.protectedWords });
+        }
+        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, protectedTitles };
+}

package/build/src/bib.js

@@ -86,7 +86,16 @@ export function detectFormat(text) {
         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.");
+    const looksLikeIds = t.split(/\s+/).every((w) => /^(https?:\/\/\S+|(doi:)?10\.\d{4,9}\/\S+)$/i.test(w));
+    const hint = looksLikeIds
+        ? "This looks like a list of DOIs or URLs. This server does not look them up online, so paste the reference entries instead.\n"
+        : "This looks like plain text. Paste the reference entries in one of the formats below, or pass format.\n";
+    throw new Error("Could not tell the format. " +
+        hint +
+        "Accepted formats are bibtex, ris and csl_json. Examples:\n" +
+        "bibtex:\n@article{smith2020, author = {Smith, Jane}, title = {A title}, journal = {A Journal}, year = {2020}}\n" +
+        "ris:\nTY  - JOUR\nAU  - Smith, Jane\nTI  - A title\nJO  - A Journal\nPY  - 2020\nER  - \n" +
+        'csl_json:\n[{"id":"smith2020","type":"article-journal","title":"A title","author":[{"family":"Smith","given":"Jane"}],"container-title":"A Journal","issued":{"date-parts":[[2020]]}}]');
 }
 /* ---------- entry normalizing ---------- */
 const TYPE_ALIASES = {
@@ -510,9 +519,171 @@ 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}`;
+}
+function chicagoText(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 > 1) {
+        const rest = people.slice(1).map((p) => p.last);
+        who = `${people[0].first}, ${rest.length > 1 ? `${rest.slice(0, -1).join(", ")}, and ${rest[rest.length - 1]}` : `and ${rest[0]}`}`;
+    }
+    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)));
+    if (container) {
+        let c = plain(container);
+        if (f.volume)
+            c += ` ${f.volume}`;
+        if (f.number)
+            c += `, no. ${f.number}`;
+        if (f.year)
+            c += ` (${f.year})`;
+        if (f.pages)
+            c += `: ${normalizePages(f.pages).replace("--", "-")}`;
+        parts.push(`${c}.`);
+    }
+    else {
+        const pub = [f.address ? plain(f.address) : "", f.publisher ? plain(f.publisher) : ""].filter(Boolean).join(": ");
+        const tail = [pub, f.year].filter(Boolean).join(", ");
+        if (tail)
+            parts.push(`${tail}.`);
+    }
+    if (f.doi)
+        parts.push(`https://doi.org/${f.doi}.`);
+    else if (f.url)
+        parts.push(`${f.url}.`);
+    return parts.join(" ");
+}
+function harvardText(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(", ")} and ${names[names.length - 1]}`;
+    const container = f.journal ?? f.booktitle;
+    const title = f.title ? plain(f.title).replace(/[.,]$/, "") : "";
+    let out = `${who ? `${who} ` : ""}(${f.year ?? "n.d."})`;
+    if (title)
+        out += container ? ` '${title}',` : ` ${title}.`;
+    if (container) {
+        let c = plain(container);
+        if (f.volume)
+            c += `, ${f.volume}`;
+        if (f.number)
+            c += `(${f.number})`;
+        if (f.pages)
+            c += `, pp. ${normalizePages(f.pages).replace("--", "-")}`;
+        out += ` ${c}.`;
+    }
+    else {
+        const pub = [f.address ? plain(f.address) : "", f.publisher ? plain(f.publisher) : ""].filter(Boolean).join(": ");
+        if (pub)
+            out += ` ${pub}.`;
+    }
+    if (f.doi)
+        out += ` doi:${f.doi}.`;
+    else if (f.url)
+        out += ` Available at: ${f.url}`;
+    return out;
+}
+export function toText(entries, style = "apa") {
     return entries
-        .map((e) => {
+        .map((e, i) => {
+        if (style === "mla")
+            return mlaText(e);
+        if (style === "chicago")
+            return chicagoText(e);
+        if (style === "harvard")
+            return harvardText(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 = "";
@@ -563,7 +734,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);
@@ -572,7 +743,7 @@ export function serialize(entries, format) {
         case "csl_json":
             return toCslJson(entries);
         default:
-            return toText(entries);
+            return toText(entries, style);
     }
 }
 /* ---------- cite keys ---------- */
@@ -602,3 +773,25 @@ export function uniqueKey(base, used) {
             return base + suffix;
     }
 }
+/* ---------- LaTeX citations ---------- */
+const CITE_COMMAND = /\\[a-zA-Z]*cite[a-zA-Z]*\*?\s*(?:\[[^\]]*\]\s*)*\{([^}]*)\}/g;
+/**
+ * Pulls cite keys out of \cite, \citep, \citet, \parencite, \autocite and
+ * similar commands, including lists like \cite{a,b} and optional arguments.
+ * Keys come back once each, in order of first use. Commented text is skipped.
+ */
+export function extractCiteKeys(tex) {
+    const text = tex.replace(/(^|[^\\])%.*$/gm, "$1");
+    const seen = new Set();
+    const keys = [];
+    for (const m of text.matchAll(CITE_COMMAND)) {
+        for (const raw of m[1].split(",")) {
+            const key = raw.trim();
+            if (key && !seen.has(key)) {
+                seen.add(key);
+                keys.push(key);
+            }
+        }
+    }
+    return 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.1";
+export const VERSION = "0.1.3";
 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
@@ -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. Example: text is a BibTeX entry and to is \"ris\", and output is the same reference as RIS. Set from only to override detection.",
+    description: "Convert a reference list between BibTeX, RIS, CSL JSON and plain text (a simple reference list style, APA by default, or MLA, IEEE, Chicago or Harvard 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", "chicago", "harvard"])
+            .optional()
+            .describe("The citation style for the text output: apa, mla, ieee, chicago or harvard. 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 },
@@ -84,6 +88,10 @@ const dedupeEntries = {
             .max(1)
             .optional()
             .describe("How alike two titles must be to count as the same, from 0.5 to 1. Defaults to 0.9."),
+        merge_duplicates: z
+            .boolean()
+            .optional()
+            .describe("Set to true to also return a merged list that shows, for each group, the fields only the removed copies had, like doi or pages. The kept entry's own fields are never changed. Defaults to false."),
     },
     outputSchema: {
         total: z.number().describe("How many entries were read."),
@@ -95,10 +103,33 @@ const dedupeEntries = {
             remove: z.array(z.string()),
         })),
         deduplicated_bibtex: z.string().describe("The list as BibTeX without the removed copies."),
+        merged: z
+            .array(z.object({
+            key: z.string().describe("The cite key of the kept entry."),
+            added_fields: z.record(z.string(), z.string()).describe("Fields that only the removed copies had, with the value taken from the first copy that has it."),
+            fields: z.record(z.string(), z.string()).describe("The kept entry's fields plus the added ones."),
+        }))
+            .optional()
+            .describe("Only present when merge_duplicates is true: one item per group showing the merged fields."),
     },
     run: async (a) => {
         const { entries } = parseAny(a.text, a.format ?? "auto");
         const groups = findDuplicates(entries, a.title_threshold ?? 0.9);
+        const merged = a.merge_duplicates
+            ? groups.map((g) => {
+                const fields = { ...entries[g.keepIndex].fields };
+                const added = {};
+                for (const i of g.indexes) {
+                    if (i === g.keepIndex)
+                        continue;
+                    for (const [name, value] of Object.entries(entries[i].fields)) {
+                        if (value && !fields[name])
+                            fields[name] = added[name] = value;
+                    }
+                }
+                return { key: g.keep, added_fields: added, fields };
+            })
+            : undefined;
         const drop = new Set();
         for (const g of groups) {
             for (const i of g.indexes)
@@ -114,6 +145,7 @@ const dedupeEntries = {
                 unique: kept.length,
                 groups: groups.map(({ keys, reasons, keep, remove }) => ({ keys, reasons, keep, remove })),
                 deduplicated_bibtex: toBibtex(kept),
+                ...(merged ? { merged } : {}),
             },
         };
     },
@@ -121,7 +153,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. 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.",
+    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, repeated keys and unescaped &, %, _ or # in titles, journal names and other text fields (rule unescaped-character). 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."),
@@ -129,7 +161,7 @@ const lintEntriesTool = {
         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"]),
+            rule: z.enum(["missing-field", "bad-pages", "uncapitalized-title", "invalid-doi", "bad-year", "duplicate-key", "unescaped-character"]),
             severity: z.enum(["error", "warning"]),
             field: z.string().optional(),
             message: z.string(),
@@ -147,6 +179,38 @@ 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 acronyms like DNA, NASA or iOS in those titles are wrapped as {DNA} so BibTeX keeps their case; they are listed in protected_titles), 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."),
+        protected_titles: z
+            .array(z.object({ key: z.string(), words: z.array(z.string()) }))
+            .describe("Acronyms wrapped in braces, like DNA, in titles that got a capitalization fix."),
+    },
+    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, protectedTitles } = 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, protected_titles: protectedTitles },
+        };
+    },
+};
 const generateCiteKeys = {
     name: "generate_cite_keys",
     title: "Generate cite keys",
@@ -155,6 +219,7 @@ const generateCiteKeys = {
         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."),
+        show_bibtex: z.boolean().optional().describe("Also print the full entries with the new keys in the text reply, ready to paste into a .bib file. Defaults to false."),
     },
     outputSchema: {
         count: z.number(),
@@ -171,10 +236,12 @@ const generateCiteKeys = {
         });
         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}`));
+        const bibtex = toBibtex(renamed);
+        const head = `Made ${plural(keys.length, "cite key")}.\n${bullets(lines, "No entries were found.")}`;
         return {
-            text: `Made ${plural(keys.length, "cite key")}.\n${bullets(lines, "No entries were found.")}`,
-            structured: { count: keys.length, keys, bibtex: toBibtex(renamed) },
+            text: a.show_bibtex && keys.length ? `${head}\n\n${bibtex}` : head,
+            structured: { count: keys.length, keys, bibtex },
         };
     },
 };
-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.1.
+> 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.3.
 
 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.
 
@@ -66,7 +66,7 @@ Example result:
 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 (a simple author, year, title style). Input format is detected unless passed. Page ranges become 12--15 in BibTeX. DOIs and names are cleaned on the way.
+Convert between BibTeX, RIS, CSL JSON and plain text. For plain text, pass style as apa (the default), mla, ieee, chicago or harvard 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
@@ -94,6 +94,7 @@ Inputs:
 - text (required): the reference list
 - format (optional): auto, bibtex, ris, or csl_json
 - title_threshold (optional): 0.5 to 1, default 0.9
+- merge_duplicates (optional): true adds a merged list. For each group it shows the fields only the removed copies had (like doi or pages) and the kept entry's fields with those added. Existing fields are never changed.
 
 How matching works:
 - DOI match: normalizes DOI (strips https://doi.org/) and matches case insensitively
@@ -118,6 +119,7 @@ Rules:
 - 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
+- unescaped-character: a raw &, %, _ or # in title, booktitle, journal, publisher, series, school, institution or address (text between $ signs is skipped). Write \&, \%, \_ or \# instead.
 
 Example issues:
 - bad1: missing-field on journal (error)
@@ -130,6 +132,20 @@ Example issues:
 
 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.
 
@@ -137,6 +153,7 @@ 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)
+- show_bibtex (optional): also print the full entries with the new keys in the text reply (default false)
 
 Behavior:
 - Uses first author's family name, normalized (accents removed)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bibtex-reference-manager-mcp",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "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",