sharedoc-mcp

sharedoc-mcp

由 Agent 生成的 Markdown → 一个可分享给任何人的链接。今天用 GitHub gists，明天用你自己的服务器。

English | 繁體中文

一个 MCP stdio 服务，可用于 Claude Code、Codex CLI 和任何 MCP 客户端，为你的 Agent 提供 9 个工具，用于发布、更新、搜索和撤销可分享的文档。两个可插拔后端共用一个接口：gist（无需配置，使用已登录的 gh CLI）和 selfhost（在你的机器上使用 SQLite、密码和强制到期时间）。

如果后端无法处理某个参数（例如 gist 的 password），它会返回清晰的错误，而不是默默忽略。

为什么？

AI Agent 不断生成 Markdown——报告、研究摘要、会议记录。要把这些内容交给其他人，通常只能把大段文字复制粘贴到聊天窗口。

Without sharedoc-mcp                  With sharedoc-mcp
────────────────────                  ─────────────────
copy a wall of text into chat         "share this as a doc"
paste again for each person           one link for everyone
content lives in chat scroll          revoke / extend / append later
"can you password it?"  …no           selfhost backend: bcrypt + expiry

这些 Markdown 摘要从何而来？它们通常由其他技能生成，例如： audio-tldr 会将视频和播客转成 Markdown 摘要；sharedoc-mcp 则会将摘要转成链接。

功能

• ✓ 9 个 MCP 工具：创建 / 追加 / 更新内容 / 扩展 / 重置密码 / 重命名 / 撤销 / 删除 / 搜索
• ✓ sharedoc-mcp serve 守护进程模式 — MCP 客户端关闭后，自托管链接仍可正常使用
• ✓ 内容搜索：根据分享内容查找旧分享链接，而不只是按标题搜索
• ✓ GET /healthz — 支持身份识别的健康检查端点，供外部监控 / 重启自动化使用
• ✓ 两种后端，一个接口 — 只需一个环境变量即可切换，工具架构保持一致
• ✓ Gist 后端（默认）：通过已登录的 gh CLI 创建私有 gist — 无需管理令牌，也无需托管新服务
• ✓ 自托管后端：文档保留在你的设备上（通过内置的 node:sqlite 使用 SQLite — 无需原生模块）
• ✓ 服务端验证密码（bcrypt）并限制尝试频率 — 每分钟 5 次，返回 HTTP 429；计数器持久化到 SQLite，因此重启无法重置计数（自托管）
• ✓ 强制执行过期规则（410），并在撤销后提供 7 天内容清除宽限期（自托管）；惰性清理过期内容（gist）
• ✓ 通过 marked + sanitize-html 渲染 Markdown — 会移除分享内容中的脚本、事件处理程序和 javascript: URL
• ✓ 查看器仅绑定到 127.0.0.1，并返回一组严格的安全标头（CSP default-src 'none'、nosniff、DENY 框架嵌入、no-referrer、no-store）— 暴露访问需通过你控制的隧道（见下方配置示例）
• ✓ 为 search_shared_docs 提供本地索引，并支持创建去重（5 分钟内内容相同且未受保护的重试会返回相同 URL；添加密码 / 过期时间的重试始终会创建新文档）
• ✓ search_shared_docs 支持偏移分页（响应中包含 hasMore）；在自托管模式下还提供查看统计信息（viewCount/lastViewedAt，仅在成功渲染时计数）
• ✓ 提供用于独立 serve 守护进程的 Docker 单行命令，默认与其他场景一样仅绑定到 127.0.0.1
• ✓ 两个 MCP 客户端可共享一个数据目录：SQLite WAL + 忙碌超时，支持优雅的端口共享
• ✓ 110 项离线测试；在全新检出的代码上运行 npm test 可通过

安装

需要 Node.js ≥ 22.13.0。Gist 后端还需要已登录的 GitHub CLI（gh auth login）。

选项 A — Claude Code（一行命令）：

claude mcp add sharedoc --scope user -- npx -y sharedoc-mcp@^2

选项 B — Codex CLI（~/.codex/config.toml）：

[mcp_servers.sharedoc]
command = "npx"
args = ["-y", "sharedoc-mcp@^2"]

选项 C — Cursor（一键安装）： 点击添加到 Cursor，或合并到 ~/.cursor/mcp.json：

{ "mcpServers": { "sharedoc": { "command": "npx", "args": ["-y", "sharedoc-mcp@^2"] } } }

选项 D — VS Code（一键安装）： 点击在 VS Code 中安装，或在终端中运行：

code --add-mcp '{"name":"sharedoc","command":"npx","args":["-y","sharedoc-mcp@^2"]}'

选项 E — 其他 MCP 客户端： 以 stdio 服务的方式运行 npx -y sharedoc-mcp@^2。

为什么使用 @^2？ 直接使用 npx -y sharedoc-mcp，每次冷启动都会解析为最新发布版本 — 未来的 3.0 版本可能在你不知情的情况下更改行为（或移除工具）。@^2 会跟进 2.x 修复，但绝不会跨越不兼容的主版本；如果你希望版本完全固定，可指定确切版本（@2.2.0）。

选择后端

	🅰 gist（默认）	🅱 selfhost
设置	无 — 使用已登录的 gh CLI	无需额外设置 — 数据保留在你的设备上
文档存储位置	GitHub（私有 gist）	你的设备（SQLite）
链接可访问范围	任何地方，立即可用	localhost — 添加隧道以便对外分享
密码	✗（通过私密 URL 进行保护）	✓ 服务端验证（bcrypt），限制尝试频率
过期	惰性处理 — 过期 gist 会在下次使用时删除	强制执行 — 过期链接返回 410
撤销	立即且不可逆地删除 gist	立即返回 410，7 天宽限期后清除内容
查看统计信息	✗（GitHub 的 gist API 不提供查看次数数据）	✓ viewCount + lastViewedAt，仅在成功渲染时计数

Gist 快速入门

让你的 Agent“将此内容分享为文档”——它会调用 create_shared_doc 并返回一个秘密 gist URL。秘密 gist 不会公开列出，URL 也无法猜出，但任何拿到链接的人都可以阅读——这就是此后端的全部安全机制。需要密码？请使用 selfhost。

本地索引（~/.config/sharedoc-mcp/index.json）会跟踪你分享的内容，为搜索和过期清理提供支持。这里的过期清理是延迟执行的：过期 gist 会在下次运行任何工具时删除，而不是在过期的准确时刻删除。

Selfhost 快速入门

claude mcp add sharedoc --scope user --env SHAREDOC_BACKEND=selfhost -- npx -y sharedoc-mcp@^2

文档存储在 ~/.local/share/sharedoc-mcp/ 下的 SQLite 中；查看器在 http://127.0.0.1:8377 提供服务。要在你的设备之外分享，请在前面配置隧道并设置 SHAREDOC_PUBLIC_URL：

**让链接在编辑器关闭后仍然有效：**在 MCP 模式下，查看器会随 MCP 客户端一起关闭——关闭 Claude Code 后，selfhost 链接就会停止响应，直到下次会话（数据在 SQLite 中是安全的）。运行独立守护进程，让链接全天候保持可用：

npx -y sharedoc-mcp@^2 serve   # 仅运行查看器，使用同一数据库——通过 launchd/systemd/tmux 保持运行（Windows：任务计划程序或 NSSM）

MCP 客户端会检测到守护进程已占用该端口，并直接使用它。

**何时进行此设置：**首次将链接交给其他人时——同时设置好隧道（两者都应长期运行，例如由 launchd/systemd 管理）。在此之前，MCP 模式的查看器已经够用；使用 gist 后端的用户则永远不需要此设置。

方案	适用情况	设置
Tailscale 私有网络（推荐）	接收者是你自己的设备，或是你可以邀请加入 tailnet 的人员	tailscale serve --bg 8377 → https://<machine>.<tailnet>.ts.net，仅在你的 tailnet 内可访问——不会向公共互联网暴露任何内容
Tailscale Funnel	与任何人分享，且没有域名	tailscale funnel 8377 → 同一个稳定 URL，但可公开访问
Cloudflare 命名隧道	你拥有域名	在 Cloudflare 上添加域名，运行 cloudflared tunnel create，并将主机名路由到 http://127.0.0.1:8377
cloudflared 快速隧道	临时分享	cloudflared tunnel --url http://127.0.0.1:8377 → 随机 URL，每次重启都会变化

拥有域名？Cloudflare 命名隧道分步指南

使用品牌化、稳定的分享 URL，例如 https://docs.example.com/docs/<uuid>——TLS 由 Cloudflare 处理，即使位于 NAT 后面也能使用：

# one-time setup (domain already added to Cloudflare — the free plan is enough)
cloudflared tunnel login
cloudflared tunnel create sharedoc
cloudflared tunnel route dns sharedoc docs.example.com

~/.cloudflared/config.yml：

tunnel: sharedoc
credentials-file: ~/.cloudflared/<tunnel-id>.json
ingress:
  - hostname: docs.example.com
    service: http://127.0.0.1:8377
  - service: http_status:404

运行 cloudflared tunnel run sharedoc（或将其安装为服务以保持始终运行），然后使用公共 URL 注册 MCP 服务：

claude mcp add sharedoc --scope user \
  --env SHAREDOC_BACKEND=selfhost \
  --env SHAREDOC_PUBLIC_URL=https://docs.example.com \
  -- npx -y sharedoc-mcp

额外优势：Cloudflare 免费提供 DDoS 防护；你可以叠加 WAF 规则，或者在除分享路径之外的所有内容前配置 Cloudflare Access（SSO），实现“内部使用 SSO，外部分享需密码保护”的分离模式。

**替代方案——不使用家用设备也能始终在线：**在 VPS 上运行 sharedoc-mcp（你的 Agent 也在此运行），并将 nginx/caddy 指向 127.0.0.1:8377，配置你的域名和自动 TLS；无需隧道。

Docker

在容器中运行与上述相同的独立 serve 守护进程：

docker build -t sharedoc-mcp .
docker run -d --name sharedoc \
  -p 8377:8377 \
  -e SHAREDOC_BIND_HOST=0.0.0.0 \
  -v sharedoc-data:/data \
  sharedoc-mcp

• -v sharedoc-data:/data 会将 docs.db 持久化到命名卷中——重新创建容器后，你的文档仍会保留。
• 必须设置 SHAREDOC_BIND_HOST=0.0.0.0 才能访问容器。 查看器默认绑定到 127.0.0.1——与本 README 中的其他所有部署方式相同——而在容器内，这个地址无法通过 docker run -p 访问，因为 -p 转发到容器的网络接口，而不是它的回环接口。若未设置此环境变量，docker logs 会显示查看器正在监听，但映射的主机端口会拒绝所有连接。
• 将其设为 0.0.0.0 意味着，任何能够访问容器暴露端口的进程，无论其网络位置如何，都能在未经身份验证的情况下访问查看器——这与在容器中运行任何其他未经身份验证且前面没有代理的应用时面临的暴露风险相同。请将它置于与上文其他可自托管方案相同类型的入口之后（主机上的反向代理、Tailscale sidecar、Cloudflare 隧道），而不要直接通过 -p 8377:8377 将其发布到互联网。为单个文档设置密码（此后端的内置功能）不能替代这一措施。
• 如果收件人使用的地址与 http://<host>:8377 不同（例如反向代理、域名或隧道），也请设置 SHAREDOC_PUBLIC_URL——容器无法自行推断该地址。
• MCP stdio 服务本身不适合在 Docker 中运行——它需要一个本地进程连接到 MCP 客户端的 stdin/stdout。照常让你的 MCP 客户端在主机上运行 npx -y sharedoc-mcp；只有独立查看器守护进程需要放在容器中。

环境变量：

变量	默认值	含义
SHAREDOC_BACKEND	gist	gist 或 selfhost
SHAREDOC_PORT	8377	查看器端口（selfhost）
SHAREDOC_BIND_HOST	127.0.0.1	查看器绑定地址（selfhost）——设为 0.0.0.0 可从 Docker 容器外部访问；更改此项前，请参阅 Docker 了解暴露风险
SHAREDOC_PUBLIC_URL	http://127.0.0.1:<port>	分享链接中的 URL 前缀——设为你的隧道主机名
SHAREDOC_DATA_DIR	~/.local/share/sharedoc-mcp	SQLite 存储位置（selfhost）
SHAREDOC_INDEX_PATH	~/.config/sharedoc-mcp/index.json	本地索引（gist）
MCP_CALLER	—	为创建的文档设置默认作者署名

9 个工具

工具	功能
create_shared_doc	标题 + Markdown（+ 可选密码 / expires_in_hours / 作者）→ 分享 URL
append_to_shared_doc	追加 Markdown（非幂等——重试会追加两次）
update_shared_doc_content	替换全部内容（标题/密码/过期时间不变）——幂等，可安全重试
extend_shared_doc	将过期时间延长 N 小时
reset_shared_doc_password	设置 / 更改 / 移除（null）密码（仅 selfhost）
update_shared_doc_title	重命名
revoke_shared_doc	使链接失效，但保留记录（语义见后端表格）
delete_shared_doc	使链接失效并删除记录——不可撤销；需要 confirm: true（Agent 应先征得用户明确批准）
search_shared_docs	不带参数 = 列出最新链接；标题子串搜索、正文搜索（selfhost：全文；gist：开头摘录）、状态筛选、偏移分页（响应中包含 hasMore）、selfhost 上的浏览统计

隐私

按后端划分的数据流：

• Gist 后端：文档内容会以私密 gist 的形式上传到你账号下的 GitHub——适用 GitHub 的条款和数据保留政策。本地索引保存在 ~/.config/sharedoc-mcp/ 中，其中存储标题、URL、时间戳以及每篇文档的前 200 个字符（用于本地内容搜索）；不会存储完整内容。除通过你自己的 gh CLI 发送到 GitHub 外，不会向任何地方发送数据。
• 自托管后端：除非你连接隧道，否则内容不会离开你的设备——连接隧道后，获得链接的任何人都可以访问内容（隧道提供商会转发流量）。密码仅以 bcrypt 哈希形式存储。
• sharedoc-mcp 本身不收集遥测数据，也不会自行调用任何第三方服务。

坦诚说明安全机制

• Gist 链接是持有者令牌：任何拥有 URL 的人都能读取文档。撤销会立即且不可逆地删除 gist。
• 自托管密码会在服务器端验证，通过后才会提供内容；只有错误尝试会受到速率限制（每个来源地址和文档每分钟 5 次；成功解锁会清除计数器），计数器会持久化到 SQLite 中——重启服务器不会重置计数。通过隧道访问时，所有外部访客共用一个来源地址，因此实际限制是每篇文档每分钟 5 次，比按访客限制更严格；一个人输错密码就可能短暂锁定其他人对文档的访问。
• 我们有意不提供文件共享工具：基于任意路径的“共享此文件”工具存在提示词注入导致数据外泄的风险（.env、密钥）——被劫持的 Agent 可能会公开机密。我们选择移除该工具，而不是通过允许列表来限制它。
• 查看器绑定的地址不会超出 127.0.0.1。它是否以及如何连接到互联网，完全取决于你的隧道配置。

开发

git clone https://github.com/AugustusW/sharedoc-mcp.git
cd sharedoc-mcp
npm install
npm test        # builds, then runs 110 offline tests — gh CLI is mocked, HTTP tests hit 127.0.0.1 only

版本管理：每次发布都会更新 package.json 中的 version，添加 CHANGELOG 条目，并以 git 标签、GitHub Release 和 npm 的形式发布。 接收更新通知：关注此仓库（选择“自定义”→“发布”）。每次冷启动时，npx -y 都会获取最新发布版本；你的索引和文档数据库保存在软件包之外，因此更新不会触及它们。

状态

v2.2.0（CHANGELOG）——核心逻辑由 110 个离线单元测试和集成测试覆盖（gh CLI 使用模拟对象；HTTP 测试仅针对 127.0.0.1 运行；无需网络）。已手动验证完整流程（2026-07-25：通过 stdio JSON-RPC 和已构建的服务器，实际创建、索引和删除私密 gist；以及端到端验证自托管密码流程——表单 → 错误密码 401 → 正确密码 200 → 速率限制 429 → 撤销 410——并通过 lsof 确认仅绑定到 127.0.0.1）：

• macOS（Apple Silicon），Node v25——Gist 和自托管后端

隧道配置示例根据工具的标准行为编写；Windows/Linux 和真实隧道端到端运行尚未验证——欢迎反馈。上述手动验证是在 2.2.0 之前进行的：新增功能（update_shared_doc_content、查看统计、分页、Docker）已由测试套件覆盖，但尚未进行同等的实机验证。

许可证

MIT © AugustusW