noddle draw

noddle draw MCP 服务

让 AI Agent（Claude Code、Claude Desktop 或任何 MCP 客户端）与你一起操作画板：读取、创建和编辑画板，浏览版本历史，并像其他协作者一样发表评论。

noddle draw 是匿名的。没有账户，也不需要令牌。画板 ID（12 位十六进制字符）或画板 URL 就是访问凭证。Agent 可以打开你提供的任何画板；任何持有 Agent 创建的画板链接的人也都可以打开。Agent 使用 NODDLE_AGENT_NAME 为评论和版本快照署名。

• 仅使用 Python ≥ 3.9 标准库（urllib + json），无需安装任何内容。
• stdio 传输：每行一条 JSON-RPC 2.0 消息。stdout 仅承载协议消息，日志写入 stderr。
• MCP 协议，兼容两个时代：
  • 2026-07-28（现代、无状态）：每个请求都携带 _meta["io.modelcontextprotocol/protocolVersion"] + clientCapabilities。服务实现了 server/discover，并在每个结果中设置 resultType 和 _meta["io.modelcontextprotocol/serverInfo"]，同时在列表/读取结果中设置 ttlMs/cacheScope。不支持的版本会返回 -32022 UnsupportedProtocolVersion。
  • 旧版 initialize 握手：2025-11-25、2025-06-18、2025-03-26、2024-11-05。服务支持客户端的版本时会以该版本响应，否则使用 2025-11-25 响应。此模式下支持 ping。仅接受 2025-03-26 版本的 JSON-RPC 批处理，这是唯一允许批处理的修订版。

1. 注册

Claude Code（在仓库根目录中运行；使用脚本的绝对路径更可靠）：

claude mcp add noddle -- python3 mcp/noddle_mcp.py
# a self-hosted instance instead of draw.noddle.dev:
claude mcp add noddle --env NODDLE_BASE_URL=http://127.0.0.1:8000 -- python3 mcp/noddle_mcp.py

Claude Desktop（~/Library/Application Support/Claude/claude_desktop_config.json） 或项目 .mcp.json 使用相同格式：

{
  "mcpServers": {
    "noddle": {
      "command": "python3",
      "args": ["/absolute/path/to/noddle-draw/mcp/noddle_mcp.py"],
      "env": { "NODDLE_BASE_URL": "https://draw.noddle.dev" }
    }
  }
}

MCP Bundle（在 Claude Desktop 和其他 MCPB 客户端中一键安装）：从最新的 mcpb-v* 发布版本下载 noddle-draw.mcpb 并打开。它只需要 Python 3.10+（标准库，无需安装步骤）。

从检出目录安装（此处的 pyproject.toml）：

uvx --from ./mcp noddle-draw-mcp       # or: pipx install ./mcp && noddle-draw-mcp

该服务已列入官方 MCP 注册表，名称为 dev.noddle/draw（参见发布）。

环境变量	默认值
NODDLE_BASE_URL	https://draw.noddle.dev	noddle draw 实例的 http(s) 源站。若值不是 http(s)，则以代码 2 退出
NODDLE_AGENT_NAME	MCP agent	评论和版本历史中显示的名称（最多 40 个字符）
NODDLE_TIMEOUT	30	每次画板 API 调用的秒数
NODDLE_AI_TIMEOUT	180	generate_diagram 的秒数
NODDLE_AI_PROVIDER	—	generate_diagram 的可选 BYOK：claude、openai、gemini、openrouter 或 custom
NODDLE_AI_KEY	—	你的 AI 提供商密钥。它只会发送到 NODDLE_BASE_URL，并作为 Web 应用使用的相同 X-AI-* 标头发送，且绝不会存储。未设置时，如果该实例有共享密钥池，则会使用该密钥池
NODDLE_AI_MODEL	—	可选的模型覆盖值
NODDLE_AI_BASE	—	OpenAI 兼容的基础 URL（仅适用于提供商 custom）

CLI：--help、--version、--list-tools（以 JSON 格式输出工具定义）。 退出代码：stdin 关闭时为 0（正常关闭），配置错误时为 2。

2. 工具

每个工具都会返回符合其 outputSchema 的 structuredContent，以及包含相同 JSON 的文本块。Board 工具还会返回指向 noddle://board/{id} 的 resource_link （版本 ≥ 2025-06-18）。凡是工具接受 doc_id，都可以传入 12 位十六进制 id 或 board URL（{base}/d/{id} 或 /embed/{id}）。与 NODDLE_BASE_URL 来源不同的 URL 会被拒绝。

工具	只读	有破坏性	幂等	开放世界	功能说明
get_board	✓			✗	名称、url、my_role（editor/viewer）、updated_at、页面摘要和图表 JSON。可选 page_id 和 include_svg
create_board	✗	✗	✗	✗	创建新 board，可选提供图表 JSON。任何拥有其 url 的人都可以编辑
update_board	✗	✓	✓	✗	替换整个图表（获取 → 编辑 → 发回）。会保留版本快照。expected_updated_at 可将并发编辑转为冲突错误，而不是覆盖
rename_board	✗	✗	✓	✗	重命名
list_versions	✓			✗	版本历史快照，按时间从新到旧排列
get_version	✓			✗	单个快照的图表。要恢复该快照，请将其传给 update_board
list_comments	✓			✗	评论串
add_comment	✗	✗	✗	✗	固定到 node_id / edge_id / parent_id（回复）/ 点位 x、y 中的一个（以及 page_id）。仅查看链接也可使用
generate_diagram	✓			✓	通过该实例的 AI（你的 BYOK 密钥或其共享池）将文字描述或 Mermaid 转为图表 JSON。它不会保存任何内容，因此请将结果传给 create_board/update_board

这里有意不提供 list_boards 和删除功能：API 两者都不支持。拥有链接不代表可以发现 board，而匿名 board 没有可被信任的所有者来删除它。对仅可查看链接对应的 board 执行写入会返回 403 工具错误。

图表载荷会原样透传。服务端仅检查封装格式 （{pages:[{id,nodes,edges}]} 或旧版 {nodes,edges}，且 id 必须为字符串）。节点和边的字段会原样转发，因此新的编辑器字段（例如带有 points 的 freedraw 类型，或 curved 路由）无需更新服务端即可使用。请参阅 contracts/openapi.yaml 中的 DiagramNode / DiagramEdge。

错误：

• 参数错误、API 故障（400/403/404/413/422/429/503）和冲突会以 isError: true 工具结果的形式返回，模型可以据此采取行动。
• 协议错误使用标准 JSON-RPC 代码：未知工具或参数无效为 -32602，未知方法为 -32601，JSON 格式错误为 -32700，请求无效为 -32600。

3. 资源与提示词

• 资源：resources/list 会将此会话创建、读取或编辑过的 board 列为 noddle://board/{id}（application/json、lastModified）。由于 API 不支持列表查询，初始列表为空。resources/templates/list 会公开 noddle://board/{doc_id}，因此客户端可以通过 id 读取任意 board。resources/read 返回与 get_board 相同的 JSON。未知 board 会返回 -32602。
• 提示词：
  • design_board(topic, notes?)：生成 → 检查合理性 → create_board → 回复 url。
  • review_board(doc_id)：将 board 作为资源嵌入，并要求生成批评意见，以锚定评论的形式发布。

4. 示例（Claude Code）

> Create a board "Payment flow" with Client → API Gateway → Payment Service → Database,
  then comment on the Database node reminding the team to review indexes.

Claude: generate_diagram(text="Client -> API Gateway -> Payment Service -> Database")
        → create_board(name="Payment flow", diagram=…)
        → add_comment(doc_id, body="Please review indexes for the payments table", node_id="db")
        → returns https://draw.noddle.dev/d/{id}

评论会实时显示在已打开的 board 上。通过 update_board 写入的图表会在重新加载 board 时显示。

5. 测试

python3 -m pytest mcp -q        # or: python3 -m unittest discover mcp

test_noddle_mcp.py 通过 stdio 使用伪造的进程内 REST 后端运行真实服务端。它涵盖版本协商（现代版和旧版）、架构有效性、读写工具、board URL id、仅查看链接、资源、提示词、BYOK 请求头转发和错误路径。它还会断言 stdout 仅包含 JSON-RPC、请求从不携带 Authorization 请求头，以及 BYOK 密钥绝不会泄漏到输出或日志中。

发布

mcp/server.json 是注册表清单（dev.noddle/draw）；它指向附加到 GitHub 发布版本的 MCP Bundle。dev.noddle/* 命名空间通过 HTTP 验证：noddle.dev 在 /.well-known/mcp-registry-auth 提供发布者的 ed25519 公钥。

1. 在所有位置更新版本号，确保一致：noddle_mcp.py 中的 __version__、mcpb/manifest.json 中的 version、pyproject.toml 中的 version，以及 server.json 中的 version。 注册表版本不可修改；仅修改元数据时，使用类似 1.0.0-1 的后缀。
2. 构建 Bundle：mcp/build_mcpb.sh → mcp/dist/noddle-draw.mcpb（会打印其 SHA-256）。
3. 使用该确切文件创建发布版本： gh release create mcpb-v<version> mcp/dist/noddle-draw.mcpb --title "MCP server <version>"。
4. 在 server.json 中，将 package 的 identifier 设为发布版本的下载 URL，并将 fileSha256 设为打印出的哈希值，然后由命名空间密钥持有者使用 mcp-publisher login http --domain noddle.dev --private-key … 登录，并运行 mcp-publisher publish mcp/server.json 发布。

备注

• update_board 会保留已存储的 SVG 预览。预览会在编辑器中下次保存时刷新。
• 系统会拒绝跨源 HTTP 重定向，因此 BYOK 密钥绝不会转发到其他主机。通过纯 http 向非回环主机发送 BYOK 密钥时，会记录警告。
• generate_diagram 会将文本发送给 AI 提供商。切勿传入客户个人身份信息、凭据或账号号码。