latexmk-mcp 1.0.0

package/.gitattributes

@@ -0,0 +1,5 @@
+# Force ignore build artifacts and lockfiles in stats
+dist/* linguist-vendored
+bun.lock linguist-generated
+
+*.ts linguist-language=TypeScript

package/GEMINI.md

@@ -0,0 +1,60 @@
+# GEMINI.md - Instructional Context for `latexmk-mcp`
+
+This file provides context and guidelines for interacting with the `latexmk-mcp` project.
+
+## Project Overview
+
+`latexmk-mcp` is a **Model Context Protocol (MCP)** server that exposes the `latexmk` LaTeX build tool as a set of tools for MCP-compatible AI assistants. It allows an AI to compile, check, clean, and inspect LaTeX documents directly through a standardized interface.
+
+### Key Technologies
+- **Runtime:** Node.js (Primary), Bun (Optional for dev)
+- **Language:** TypeScript
+- **Schemas:** Zod
+- **Core SDK:** `@modelcontextprotocol/sdk`
+- **External Tool:** `latexmk` (Must be on `$PATH`)
+
+### Architecture
+The server follows a standard MCP pattern:
+1. **Tool Definitions:** Located in `src/index.ts`, defining the inputs via Zod schemas and metadata for the MCP `list_tools` request.
+2. **Handlers:** Asynchronous functions (`handleCompile`, `handleClean`, etc.) that validate input, prepare arguments, and execute `latexmk` as a subprocess.
+3. **Transport:** Communicates via **stdio**, allowing easy integration with clients like Claude Desktop.
+
+---
+
+## Building and Running
+
+### Prerequisites
+- Node.js 18+ and `npm`.
+- `latexmk` and a TeX distribution (e.g., TeX Live, MiKTeX) must be installed on the system.
+
+### Key Commands
+- **Build:** `npm run build`
+  - Compiles TypeScript files from `src/` to `dist/`.
+- **Run (Production):** `npm start`
+  - Executes the compiled JavaScript in `dist/index.js`.
+- **Run (Development):** `npm run dev`
+  - Runs `src/index.ts` directly using `bun`.
+- **Test:** *TODO: Implement automated tests (e.g., using Vitest or Bun's built-in test runner).*
+
+---
+
+## Development Conventions
+
+### Code Style and Standards
+- **ESM:** The project is a pure ES Module (`"type": "module"` in `package.json`).
+- **TypeScript:** Uses `NodeNext` for module resolution. Avoid using `any`; prefer Zod-inferred types for tool inputs.
+- **Surgical Changes:** When modifying tools, ensure the Zod schema and the handler remain in sync.
+
+### File Structure
+- `src/index.ts`: The main entry point containing all tool definitions and handlers.
+- `dist/`: Compiled JavaScript output (ignored by Git).
+- `tsconfig.json`: Configured for ESM and `NodeNext` resolution.
+- `README.md`: Contains setup and configuration instructions for users.
+
+---
+
+## Future Improvements (Roadmap)
+- [ ] Add a comprehensive test suite with sample `.tex` files.
+- [ ] Implement a file watcher for automatic recompilation.
+- [ ] Add support for more advanced `latexmk` configuration files (`.latexmkrc`).
+- [ ] Improve error parsing for more granular feedback to the user.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 coolport
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,149 @@
+# latexmk-mcp
+
+A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that exposes the [`latexmk`](https://personal.psu.edu/~jcc8/software/latexmk/) LaTeX build tool as MCP tools — letting any MCP-compatible AI assistant compile, check, clean, and inspect LaTeX documents.
+
+---
+
+## Prerequisites
+
+- **Node.js** 18+
+- **latexmk** installed and on `$PATH` (usually ships with TeX Live or MiKTeX)
+- A TeX distribution with your required engines (`pdflatex`, `xelatex`, `lualatex`, …)
+
+```bash
+# Debian/Ubuntu
+sudo apt install latexmk texlive-full
+
+# macOS (Homebrew + MacTeX)
+brew install --cask mactex
+
+# Arch Linux
+sudo pacman -S texlive-most
+```
+
+---
+
+## Installation & Build
+
+```bash
+git clone <this-repo>
+cd latexmk-mcp
+npm install
+npm run build          # outputs to dist/
+```
+
+---
+
+## 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).
+
+---
+
+## Claude Desktop Configuration
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "latexmk": {
+      "command": "node",
+      "args": ["/absolute/path/to/latexmk-mcp/dist/index.js"]
+    }
+  }
+}
+```
+
+---
+
+## Tools
+
+### `latexmk_compile`
+Full compile of a LaTeX document with configurable engine, output format, bibliography processor, and latexmk flags.
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `tex_content` | string | — | Raw LaTeX source (mutually exclusive with `file_path`) |
+| `file_path` | string | — | Path to existing `.tex` file |
+| `output_format` | `pdf\|dvi\|ps\|xdv` | `pdf` | Target format |
+| `engine` | `pdflatex\|xelatex\|lualatex\|latex\|pdftex` | `pdflatex` | TeX engine |
+| `bibtex` | `bibtex\|biber\|none` | `none` | Bibliography processor |
+| `shell_escape` | boolean | `false` | Enable `--shell-escape` |
+| `synctex` | boolean | `false` | Generate SyncTeX data |
+| `extra_args` | string[] | `[]` | Extra latexmk CLI flags |
+| `working_dir` | string | temp dir | Build directory |
+
+**Returns:** `success`, `exit_code`, `output_file` path, `errors[]`, `warnings[]`, `working_dir`, `stdout`, `stderr`.
+
+---
+
+### `latexmk_draft_compile`
+Fast single-pass compile (no reruns, no bibliography) — ideal for quick syntax/error checks while editing.
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `tex_content` | string | — | Raw LaTeX source |
+| `file_path` | string | — | Path to `.tex` file |
+| `engine` | string | `pdflatex` | TeX engine |
+| `working_dir` | string | temp dir | Build directory |
+
+**Returns:** `success`, `errors[]`, `warnings[]`, `stdout`, `stderr`.
+
+---
+
+### `latexmk_clean`
+Remove build artifacts using `latexmk -c` (auxiliaries only) or `latexmk -C` (auxiliaries + output files).
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `working_dir` | string | **required** | Directory to clean |
+| `job_name` | string | — | Clean a specific job only |
+| `clean_all` | boolean | `false` | `-C` instead of `-c` |
+
+---
+
+### `latexmk_check`
+Detect whether `latexmk` is installed and which TeX engines are available on the system.
+
+**Returns:** `latexmk_available`, `latexmk_version`, `latexmk_path`, `engines_available` map.
+
+---
+
+### `latexmk_list_dependencies`
+List all file dependencies of a document (included `.tex` files, `.bib` files, packages, images…) via `latexmk -deps`.
+
+| Parameter | Type | Description |
+|---|---|---|
+| `tex_content` | string | Raw LaTeX source |
+| `file_path` | string | Path to `.tex` file |
+| `working_dir` | string | Working directory |
+
+**Returns:** `dependencies[]` (deduplicated list of file paths).
+
+---
+
+## Development
+
+```bash
+npm run dev       # run with tsx (no build needed)
+npm run build     # compile TypeScript → dist/
+npm start         # run compiled output
+```
+
+---
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "latexmk-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for the latexmk LaTeX build tool",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "latexmk-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "bun run src/index.ts",
+    "prepublishOnly": "bun run build"
+  },
+  "keywords": ["mcp", "latex", "latexmk", "tex"],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.0.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,671 @@
+#!/usr/bin/env node
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  Tool,
+} from "@modelcontextprotocol/sdk/types.js";
+import { execFile } from "child_process";
+import { promisify } from "util";
+import { z } from "zod";
+import * as fs from "fs/promises";
+import * as path from "path";
+import * as os from "os";
+
+const execFileAsync = promisify(execFile);
+
+const CompileSchema = z.object({
+  tex_content: z.string().optional().describe("LaTeX source content (if not providing file_path)"),
+  file_path: z.string().optional().describe("Absolute path to an existing .tex file"),
+  output_format: z
+    .enum(["pdf", "dvi", "ps", "xdv"])
+    .default("pdf")
+    .describe("Target output format"),
+  engine: z
+    .enum(["pdflatex", "xelatex", "lualatex", "latex", "pdftex"])
+    .default("pdflatex")
+    .describe("TeX engine to use"),
+  bibtex: z
+    .enum(["bibtex", "biber", "none"])
+    .default("none")
+    .describe("Bibliography processor"),
+  shell_escape: z.boolean().default(false).describe("Enable shell-escape (--shell-escape)"),
+  synctex: z.boolean().default(false).describe("Generate SyncTeX data"),
+  extra_args: z.array(z.string()).default([]).describe("Extra latexmk CLI arguments"),
+  working_dir: z.string().optional().describe("Working directory (defaults to system temp)"),
+});
+
+type CompileOptions = z.infer<typeof CompileSchema>;
+
+const CleanSchema = z.object({
+  working_dir: z.string().describe("Directory containing the LaTeX build artifacts to clean"),
+  job_name: z.string().optional().describe("Specific job name (base filename without extension)"),
+  clean_all: z.boolean().default(false).describe("Use -C (remove output files too) instead of -c"),
+});
+
+type CleanOptions = z.infer<typeof CleanSchema>;
+
+const PreviewSchema = z.object({
+  tex_content: z.string().optional().describe("LaTeX source content"),
+  file_path: z.string().optional().describe("Absolute path to an existing .tex file"),
+  engine: z
+    .enum(["pdflatex", "xelatex", "lualatex", "latex"])
+    .default("pdflatex")
+    .describe("TeX engine"),
+  working_dir: z.string().optional().describe("Working directory"),
+});
+
+type PreviewOptions = z.infer<typeof PreviewSchema>;
+
+const CheckSchema = z.object({
+  working_dir: z.string().optional().describe("Directory to check for latexmk availability"),
+});
+
+const ListDependenciesSchema = z.object({
+  tex_content: z.string().optional().describe("LaTeX source content"),
+  file_path: z.string().optional().describe("Absolute path to an existing .tex file"),
+  working_dir: z.string().optional().describe("Working directory"),
+});
+
+type ListDependenciesOptions = z.infer<typeof ListDependenciesSchema>;
+
+// Helpers
+
+async function createTempDir(): Promise<string> {
+  return fs.mkdtemp(path.join(os.tmpdir(), "latexmk-mcp-"));
+}
+
+async function writeTex(content: string, dir: string, name = "document"): Promise<string> {
+  const filePath = path.join(dir, `${name}.tex`);
+  await fs.writeFile(filePath, content, "utf-8");
+  return filePath;
+}
+
+async function readFileIfExists(filePath: string): Promise<string | null> {
+  try {
+    return await fs.readFile(filePath, "utf-8");
+  } catch {
+    return null;
+  }
+}
+
+function buildLatexmkArgs(opts: {
+  outputFormat: string;
+  engine: string;
+  bibtex: string;
+  shellEscape: boolean;
+  synctex: boolean;
+  extraArgs: string[];
+  jobName?: string;
+  outputDir?: string;
+}): string[] {
+  const args: string[] = ["-interaction=nonstopmode", "-halt-on-error", "-f"];
+
+  // Output format
+  switch (opts.outputFormat) {
+    case "pdf":
+      args.push("-pdf");
+      break;
+    case "dvi":
+      args.push("-dvi");
+      break;
+    case "ps":
+      args.push("-ps");
+      break;
+    case "xdv":
+      args.push("-xdv");
+      break;
+  }
+
+  // Engine override
+  switch (opts.engine) {
+    case "xelatex":
+      args.push("-xelatex");
+      break;
+    case "lualatex":
+      args.push("-lualatex");
+      break;
+    case "pdftex":
+    case "pdflatex":
+      if (opts.outputFormat === "pdf") args.push("-pdflatex");
+      break;
+  }
+
+  // Bibliography
+  if (opts.bibtex === "bibtex") args.push("-bibtex");
+  else if (opts.bibtex === "biber") args.push('-bibtex', '-e', '$biber=q/biber/');
+  else args.push("-bibtex-");
+
+  if (opts.shellEscape) args.push("-shell-escape");
+  if (opts.synctex) args.push("-synctex=1");
+
+  if (opts.outputDir) args.push(`-outdir=${opts.outputDir}`);
+  if (opts.jobName) args.push(`-jobname=${opts.jobName}`);
+
+  return [...args, ...opts.extraArgs];
+}
+
+function parseLatexLog(log: string): {
+  errors: string[];
+  warnings: string[];
+  info: string[];
+} {
+  const lines = log.split("\n");
+  const errors: string[] = [];
+  const warnings: string[] = [];
+  const info: string[] = [];
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]?.trim();
+    if (!line) continue;
+
+    if (/^!(?: LaTeX| Package| Class)? Error/i.test(line)) {
+      // Collect multi-line error context
+      const ctx = [line];
+      while (i + 1 < lines.length && lines[i + 1]?.startsWith(" ")) {
+        ctx.push(lines[++i]!.trim());
+      }
+      errors.push(ctx.join(" "));
+    } else if (/^(LaTeX|Package|Class) Warning/i.test(line)) {
+      warnings.push(line);
+    } else if (line.startsWith("Latexmk:")) {
+      info.push(line);
+    }
+  }
+
+  return { errors, warnings, info };
+}
+
+// Tool Handlers
+
+async function handleCompile(rawArgs: unknown) {
+  const args: CompileOptions = CompileSchema.parse(rawArgs);
+
+  if (!args.tex_content && !args.file_path) {
+    throw new Error("Either tex_content or file_path must be provided.");
+  }
+
+  const ownDir = !args.working_dir && !args.file_path;
+  const workDir = args.working_dir ?? (await createTempDir());
+
+  let texPath: string;
+  let jobName = "document";
+
+  if (args.file_path) {
+    texPath = path.resolve(args.file_path);
+    jobName = path.basename(texPath, ".tex");
+  } else {
+    texPath = await writeTex(args.tex_content!, workDir, jobName);
+  }
+
+  const lmkArgs = buildLatexmkArgs({
+    outputFormat: args.output_format,
+    engine: args.engine,
+    bibtex: args.bibtex,
+    shellEscape: args.shell_escape,
+    synctex: args.synctex,
+    extraArgs: args.extra_args,
+    jobName,
+    outputDir: workDir,
+  });
+
+  lmkArgs.push(texPath);
+
+  let stdout = "";
+  let stderr = "";
+  let exitCode = 0;
+
+  try {
+    const result = await execFileAsync("latexmk", lmkArgs, {
+      cwd: workDir,
+      maxBuffer: 10 * 1024 * 1024,
+    });
+    stdout = result.stdout;
+    stderr = result.stderr;
+  } catch (err: unknown) {
+    const e = err as { stdout?: string; stderr?: string; code?: number };
+    stdout = e.stdout ?? "";
+    stderr = e.stderr ?? "";
+    exitCode = e.code ?? 1;
+  }
+
+  const logFile = path.join(workDir, `${jobName}.log`);
+  const logContent = (await readFileIfExists(logFile)) ?? "";
+  const parsed = parseLatexLog(logContent + "\n" + stdout);
+
+  const outputExt = args.output_format === "dvi" ? "dvi" : args.output_format === "ps" ? "ps" : args.output_format === "xdv" ? "xdv" : "pdf";
+  const outputFile = path.join(workDir, `${jobName}.${outputExt}`);
+  let outputExists = false;
+  try {
+    await fs.access(outputFile);
+    outputExists = true;
+  } catch { /* noop */ }
+
+  return {
+    success: exitCode === 0 && outputExists,
+    exit_code: exitCode,
+    output_file: outputExists ? outputFile : null,
+    working_dir: workDir,
+    errors: parsed.errors,
+    warnings: parsed.warnings,
+    latexmk_info: parsed.info,
+    stdout: stdout.slice(0, 4000),
+    stderr: stderr.slice(0, 2000),
+  };
+}
+
+async function handleClean(rawArgs: unknown) {
+  const args: CleanOptions = CleanSchema.parse(rawArgs);
+  const flag = args.clean_all ? "-C" : "-c";
+
+  const lmkArgs = [flag];
+  if (args.job_name) lmkArgs.push(`-jobname=${args.job_name}`);
+
+  let stdout = "";
+  let stderr = "";
+  let exitCode = 0;
+
+  try {
+    const result = await execFileAsync("latexmk", lmkArgs, {
+      cwd: path.resolve(args.working_dir),
+      maxBuffer: 5 * 1024 * 1024,
+    });
+    stdout = result.stdout;
+    stderr = result.stderr;
+  } catch (err: unknown) {
+    const e = err as { stdout?: string; stderr?: string; code?: number };
+    stdout = e.stdout ?? "";
+    stderr = e.stderr ?? "";
+    exitCode = e.code ?? 1;
+  }
+
+  return {
+    success: exitCode === 0,
+    exit_code: exitCode,
+    clean_all: args.clean_all,
+    stdout,
+    stderr,
+  };
+}
+
+async function handleDraftCompile(rawArgs: unknown) {
+  // Fast single-pass compile to check for errors quickly (no reruns)
+  const args: PreviewOptions = PreviewSchema.parse(rawArgs);
+
+  if (!args.tex_content && !args.file_path) {
+    throw new Error("Either tex_content or file_path must be provided.");
+  }
+
+  const workDir = args.working_dir ?? (await createTempDir());
+  let texPath: string;
+  let jobName = "document";
+
+  if (args.file_path) {
+    texPath = path.resolve(args.file_path);
+    jobName = path.basename(texPath, ".tex");
+  } else {
+    texPath = await writeTex(args.tex_content!, workDir, jobName);
+  }
+
+  const lmkArgs = [
+    "-pdf",
+    "-interaction=nonstopmode",
+    "-f",
+    "-bibtex-",
+    `-outdir=${workDir}`,
+    `-jobname=${jobName}`,
+    texPath,
+  ];
+
+  let stdout = "";
+  let stderr = "";
+  let exitCode = 0;
+
+  try {
+    const result = await execFileAsync("latexmk", lmkArgs, {
+      cwd: workDir,
+      maxBuffer: 10 * 1024 * 1024,
+    });
+    stdout = result.stdout;
+    stderr = result.stderr;
+  } catch (err: unknown) {
+    const e = err as { stdout?: string; stderr?: string; code?: number };
+    stdout = e.stdout ?? "";
+    stderr = e.stderr ?? "";
+    exitCode = e.code ?? 1;
+  }
+
+  const logFile = path.join(workDir, `${jobName}.log`);
+  const logContent = (await readFileIfExists(logFile)) ?? "";
+  const parsed = parseLatexLog(logContent + "\n" + stdout);
+
+  return {
+    success: exitCode === 0,
+    exit_code: exitCode,
+    working_dir: workDir,
+    errors: parsed.errors,
+    warnings: parsed.warnings,
+    stdout: stdout.slice(0, 4000),
+    stderr: stderr.slice(0, 2000),
+  };
+}
+
+async function handleCheck(_rawArgs: unknown) {
+  let version = "";
+  let available = false;
+  let path_found = "";
+
+  try {
+    const { stdout } = await execFileAsync("latexmk", ["--version"]);
+    version = stdout.trim().split("\n")[0] ?? "";
+    available = true;
+  } catch {
+    // latexmk not found
+  }
+
+  try {
+    const { stdout } = await execFileAsync("which", ["latexmk"]);
+    path_found = stdout.trim();
+  } catch {
+    // ignore
+  }
+
+  // Check for common TeX engines
+  const engines: Record<string, boolean> = {};
+  for (const eng of ["pdflatex", "xelatex", "lualatex", "latex"]) {
+    try {
+      await execFileAsync("which", [eng]);
+      engines[eng] = true;
+    } catch {
+      engines[eng] = false;
+    }
+  }
+
+  return {
+    latexmk_available: available,
+    latexmk_version: version,
+    latexmk_path: path_found,
+    engines_available: engines,
+  };
+}
+
+async function handleListDependencies(rawArgs: unknown) {
+  const args: ListDependenciesOptions = ListDependenciesSchema.parse(rawArgs);
+
+  if (!args.tex_content && !args.file_path) {
+    throw new Error("Either tex_content or file_path must be provided.");
+  }
+
+  const workDir = args.working_dir ?? (await createTempDir());
+  let texPath: string;
+  let jobName = "document";
+
+  if (args.file_path) {
+    texPath = path.resolve(args.file_path);
+    jobName = path.basename(texPath, ".tex");
+  } else {
+    texPath = await writeTex(args.tex_content!, workDir, jobName);
+  }
+
+  // Use -deps flag to print dependencies
+  const lmkArgs = [
+    "-pdf",
+    "-deps",
+    "-bibtex-",
+    "-f",
+    `-outdir=${workDir}`,
+    `-jobname=${jobName}`,
+    texPath,
+  ];
+
+  let stdout = "";
+  let exitCode = 0;
+
+  try {
+    const result = await execFileAsync("latexmk", lmkArgs, {
+      cwd: workDir,
+      maxBuffer: 5 * 1024 * 1024,
+    });
+    stdout = result.stdout;
+  } catch (err: unknown) {
+    const e = err as { stdout?: string; code?: number };
+    stdout = e.stdout ?? "";
+    exitCode = e.code ?? 1;
+  }
+
+  // Parse dependencies from the output
+  const deps: string[] = [];
+  const depRegex = /^\s{2,}(.+\.(?:tex|bib|sty|cls|clo|def|cfg|fd|enc|tfm|pfb|png|jpg|pdf|eps|svg))\s*\\?$/gim;
+  let match;
+  while ((match = depRegex.exec(stdout)) !== null) {
+    const dep = match[1];
+    if (dep) {
+      deps.push(dep.trim());
+    }
+  }
+
+  return {
+    success: exitCode === 0,
+    dependencies: [...new Set(deps)],
+    working_dir: workDir,
+    raw_output: stdout.slice(0, 3000),
+  };
+}
+
+// Tool Definitions
+
+const TOOLS: Tool[] = [
+  {
+    name: "latexmk_compile",
+    description:
+      "Compile a LaTeX document using latexmk. Accepts raw LaTeX source or a path to an existing .tex file. Returns compile success/failure, errors, warnings, and the path to the output file.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        tex_content: {
+          type: "string",
+          description: "LaTeX source content (mutually exclusive with file_path)",
+        },
+        file_path: {
+          type: "string",
+          description: "Absolute path to an existing .tex file (mutually exclusive with tex_content)",
+        },
+        output_format: {
+          type: "string",
+          enum: ["pdf", "dvi", "ps", "xdv"],
+          default: "pdf",
+          description: "Target output format",
+        },
+        engine: {
+          type: "string",
+          enum: ["pdflatex", "xelatex", "lualatex", "latex", "pdftex"],
+          default: "pdflatex",
+          description: "TeX engine to use",
+        },
+        bibtex: {
+          type: "string",
+          enum: ["bibtex", "biber", "none"],
+          default: "none",
+          description: "Bibliography processor",
+        },
+        shell_escape: {
+          type: "boolean",
+          default: false,
+          description: "Enable --shell-escape",
+        },
+        synctex: {
+          type: "boolean",
+          default: false,
+          description: "Generate SyncTeX data",
+        },
+        extra_args: {
+          type: "array",
+          items: { type: "string" },
+          default: [],
+          description: "Extra latexmk CLI arguments to pass through",
+        },
+        working_dir: {
+          type: "string",
+          description: "Working directory. Defaults to a fresh temp directory.",
+        },
+      },
+      oneOf: [{ required: ["tex_content"] }, { required: ["file_path"] }],
+    },
+  },
+  {
+    name: "latexmk_draft_compile",
+    description:
+      "Run a fast single-pass draft compile to quickly surface errors without running multiple passes or bibliography. Good for syntax/error checking during editing.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        tex_content: {
+          type: "string",
+          description: "LaTeX source content",
+        },
+        file_path: {
+          type: "string",
+          description: "Absolute path to an existing .tex file",
+        },
+        engine: {
+          type: "string",
+          enum: ["pdflatex", "xelatex", "lualatex", "latex"],
+          default: "pdflatex",
+        },
+        working_dir: {
+          type: "string",
+          description: "Working directory",
+        },
+      },
+      oneOf: [{ required: ["tex_content"] }, { required: ["file_path"] }],
+    },
+  },
+  {
+    name: "latexmk_clean",
+    description:
+      "Clean LaTeX build artifacts in a directory using `latexmk -c` (auxiliary files only) or `latexmk -C` (auxiliary + output files).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        working_dir: {
+          type: "string",
+          description: "Directory containing the LaTeX build artifacts",
+        },
+        job_name: {
+          type: "string",
+          description: "Specific job name (base filename without extension). Cleans all if omitted.",
+        },
+        clean_all: {
+          type: "boolean",
+          default: false,
+          description: "If true, uses -C to also remove output files (PDF/DVI/PS). If false, uses -c for auxiliary files only.",
+        },
+      },
+      required: ["working_dir"],
+    },
+  },
+  {
+    name: "latexmk_check",
+    description:
+      "Check whether latexmk is installed and which TeX engines are available on this system.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        working_dir: {
+          type: "string",
+          description: "Optional working directory (not required for this check)",
+        },
+      },
+    },
+  },
+  {
+    name: "latexmk_list_dependencies",
+    description:
+      "List all file dependencies of a LaTeX document (included .tex files, .bib files, packages, images, etc.) using `latexmk -deps`.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        tex_content: {
+          type: "string",
+          description: "LaTeX source content",
+        },
+        file_path: {
+          type: "string",
+          description: "Absolute path to an existing .tex file",
+        },
+        working_dir: {
+          type: "string",
+          description: "Working directory",
+        },
+      },
+      oneOf: [{ required: ["tex_content"] }, { required: ["file_path"] }],
+    },
+  },
+];
+
+// Server
+
+const server = new Server(
+  { name: "latexmk-mcp", version: "1.0.0" },
+  { capabilities: { tools: {} },
+    instructions: "Compile, clean, and inspect LaTeX documents using latexmk."
+  }
+
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  try {
+    let result: unknown;
+    switch (name) {
+      case "latexmk_compile":
+        result = await handleCompile(args);
+        break;
+      case "latexmk_draft_compile":
+        result = await handleDraftCompile(args);
+        break;
+      case "latexmk_clean":
+        result = await handleClean(args);
+        break;
+      case "latexmk_check":
+        result = await handleCheck(args);
+        break;
+      case "latexmk_list_dependencies":
+        result = await handleListDependencies(args);
+        break;
+      default:
+        return {
+          content: [{ type: "text", text: `Unknown tool: ${name}` }],
+          isError: true,
+        };
+    }
+
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    };
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      content: [{ type: "text", text: `Error: ${message}` }],
+      isError: true,
+    };
+  }
+});
+
+// Entry
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("latexmk MCP server running on stdio");
+}
+
+main().catch((err) => {
+  console.error("Fatal:", err);
+  process.exit(1);
+});

package/src/test.ts

@@ -0,0 +1 @@
+// Test

package/tsconfig.json

@@ -0,0 +1,27 @@
+{
+  "compilerOptions": {
+    /* Base environment */
+    "lib": ["ESNext"],
+    "target": "ESNext",
+    "moduleDetection": "force",
+    "allowJs": true,
+
+    /* Building for npm */
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "dist",
+    "sourceMap": true,
+    "declaration": true,
+    "noEmit": false, // Enabled for npm builds
+
+    /* Best practices */
+    "strict": true,
+    "skipLibCheck": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+
+    /* Project structure */
+    "rootDir": "src"
+  },
+  "include": ["src/**/*"]
+}