MagicTeX-mcp

# MagicTeX — LaTeX 编辑器，用于 AI 代理 <!-- badges --> [](https://www.npmjs.com/package/magictex-mcp) [](https://registry.modelcontextprotocol.io) [](https://github.com/ZoeLinUTS/MagicTeX-mcp/actions/workflows/ci.yml) [](https://github.com/ZoeLinUTS/MagicTeX-mcp/stargazers) [](https://github.com/ZoeLinUTS/MagicTeX-mcp/commits/main) [](LICENSE) [](https://github.com/sponsors/ZoeLinUTS) **简体中文** · [日本語](docs/i18n/README.ja.md) · [한국어](docs/i18n/README.ko.md) · [Español](docs/i18n/README.es.md) · [Français](docs/i18n/README.fr.md) · [Deutsch](docs/i18n/README.de.md) · [Português](docs/i18n/README.pt.md) **MagicTeX** 是一款专为 AI 代理设计的 **LaTeX 编辑器**，提供类似 Overleaf 的单窗口工作空间，适用于 Claude Code，由 MCP 服务器提供服务，无需本地 TeX 安装，也无需 Overleaf 账户：实时 PDF 预览、源代码编辑器，视觉（所见即所得）模式、更改历史记录，以及 **您可以锚定在渲染的 PDF 上的评论，这些评论将成为代理的编辑指令**。（npm 包：`magictex-mcp`。） 它使用 WASM TeX Live 2026 引擎（[texlyre-busytex](https://github.com/TeXlyre/texlyre-busytex)）编译，该引擎在无头浏览器中运行，因此无需安装多 GB 的软件包 - 只需一次性下载 WASM 资产即可。  ## 在安装前查看 一个引导式教程，演示评论 → 代理循环，位于 **[zoelin.dev/tools/magictex](https://zoelin.dev/tools/magictex)**，基于实际工具输出构建。这是一个重放，而不是托管实例 - TeX 引擎是一次性下载约 480 MB，代理部分是 Claude 本身，因此 MagicTeX 在您的项目旁边运行，而不是在网页中。 ## 工作空间 单个浏览器窗口（灵感来自 Typst 的单表面编辑器和 LiquidText 的锚定注释）： ``` ┌──────────────────────────────────────────────────────────────┐ │ ✓ 最新 · 13 页 导出 .zip · 下载 PDF │ ├────────────┬──────────────────────────────┬──────────────────┤ │ 源代码 / │ PDF（实时） │ 评论 │ │ 历史记录 │ 选择文本 → 💬 评论 │ 已接受 → 请求 │ │ 编辑器， │ 高亮保持锚定 │ 克劳德解决它们 │ │ 时间线 │ 自动重新加载 │ → 已解决 ✓ │ └────────────┴──────────────────────────────┴──────────────────┘ ``` - **评论 → 克劳德循环（这是关键）。** 审阅 *渲染* 文档，如同主管审核打印稿：选择文本，附加评论（“压缩此段落”）。然后告诉克劳德 *“解决我的评论”* - 它通过 `check_comments` 拉取它们作为 **定位工作项**（页面 + 引用的段落 + 源代码 `file:line` 它锚定到 + 您的请求），编辑源代码，并用注释解决每个卡片。您与文档交互；克劳德与源代码交互。运行它时无需人工干预，使用 `/loop` - 请参阅 [`docs/AGENT-LOOP.md`](docs/AGENT-LOOP.md)。 - **可编辑的源代码面板。** CodeMirror LaTeX 编辑器与项目文件 - 保存（Ctrl+S）重新编译并刷新 PDF，Typst 样式。或者继续使用您自己的编辑器：任何保存都触发相同的实时循环。 - **实时重载。** 文件监视器在每次保存时重新编译 - 克劳德的编辑，内置编辑器，或您的外部编辑器。 - **更改历史记录。** 每个成功的编译都被自动快照到一个 **隐藏的 git 引用**（`refs/latex-preview/checkpoints`）- 从不触及您的分支，`git log` 或工作树。历史记录选项卡显示时间线和每个检查点的彩色差异，位于 PDF 旁边。 - **前往 Overleaf。** **下载 PDF**，**导出 .zip**（干净的构建输入包），以及公共 GitHub 仓库的一键 **在 Overleaf 中打开** 链接；高级 Git 桥同步是一个有文档记录的 `git push`。请参阅 [`docs/USER-GUIDE.md`](docs/USER-GUIDE.md)。 - **审阅工作流（审阅者 → 网关 → 解决者）。** 审阅者/防御者代理通过 `add_comment` 发布评论；您 **接受/拒绝** 它们（或翻转 *自动接受* 为协作者模式）；作者循环解决已接受的评论。评论带有角色和回复线程。请参阅 [`docs/AGENT-LOOP.md`](docs/AGENT-LOOP.md)。 - **保存与重新编译，您来决定。** 内置编辑器每 30 秒自动保存一次而不重新编译； **Ctrl+S** / **保存** / **重新编译** 按需重新构建 PDF。（翻转 **⚡ 实时** 以实时编译。）您的编辑器和克劳德的编辑仍然通过监视器自动重新编译。 - **真实项目。** 自动检测主文件，收集多文件 `\input`/`\include`，`.bib`，存储库中的 `.cls`/`.sty`/`.bst` 和图形，运行 BibTeX 并在需要时重新运行；常见的缺失软件包会自动注入。 - **编译后端。** 默认情况下，无需安装 **WASM** TeX Live；传递 `backend: "system"`（或 `"auto"`）到 `render_preview` 以使用您本地的 **latexmk** 以实现完整的软件包保真度。 - **MCP 工具：** `render_preview`（编译 + 打开工作空间），`check_comments` / `resolve_comment` / `add_comment` / `reply_to_comment`（审阅循环），`show_diff`（并排差异作为图像 - 在支持图像的客户端上很有用）。 - **可操作错误。** 失败的编译返回解析的 `{file, line, message}` 错误，以便克劳德可以自我纠正，并在工作空间中显示。 ## 安装 MagicTeX 在 npm 上作为 [`magictex-mcp`](https://www.npmjs.com/package/magictex-mcp) 提供，并在 [官方 MCP 注册表](https://registry.modelcontextprotocol.io) 中列出为 **`io.github.ZoeLinUTS/magictex`** - 因此，任何读取注册表的客户端都可以找到它。 1. **将它添加到您论文项目的 `.mcp.json` 中**（参见 [.mcp.json.example](.mcp.json.example)）： ```json { "mcpServers": { "magictex": { "command": "npx", "args": ["-y", "magictex-mcp"] } } } ``` 对于从克隆的本地开发，请将其指向源代码：`"command": "npx", "args": ["tsx", "/absolute/path/to/magictex-mcp/src/server.ts"]` 2. **重启克劳德代码**（或 `/mcp` 重新连接），使其获取服务器。 3. **请求克劳德渲染。** 例如 *"渲染此论文的预览"* → 第一次调用会下载 WASM TeX Live 资产（~480 MB，一次性），编译并打开实时预览选项卡。后续编辑会自动重新加载它。 WASM 资产 **不** 在此仓库中 - 它们会在首次运行时被获取到 `assets/` 中。要手动预获取它们：`npx texlyre-busytex download-assets assets`。 ## 安装为克劳德代码插件（斜杠命令） 为了实现低输入工作流，将 MagicTeX 安装为插件 - 一次安装为您提供 MCP 服务器 **和** 斜杠命令： ``` /plugin marketplace add ZoeLinUTS/MagicTeX-mcp /plugin install magictex ``` 然后，在您的论文项目中，使用 **工作流命令** 执行常见流程： - **`/magic-latex`** - 编译并打开工作空间（实时预览）。 - **`/ai-review [skill]`** - 使用技能（默认 `academic-paper-revision`;传递任意技能名称）审阅论文并发布评论，供您接受/拒绝。缺少的技能会报告安装提示。 - **`/address-comments`** - 解决您已接受的评论（循环它与 `/loop 60s /address-comments`）。 - ⚡ **`/ultra-agents [skill] [depth]`** - 全自主：审阅，自动接受，修复，重复，直到 `depth` 轮（默认为 2），在发现新内容时提前停止。无每轮批准 - 这就是重点，也是风险。`depth > 5` 会要求您在启动前确认。结束时提供总结（提出了什么，发生了什么更改，应查看哪些检查点）- 每个轮次仍然是一个普通的，可逆转的检查点。请参阅 [`docs/AGENT-LOOP.md`](docs/AGENT-LOOP.md#ultra-agents). ### 每个工具一个命令 每个 MCP 工具也有一个具有 **相同名称** 的斜杠命令，因此您可以输入工具名称来驱动任何单个步骤。规则是：*工具是 `X` → 输入 `/X`*。 | 输入此内容 | 运行工具 | 它执行的操作 | | -------------- | ----------------- | ------------ | | `/render_preview` | `render_preview` | 编译论文并打开/刷新实时预览。 | | `/check_comments` | `check_comments` | 返回您已接受的评论，作为位于工作项 - 页面，引用的段落，源代码 `file:line` 以及请求。 | | `/resolve_comment [id] [note]` | `resolve_comment` | 在编辑后标记评论完成；它在您的审阅中变为 **绿色**。 | | `/add_comment ["quote"] [note]` | `add_comment` | 将评论锚定到一个段落上。作为 *建议* 发布，等待您的接受/拒绝，除非设置了 `accepted` 标志 - 该标志使自主模式自主。 | | `/reply_to_comment [id] [text]` | `reply_to_comment` | 添加一个线程回复，以便在评论中解决问题，而不是在聊天中。 | | `/show_diff [checkpoint]` | `show_diff` | 呈现 **并排差异作为图像**，显示内联在对话中。默认为当前未提交的更改；传递检查点 sha 以获取保存的版本。 | | `/list_checkpoints [limit]` | `list_checkpoints` | 最近的检查点及其 sha，新版本优先 - 使用它来查找一个传递给 `/show_diff`。 | 您 **不必** 始终输入这些 - 普通英语也有效（例如 *"渲染预览"*， *"解决我的评论"*）。命令只是快速，可教的速记。 > 插件捆绑了 MCP 服务器（`npx magictex-mcp`），因此安装插件是一切您需要的 - 上面的 `.mcp.json` 是另一种选择，如果您不想安装插件。斜杠命令无论哪种方式都有效。 ## 工具 MCP 接口，用于任何支持 MCP 的客户端。（在克劳德代码中，您可以直接用普通英语询问，或使用上面的斜杠命令 - 这些是底层工具。） | 工具 | 参数 | 它执行的操作 | | ---- | ---------- | ------------ | | `render_preview` | `mainFile?` · `engine?`（`pdflatex` \| `xelatex` \| `lualatex`，默认为 `xelatex`) · `backend?`（`wasm` \| `system` \| `auto`，默认为 `wasm`） | 编译项目并打开/刷新实时工作空间。 如果省略，则自动检测主文件以扫描 `\documentclass`。 | | `check_comments` | `includeResolved?`（默认为 `false`） | 返回已接受的评论，作为位于工作项 - 页面，引用的段落，源代码 `file:line` 以及请求。审阅者建议等待您的决定，但不作为工作返回。 | | `add_comment` | `quote` · `comment` · `role?`（`reviewer` \| `defender`) · `page?` · `accepted?` | 将评论锚定到一个段落上。作为 *建议* 发布，等待您的接受/拒绝，除非设置了 `accepted` 标志 - 该标志使自主模式自主。 | | `resolve_comment` | `id` · `note` | 在编辑后标记评论完成，并附上一行描述它更改的内容。它在您的审阅中变为 **绿色**。 | | `reply_to_comment` | `id` · `text` · `role?`（`author` \| `reviewer` \| `defender`) | 添加线程回复，以便在评论中解决问题，而不是在聊天中。 | | `show_diff` | `checkpoint?` | 呈现 **并排差异作为图像**，显示内联在对话中。默认为当前未提交的更改；传递检查点 sha 以获取保存的版本。 | | `list_checkpoints` | `limit?`（默认为 10，最大 50） | 最近的检查点及其 sha，新版本优先 - 使用它来查找一个传递给 `/show_diff`。 | **标语工作流建立在这些之上，而不是它们之间。** `/magic-latex`，`/ai-review`，`/address-comments` 和 ⚡ `/ultra-agents` 是克劳德代码插件命令，它们协调上面的工具 - `/ultra-agents` 链接审阅 → 自动接受 → 修复，重复，直到您允许的次数，并且这是 `add_comment` 标志 `accepted` 的原因。它们不是 MCP 接口的一部分，因此另一个 MCP 客户端只看到七个工具。请参阅 [插件部分](#install-as-a-claude-code-plugin-slash-commands) 和 [docs/AGENT-LOOP.md](docs/AGENT-LOOP.md). ## 在终端中查看 这些是实际的工具输出，直接从实际运行中捕获 - 不是模拟的。这是您在克劳德代码中看到的内容，而浏览器工作空间（上面的截图）实时反映相同状态。 您输入： ``` /magic-latex` 克劳德调用 `render_preview` 并回复： ``` ✓ 使用 xelatex 编译 main.tex 1900ms - 2 个文件。工作空间（实时预览，源代码编辑器，历史记录，PDF 评论 - 自动重新加载 http://127.0.0.1:52042/app ``` 您（或审阅技能）留下评论，然后请求什么准备好执行。克劳德调用 `check_comments`： ``` 1 accepted comment — edit each at its source location per the instruction, then call resolve_comment with its id and a one-line note: [id: 2fce9e3c8b5f] p.1 — "Sorting widgets efficiently is a long-standing problem" ↳ source: main.tex:15 → Tighten this opening sentence. (1 reviewer suggestion still awaits the human's accept in the workspace — not actionable yet.) ``` 克劳德进行编辑并调用 `resolve_comment`： ``` ✓ Resolved comment 2fce9e3c8b5f ("Sorting widgets efficiently is a long-standing problem…") — the card now shows: Rewrote the opening sentence. ``` 询问再次，得到已接受的队列为空 - 只有仍未接受的建议仍然存在，等待您： ``` No accepted comments. (2 already resolved.) (1 reviewer suggestion still awaits the human's accept in the workspace — not actionable yet.) ``` ## 工作原理 ``` 克劳德编辑 .tex ─┐ 文件监视器 ─────┼─▶ 编译协调器 ─▶ 无头铬 ─▶ WASM TeX ─▶ PDF render_preview ───┘ (序列化) (引擎主机) │ ▼ 您的空间 (/app) ◀── WebSocket "reload" ◀── 本地 HTTP 服务器 源代码 · PDF · 历史记录 · 评论 (服务 /app + /latest.pdf) ``` WASM 引擎需要 DOM/Worker 全局变量，因此服务器托管一个隐藏的无头铬作为其编译工作器；您打开的工作区是一个轻量级 React + pdf.js 应用程序，其中不包含 WASM。参见 [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)。 ```mermaid flowchart LR H["👤 您<br/>源代码 · PDF · 历史记录 · 评论"] A["🤖 克劳德代码<br/>+ 审查 / 作者代理"] H <-->|"选择文本 →<br/>锚定评论"| SRV["预览服务器<br/>HTTP + WebSocket · 服务 /app"] A -->|"7 个 MCP 工具"| MCP["MCP 服务器<br/>render_preview · show_diff · list_checkpoints<br/>check / resolve / add / reply_comment"] SRV --> CO["编译协调器<br/>(序列化)"] MCP --> CO A -. 编辑源代码 .-> FILES[("论文文件 · git 仓库")] FILES --> WATCH["文件监视器"] --> CO CO --> ENG["WASM busytex<br/>(无头铬)"] --> PDF["/latest.pdf"] PDF -. 实时重载 .-> H CO --> CK["git 检查点<br/>(隐藏引用) → 历史记录"] SRV <--> CJSON[(".latex-preview/<br/>comments.json")] MCP <--> CJSON CJSON -->|"检查评论<br/>(您的已接受请求)"| A ``` 两个入口 - 您在工作区，代理通过 7 个 MCP 工具 - 在同一个协调器、评论存储库和 git 历史记录中相遇。您操作 *渲染* 文档（锚定评论）；克劳德操作 *源代码*（读取您的评论，通过 `check_comments` 编辑，`resolve_comment`）。这个共享的子基是使评论循环、审查工作流和可跟踪的历史记录成为可能的原因。 ## 要求 - 节点 20+ - Playwright 的 Chromium（自动安装；~150–300 MB）- 或设置为重用您已安装的 Chrome。 - ~650 MB 磁盘用于一次性 WASM TeX Live 资产（一个普通论文仅需要 ~118 MB 基本集合；较大的软件包集合按需加载）。 ## 开发 ```bash npm install npm run typecheck # 服务端和 UI 的 tsc npm run build:ui # 构建 React 工作空间到 ui/dist npm test # 评论存储库，锚点匹配和一个 MCP 工作流 E2E npm start # 在标准输入/输出上运行服务器（用于手动 MCP 客户端） ``` CI（`.github/workflows/ci.yml`）在 Node 20 和 eval 22 上运行类型检查 + UI 构建 + 测试 - 每次推送和拉取请求。测试是引擎无关的（无无头浏览器），因此速度快且确定性强；请保持它们绿色并在更改时添加覆盖率。 ## 文档 - [**用户指南**](docs/USER-GUIDE.md) — 日常使用，评论循环，视觉模式，文件树，将您的论文导入 Overleaf，软件包覆盖率。 - [**代理循环**](docs/AGENT-LOOP.md) — 评论作为触发器，手动运行 `/loop`，审查员 → 网关 → 解决者工作流，和 ⚡ `/ultra-agents`。 - [**路线图**](docs/ROADMAP.md) — 已发布的并发代理功能，以及实际的并行多代理编辑仍需要什么。 - [**架构**](docs/ARCHITECTURE.md) — 为什么使用无头浏览器，每个模块的作用，编译流程。 所有四个文档都翻译成了与此 README 相同的 8 种语言 - 每个页面都有自己的语言切换器。 ## 路线图 多个克劳德代码会话可以同时处理同一个项目而不会损坏评论或检查点历史记录（参见 [`docs/ROADMAP.md`](docs/ROADMAP.md)）- 真正的并行多代理编辑（审查者/作者/防御者位于自己的 git 分支上，合并回一起）是下一个里程碑。 ## 赞助该项目 MagicTeX 免费且开源（AGPL-3.0）。如果它为您节省了论文时间，请考虑 **[赞助该项目](https://github.com/sponsors/ZoeLinUTS)** - 它资助了持续的开发。仓库上的 ⭐ 也很有帮助。 ## 许可 [AGPL-3.0-or-later](LICENSE) — 与其构建的 `texlyre-busytex` 引擎相匹配。参见 [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md)。