jotview

jotview

将 Markdown 文件转换为可渲染它的 jotbins 链接。

npx jotview notes.md
# https://jotbins.com/d#z:U1bwSM3JyecCAA

零依赖。无需安装、账号或配置。

工作原理

文档会被压缩并打包到 URL 的片段中——也就是 # 后面的部分。片段不会发送到服务端，因此对于不超过 2000 个字符的链接，你写下的内容不会离开你的设备。打开链接后，内容完全在浏览器中渲染。

用法

jotview <file>            mint a link from a file
jotview                   read markdown from stdin
jotview decode <url>      print the markdown behind a /d or short link
jotview mcp [--raw]       run as an MCP server for AI agents

  --raw                   never shorten; always the full /d URL
  --short                 always shorten, even when small
  --keep                  make a shortened link permanent
  --open                  open the link in your browser
  --copy                  copy the link to your clipboard
  --json                  print the result as one JSON line (see below)
  --base-url <url>        override https://jotbins.com
  -h, --help
  -v, --version

示例：

jotview README.md --open
cat notes.md | jotview
jotview notes.md | pbcopy
LINK=$(jotview notes.md --raw)
jotview decode https://surl.jotbins.com/abc123 > notes.md

decode 接受 jotbins.com/d 链接（在本地解码）和 surl.jotbins.com 短链接（通过请求获取；与点击链接一样，这会让短链接保持有效）。

缩短链接及其代价

文档越长，链接也越长——字符数约为 Markdown 大小的一半。20 KB 的文件会生成约 8,700 个字符的 URL，Discord、X 和大多数聊天客户端都无法接受。

因此，超过 2000 个字符的链接会通过 surl.jotbins.com 缩短；发生这种情况时，jotview 会向 stderr 输出提示：

note: uploaded to jotbins to shorten (8768 → 30 chars). use --raw to keep it local.
note: short link expires after 30 days unused. use --keep to keep it forever.

缩短链接会上传你的文档。 片段就是 Markdown，因此存储 URL 就等于存储文本。低于此阈值时，不会上传任何内容，也不会发出任何网络请求。使用 --raw 可让长文档保留在本地，但生成的 URL 可能长到无法粘贴到大多数地方。

短链接会自动清理。 30 天内无人打开的短链接会被删除，但可在之后的 60 天内通过等待页面恢复。传入 --keep 可从一开始就将链接设为永久有效；也可以在此期限内随时点击等待页面上的 保存链接。完整的 /d 链接绝不会被存储，因此永不过期。

如果短链接服务无法访问或受到速率限制，jotview 会输出完整链接并以 0 退出——缩短链接的问题绝不会导致你的工作流失败。

与 AI Agent 配合使用（MCP）

jotview mcp 是一个 stdio MCP 服务，提供两个工具。使用 render_markdown，AI 可以编写 Markdown——笔记、报告或 Mermaid 图表——并获取一个 jotbins 链接供你使用；使用 read_link，它可以读取你分享的 jotbins 链接。

Claude Code

claude mcp add jotview -- npx -y jotview mcp

Claude Desktop——从最新版本下载 jotview.mcpb 并双击打开。也可以选择一个它获准读取文件的文档文件夹。

Cursor 和其他客户端——将以下内容添加到 MCP 配置中：

{ "mcpServers": { "jotview": { "command": "npx", "args": ["-y", "jotview", "mcp"] } } }

然后只需提出请求：“画一张我们的部署流程图，并给我一个 jotbins 链接。”

render_markdown 接受 content（Markdown 内容），以及可选的 title（用作链接文本，而非第一个标题）、keep（将短链接设为永久有效）和 shorten（"auto"、"always" 或 "never"）。它会返回一个现成的 Markdown 链接 [First heading](url)，并说明是否上传了内容。它绝不会读取文件——AI 会传入已有的文本。

渲染文件。 本地服务还可以接受 path 而非 content，这样 AI 就不必在工具调用中粘贴整个文件。它只读取 .md、.markdown、.mdx 和 .txt 文件，并且只能读取服务运行所在文件夹中的文件（Claude Code 会在你的项目目录中启动服务），或通过 --allow-dir 授权的文件夹中的文件：

claude mcp add -s user jotview -- npx -y jotview mcp --allow-dir ~/notes

如果服务在 / 或你的主目录中运行，且未提供 --allow-dir，则会禁用 path。远程服务绝不会读取文件。

read_link 接受一个 url（/d 链接或短链接），并返回链接背后的 Markdown。你可以粘贴一个链接并说：“修正错别字，然后给我一个新链接。” 链接不会改变；编辑后会生成新链接。

上传。 链接中的每个字符都会消耗 token，因此 MCP 会比 CLI 更早缩短链接：超过 500 个字符的链接会通过 surl.jotbins.com 处理，这会上传文档（除非设置了 keep，否则短链接在 30 天无人使用后会过期）。要完全禁止上传，请使用 --raw 启动服务：

claude mcp add jotview -- npx -y jotview mcp --raw

兼容 MCP 版本从 2024-11-05 到 2026-07-28 的客户端。

远程服务——无需安装

相同的工具也运行于 https://mcp.jotbins.com/mcp（Streamable HTTP，无需 登录），适用于无法运行本地命令的客户端。

• claude.ai（网页和移动端）： Settings → Connectors → Add custom connector → 粘贴 https://mcp.jotbins.com/mcp。
• Claude Code： claude mcp add -s user --transport http jotview https://mcp.jotbins.com/mcp

规则与本地服务相同，但它无法禁止上传：每次调用时使用 shorten: "never"，或使用本地 --raw 服务，以确保文档不会上传到 surl.jotbins.com。上传按客户端限流；超出限制后， 仍会返回完整链接。

Worker 位于 worker/，使用 cd worker && npx wrangler deploy 部署。

输出约定

stdout 只输出 URL，不输出其他内容。 通知、警告和错误会输出到 stderr，因此 $(jotview x.md) 和 jotview x.md | pbcopy 能保持干净。

使用 --json 时，stdout 会改为输出一行 JSON，供脚本和 CI 使用：

{"url":"https://surl.jotbins.com/abc123","rawUrl":"https://jotbins.com/d#z:…","shortened":true,"permanent":false,"failure":null}

failure 是尝试缩短链接但失败时返回的缩短服务错误 （此时 url 为完整链接）。

退出代码：0 成功，1 运行时错误，2 用法错误。

限制

输入上限为 1 MB，与 /d 渲染器可打开的大小一致。

要求

Node 18 或更高版本。

发布

发布通过 GitHub Actions 运行。在已更新至最新的 main 分支上：

npm version minor
git push --follow-tags

npm version 还会更新 manifest.json 和 server.json。随后，v* 标签会 运行测试、发布到 npm（可信发布，附带来源证明）、将 jotview.mcpb 附加到 GitHub 发布版本，并更新 MCP Registry 条目。先将 CHANGELOG.md 中的 Unreleased 条目移至新版本名下（在执行 npm version 前提交此更改）。Worker 单独部署：cd worker && npx wrangler deploy。

如果发布流程中途失败，修复原因后运行 gh workflow run release.yml -f tag=vX.Y.Z 完成发布——已完成的步骤会跳过。

许可证

MIT