latexmk-mcp 1.0.0 → 2.0.0

package/AGENTS.md

@@ -0,0 +1,26 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+The runtime is split across three source files. `src/index.ts` is the thin MCP entrypoint: tool metadata, server setup, and request dispatch. `src/handlers.ts` contains Zod schemas plus the tool implementations for compile, clean, dependency listing, watch sessions, config management, and citation inspection. `src/parser.ts` contains the structured LaTeX log parser. Tests live in `tests/`: `tests/index.test.ts` covers log parsing, and `tests/handlers.test.ts` covers config and citation handlers. `dist/` is generated output and should not be edited.
+
+## Build, Test, and Development Commands
+Use the scripts from `package.json`:
+
+- `bun run dev`: run the server directly from `src/index.ts`.
+- `bun run build`: compile TypeScript to `dist/` with `tsc`.
+- `bun test`: execute the Bun test suite.
+- `node dist/index.js`: run the built MCP server over stdio.
+
+Run `bun run build` before release; `prepublishOnly` already enforces it.
+
+## Coding Style & Naming Conventions
+Write strict TypeScript as ESM with `NodeNext` conventions. Match the existing style in [`src/handlers.ts`](/home/aidan/projects/latexmk-mcp/src/handlers.ts) and [`src/parser.ts`](/home/aidan/projects/latexmk-mcp/src/parser.ts): 2-space indentation, double quotes, semicolons, and descriptive names such as `CompileSchema`, `handleCompile`, and `ParsedWarning`. Keep schemas and handler behavior in sync when tool inputs change.
+
+## Testing Guidelines
+Tests use Bun's built-in runner via `bun:test`. Add new cases under `tests/*.test.ts` and name them after the behavior being verified, for example `should identify box warnings and dimensions`. Prefer file-based tests for handlers that can run against temp directories without a live `latexmk` install. If you add subprocess-heavy features such as watch mode, introduce a small seam or wrapper before trying to test them. Run `bun test` and `bun run build` before opening a pull request.
+
+## Commit & Pull Request Guidelines
+Recent history favors small, incremental commits with a Conventional Commit lean, such as `refactor: split server entrypoint from handlers`, `feat: add structured latex log parsing`, and `test: cover config and citation handlers`. Prefer `refactor:`, `feat:`, `fix:`, `test:`, and `docs:` where they fit. Keep pull requests focused, explain user-visible behavior changes, and include relevant test/build results.
+
+## Security & Configuration Tips
+This project shells out to `latexmk`, so validate new inputs before they reach `execFile` or `spawn`. Avoid passing unchecked command fragments through `extra_args`, and document any feature that depends on TeX binaries or `latexmk` being present on `$PATH`. Watch sessions are kept in memory only, so design follow-up changes with process cleanup in mind.

package/README.md

@@ -7,7 +7,7 @@ A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that e
 ## Prerequisites
 
 - **Node.js** 18+
-- **latexmk** installed and on `$PATH` (usually ships with TeX Live or MiKTeX)
+- **latexmk** installed and on `$PATH` (usually ships with major TeX distributions such as TeX Live or MiKTeX)
 - A TeX distribution with your required engines (`pdflatex`, `xelatex`, `lualatex`, …)
 
 ```bash
@@ -23,31 +23,13 @@ sudo pacman -S texlive-most
 
 ---
 
-## Installation & Build
+## Installation
 
 ```bash
-git clone <this-repo>
-cd latexmk-mcp
-npm install
-npm run build          # outputs to dist/
+npx latexmk-mcp
 ```
 
----
-
-## Running
-
-```bash
-# Direct
-node dist/index.js
-
-# Via npm
-npm start
-
-# During development (no build step)
-npm run dev
-```
-
-The server communicates over **stdio** (standard MCP transport).
+This is the standard MCP usage pattern: no global install is required. `npx` downloads the published package and runs the stdio server on demand.
 
 ---
 
@@ -59,13 +41,15 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
 {
   "mcpServers": {
     "latexmk": {
-      "command": "node",
-      "args": ["/absolute/path/to/latexmk-mcp/dist/index.js"]
+      "command": "npx",
+      "args": ["-y", "latexmk-mcp"]
     }
   }
 }
 ```
 
+The server communicates over **stdio** (standard MCP transport).
+
 ---
 
 ## Tools
@@ -84,8 +68,9 @@ Full compile of a LaTeX document with configurable engine, output format, biblio
 | `synctex` | boolean | `false` | Generate SyncTeX data |
 | `extra_args` | string[] | `[]` | Extra latexmk CLI flags |
 | `working_dir` | string | temp dir | Build directory |
+| `return_pdf` | boolean | `false` | Return compiled PDF as base64 when building PDF output |
 
-**Returns:** `success`, `exit_code`, `output_file` path, `errors[]`, `warnings[]`, `working_dir`, `stdout`, `stderr`.
+**Returns:** `success`, `exit_code`, `output_file`, `page_count`, structured `errors[]`, structured `warnings[]`, `missing_packages[]`, `install_hints[]`, `working_dir`, `stdout`, `stderr`, and optional `pdf_base64`.
 
 ---
 
@@ -99,7 +84,7 @@ Fast single-pass compile (no reruns, no bibliography) — ideal for quick syntax
 | `engine` | string | `pdflatex` | TeX engine |
 | `working_dir` | string | temp dir | Build directory |
 
-**Returns:** `success`, `errors[]`, `warnings[]`, `stdout`, `stderr`.
+**Returns:** `success`, structured `errors[]`, structured `warnings[]`, `missing_packages[]`, `install_hints[]`, `stdout`, `stderr`.
 
 ---
 
@@ -134,12 +119,33 @@ List all file dependencies of a document (included `.tex` files, `.bib` files, p
 
 ---
 
+### `latexmk_watch_start` / `latexmk_watch_stop` / `latexmk_watch_list`
+Manage background `latexmk -pvc` watch sessions. Start returns a `session_id`; stop terminates it; list shows active sessions with PID, job name, and start time.
+
+---
+
+### `latexmk_write_config` / `latexmk_read_config`
+Write or inspect `.latexmkrc` files. The write tool can set engine, output mode, shell escape, extra `pdflatex` args, and custom Perl rules.
+
+---
+
+### `latexmk_list_citations`
+Extract citation keys from LaTeX source and optionally compare them to a `.bib` file.
+
+**Returns:** `cited_keys[]`, `cited_count`, and when `bib_path` is provided, `bib_entries[]`, `missing_from_bib[]`, and `unused_in_bib[]`.
+
+---
+
 ## Development
 
 ```bash
-npm run dev       # run with tsx (no build needed)
-npm run build     # compile TypeScript → dist/
-npm start         # run compiled output
+git clone <this-repo>
+cd latexmk-mcp
+npm install
+bun run dev       # run directly from src/index.ts
+bun test          # run tests
+bun run build     # compile TypeScript -> dist/
+node dist/index.js
 ```
 
 ---