bibtex-reference-manager-mcp 0.1.1 → 0.1.2

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # 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.

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` 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.
@@ -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

@@ -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

@@ -510,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 = "";
@@ -563,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);
@@ -572,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.1";
+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
@@ -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 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 },
@@ -147,6 +151,35 @@ 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",
@@ -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.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.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.
 
@@ -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 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
@@ -130,6 +130,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.
 

package/package.json

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