AI导哈

tldraw文件管理服务

用于管理本地tldraw画布文件(.tldr)的MCP服务器，支持读取、写入、搜索和形状操作。

  • by talhaorak
  • JavaScript
  • 本地部署
  • 3 星标
  • 更新于
在 GitHub 查看 talhaorak/tldraw-mcp

使用说明

@塔拉奥拉克/tldraw mcp

用于管理本地的MCP（模型上下文协议）服务器 tldraw 画布文件(.tldr).

是什么让这与众不同？

现有的tldraw MCP服务器允许AI在内存画布上绘图。 这个项目不一样 --它读取、写入和搜索 本地 .tldr 文件 在磁盘上，使tldraw成为一个持久的视觉草稿栏，AI代理可以通过编程进行更新。

特性

  • 📖 阅读 --加载并解析 .tldr 文件
  • ✍️ 写 --通过验证创建和更新画布文件
  • 📋 列表 --枚举所有 .tldr 带有元数据的文件
  • 🔍 搜索 --在所有画布上进行全文搜索
  • 🔷 形状CRUD --以编程方式添加、更新、删除形状

安装

npm（推荐）

npx @talhaorak/tldraw-mcp

来源

git clone https://github.com/talhaorak/tldraw-mcp.git
cd tldraw-mcp
bun install
bun run start

配置

克劳德桌面

增添 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "tldraw": {
      "command": "npx",
      "args": ["@talhaorak/tldraw-mcp"],
      "env": {
        "TLDRAW_DIR": "/path/to/your/tldraw/files"
      }
    }
  }
}

开爪

添加到您的OpenClaw配置中：

mcp:
  servers:
    tldraw:
      command: npx
      args: ["@talhaorak/tldraw-mcp"]
      env:
        TLDRAW_DIR: /path/to/your/tldraw/files

或者作为技能安装：

curl -fsS https://raw.githubusercontent.com/talhaorak/tldraw-mcp/main/SKILLS.md | bash

环境变量

变量 默认值 描述
TLDRAW_DIR ~/.tldraw 的基本目录 .tldr 文件

工具

tldraw_read

阅读a .tldr 并返回其解析后的内容。

tldraw_read({ path: "notes.tldr" })

tldraw_write

编写或更新 .tldr 文件（验证格式）。

tldraw_write({ 
  path: "notes.tldr",
  content: { /* tldraw file object */ }
})

tldraw_create

创建一个新的空tldraw画布。

tldraw_create({ path: "new-canvas.tldr", name: "My Canvas" })

tldraw_list

列出所有 .tldr 具有页面/形状计数的文件。

tldraw_list({ recursive: true })

tldraw_search

在所有画布上搜索文本内容。

tldraw_search({ query: "TODO", searchIn: "text" })

tldraw_get_shapes

从文件中获取所有形状，可选择按页面过滤。

tldraw_get_shapes({ path: "notes.tldr", pageId: "page:abc123" })

tldraw_add_shape

在画布上添加新形状。

tldraw_add_shape({
  path: "notes.tldr",
  shape: {
    type: "geo",
    x: 100,
    y: 100,
    props: {
      w: 200,
      h: 100,
      geo: "rectangle",
      color: "blue",
      fill: "semi"
    }
  }
})

tldraw_update_shape

更新现有形状的属性。

tldraw_update_shape({
  path: "notes.tldr",
  shapeId: "shape:abc123",
  updates: { x: 200, props: { color: "red" } }
})

tldraw_delete_shape

从画布中删除形状。

tldraw_delete_shape({
  path: "notes.tldr",
  shapeId: "shape:abc123"
})

用例

  • AI代理的视觉草稿 --AI更新您可以在tldraw中查看的画布
  • 图表生成 --以编程方式创建流程图、架构图
  • 注释组织 --在多个画布上搜索和组织视觉笔记
  • 与tldraw桌面/VS代码集成 --文件自动同步

tldraw文件格式

此服务器使用tldraw v2格式：

{
  "tldrawFileFormatVersion": 1,
  "schema": {
    "schemaVersion": 2,
    "sequences": { ... }
  },
  "records": [
    { "id": "document:document", "typeName": "document", ... },
    { "id": "page:xxx", "typeName": "page", ... },
    { "id": "shape:xxx", "typeName": "shape", "type": "geo", ... }
  ]
}

发展

# Install dependencies
bun install

# Run in development mode
bun run dev

# Type check
bun run typecheck

# Build for distribution
bun run build

# Run tests
bun test

出版

./scripts/publish.sh          # Auto-increment patch (0.1.0 → 0.1.1)
./scripts/publish.sh 0.2.0    # Use specific version
./scripts/publish.sh minor    # Bump minor (0.1.1 → 0.2.0)
./scripts/publish.sh major    # Bump major (0.2.0 → 1.0.0)

脚本更新 package.json、提交、标记和推送。GitHub Actions通过可信发布者自动处理npm发布。

安全

  • 路径遍历预防 --相对路径无法逃脱 TLDRAW_DIR
  • 格式验证 --所有写入都根据tldraw模式进行验证
  • 无网络访问 --纯本地文件操作

许可证

MIT© Talha Orak

相关

相关 MCP