convez.ai
MCP ServerDesenvolvimento WebIntermediário
jananadiw

Codex Tldraw MCP

jananadiw/codex-tldraw-mcp

Gera diagramas de fluxo tldraw analisando repositórios localmente

Ver no GitHub
BomPluginScore · de 0 a 100

Servidor MCP que gera diagramas de fluxo de produto em formato tldraw (.tldr) pela análise local de repositórios. Funciona como fallback para ambientes que não suportam canvas interativo, salvando os diagramas como arquivos no repositório para visualização posterior.

Instalação

$npx convez-ai jananadiw/codex-tldraw-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
25
Forks
0
Acompanhando
0
Saúde
57%
Último commit
há 6 dias
Versão
v0.7.1
Issues abertas
1
Contribuidores
1

Casos de uso

  • Documentar fluxos de produtos e workflows em repositórios
  • Criar diagramas visuais de arquitetura e processos automaticamente
  • Integrar visualização de diagramas em pipelines de desenvolvimento

Veredito

Ferramenta prática para quem precisa documentar fluxos visuais dentro de repositórios. Funciona bem em ambientes locais com geração confiável de arquivos, embora com menos interatividade que soluções canvas ao vivo.

README

A tradução para o português deste README ainda está na fila.

codex-tldraw-mcp

A Codex stdio MCP server that generates simple tldraw product workflow diagrams as .tldr files.

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.

Why This Exists

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 we decided to build. 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.

Add To Codex

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

Then ask Codex to use codex-tldraw and call diagram_repo.

Example prompt:

Use codex-tldraw to diagram this repo.

For manual Codex stdio MCP configuration:

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

What It Does

  • Scans a local repo from package metadata and source text.
  • Infers a simple user-facing product workflow.
  • Draws that workflow as tldraw steps and arrows.
  • Appends a new diagram to the right when the board already contains shapes.
  • Exposes board summaries as MCP resources.

Output

The default board is:

<repo>/boards/main.tldr

If main.tldr is empty or missing, diagram_repo creates the first diagram near the canvas origin. If it already has shapes, diagram_repo appends the next diagram to the right of the existing content instead of clearing the board.

Tools

  • diagram_repo: scans a repo and appends a product workflow diagram to <repo>/boards/<boardName>.tldr.
  • 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.

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:

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

When the allowlist is set, repoPath must resolve inside one of those roots.

Generated .tldr files do not store absolute local repository paths in shape metadata.

Local Development

This repo uses Bun for development:

bun install
bun run build
bun run smoke

Run the server from source:

bun run dev

Use a local build in Codex:

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

Publish

Build, test, inspect the package contents, then publish:

bun install
bun run build
bun run smoke
bun publish --dry-run
bun publish --access public

For a handwriting font app, the workflow may be inferred as:

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
Ver o original no GitHub

Bom para

Relacionados