内容
# tex-mcp-web
**基于Claude Code的首个智能PDF评审工具，适用于LaTeX论文。**
从 [queelius/scholia](https://github.com/queelius/scholia) v0.6.1（MIT）硬分叉而来。已重命名并独立开发。
您在浏览器中阅读渲染的PDF，并在段落、章节或整篇论文上留下评论。Claude Code读取队列（通过MCP），编辑源代码，并回复更改内容。PDF在您面前重建。重复直到完成。
## 为什么存在
tex-mcp-web **刻意不作为编辑器**，**不作为IDE**，**不作为Overleaf克隆**。智能体（Claude Code）已经比我们能构建的任何工具都更擅长读取源代码、解析LaTeX、搜索引用和编辑文件。所以我们不尝试。
tex-mcp-web是**智能体优先写作工作流的基板**：
- **实时PDF预览**，人类可以观看和操作。
- **评论队列**，锚定在PDF区域、章节、源代码范围或整篇论文上。
- **结构化错误编译预言机**，智能体在需要事实依据时会调用。
仅此而已。三个职责。任何重新实现智能体做得好的事情（文件解析、日志分析、语义理解）的功能都被刻意删除。
## 安装
需要Python 3.10+和`latexmk`（或`pdflatex`/`xelatex`/`lualatex`/`pandoc`）位于您的`PATH`中。
```bash
pip install "tex-mcp-web[mcp] @ git+https://github.com/MiiKiyoshi/tex-mcp-web"
```
`[mcp]`额外功能添加了Claude Code的MCP服务器；`[image]`添加了PDF区域渲染（pymupdf）。纯`tex-mcp-web @ git+...`仅安装Web查看器。
## 快速开始
```bash
cd my-paper/
tex-mcp-web init --main main.tex # 编写 .tex-mcp-web.yaml（主文件，端口）
tex-web # 在 http://localhost:8765 启动守护进程
```
在浏览器中：
- PDF显示在左侧，评论侧边栏显示在右侧。
- **在PDF中选择文本**，以将评论锚定到该区域。SyncTeX自动将选择映射回源代码行范围。
- **Shift-click-drag**，以在任何区域（图形、方程式、空白空间）周围绘制矩形，其中文本选择无法到达。相同的`pdf_region`锚点；智能体可以使用`image(comment_id=...)`渲染确切的区域。
- **建议重写**，在任何评论旁边：撰写对话框具有可选的`{old, new}`块。当您首先选择文本时，“old”预填充为所选文本，因此您只需输入替换内容。智能体获得一个可以直接应用的结构化编辑。
- **"+ Note"**，在顶部栏中，用于论文级评论（“摘要太长了”）。
- **章节选项卡**，是目录：编号标题，点击跳转，**"+ comment"**，用于章节级评论。
- **编译选项卡**，列出编译错误和警告；选项卡徽章显示打开的评论和错误/警告计数。
- **回复 / 解决 / 忽略**，是每个评论的内联表单，而不是模态窗口。
- **键盘导航**：`j` / `k`，逐个评论，`r`，打开回复表单，`R`，打开解决，`d`，打开忽略，`Esc`，取消，`\`，折叠侧边栏。
- **Ctrl/Cmd + 轮滚**，围绕光标缩放PDF。
## Claude Code工作流
全局注册MCP服务器：
```bash
claude mcp add --scope user tex-mcp -- tex-mcp
```
服务器通过搜索Claude Code工作目录向上查找`.tex-mcp-web.yaml`，因此相同的注册服务于每篇论文：在论文目录中打开Claude Code，工具指向该论文。
这暴露了**7种工具**：
| 工具 | 功能 |
|---|---|
| `paper(include_comments=True)` | 一次调用论文状态：章节（带行范围），评论队列，最后编译缓存，主文件路径。 |
| `compile()` | 重新编译并返回带有源代码上下文的结构化错误。 |
| `comment(action, ...)` | `add` / `reply` / `resolve` / `dismiss` / `delete`。在添加时可选`suggestion={"old", "new"}`。 |
| `image(...)` | 将PDF区域渲染为PNG。模式：`page=N`，`page+bbox`，`source="file:lstart-lend"`，`comment_id="c-..."`。 |
| `section(name)` | 深入：源代码切片 + 渲染图像 + 作用域评论，针对一个章节，一次调用。 |
| `audit(focus=...)` | 智能体发起的审查工作流引导。返回指导；智能体然后以`author="claude"`的文件形式将评论反馈回去。 |
| `goto(target)` | 将正在运行的查看器滚动到章节 / 页面 / 行 / 标签。 |
当编译完成时，WebSocket广播`{"type": "compiled", ..., "pages_changed": [3, 7]}`，以便智能体仅验证实际更改的页面，而不是重新渲染整个文档。
注意缺失的内容：没有`labels()`，没有`citations()`，没有`environments()`。使用`Grep`。智能体比我们更擅长使用它。
**视觉审查**是`image`的杀手级模式。Claude是多模态的；纯文本无法告诉它图形标题是否附加到正确的图形或方程式是否正确渲染。`comment_id`模式是快速通道：人类在图形周围绘制矩形，提交评论，智能体渲染该区域，查看人类指向的内容，修复LaTeX。
**主动审查**在任一方向上运行循环：
```
您： [在PDF上留下8条评论；对于“重写X”的评论，填写建议的重写（智能体直接应用）]
“处理打开的评论。”
Claude： paper() # 查看评论 + 章节
对于每个：读取/编辑源代码；如果存在建议，则应用它
comment(action="resolve", id=..., summary="...")
compile() # 验证构建
您： [PDF重建；根据需要回复/忽略]
您： “审核我的方法部分是否存在符号漂移。”
Claude： audit(focus="math") # 引导性介绍
读取paper.tex； image() 检查渲染
comment(action="add", author="claude",
anchor=..., text="...", suggestion=...)
# 提交回队列，视觉处理不同
```
## 评论锚点
四种类型，具有不同的过时行为：
| 锚点 | 使用场景 | 过时处理 |
|---|---|---|
| `pdf_region` | 阅读PDF并指向段落。 | SyncTeX解析为源代码；捕获内容片段；如果Claude重写该区域，片段匹配失败，评论被标记为`STALE`。 |
| `section` | “扩展方法部分。” | 通过章节标题或`\label{...}`解析。仅当章节被删除或重命名时才过时。 |
| `source_range` | 当智能体已经知道行时（MCP中最常见）。 | 片段匹配，如`pdf_region`。 |
| `paper` | 关于论文的全局注释。 | 永远不会过时。 |
## 命令行界面
```
tex-mcp-web # 服务（默认）
tex-mcp-web init # 搭建 .tex-mcp-web.yaml
tex-mcp-web config # 打印 .tex-mcp-web.yaml
tex-mcp-web config port 9000 # 设置值（主/端口/编译器/监视/忽略/页面限制）
tex-mcp-web compile # 一次编译，结构化错误
tex-mcp-web goto "Methods" # 告诉正在运行的查看器滚动
tex-web # `tex-mcp-web serve` 的别名
tex-mcp # 运行MCP服务器（标准输入/输出）
```
这就是整个命令行界面。评论管理位于浏览器中（适用于人类）和MCP工具中（适用于智能体）。由于没有人会输入，因此没有`tex-mcp-web comment add`的shell命令。
## 配置
`.tex-mcp-web.yaml`：
```yaml
main: main.tex
watch: ["*.tex", "*.bib", "*.md", "*.txt", "**/*.tex"]
ignore: ["*_backup.tex"]
compiler: auto # auto | latexmk | pdflatex | xelatex | lualatex | pandoc
port: 8765
```
`tex-mcp-web init`搭建了这个；`tex-mcp-web config <key> <value>`编辑它。
评论存储在`.tex-mcp-web/comments.json`中。`git add`它以保留您的审查历史与论文。
## 许可证
MIT。参见`LICENSE`。
