A Codex stdio MCP server that generates repo-local tldraw diagrams and detects code graph drift.
A Codex stdio MCP server that generates repo-local tldraw diagrams and detects code graph drift. It operates within a repository context to visualize workflows and architecture diagrams, aligning diagram outputs with the surrounding codebase for accurate context.
🛠️ Key Features
Generates repo-local tldraw diagrams from Codex MCP context
Detects code graph drift to surface divergence between code and visuals
TypeScript-based MCP implementation with standard tooling
Focused on repository visualization and workflow diagrams
🚀 Use Cases
Visualizing architecture diagrams within a repo
Monitoring and highlighting drift between code and diagrams
Integrating MCP outputs into development workflows
⚡ Developer Benefits
Grounded diagrams in repository context for accuracy
Lightweight, stdio MCP server suitable for local runs
Rich topics for discoverability: codex, mcp, tldraw, repo-visualization
⚠️ Limitations
Details on runtime environment or configuration are not provided
No explicit API or input/output schema in the source data
diagram_repo: scans a repo and appends a product workflow diagram to <repo>/boards/<boardName>.tldr.
draw_canvas: appends a prompt-provided workflow, state machine, architecture sketch, or plan to <repo>/boards/<boardName>.tldr.
diagram_code_graph: scans repository-local JavaScript and TypeScript modules and appends a trackable import graph.
compare_code_graph: previews drift or marks changed and stale elements on an existing trackable code graph.
list_boards: lists boards under a repo's boards/ directory.
read_board_summary: summarizes generated diagrams and shape counts.
Each tool accepts an optional repoPath. Relative paths are resolved from the MCP server working directory.
Board resources list and read boards from the most recent repoPath used by a tool call. Before any tool call, resources default to the MCP server working directory.
Code Graph Drift
diagram_code_graph stores stable repository-relative identities and fingerprints in MCP-owned shape metadata. Each source module becomes a node. Static imports, dynamic imports, re-exports, and CommonJS require calls between repository modules become edges.
Run compare_code_graph after the repository changes. Preview mode is the default and does not write the board:
text
Compare the current code with the newest code graph on boards/main.tldr.
To update the board, ask Codex to apply the drift markers or pass applyMarkers: true. The comparison uses four states:
unchanged: the stored identity and fingerprint still match.
changed: the module still exists, but its exports or local import relationships changed.
stale: the board contains an element that no longer exists in the current code graph.
new: the current graph contains an element that is absent from the board.
Stale elements become red and dashed. Changed modules become orange and dashed. New elements appear in the tool result; v0.4.0 does not insert or rearrange them. Re-running the comparison restores the original generated style when code matches again.
The comparison changes only MCP-generated graph styling and metadata. It preserves positions, sizes, labels, manual shapes, and other diagrams on the board, and it restores each element's prior color when drift clears. Boards created by diagram_repo, draw_canvas, or an older release do not contain trackable code-graph metadata; create a graph with diagram_code_graph before comparing drift.
The v0.4.0 scanner supports .js, .jsx, .mjs, .cjs, .ts, .tsx, .mts, and .cts modules. It reports unresolved relative imports and counts external imports without drawing external packages. It models module/import relationships, not runtime call graphs.
Prompt-Driven Diagrams
draw_canvas does not scan source files. The current repository is only the storage location for the generated board.
Example prompts:
text
Use codex-tldraw to draw the auth flow:
Visitor opens login -> chooses email or SSO -> completes MFA -> lands in dashboard.
text
Use codex-tldraw to make a state machine for password reset:
Idle -> Reset requested -> Email sent -> Token verified -> Password updated.
text
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.
Feedback
This project is early and feedback is useful. Please open an issue if:
The generated workflow misses the real product flow.
A board does not open in your tldraw-compatible viewer.
Code graph drift reports an incorrect module or import relationship.
You have a messy repo where a PM and engineer need a clearer shared map.
Use the GitHub issue templates for bugs, feature requests, and real-world examples.
Why This Exists
This project is snapshot-only. It does not control a live browser canvas or provide live collaboration. It writes board files to the repository being diagrammed so a tldraw-compatible viewer can open them later.
The official tldraw MCP App is designed for hosts that can render an interactive tldraw canvas inside the chat context. In Codex Desktop, tool discovery worked in testing, and the tldraw search tool returned Editor API details, shape types, and helpers. The live exec path did not work: every call timed out after 30 seconds, including a read-only call to count the current page shapes.
That failure mode suggested a host compatibility gap, not a tldraw file format problem. Codex can reliably call local stdio MCP tools and inspect generated files, but it does not currently provide the same embedded interactive MCP App canvas path used by hosts such as Cursor.
This server is the Codex-first fallback. Instead of trying to drive a live canvas, it generates .tldr snapshots on disk through a normal stdio MCP tool call. The result is less interactive, but it works reliably in Codex and keeps the generated board with the repository it explains.
Security
This is a local filesystem tool. It reads source files from repoPath and writes .tldr files under repoPath/boards.
To restrict access to specific directories, set TLDRAW_MCP_ALLOWED_ROOTS to a path-delimited allowlist:
bun install --frozen-lockfile
bun run build
bun run smoke
bun run check:package
Publishing is handled by .github/workflows/publish-npm.yml when a GitHub Release is published. The npm trusted publisher must allow jananadiw/codex-tldraw-mcp, workflow publish-npm.yml, with no GitHub environment and the publish action enabled. The workflow uses GitHub OIDC and does not require an npm token.
Use the workflow's dry_run dispatch option to validate a release without publishing it.
The package includes MCP Registry metadata:
package.json declares mcpName.
server.json describes the npm stdio package.
After the workflow publishes and the npm package version is available, authenticate and publish the registry metadata:
