内容
# Overleaf MCP
[](https://www.npmjs.com/package/overleaf-mcp-rt)
[](https://www.npmjs.com/package/overleaf-mcp-rt)
[](LICENSE)
[](https://nodejs.org/)
> **适用于自托管 Overleaf 的实时 [模型上下文协议](https://modelcontextprotocol.io/) 服务器 - 无需 git-bridge，无需 Server Pro，无需分叉。**
**Overleaf MCP** 允许 AI 编程代理（Claude Code、Claude Desktop、Codex、Cursor、Continue 和任何其他符合 MCP 的客户端）读取、写入和编译任何 **个人或自托管 Overleaf 社区版** 实例中的 LaTeX 项目。 与其依赖 git-bridge 集成 - 一个付费的 Server Pro 功能，个人 Overleaf 安装不具备 - 它通过 **Socket.IO** 使用 Overleaf 的 **原生操作转换（OT）协议**。 编辑实时流入编辑器作为协作者操作，没有“文件外部更改”提示，也无需额外基础设施。
在 npm 上以 **[`overleaf-mcp-rt`](https://www.npmjs.com/package/overleaf-mcp-rt)** 分发 - `rt` 后缀标记为 **r**eal-**t**ime / OT 支持的风格，与 git-bridge 风格的 Overleaf MCP 服务器不同。
```bash
npx overleaf-mcp-rt@latest --help
```
## 目录
- [为什么是“实时”？原生 OT 与 git-bridge](#为什么是“实时”？原生OT与git-bridge)
- [安装](#安装)
- [快速开始](#快速开始)
- [MCP 客户端配置](#mcp-客户端配置)
- [健康检查：`diagnose`](#健康检查diagnose)
- [工具](#工具)
- [发现和读取](#发现和读取)
- [编辑](#编辑)
- [项目树 CRUD](#项目树crud)
- [编译](#编译)
- [错误信封](#错误信封)
- [v1.1 版本说明](#v11-版本说明)
- [v1.0 版本说明](#v10-版本说明)
- [路线图](#路线图)
- [常见问题](#常见问题)
- [真相来源](#真相来源)
- [许可证](#许可证)
- [致谢](#致谢)
## 为什么是“实时”？原生 OT 与 git-bridge
| | **Overleaf MCP** (原生 OT) | git-bridge 风格的 MCP 服务器 |
|---|---|---|
| 在个人/社区版 Overleaf 上工作 | ✅ | ❌（仅限 Server Pro） |
| 编辑器延迟 | 实时（每个补丁） | 分钟（git push + 桥同步） |
| 服务器要求 | Stock Overleaf CE 3.x – 5.x | Overleaf Server Pro + git-bridge 许可证 |
| “文件外部更改”提示 | 绝不会 - 编辑作为协作者 OT 操作到达 | 是 - 每次 git 同步都会触发 |
| 认证模型 | 会话 cookie | git over HTTPS / SSH |
如果您运行自己的 Overleaf 社区版 - 在 Docker 上，在 homelab 上，任何地方 - 并且您希望 Claude Code 或其他 AI 代理在其中编辑 LaTeX，并实时在浏览器中显示编辑内容，那么这就是您的项目。
## 安装
```bash
# A. 通过 npx 零安装（推荐用于 MCP 客户端）
npx overleaf-mcp-rt@latest --help
# B. 用于 shell 的全局安装
npm install -g overleaf-mcp-rt
overleaf-mcp-rt --help
```
需要 Node.js ≥ 20。
## 快速开始
```bash
# 1. 获取会话 cookie（从 devtools 粘贴或使用 --email/--password）
npx overleaf-mcp-rt login --url https://overleaf.example.com
# 2. 烟雾测试连接、身份验证和 OT 握手
npx overleaf-mcp-rt diagnose
# 3. 列出您的项目
npx overleaf-mcp-rt ls
```
## MCP 客户端配置
适用于 Claude Code、Claude Desktop、Cursor、Codex（通过 MCP）、Continue 和任何符合 MCP 的客户端。
```jsonc
{
"mcpServers": {
"overleaf": {
"command": "npx",
"args": ["-y", "overleaf-mcp-rt@latest"],
"env": {
"OVERLEAF_URL": "https://overleaf.example.com",
"OVERLEAF_SESSION_COOKIE": "overleaf_session2=s%3A..."
}
}
}
}
```
如果您的 Overleaf 前面有一个身份验证代理（Cloudflare Access、Authelia、oauth2-proxy、HTTP 基本身份验证等），请通过可选的 `OVERLEAF_EXTRA_HEADERS` 环境变量以 JSON 对象传递代理标头 - 其键/值合并到每个 REST 请求和 Socket.IO 升级中。运行 `diagnose`（下一节）以验证两层。
## 健康检查：`diagnose`
配置凭证后，从 shell 运行：
```bash
overleaf-mcp-rt diagnose
```
输出是逐步报告：
```
✓ 配置 — URL https://overleaf.example.com
✓ REST 握手 — cookie 有效，CSRF 抓取
✓ 项目列表 — 3 个项目（s）可访问
✓ OT 握手 — publicId P.abc...
```
任何步骤的 `✗` 都会打印底层错误代码（`OVERLEAF_AUTH_FAILED`、`PROXY_AUTH_FAILED`、`PROJECT_ACCESS_DENIED`），以便您知道要修复哪一层。
## 工具
16 个 MCP 工具，所有工具都以 `overleaf_*` 为前缀，以便在不自动按服务器名称命名空间的主机中保持无歧义。 每个工具的错误响应都使用 [结构化错误信封](#错误信封)。
### 发现和读取
| 工具 | 目的 |
|---|---|
| `overleaf_list_projects` | 列出可访问的项目。 |
| `overleaf_get_project_tree(projectId)` | 文件夹 + 文件树（实时，OT 支持）。 |
| `overleaf_read_doc(projectId, path)` | 完整的文本文档内容（实时，OT 支持）。 |
| `overleaf_read_doc_range(projectId, path, startLine?, endLine?, startOffset?, length?)` | 文档的子字符串，按 1-indexed 的行范围或字符偏移/长度。 返回 `totalLines` / `totalChars`。 使用此功能在编辑后验证小区域，而无需重新获取整个文档。 |
| `overleaf_read_file(projectId, path, as?)` | 二进制文件。 默认 `as=auto`：MCP 图像内容的原生内容，用于图像 MIME，用于文本 MIME 的文本内容，用于 PDF 的资源，用于其他类型的基础64 信封。 传递 `as=base64` 以强制 `{contentBase64, mimeType}` 信封用于任何类型 - 在通过 `overleaf_upload_file` 以编程方式复制时非常有用。 |
### 编辑
| 工具 | 目的 |
|---|---|
| **`overleaf_edit_doc(projectId, path, edits[], dryRun?)`** | **推荐的编辑界面。** 六种模式的高级文本编辑：`replace`、`insert_before`、`insert_after`、`replace_lines`、`unified_diff` 和 `raw_ops`。 单个调用中的所有编辑都原子性应用（全部或无）。 传递 `dryRun: true` 以预览解析的 OT 操作而不应用。 返回写入摘要。 |
| `overleaf_write_doc(projectId, path, content)` | 替换文本文档； 流式传输为 OT 操作，无提示。 返回摘要 `{versionBefore, versionAfter, charsBefore, charsAfter, charsDelta, opsApplied}`。 在您拥有整个所需内容时使用。 |
#### `overleaf_edit_doc` 模式
| 模式 | 用例 |
|---|---|
| `replace` | 基于锚点的查找和替换。 默认 `occurrence: 'unique'` 如果查找字符串出现 0 或 >1 次，则错误；传递 `'all'`、`'first'` 或整数 N 以消歧义。 |
| `insert_before` / `insert_after` | 在唯一锚点之前/之后插入文本。 |
| `replace_lines` | 用新文本替换 1-indexed 的行范围。 |
| `unified_diff` | 应用 `diff -u` 样式的补丁（LLM 流畅地发出）。 不能与基于锚点的编辑在同一个调用中组合。 |
| `raw_ops` | 调用者提供的 OT 操作 `[{p, i?, d?}]`。 每个操作都针对本地基线预验证； 不匹配的 `d`-字符串抛出 [`OT_DELETE_MISMATCH`](#错误信封) 在任何服务器调用之前。 不能与基于锚点的编辑组合。 |
### 项目树 CRUD
| 工具 | 目的 |
|---|---|
| `overleaf_create_doc(projectId, parentPath, name, content?)` | 创建文本文档； 可选的初始内容是 OT 编写的创建后。 使用 `parentPath: ""` 表示项目根目录。 |
| `overleaf_create_folder(projectId, parentPath, name)` | 创建文件夹。 |
| `overleaf_upload_file(projectId, parentPath, name, contentBase64, mimeType?)` | 上传二进制文件； 当省略时，MIME 类型从扩展名推断。 服务器可能会自动将文本 MIME 类型提升为文档。 |
| `overleaf_rename(projectId, path, newName)` | 重命名文档/文件/文件夹。 |
| `overleaf_move(projectId, path, newParentPath)` | 移动文档/文件/文件夹。 使用 `newParentPath: ""` 表示项目根目录。 |
| `overleaf_delete_entity(projectId, path)` | 删除文档/文件/文件夹。 |
### 编译
| 工具 | 目的 |
|---|---|
| `overleaf_compile(projectId, draft?, stopOnFirstError?)` | 触发 LaTeX 编译，返回输出 URL。 |
| `overleaf_read_compile_log(projectId)` | 编译并返回 `output.log` 文本。 |
| `overleaf_download_pdf(projectId)` | 编译并返回 PDF 作为 MCP 资源（`application/pdf`，base64 块）。 |
### 错误信封
每个工具错误都序列化为 MCP `text` 内容块中的 JSON（带有 `isError: true`）：
```json
{
"code": "OT_DELETE_MISMATCH",
"message": "删除操作 #0 在位置 0 预期 \"FOO\" 但文档有 \"BAR\"",
"context": { "p": 0, "expected": "FOO", "actual": "BAR", "opIndex": 0 },
"retryable": false,
"hint": "d-字符串与位置 p 处的文档不匹配。 重新读取文档以获取当前文本，然后重新计算偏移量。"
}
```
| 代码 | 含义 |
|---|---|
| `OVERLEAF_GENERIC` | 验证或其他非类型错误（模糊锚点、超出边界的行范围、混合模式 `edit_doc` 等）。 |
| `OVERLEAF_AUTH_FAILED` | 会话 cookie 无效/过期。 重新运行 `overleaf-mcp-rt login`。 |
| `PROXY_AUTH_FAILED` | 反向代理阻止了请求 - 设置 `OVERLEAF_EXTRA_HEADERS`。 |
| `PROJECT_ACCESS_DENIED` | 会话无法访问请求的项目。 |
| `NOT_FOUND` | 给定路径下无文档/文件/文件夹。 |
| `NETWORK_ERROR` | 传输级故障（`retryable: true`）。 |
| `OT_DELETE_MISMATCH` | `overleaf_edit_doc` 的 `raw_ops` 模式中的 d-字符串与文档在 `p` 处不匹配。 在环路前在客户端预验证，因此您在进行往返之前就会知道。 |
| `OT_VERSION_DRIFT` | 文档在写入重试期间移动（`retryable: true`）。 |
| `INVALID_CONFIG` | 缺失或格式错误的 `OVERLEAF_URL` / cookie / 额外标头。 |
`retryable: true` 为暂时性故障（`NETWORK_ERROR`、`OT_VERSION_DRIFT`）设置； 代理可以使用它来驱动重试循环。 `hint` 为最常见的故障提供了一行下一步骤。
## v1.1 版本说明
v1.1 添加了 v1.0 原始 OT 操作表面使得痛苦的使用体验的代理工程表面，并将所有工具重命名为 `overleaf_*` 前缀：
- **所有工具重命名为 `overleaf_*`** - `read_doc` → `overleaf_read_doc`，`compile` → `overleaf_compile` 等。 前缀在不自动按服务器命名空间的 MCP 主机（Cursor、Continue、自定义 stdio）中保持工具名称无歧义。 Claude Code 的 `mcp__<server>__<tool>` 命名空间仍然在上面应用。
- **`overleaf_edit_doc` 工具** - 基于锚点的 `replace`（具有 `unique`/`first`/`all`/Nth 出现语义）、 `insert_before` / `insert_after`、行范围 `replace_lines`、`unified_diff` 和 `raw_ops` 作为逃生口。 一个调用中的所有编辑都解析为相同的基线并原子性应用； `dryRun: true` 返回解析的 OT 操作而不发出它们。 **这是推荐的编辑界面** - `apply_patch`（v1.0 原始操作工具）被删除，因为 `overleaf_edit_doc` 的 `raw_ops` 模式是严格的超集。
- **`overleaf_read_doc_range`** - 按行范围或偏移量/长度获取文档的子字符串，并返回 `totalLines` / `totalChars`。 为代理节省了往返费用，只需获取 50 KB 文档即可验证 200 字节的编辑。
- **`overleaf_read_file as=base64`** - 即使对于图像 MIME，也选择 `{contentBase64, mimeType}` 信封。 这样，代理可以通过 `overleaf_upload_file` 在两个项目路径之间复制二进制资产，而无需访问字节。
- **编辑摘要** - `overleaf_write_doc` 和 `overleaf_edit_doc` 都返回 `{versionBefore, versionAfter, charsBefore, charsAfter, charsDelta, opsApplied}`。 代理可以在不重新读取文档的情况下检查编辑。
- **结构化错误信封** - 工具错误序列化为 `{code, message, context, retryable, hint?}` JSON，而不是平面字符串。 新错误代码：`OT_DELETE_MISMATCH` 和 `OT_VERSION_DRIFT`。
- **错误线格式更改：** 错误响应现在是 `text` 内容中的 JSON；v1.0 发出的是 `${code}: ${message}` 普通文本。 v1.0 客户端需要将错误字符串解析切换为 JSON 解析。
- **防御性验证** - `overleaf_edit_doc` 在发出之前会根据本地基线预验证操作，因此错误偏移量会在不透明的服务器拒绝（或更糟糕的是无声无息的操作）之前出现。
- **删除：`apply_patch`** - 被 `overleaf_edit_doc` 替换为 `mode: 'raw_ops'`。 迁移：将旧的 `ops` 数组包装在 `{edits: [{mode: 'raw_ops', ops: [...]}]}` 中。
## v1.0 版本说明
这是 npm 上的第一个稳定版本。它包含了从之前的内部开发阶段（只读、OT 编写、树突变、润色）到一个单一的发布包：
- **实时 OT 读取和写入** - `read_doc`、`write_doc` 和原始 OT `apply_patch`（后来在 v1.1 中合并到 `overleaf_edit_doc` 中）通过 Overleaf 的原生操作转换管道流动。 其他连接的浏览器会话将编辑视为协作者的输入，而不是“文件外部更改”提示。
- **完整的 REST 树 CRUD** - `create_doc`、`create_folder`、`upload_file`、`rename`、`move`、`delete_entity`。
- **编译管道** - `compile`、`read_compile_log`、`download_pdf`（作为二进制 MCP 资源返回）。
- **`diagnose` CLI 子命令** - 逐步报告（配置 → REST → 反向代理 → 项目 → OT），以便失败的设置显示确切的失败层，并带有类型错误代码。
- **反向代理身份验证传递** - `OVERLEAF_EXTRA_HEADERS` 合并到 REST 客户端和 Socket.IO 握手中。
- **弹性** - 文档写入序列化（无基线竞争）、带有抖动的重新连接、OT 引擎驱逐信号、WHATWG-URL 规范化（子路径安全）、遵守 `pdfDownloadDomain` 以获取 overleaf.com REST 流。
- **兼容性** - Stock Overleaf CE 3.x – 5.x。 **无需分叉** `sharelatex/sharelatex` 和无需修补的服务器镜像，因此您可以干净地升级 Overleaf。
- **许可证** - AGPL-3.0-or-later（因为 OT/身份验证客户端是从 Overleaf-Workshop 移植的）。
## 路线图
### v1.x - 完整的 CLI 对等 + 代理技能
目前，上述每个工具都可以通过 MCP 访问；捆绑的 CLI 只涵盖 `login`、`ls` 和 `diagnose`。一些代理（Codex CLI、Aider、仅限终端的设置，任何需要 shell 之外的 MCP 信封的代理）更喜欢驱动一个普通的命令行工具。计划用于 v1.x：
- **每种工具的 CLI 对等** - 一个子命令对应一个工具，默认 JSON 输出以便代理解析， `--human` 用于 tty 友好表格。草图：
- `overleaf-mcp-rt projects ls` / `tree <projectId>`
- `overleaf-mcp-rt doc read <projectId> <path>` / `write <projectId> <path>`（stdin）/ `edit <projectId> <path> <edits.json>` / `patch <projectId> <path> <ops.json>`
- `overleaf-mcp-rt file read <projectId> <path>` / `upload <projectId> <parentPath> <name> <file>`
- `overleaf-mcp-rt fs mkdir | mv | rm | rename`
- `overleaf-mcp-rt compile <projectId> [--draft] [--stop-on-first-error]` / `log` / `pdf -o out.pdf`
- **用于 CLI 的代理技能** - 一个 `skills/` 目录与包一起提供，采用 [Claude Code 技能](https://docs.claude.com/en/docs/claude-code/skills) 格式（也适用于其他可以消化类似指令的代理）。每个技能都教授基于 CLI 的规范 Overleaf 工作流：编辑-编译-读取日志，上传图片并引用，重新组织参考文献，恢复编译错误。
- **相同的环境，两个界面** - `OVERLEAF_URL` / `OVERLEAF_SESSION_COOKIE` / `OVERLEAF_EXTRA_HEADERS` 适用于两种模式。MCP 服务器仍然是默认调用以保持向后兼容；CLI 是附加的。
### 超越 v1.x
- `recipes/` 目录中的光标规则和继续工具定义。
- `overleaf-mcp-rt watch` - 将本地目录镜像到项目中，就像您编辑它一样，用于非 MCP 工作流。
- 项目级回滚的可选进程内快照历史记录。
在 [GitHub 问题](https://github.com/DanielHou315/overleaf-mcp-rt/issues) 上跟踪或贡献。
## 常见问题
**这是否需要 Overleaf Server Pro？**
不。它针对的是股票 **Overleaf 社区版**（3.x – 5.x）。该项目的全部意义在于为个人/自托管的 CE 用户提供与 Server Pro git-bridge 用户相同的代理驱动编辑体验。
**这是否需要 git-bridge？**
不。编辑作为实时 OT 操作通过 Socket.IO 发送 - 与 Overleaf 的网络编辑器内部使用的相同协议。
**编辑会在浏览器中显示“文件外部更改”提示吗？**
不。MCP 服务器连接为常规协作者，因此其他浏览器会话将编辑视为协作者的输入。
**它是否适用于 overleaf.com（托管的 SaaS）？**
通过提供的会话 cookie，REST 支持的工具（`list_projects`、`compile`、`download_pdf`）可与 overleaf.com 配合使用。OT 支持的读写操作是为社区版设计的；SaaS 在协议细节上可能有所不同，并不是目标平台。
**它是否在反向代理后面工作？**
是的。通过 `OVERLEAF_EXTRA_HEADERS` 以 JSON 对象传递任何必需的标头（Cloudflare Access 服务令牌、基本身份验证、oauth2-proxy / Authelia 转发的用户等）。在配置后运行 `overleaf-mcp-rt diagnose`；缺少的标头将在 REST 步骤中显示为 `OVERLEAF_AUTH_FAILED` 或在 OT 步骤中显示为 `OT connectionRejected`。
**它与 [Overleaf-Workshop](https://github.com/iamhyc/Overleaf-Workshop) 有何比较？**
Overleaf-Workshop 是 VS Code 扩展，它率先使用 Overleaf 的原生 OT/Socket.IO 协议从浏览器外部进行通信。该项目将身份验证和 OT 客户端的重要部分移植到一个 Model Context Protocol 服务器中，以便任何兼容 MCP 的 AI 代理 - 而不仅仅是 VS Code 用户 - 都可以实时编辑 Overleaf 项目。两者都是 AGPL-3.0。
**为什么 npm 包是 `overleaf-mcp-rt`，而项目被称为“Overleaf MCP”？**
`rt` 后缀标记为 **r**eal-**t**ime / OT 支持的风格，因为其他“overleaf-mcp”风格的包可能使用 git-bridge 或 zip 快照方法。较短的“Overleaf MCP”是一个人类可读的项目名称。
## 真相来源
设计文档和每个阶段的计划位于 [`docs/superpowers/`](docs/superpowers/)。如果有疑问，文档规范是规范。
## 许可证
[**AGPL-3.0-or-later**](LICENSE)。由于该项目移植了 [Overleaf-Workshop](https://github.com/iamhyc/Overleaf-Workshop) 的部分代码（也是 AGPL-3.0）。
## 致谢
本项目移植了 [**Overleaf-Workshop**](https://github.com/iamhyc/Overleaf-Workshop) 的部分身份验证和 OT 代码，由 iamhyc 及其贡献者使用。 在 AGPL-3.0 下使用。
由 Anthropic 的 [模型上下文协议](https://modelcontextprotocol.io/) 构建。
---
**关键词：** Overleaf · ShareLaTeX · MCP · 模型上下文协议 · Claude Code · Claude Desktop · Codex · Cursor · Continue · LaTeX · 自托管 Overleaf · Overleaf 社区版 · 操作转换 · Socket.IO · git-bridge 替代品 · AI LaTeX 代理 · 实时协作编辑
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器