codex-tldraw-mcp

codex-tldraw-mcp

一个 stdio MCP 服务，用于生成可编辑的仓库本地 tldraw 图表、可移植的 SVG 预览，以及带漂移检测的可追踪代码图。

快速开始

将服务添加到 Codex：

codex mcp add codex-tldraw -- npx -y codex-tldraw-mcp

然后让 Codex 为当前仓库绘制图表：

Use codex-tldraw to diagram this repo.

逆向分析其运行时架构：

Use codex-tldraw to show how this repo works across its main components.
Show the main flow first, keep short errors inside components, and label each interaction once.

或直接请求一张图表：

Use codex-tldraw to draw a password reset state machine.

创建可追踪的 JavaScript 或 TypeScript 模块图：

Use codex-tldraw to create a code graph for this repo.

代码变更后，将其与保存的图进行对比：

Use codex-tldraw to preview code graph drift, then mark stale elements.

默认输出为：

<repo>/boards/main.tldr
<repo>/boards/main.svg

在兼容 tldraw 的查看器中打开 .tldr 画板即可编辑。任何 MCP 宿主、浏览器、文档系统或代码审查都可以直接显示 .svg 预览。

有关插件修复和验证细节，请参阅 v0.7.1 发布说明。

Codex 插件

本仓库还将该服务打包为 Codex 插件。现有的 MCP 工具仍会写入 .tldr 和 .svg 文件；该插件新增了一个 .tldr 文件处理器，可在内嵌的 React/tldraw 应用中打开可编辑画板。

两种路径打开同一个编辑器：

图表工具面板 —— 在 draw_canvas、diagram_repo 或类似工具运行后，内联的 MCP App 会从仓库作用域的服务资源 tldraw://repos/<encoded-repo-path>/boards/<name>/file 加载画板，并通过仅限应用使用的 save_board 工具保存。

.tldr 文件入口 —— 当 Codex 直接打开仓库文件时，应用会使用宿主文件资源 API（open_tldraw_file）。可写文件保存时带有 ETag 冲突保护。

构建服务及其单文件应用：

bun install
bun run build

从 npm 安装已发布的插件（推荐）：

npm install -g codex-tldraw-mcp
codex plugin marketplace add "$(npm root -g)/codex-tldraw-mcp"
codex plugin add codex-tldraw@codex-tldraw-mcp

或从 GitHub 安装：

codex plugin marketplace add jananadiw/codex-tldraw-mcp
codex plugin add codex-tldraw@codex-tldraw-mcp

该插件需要 Node.js 20.11 或更高版本，以及位于 PATH 中的 npm。从 GitHub 下载的插件不会构建源码或安装依赖。启动器在可用时会使用本地已构建副本；否则通过 npx 运行匹配的已发布 npm 版本。首次回退启动需要访问软件包注册表。使用该插件无需安装 Bun。

从本检出目录进行开发：

bun run build
codex plugin marketplace add .
codex plugin add codex-tldraw@codex-tldraw-mcp

市场描述文件为 .agents/plugins/marketplace.json，插件清单为 .codex-plugin/plugin.json，其 MCP 配置为 .mcp.json，捆绑的应用为 dist/app.html。不支持应用的 MCP 宿主仍可继续使用现有的文本结果、.tldr 资源和 SVG 预览。

你将获得

• 一个与它所描述的項目放在一起的仓库本地 .tldr 画板，以及一份可移植的 .svg 预览。
• 根据包元数据和源文本推断出的面向用户的产品工作流。
• 一个由提示词驱动的离线画布 API，用于绘制与仓库扫描无关的工作流、状态机、计划和架构草图。
• 简洁的架构图，先展示主流程，再在其下方展示支撑服务。
• 一个可追踪的 JavaScript 和 TypeScript 模块/导入图，带漂移检测。
• 用红色标记过时的节点和边，用橙色标记已变更的模块，并报告新增元素。
• 按从左到右布局的 tldraw 步骤和箭头。
• 非破坏性更新：现有画板会将下一张图追加到右侧。
• 用于列出画板和读取画板摘要的 MCP 资源。

对于一款手写字体应用，推断出的工作流可能是：

User writes alphabet on paper -> User takes a photo of the paper -> User uploads the image -> AI generates a font -> User downloads a .ttf file

手动配置

如果你更愿意直接编辑 Codex MCP 配置：

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

工具

• diagram_repo：扫描仓库并将产品工作流图追加到 <repo>/boards/<boardName>.tldr。
• draw_canvas：将提示词提供的 workflow、状态机、架构草图或计划追加到 <repo>/boards/<boardName>.tldr。
• draw_architecture：追加一个包含主流程、支撑组件、操作、调用和错误的简单代码库架构视图。
• diagram_code_graph：扫描仓库本地的 JavaScript 和 TypeScript 模块，并追加一个可跟踪的导入图。
• compare_code_graph：在现有的可跟踪代码图上预览漂移，或标记已更改和陈旧的元素。
• list_boards：列出仓库 boards/ 目录下的看板。
• read_board_summary：汇总生成的图表和形状数量，并返回两个产物路径。

使用该插件时，在每次调用仓库工具时传入仓库的绝对路径作为 repoPath。插件从其安装目录运行，而不是从聊天工作区运行。缺失或相对路径会被拒绝，以防止图表被写入插件缓存。对于远程仓库 URL，请先将其克隆到本地，然后使用检出路径。

独立的 MCP 工具接受一个可选的 repoPath。相对路径从 MCP 服务工作目录解析。

每个写入图表工具都会保存两个产物，并在结构化输出中返回 boardPath 和 svgPath。工具内容还包含指向可编辑看板和 SVG 预览的 MCP 资源链接。SVG 渲染器覆盖此服务生成的文本、矩形和箭头形状，无需浏览器运行时。

新的看板资源链接携带编码后的绝对仓库路径。它们能在服务重启或针对另一个仓库的工具调用后继续工作，包括两个仓库使用同一看板名称的情况。资源读取仍然强制执行 TLDRAW_MCP_ALLOWED_ROOTS。

旧版 tldraw://boards/<name>/... 资源仍可供较旧的独立客户端使用，并使用最后选定的仓库。重新运行图表工具，以将较旧的编辑器链接替换为仓库作用域链接。

编辑器在保存前检查已加载看板的 ETag，阻止陈旧保存，并在发生冲突后提供 Discard and reload。无效的看板数据会在替换文件前被拒绝。图表写入使用每看板的文件系统锁，因此来自不同服务进程的并发调用会同时保留两次追加。

代码图漂移

diagram_code_graph 将稳定的仓库相对身份和指纹存储在 MCP 拥有的形状元数据中。每个源模块成为一个节点。仓库模块之间的静态导入、动态导入、重新导出和 CommonJS require 调用成为边。

在仓库发生变化后运行 compare_code_graph。预览模式是默认模式，不会写入画板：

Compare the current code with the newest code graph on boards/main.tldr.

要更新画板，请让 Codex 应用漂移标记，或传入 applyMarkers: true。比较使用四种状态：

• unchanged：存储的身份和指纹仍然匹配。
• changed：模块仍然存在，但其导出或本地导入关系发生了变化。
• stale：画板上包含一个在当前代码图中已不存在的元素。
• new：当前图中包含一个画板上不存在的元素。

过期元素变为红色和虚线。已更改的模块变为橙色和虚线。新元素出现在工具结果中；v0.4.0 不会插入或重新排列它们。当代码再次匹配时，重新运行比较会恢复原始的生成样式。

比较仅更改 MCP 生成的图形样式和元数据。它保留画板上的位置、大小、标签、手动形状和其他图表，并在漂移清除后恢复每个元素的先前颜色。由 diagram_repo、draw_canvas 或旧版本创建的画板不包含可追踪的代码图元数据；在比较漂移之前，请使用 diagram_code_graph 创建图表。

v0.4.0 扫描器支持 .js、.jsx、.mjs、.cjs、.ts、.tsx、.mts 和 .cts 模块。它报告未解析的相对导入，并统计外部导入而不绘制外部包。它建模模块/导入关系，而非运行时调用图。

提示词驱动的图表

draw_canvas 不扫描源文件。当前仓库仅是生成的画板的存储位置。

示例提示词：

Use codex-tldraw to draw the auth flow:
Visitor opens login -> chooses email or SSO -> completes MFA -> lands in dashboard.

Use codex-tldraw to make a state machine for password reset:
Idle -> Reset requested -> Email sent -> Token verified -> Password updated.

Use codex-tldraw to append an architecture diagram for this plan:
Web app calls API gateway, API gateway calls worker queue, worker writes generated files to object storage.

简单架构

draw_architecture 帮助新读者理解工作如何在代码库中流转。Codex 首先检查代码，然后向渲染器发送一个小型模型：

• 主要用户流变为一排直线排列的方框。
• 支持服务位于调用它们的组件下方。
• 每个组件最多显示三个重要操作和两个简短错误。
• 每个交互获得一个简洁的箭头；请求和响应共享该箭头。
• 源证据是可选的元数据，不会使图表显得杂乱。

将库和辅助模块保留在组件操作内。例如，"使用 Zod 验证响应" 应属于 API 组件内部，而不是成为单独的 Zod 组件。有意义的箭头具有对两个端点形状的绑定。

参见 架构图 了解分析契约和输入模型。

反馈

该项目处于早期阶段，反馈很有用。请在以下情况下提交 issue：

• 生成的工作流遗漏了真实的产品流。
• 画板无法在你兼容 tldraw 的查看器中打开。
• 代码图漂移报告了错误的模块或导入关系。
• 你有一个混乱的仓库，其中 PM 和工程师需要更清晰的共享地图。

使用 GitHub issue 模板来报告错误、功能请求和真实世界示例。

为什么会有这个项目

本项目仅支持快照。它不会控制实时浏览器画布，也不提供实时协作。它会把画板文件写入正在被绘制的仓库中，以便之后由兼容 tldraw 的查看器打开。

官方 tldraw MCP App 是为能够在聊天上下文中渲染交互式 tldraw 画布的宿主而设计的。在 Codex Desktop 中，工具发现在测试中正常工作，tldraw 的 search 工具返回了 Editor API 细节、形状类型和辅助工具。实时 exec 路径无法正常工作：每次调用都在 30 秒后超时，包括一次用于统计当前页面形状数量的只读调用。

正是这种失败模式促成了最初基于文件的回退方案。v0.7.0 插件现在包含其自有的内嵌 MCP App 编辑器，而生成的 SVG 预览在不支持 app 的宿主中仍然可用。

这个服务最初是作为 Codex 优先的回退方案开始的。它不试图驱动实时画布，而是通过一次普通的 stdio MCP 工具调用在磁盘上生成 .tldr 快照。它的 stdio 传输和 SVG 预览现在让同样的输出可用于任何兼容 MCP 的宿主，同时 Codex 仍然是文档中记录的主要配置方式。

安全

这是一个本地文件系统工具。它从 repoPath 读取源文件，并将 .tldr 和 .svg 文件写入 repoPath/boards 下。

要将访问限制在特定目录，请将 TLDRAW_MCP_ALLOWED_ROOTS 设置为以路径分隔的允许列表：

[mcp_servers.codex-tldraw]
command = "npx"
args = ["-y", "codex-tldraw-mcp"]
env = { TLDRAW_MCP_ALLOWED_ROOTS = "/Users/me/dev:/Users/me/work" }

设置允许列表后，repoPath 必须解析到这些根目录之一内部。

生成的 .tldr 文件不会在形状元数据中存储本地仓库的绝对路径。可跟踪的代码图会存储相对于仓库的源路径。

本地开发

本仓库使用 Bun 进行开发：

bun install
bun run build
bun run smoke

从源码运行服务：

bun run dev

在 Codex 中使用本地构建：

[mcp_servers.codex-tldraw]
command = "node"
args = ["/absolute/path/to/codex-tldraw-mcp/dist/index.js"]

发布

构建、测试并检查包内容：

bun install --frozen-lockfile
bun run build
bun run smoke
bun run check:package
bun run check:plugin

当发布 GitHub Release 时，发布由 .github/workflows/publish-npm.yml 处理。npm 可信发布者必须允许 jananadiw/codex-tldraw-mcp、工作流 publish-npm.yml，不设置 GitHub environment 并启用 publish action。该工作流使用 GitHub OIDC，不需要 npm token。

使用该工作流的 dry_run 调度选项可以在不实际发布的情况下验证一次发布。

该包包含 MCP Registry 元数据：

• package.json 声明了 mcpName。
• server.json 描述了 npm stdio 包。

在工作流完成发布且 npm 包版本可用后，进行身份验证并发布 registry 元数据：

mcp-publisher login github
mcp-publisher publish

验证 registry 条目：

curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.jananadiw/codex-tldraw-mcp"