# LaTeX Workspace MCP

Restricted Model Context Protocol tools for local LaTeX projects. The server lets an AI assistant inspect a configured workspace, make narrow `.tex` edits, compile with a fixed `latexmk` command, and verify that the generated PDF and image assets are usable.

## Features

- Scan LaTeX projects and infer the main file, engine, bibliography mode, included files, figure references, citations, and labels.
- Read `.tex` files, create or overwrite `.tex` files only with explicit overwrite approval, and replace exactly one unique text occurrence.
- Compile a selected main file with `pdflatex` or `xelatex` through `latexmk` into the document-local `build/` directory.
- Analyze build logs for errors, warnings, undefined references, and undefined citations.
- Check citation keys, duplicate labels, undefined labels, and figure path existence.
- Validate image assets before a build with `validate_latex_assets`, including reachable `\input`/`\include` files, first-page PDF metadata, dimensions for PNG/JPEG/PDF assets, and similar-path suggestions.
- Verify generated PDFs with `verify_latex_pdf`, including MIME type, page count, page sizes, and embedded image metadata from `pdfimages`.
- Run the full asset-check, build, and PDF-verification flow with `build_and_verify_latex`.
- Use either stdio MCP for local editors or Streamable HTTP MCP for ChatGPT-style clients.

## Security Model

- Every path is resolved under the configured `--root` directory. Paths outside the root are rejected.
- Write tools only accept project-relative `.tex` files. There is no delete, rename, arbitrary shell, or generic file-write API.
- `write_tex_file` refuses to overwrite existing files unless `overwrite: true` is supplied.
- `replace_tex_text` requires one exact unique match. Empty, missing, or multiple matches are rejected.
- Compilation uses a fixed `latexmk` command with `shell: false`, disabled shell escape, bounded output, and build artifacts under `build/`.
- The HTTP server requires an API key from `LATEX_MCP_API_KEY_FILE` and accepts either `Authorization: Bearer ...` or `X-API-Key`.
- The HTTP server binds to `127.0.0.1` by default and allows only `localhost,127.0.0.1` host headers unless `LATEX_MCP_ALLOWED_HOSTS` is set.

## Requirements

- Node.js 20 or newer.
- TeX Live or another LaTeX distribution with `latexmk`, `pdflatex`, and optionally `xelatex`.
- PDF utilities: `file`, `pdfinfo`, and `pdfimages`.

On Debian or Ubuntu, the PDF utilities are usually provided by `file` and `poppler-utils`.

## Install

```bash
git clone https://github.com/YOUR_GITHUB_USER/latex-workspace-mcp.git
cd latex-workspace-mcp
npm install
```

Use an absolute project root when starting either server:

```bash
node server.mjs --root /path/to/latex/project
```

## Stdio MCP

Use stdio when the MCP client launches local commands directly.

```json
{
  "mcpServers": {
    "latex-workspace": {
      "command": "node",
      "args": ["/path/to/latex-workspace-mcp/server.mjs", "--root", "/path/to/latex/project"]
    }
  }
}
```

## HTTP MCP

Create an API key file with permissions limited to the service user:

```bash
install -d -m 700 ~/.config/latex-workspace-mcp
openssl rand -base64 48 > ~/.config/latex-workspace-mcp/api-key
chmod 600 ~/.config/latex-workspace-mcp/api-key
```

Start the loopback HTTP server:

```bash
LATEX_MCP_API_KEY_FILE="$HOME/.config/latex-workspace-mcp/api-key" \
LATEX_MCP_HTTP_HOST=127.0.0.1 \
LATEX_MCP_HTTP_PORT=8787 \
LATEX_MCP_ALLOWED_HOSTS=localhost,127.0.0.1 \
node http-server.mjs --root /path/to/latex/project
```

The MCP endpoint is `http://127.0.0.1:8787/mcp`. Unauthenticated calls should return `401`.

If you put a trusted reverse proxy in front of the server, keep the origin private and set `LATEX_MCP_ALLOWED_HOSTS` to the exact host headers your proxy sends.

## systemd

Copy `examples/latex-mcp-http.service.example` and replace `YOUR_PROJECT_ROOT` with the absolute LaTeX workspace root. Keep `LATEX_MCP_HTTP_HOST=127.0.0.1` when the proxy runs on the same machine.

## ChatGPT Prompt Pattern

Use a prompt that keeps edits precise and makes the verification flow explicit:

```text
Use the LaTeX Workspace MCP for this project. Before changing figure paths, call validate_latex_assets with the project-relative main_file. For source edits, prefer replace_tex_text and only use write_tex_file with overwrite: true when I explicitly ask for a full-file replacement. After any document or image-path change, call build_and_verify_latex. If the build fails, use analyze_log and validate_latex_assets to make the smallest precise repair.
```

For projects with multiple `main.tex` files, always pass a project-relative `main_file`, such as `paper/main.tex`.

## Image And First-Page Validation Workflow

1. Put images under the configured project root and reference them with paths relative to the main file directory.
2. Call `validate_latex_assets` before compiling. Missing `\includegraphics` assets stop `build_and_verify_latex` before LaTeX runs.
3. For PNG and JPEG assets, the tool reports dimensions from the file header.
4. For PDF assets, the tool calls `pdfinfo` and reports first-page page-size metadata without extracting binary content.
5. After compilation, call `verify_latex_pdf` or `build_and_verify_latex` to confirm the expected `build/<stem>.pdf` exists, has pages, and lists embedded images.

## Tool Summary

- `get_project_info`
- `scan_project`
- `analyze_log`
- `check_citations`
- `check_labels`
- `check_figures`
- `validate_latex_assets`
- `verify_latex_pdf`
- `build_and_verify_latex`
- `list_tex_files`
- `read_tex_file`
- `write_tex_file`
- `replace_tex_text`
- `compile_latex`

## License

MIT