LaTeX MCP Server

1# LaTeX MCP Server
2 
3An **MCP (Model Context Protocol) server** that can supercharge your VSCode + LaTex Workshop writing workflow
4 
5Currently houses MCP tools, and new tools can be easily added in either Python and TypeScript. The Python process is the MCP server; selected tools are delegated to a small Node/TypeScript module via a bridge.
6 
7## LaTex MCP Server + Copilot/Claude/Cursor, what can you do?
8- Read your cited papers, verify / add onto your claims
9- Access your python scripts to generate new figures / latex tables based on your experiment data, and **place them into latex autonomously** 
10- Can verify every step and ensure your pdf compiles 
11- Functionally it can autonomously take your outline + experimental results and turn it into a paper (may looks like slop though)
12 
13<p align="center">
14  <video src="./docs/demo/minimal.mp4" controls width="600">
15    Your browser does not support the video tag.
16  </video>
17</p>
18 
19 
20 
21---
22 
23### Python Tools
24 
25- **list_tex_files**  
26  Lists all `.tex` files under your LaTeX workspace (relative paths). Useful for LLMs or agents to discover available chapters and sections.
27 
28- **read_file**  
29  Reads a text or binary-safe slice of a file given a relative path inside the workspace. Supports specifying a maximum number of bytes to return.
30 
31- **extract_bibliography**  
32  Parses a BibTeX file and returns structured entry metadata, including download URLs (DOI, arXiv). Helps agents or scripts work with citation data programmatically.
33 
34- **download_bibliography**  
35  Downloads PDFs for bibliography entries listed in `resources/cited_papers/index.json`. Can force re-downloads and limit the number of new downloads.
36 
37- **compile_latex**  
38  Runs LaTeX compilation (`pdflatex`/`xelatex` via `latexmk`) on the main document and returns success plus a log snippet. Supports specifying the entry `.tex` file and number of passes.
39 
40- **read_pdf**  
41  Extracts text and metadata from a PDF filepath using `pypdf`, with page and character limits. Stores a JSON artifact for downstream use.
42 
43- **read_pdf_from_citation**  
44  Resolves a citation key via `resources/cited_papers/index.json` to its PDF and extracts text (auto-downloads if needed). Returns extracted text, metadata, and the citation key.
45 
46---
47 
48### TypeScript Bridge Tools
49 
50- **summarize_text**  
51  Produces a concise natural language summary of provided LaTeX or text content. Accepts a maximum sentence count for the summary.
52 
53- **suggest_bib_key**  
54  Suggests a stable BibTeX key based on authors, year, and title metadata. Useful for generating consistent citation keys.
55 
56---
57 
58## Install (with `uv`)
59 
60From the repository root:
61 
62```bash
63cd latex-mcp-server
64uv tool install -e .
65```
66or
67```
68uv tool install -e ./latex-mcp-server
69```
70 
71This will make the console script `latex-mcp-server` available on your PATH.
72 
73> If you prefer a one-off run without installing as a tool:
74>
75> ```bash
76> uv run latex-mcp-server
77> ```
78 
79## MCP Configuration Snippet
80 
81Add to your `mcp.json` (VS Code / Claude Desktop user settings):
82 
83```jsonc
84"latex-mcp-server": {
85  "command": "uv",
86  "args": ["tool", "run", "latex-mcp-server", "--workspace", "ABSOLUTE_PATH_TO_YOUR_PROJECT_ROOT"]
87}
88```
89 
90If you omit `--workspace`, the server will infer the current working directory.
91 
92### Windows example
93 
94On Windows (PowerShell / Bash), if your paper_1 root is at `C:\Users\User\projects\paper_1`, use:
95 
96```jsonc
97"latex-mcp-server": {
98  "command": "uv",
99  "args": [
100    "tool", "run", "latex-mcp-server",
101    "--workspace", "C:/Users/User/projects/paper_1"
102  ]
103}
104```
105 
106Forward slashes are fine; they avoid the need to escape backslashes. Be sure to replace the placeholder `ABSOLUTE_PATH_TO_YOUR_PAPER_1_ROOT` — leaving a placeholder like `WORKSPACE_FOLDER_PATH` will cause the runtime error:
107 
108```
109Workspace does not exist: C:\Users\User\WORKSPACE_FOLDER_PATH\PAPER_1
110```
111 
112### Alternative: Install once, then call directly
113 
114After running:
115 
116```bash
117cd latex-mcp-server
118uv tool install -e .
119```
120 
121You can simplify the config to:
122 
123```jsonc
124"latex-mcp-server": {
125  "command": "latex-mcp-server",
126  "args": ["--workspace", "C:/Users/User/projects/paper_1"]
127}
128```
129 
130### Troubleshooting
131 
132| Symptom | Cause | Fix |
133|---------|-------|-----|
134| `No solution found when resolving tool dependencies` | The tool name `latex-mcp-server` isn’t published on PyPI and `uv` tried to resolve it as a dependency (often happens if you used a config field like `requires` or didn’t install locally) | Run `uv tool install -e ./latex-mcp-server` from repo root, then update your `mcp.json` to invoke the installed script directly |
135| `Workspace does not exist: C:\\Users\\...WORKSPACE_FOLDER_PATH...` | Placeholder path left unchanged | Replace with the real absolute path |
136| `TypeScript runtime unavailable` in tool results | Node.js not installed (only needed for TS bridge tools) | Install Node.js 18+ or ignore if you don’t need TS tools |
137 
138If you change TypeScript sources, rebuild and re-vendor (`npm run build`) before restarting the server.
139 
140## TypeScript Bridge
141 
142The TypeScript sources live in `ts_functions/src`. Their compiled JavaScript output is vendored into the Python package under `latex_mcp_server/ts_dist` so users do **not** need `npm` or `tsc` just to run the server. To modify or add TS functions:
143 
144```bash
145cd latex-mcp-server/ts_functions
146npm install
147npm run build
148```
149 
150Then copy (or allow the provided helper script to sync) the `dist/` contents into `latex_mcp_server/ts_dist/`.
151 
152## Adding New Python Tools
153 
154Add functions in `latex_mcp_server/functions/latex_ops.py` (or new modules) and register them in `server.py` inside `register_python_tools`.
155 
156### Citation-Aware PDF Reading
157 
158When a user asks about a paper (e.g. “Explain how \cite{smith2023model} differs from …”), the agent should:
159 
1601. Parse citation key(s) from the request.
1612. Call `read_pdf_from_citation` for each key (fetches / downloads PDF and extracts text snippet + metadata).
1623. Ground its answer on the extracted text (and optionally call `summarize_text` for a concise summary).
1634. Indicate if extraction was truncated (check the `truncated` flag) and avoid over-claiming beyond available pages/characters.
164 
165The `read_pdf_from_citation` tool returns the same schema as `read_pdf` plus `citation_key` so multi-citation responses can attribute snippets correctly.
166 
167## Auto-Updating `index.json` (Chosen Method: VS Code Tasks)
168 
169This project is configured to refresh `resources/cited_papers/index.json` before each LaTeX build using VS Code tasks (method #3 from the suggested approaches).
170 
171Added file: `.vscode/tasks.json` with three tasks:
172 
173- `update-index`: Runs a short Python one-liner invoking `extract_bibliography` on `src/references.bib`.
174- `latex-build`: Invokes `latexmk -pdf` on `main.tex`.
175- `build+index`: Sequentially runs `update-index` then `latex-build`.
176 
177### How to Use
1781. In VS Code, open the command palette and run “Tasks: Run Task”.
1792. Choose `build+index` (recommend marking it as the default build task when prompted).
1803. The BibTeX index will regenerate first; then LaTeX compilation proceeds.
181 
182If LaTeX Workshop cannot import the package (ModuleNotFoundError), a helper script `latex-mcp-server/update_index.py` is provided. The workspace settings have been updated to call:
183```
184python latex-mcp-server/update_index.py
185```
186so that a local editable install is not strictly required.
187 
188### Make It the Default Build
189When prompted by VS Code after first run, accept setting `build+index` as the default. You can also add to your workspace settings:
190```jsonc
191// .vscode/settings.json (optional)
192{
193  "latex-workshop.latex.recipe.default": "build+index"
194}
195```
196 
197### Why This Approach
198* No background watcher process.
199* Deterministic: index refresh tied explicitly to build command.
200* Minimal overhead (BibTeX parsing is fast relative to PDF compilation).
201 
202If you later need an alternative (e.g., Makefile or on-demand freshness check), you can still layer it on; the tasks approach is non-invasive.
203 
204## Adding New TS Tools
205 
2061. Create a new file in `ts_functions/src/functions/` exporting a function.
2072. Add it to the export map in `ts_functions/src/index.ts`.
2083. Rebuild and sync dist output.
2094. Register a Python wrapper in `server.py` using `bridge.register_ts_tool`.
210 
211## Protocol Notes
212 
213This server follows the MCP JSON-RPC message patterns. If the `mcp` Python package updates its APIs, adjust imports accordingly.
214 
215## License
216 
217MIT
218