Sketchdex

sketchdex

给你的 Agent 一块白板。sketchdex.dev

Sketchdex 是一款 MCP 服务，可让 Claude、Codex、Cursor 和其他任何 MCP 客户端在讲解内容时绘制手绘风格的 Excalidraw 图表。场景是保存在你设备文件夹中的真实 .excalidraw 文件。Agent 可以绘制、查看绘制结果并进行修正；你可以在随附的库应用或 excalidraw.com 中打开结果并继续编辑。

它基于官方 @excalidraw/excalidraw 包构建，因此使用的是真正的画布。采用 MIT 许可证。

安装

需要 Node 20 或更高版本。渲染（render_scene）需要设备上安装基于 Chromium 的浏览器：Chrome、Chromium、Edge 或 Brave。其他功能无需浏览器即可使用。

最快的方法是让你已经在使用的 Agent 来完成。将以下内容粘贴到任何可以运行命令的 Agent 中：

帮我安装 sketchdex MCP 服务。按照步骤运行 npx -y sketchdex docs install。

也可以手动安装：

Claude Code

claude mcp add --scope user sketchdex -- npx -y sketchdex

Codex

codex mcp add sketchdex -- npx -y sketchdex

Cursor

添加到 Cursor，或在 ~/.cursor/mcp.json 中添加：

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

VS Code

code --add-mcp '{"name":"sketchdex","command":"npx","args":["-y","sketchdex"]}'

Claude Desktop、Windsurf、Gemini CLI 或其他任何工具都可以使用与 Cursor 相同的 mcpServers 配置块，或将命令 npx -y sketchdex 作为 stdio 服务使用。npx -y sketchdex docs install 会提供每种工具对应的准确配置文件。

然后，在会话中输入：用 sketchdex 画图说明事件循环的工作原理。

场景默认保存在 ~/Documents/sketchdex。在包名称后添加 --vault /path/to/folder，或在服务的环境中设置 SKETCHDEX_VAULT，即可将保存位置设到其他地方。iCloud 或 Dropbox 文件夹也可以使用。

面向 Agent 的文档

手册随包一同提供，因此 Agent 无需任何人阅读页面，就能回答设置问题并解决故障：

• npx -y sketchdex docs [topic] 会打印文档（主题包括：install、vault、 app、rendering、tools、drawing、troubleshooting 或 all）。
• 服务连接后，sketchdex_docs 工具会返回相同的文本；服务说明还会告诉 Agent，在遇到任何设置或错误相关问题时使用该工具。
• 相同主题也作为 MCP 资源提供，地址为 sketchdex://docs/<topic>。

应用

npx sketchdex app

在浏览器中打开素材库：以网格形式展示场景，并提供实时预览、 搜索、置顶、重命名、复制和导入功能；每个场景都有完整的 Excalidraw 编辑器；还提供 ⌥K 切换器，以及 历史记录 侧边栏，显示 Agent 每次写入内容及其给出的标签，方便你预览、保留或撤销。应用会实时发现 Agent 的写入操作。

同一进程还会通过 POST /mcp 提供 HTTP 工具，并通过 POST /api/agent/:op 提供纯 REST 接口；仅限本地主机访问。

Agent 能获取的内容

通过 stdio 提供十九个工具。重要的工具包括：

工具	功能
describe_scene	查看结构，而非像素：边界、计数，以及每个元素的简要摘要。从这里开始。
add_elements	添加框、箭头、文本和生成的形状（polygon、star、arc、capsule、path）。在形状上设置 label 可添加绑定文本；在箭头上设置 start/end 可将其绑定。
update_elements	指定一个 id 和要更改的字段。读取-修改-写入在服务端完成，因此两行编辑只需两行操作。
import_svg	写入 SVG，并获取分组为一个整体的手绘可编辑元素。适用于绘制任何需要呈现出具体形象的内容。
render_scene	将整个场景或指定区域渲染为真实画布 PNG，供 Agent 检查自己的作品。
check_scene	根据几何关系查找布局问题：隐藏文本、标签重叠、悬空箭头、偏离的元素。
snapshot_scene、list_history、restore_snapshot	安全保障。每次写入前都会先为上一状态创建快照。
sketchdex_docs	按主题分类的手册，Agent 可借此回答设置问题并自行修复错误。

Agent 读取的完整手册是 BRIEF.md：元素格式、手绘规范（粗糙感、稀疏锚点、纯色、无剪贴画）、纸张和墨水规则，以及容易踩的坑。

稳定性

• 文件才是事实依据。 每个场景都是普通的 .excalidraw 文件。写入采用原子操作（临时文件、重命名），删除的文件会移至 trash/；如果 index.json 缓存丢失，服务端会根据文件重建。
• 每次 Agent 写入都可撤销。 快照采用 gzip 压缩，每个场景最多保留 20 个，不包含图像，也不会自动过期。
• 增量更新，不重写。 Agent 工作期间，你在编辑器中所做的更改会保留：写入会携带修订令牌，并合并冲突的保存。
• 仅限本地。 无需账户，不上传数据，也没有遥测。服务绑定到 127.0.0.1。

~/Documents/sketchdex/
├── index.json              names, timestamps, pins (a cache, not the truth)
├── scenes/<id>.excalidraw  the scene itself, real Excalidraw format
├── thumbs/<id>.svg         library previews
├── history/<id>/           snapshots taken before agent writes, gzipped
└── trash/<stamp>-<id>.excalidraw

Node API

import { createAgentApi } from "sketchdex";
const api = createAgentApi(); // or createAgentApi("/path/to/vault")
await api.describeScene("Brain Dump");

与 MCP 和 REST 接口使用相同的实现。应用关闭时也能使用。

开发

git clone https://github.com/lucasr1b/sketchdex
cd sketchdex
npm install          # also retunes Excalidraw's colour picker for dark paper
npm run dev          # app + API + HTTP MCP on http://localhost:5173
npm run build        # dist/, which the CLI and the render page need
node bin/sketchdex.js app

要让 MCP 客户端连接到检出目录，请将 node /path/to/sketchdex/mcp/server.js 设为命令。在检出目录中，server/ 或 mcp/ 下的文件发生更改时，服务端会热重载其工作进程，因此下次调用工具时更改即会生效，无需重启客户端。

提交前请运行 npm run lint、npx tsc -p tsconfig.app.json --noEmit 和 npm test。测试会打包该软件包，将其安装到干净的项目中，并通过真实的 MCP 客户端驱动测试，包括渲染；CI 会在 macOS、Linux 和 Windows 上运行测试。 AGENTS.md 介绍了代码库结构，以及编辑时必须遵循的规则。另有 macOS 桌面外壳：npm run electron:dev。

备注

• 新建场景使用深色纸张（#121212），并且永远不会反转颜色：画布、缩略图和渲染结果都会按原样显示每个十六进制颜色值。纸张颜色按场景设置（viewBackgroundColor）。
• 首次安装后第一次渲染需要等待几秒钟，让浏览器启动；之后大约需要一秒半。
• 如果浏览器位于特殊路径，请设置 SKETCHDEX_BROWSER=/path/to/browser。
• 服务端只响应 Host 为 localhost 的请求，并拒绝跨站写入，因此浏览器中打开的网页无法访问该保险库。不过，它仍绑定到一个普通的本地端口：同一台机器上以你的身份运行的任何程序都能访问它，这正是设计目的。
• 在应用中，⌘K 会打开场景切换器，这会与 Excalidraw 自带的“添加链接”快捷键冲突；添加链接请使用上下文菜单。
• 应用会注册一个小型服务工作线程（用于安装为应用）。它不会缓存内容，但如果之后你在同一端口运行另一个项目，在取消注册之前，该服务工作线程仍会显示在那个项目的开发者工具中。