Rustpad MCP Server

rustpad-mcp

一个用于 Rustpad 的 Model Context Protocol（MCP）服务。Rustpad 是一款高效、精简、可自托管的协作文本文本编辑器。

它让 Claude Code、Claude Desktop 或 Codex 等 MCP 客户端能够读取和写入 Rustpad 实例中的文档：获取文档、创建文档、整体替换文档，或直接编辑文档内容。

八个工具是上限，而非下限：设置 RUSTPAD_ALLOW_TOOLS=essential 可改为注册精心挑选的五个工具。模型从五个工具中挑选合适工具的可靠性远高于从八个中挑选——参见选择要加载的工具。

读取操作通过 Rustpad 的 HTTP API 执行；写入操作则使用操作转换 WebSocket 协议，因此针对性编辑（append_to_document、replace_in_document）能够与人类协作者同时输入的内容顺畅合并，而不会将其覆盖。服务编辑文档时，文档中的所有人都会看到名为 rustpad-mcp 的协作者。

两种无法撤销的编辑需要由真人确认。 如果客户端支持 MCP 征询，替换非空文档和跨多个匹配项执行搜索替换时，会弹出模型无法代为回答的真实对话框；replace_in_document 的对话框还会说明即将更改多少处。如果客户端不支持，则会回退到两次调用的令牌机制，并明确说明这一点，而不会暗示有人已经批准。将 ELICITATION=false 设置为有意启用此回退机制；它绝不会移除保护措施。参见征询真人确认。

与众不同之处

真正的 OT 编辑，而非覆盖。 append_to_document 和 replace_in_document 会保留所有未触及的内容，Rustpad 服务会转换并合并并发编辑——即使有人在同一时刻输入同一份文档，也不会丢失任何内容。模型会以具名协作者的身份出现在文档中。

为无身份验证的环境而设计。 Rustpad 没有账户，因此每份文档从定义上来说都不可信。从文档中获取的所有内容——读取结果、元数据，甚至上游错误正文——在交给模型查看前都会明确标记为数据，而非指令。

要求

• 可访问的 Rustpad 实例（可自托管；服务器无状态，无需凭据——Rustpad 不提供身份验证）
• Node.js >= 22，或 Docker

配置

变量	必需	说明
RUSTPAD_URL	是	实例的基本 URL，例如 https://rustpad.example.net
RUSTPAD_READ_ONLY	否	true、1 或 yes 仅注册读取工具
RUSTPAD_INSECURE_TLS	否	true 接受自签名证书（仅对此连接生效）
RUSTPAD_ALLOW_TOOLS	否	以逗号分隔的工具名称、list_* 前缀，或用于精选预设的 essential
RUSTPAD_DENY_TOOLS	否	语法相同；从 RUSTPAD_ALLOW_TOOLS 留下的工具中移除
ELICITATION	否	false 会用双次调用令牌替代审批对话框。没有前缀

同一个 URL 用于 HTTP API、WebSocket 端点，以及工具返回的分享链接（<RUSTPAD_URL>/#<pad-id>）。RUSTPAD_* 布尔值必须准确为 true。服务器无需配置即可启动并列出工具；之后每次调用都会失败并显示设置说明。

ELICITATION 有两点特殊之处：它没有前缀，因此会影响同一环境中的每个 MCP 服务；而且，如果其值既不是 true 也不是 false，服务器就会停止运行，而不会回退——它是此处唯一默认值为 开启 的变量，否则拼写错误会让对话框继续运行，而你却以为它已关闭。关闭此选项启动服务器时，会打印一行说明。

请记住 Rustpad 的特点：便笺是临时的（服务器重启后以及闲置 24 小时后都会丢失，除非实例使用 SQLITE_URI 运行），并且任何知道便笺 ID 的人都能读取和写入内容。请勿在便笺中放入机密。

选择要加载的工具

RUSTPAD_ALLOW_TOOLS 和 RUSTPAD_DENY_TOOLS 接受以逗号分隔的工具名称；末尾的 * 可匹配整个工具系列。essential 是包含五个工具的精选预设：get_document、get_document_info、create_document、set_document、append_to_document。

RUSTPAD_ALLOW_TOOLS=essential
RUSTPAD_ALLOW_TOOLS=get_document,append_to_document
RUSTPAD_DENY_TOOLS=set_document

有一点没有列表看起来那么明确：Rustpad 没有创建操作，便笺只要写入内容，就会以任意 ID 创建，因此禁止 create_document 并不能阻止新建便笺——对一个全新的 ID 调用 set_document 或 append_to_document 同样会创建便笺。请禁止你想限制的写入工具，或使用 RUSTPAD_READ_ONLY。

如果某个条目与任何工具都不匹配，启动就会中止并指出该条目，因此拼写错误不会悄悄隐藏工具——缺失的工具不会让人追溯到某个环境变量。被筛选掉的工具不会注册，因此它既不会出现在 tools/list 中，也无法通过 tools/call 调用；与 RUSTPAD_READ_ONLY 下的写入工具完全一样。

如果同时运行多个此类服务，另一个解决方案是 mcp-hub——它的 /hub 端点会用六个元工具替代每个服务的所有工具。

安装

Claude Code

claude mcp add rustpad --env RUSTPAD_URL=https://rustpad.example.net -- npx rustpad-mcp

Claude Desktop

{
  "mcpServers": {
    "rustpad": {
      "command": "npx",
      "args": ["rustpad-mcp"],
      "env": {
        "RUSTPAD_URL": "https://rustpad.example.net"
      }
    }
  }
}

Codex

~/.codex/config.toml：

[mcp_servers.rustpad]
command = "npx"
args = ["-y", "rustpad-mcp"]

[mcp_servers.rustpad.env]
RUSTPAD_URL = "https://rustpad.example.net"

Docker

docker run -i --rm -e RUSTPAD_URL=https://rustpad.example.net ghcr.io/ni-c/rustpad-mcp

通过 mcp-hub

无法启动本地进程的客户端——ChatGPT connectors、Claude 网页版、 Cursor、LibreChat——通过 mcp-hub 连接 rustpad-mcp：一个 容器通过 Streamable HTTP 为多个 stdio MCP 服务提供服务，使用单个密码进行 OAuth 2.1 登录， 并为无法使用 OAuth 的客户端提供长期有效的令牌。它的 /hub 端点通过六个元工具提供所有服务，因此一个连接器就能访问所有服务，无需在模型的上下文中加入 N×工具架构；它还支持两个协议版本——本服务提出的问题会经由它传递给另一端的用户。

它的 /config/mcp.json 使用 Claude Code 的格式，因此配置项就是你已有的：

{
  "mcpServers": {
    "rustpad": {
      "command": "npx",
      "args": ["-y", "rustpad-mcp"],
      "env": { "RUSTPAD_ALLOW_TOOLS": "essential" },
      "denyTools": ["set_document"]
    }
  }
}

其中的 allowTools 和 denyTools 是 hub 自己针对每个服务的过滤器，与 env 中的 *_ALLOW_TOOLS 不同——两者的区别以及由此可能引发的错误，详见客户端指南。

工具

工具	描述
get_document	读取便笺的纯文本内容
get_document_info	内容长度、修订版本、语言以及当前正在编辑的用户
get_stats	服务统计信息（运行时间、文档数量）
create_document	创建便笺（使用随机或指定 ID），可选择设置内容和语言
set_document 👤	替换全部内容——非空便笺会先询问用户
append_to_document	追加文本；其他位置的并发编辑会保留
replace_in_document 👤	通过 OT 精确查找并替换；如果会更改多个位置，则会先询问用户
set_language	设置 Monaco 语法高亮语言

👤 通过 MCP elicitation 询问用户 · 客户端无法显示对话框时，则使用两次调用的 confirm_token 作为后备方式。

设置 RUSTPAD_READ_ONLY=true 后，只会注册前三个工具。

结构化输出

每个工具都声明了一个 outputSchema，并在文本块之外通过 structuredContent 返回结果，因此客户端无需解析文本即可使用结果。 五个写入工具过去会用一句话作答——“已向便笺……追加 12 个字符”——这句话仍然会出现在文本块中：

{
  "id": "notes",
  "url": "https://rustpad.example/#notes",
  "appended_characters": 12,
  "characters": 137,
  "note": "Pads are ephemeral: …",
}

get_document 返回 {text}，而不是将便笺本身作为完整结果；原因与 get_document_info 一直返回对象相同：如果将根类型为字符串的架构提供给 2025 年的客户端，客户端会将其改写为 {result: …}，导致工具根据提问者不同而以两种形式作答。这里也可以放置 empty 和 truncated 字段——以前空结果会返回一句话。

两个报告便笺内容的读取工具都带有 untrusted: true 和 source: "rustpad" 字段。任何知道便笺 ID 的人都可以写入便笺，包括本服务先前写入的文本；如果客户端读取结构化内容，就会在完全没有任何提示的情况下收到这些内容。

有意不提供的功能

不提供便笺列表——Rustpad 没有此类 API。每个 ID 下都隐式存在便笺，因此你必须知道自己需要哪些 ID。get_stats 会报告服务当前持有的文档数量，但不会报告其名称。

没有账户，也没有权限。 Rustpad 两者皆无，因此每个便笺都被视为不可信输入，而不是经过登录验证的内容。

安全

• Pad 内容可由任何人写入，因此不可信：每个读取结果都会加上标记，告知模型应将其视为数据，绝不能视为指令。
• 两项不可逆编辑都需要由真人确认：通过真实对话框将 Pad 和确切替换内容绑定起来，模型无法代替用户作答。如果客户端无法显示对话框，则改用一次性令牌；该令牌只会出现在之前的工具结果中——这只能证明调用使用相同参数进行了两次，不能证明其他任何内容。回退文本会说明是哪一项编辑。
• 工具结果的大小有限制；实例写入的所有内容都会剥除控制字符，上游错误正文也会在传给模型前进行清理。
• 实例本身也不可信：WebSocket 帧会在缓冲前根据标头限制大小，消息队列的字节数有上限，并且每个帧都会先检查格式，再合并到 Pad 中。
• RUSTPAD_INSECURE_TLS 仅对已配置的连接放宽证书验证，不会影响整个进程。

文档

完整指南、工具参考和安全说明请访问 rustpad-mcp.ni-c.de（源文件位于 docs/）。

开发

npm install
npm run lint && npm run build && npm test

测试套件通过真实 MCP 协议与 rustpad-server 的内存模拟版本通信（包括对并发编辑进行 OT 转换）；无需运行中的实例。架构图和社交媒体卡片均为生成内容——请编辑 docs/assets/architecture.source.svg 并运行 npm run assets，不要编辑渲染后的副本。

发布

发布由标签触发。更新 package.json，将 CHANGELOG.md 中的 [Unreleased] 说明移至新版本下方，然后提交，接着运行：

git tag -s vX.Y.Z -m "vX.Y.Z"
git push origin main vX.Y.Z

发布工作流会通过 Trusted Publishing（OIDC，并附带来源证明）发布到 npm，将多架构容器镜像推送到 GHCR，根据 CHANGELOG 中的相应部分创建 GitHub 发布，并更新官方 MCP 注册表中的条目。

参与贡献

欢迎提交问题、参与讨论和发起拉取请求——请参阅 CONTRIBUTING.md。如需报告漏洞，请使用私密报告渠道，不要公开提交问题；相关政策请参阅 SECURITY.md。

许可证

MIT © Willi Thiel