Timeverse InfCanvas MCP Server

本地无限画布的 MCP Server，让 AI 客户端（Claude Desktop / Cursor 等）通过 Model Context Protocol 直接读写本地画布数据。

项目结构

timeverse-InfCanvas-mcp/
├── mcp-server/          ← MCP 协议服务（核心）
│   ├── server.mjs           MCP Server 主入口
│   ├── canvas-store.mjs     画布数据读写
│   ├── image-generator.mjs  大模型生图
│   ├── fractional-indexing.mjs  z-order 排序
│   ├── overlap-detector.mjs    碰撞检测
│   ├── seed-demo.mjs        演示数据生成
│   ├── test.mjs             冒烟测试
│   ├── package.json         依赖声明
│   └── node_modules/
├── web-server/          ← HTTP 可视化服务
│   └── web-server.mjs      画布浏览器查看 + 编辑 API
├── client/              ← React + tldraw 编辑器
│   ├── src/                 React 源码
│   ├── dist/                构建产物
│   └── package.json
├── canvas/              ← 画布数据目录
├── package.json             根项目脚本
├── LICENSE
└── README.md

架构

AI 客户端 ──(stdio JSON-RPC)──> mcp-server/server.mjs
                                    │
                                    ├── canvas-store.mjs     canvas/*.json
                                    ├── image-generator.mjs  模型 API
                                    ├── fractional-indexing.mjs
                                    └── overlap-detector.mjs

浏览器    ──(HTTP)──> web-server/web-server.mjs
                          │
                          ├── canvas/*.json   (读取画布)
                          └── client/dist/    (前端静态文件)

三个模块，各司其职：

模块	职责	技术栈
mcp-server	MCP 协议通信，AI 调用工具读写画布	Node.js ESM, `@modelcontextprotocol/sdk`
web-server	HTTP 可视化，浏览器实时查看/编辑画布	Node.js 原生 http 模块（零依赖）
client	前端编辑器（可选），tldraw 专业图形界面	React 18, tldraw 5, Vite

安装

# 克隆项目
git clone <repo-url>
cd timeverse-InfCanvas-mcp

# 安装 MCP Server 依赖
cd mcp-server && npm install

# （可选）构建前端编辑器
cd ../client && npm install && npm run build

在 AI 客户端中配置

MCP Server 通过 stdio 协议与 AI 客户端通信，配置时指向 mcp-server/server.mjs。

Claude Desktop

编辑 claude_desktop_config.json：

{
  "mcpServers": {
    "infcanvas": {
      "command": "node",
      "args": ["D:/path/to/timeverse-InfCanvas-mcp/mcp-server/server.mjs"],
      "env": {
        "INF_CANVAS_DIR": "D:/path/to/your-project",
        "REPLICATE_API_KEY": "r-xxxxx"
      }
    }
  }
}

Cursor

编辑 .cursor/mcp.json：

{
  "mcpServers": {
    "infcanvas": {
      "command": "node",
      "args": ["D:/path/to/timeverse-InfCanvas-mcp/mcp-server/server.mjs"]
    }
  }
}

自研客户端

支持以下方式集成：

方式一：JSON 配置（适用于支持 MCP 配置文件的客户端）

{
  "mcpServers": {
    "infcanvas": {
      "command": "node",
      "args": ["D:/path/to/timeverse-InfCanvas-mcp/mcp-server/server.mjs"],
      "env": {
        "INF_CANVAS_DIR": "D:/my-project"
      }
    }
  }
}

方式二：通过 npx（无需本地安装，自动从 npm 拉取）

{
  "mcpServers": {
    "infcanvas": {
      "command": "npx",
      "args": ["-y", "timeverse-infcanvas-mcp"],
      "env": {
        "INF_CANVAS_DIR": "D:/my-project"
      }
    }
  }
}

注意：timeverse-infcanvas-mcp 尚未发布到 npm，发布后方可使用此方式。

方式三：代码中通过 stdio 启动子进程

const { spawn } = require('node:child_process')
const cp = spawn('node', ['D:/path/to/mcp-server/server.mjs'], {
  env: { ...process.env, INF_CANVAS_DIR: 'D:/my-project' },
  stdio: ['pipe', 'pipe', 'pipe'],
})
// 通过 stdin/stdout 收发 JSON-RPC 2.0 消息

暴露的 MCP 工具

所有数据操作工具都需要 projectDir 参数（指定项目目录，在其下创建 canvas/ 文件夹）：

工具	用途	必填参数
`get_canvas_snapshot`	获取画布全量数据	`projectDir`
`get_selection`	读取当前用户选区	`projectDir`
`list_pages`	列出所有页面	`projectDir`
`create_page`	新建页面	`projectDir`
`switch_page`	切换当前页面	`projectDir`, `pageId`
`create_ai_image_holder`	创建 AI 图片占位框	`projectDir`
`insert_image`	插入图片（本地路径或 URL）	`projectDir`, `sourcePath`
`fill_ai_holder`	把已有 asset 填入占位框	`projectDir`, `holderId`, `assetId`
`update_shape`	更新 shape 位置/属性	`projectDir`, `shapeId`
`update_shape_status`	流式更新生成状态与进度	`projectDir`, `shapeId`, `status`
`delete_shapes`	删除多个 shape	`projectDir`, `shapeIds`
`generate_image`	大模型生图并直接填入画布	`projectDir`, `prompt`
`start_web_server`	启动 HTTP 可视化服务（无 projectDir 也可调用）	—

start_web_server

AI 调用此工具后，会在本地启动 HTTP 服务，打开浏览器即可实时查看/操作画布：

{
  "name": "start_web_server",
  "arguments": { "port": 3000 }
}

返回 { "url": "http://localhost:3000", "status": "started" }。重复调用不会重复启动，浏览器打开 http://localhost:3000 即可查看画布。

手动启动

# MCP Server（stdio 交互，通常由 AI 客户端自动拉起）
npm start

# Web 可视化服务
npm run web
# 浏览器打开 http://localhost:3000

# 前端开发模式
npm run dev:client

# 构建前端
npm run build:client

环境变量

变量	用途	必填
`INF_CANVAS_DIR`	兜底项目目录（不填则每次调用传 `projectDir`）	否
`OPENAI_API_KEY`	OpenAI API Key（DALL-E 3 生图）	按需
`OPENAI_API_ENDPOINT`	OpenAI 端点，默认 `https://api.openai.com/v1`	否
`REPLICATE_API_KEY`	Replicate API Token（Flux / SDXL 生图）	按需
`CUSTOM_API_ENDPOINT`	自研模型 HTTP 端点	按需
`CUSTOM_API_KEY`	自研模型 API Key	按需

大模型生图

支持的模型（通过环境变量路由）：

model	依赖
`dall-e-3`	`OPENAI_API_KEY`
`flux-schnell`	`REPLICATE_API_KEY`
`sdxl`	`REPLICATE_API_KEY`
`custom`	`CUSTOM_API_ENDPOINT` + `CUSTOM_API_KEY`

工具参数中传 endpoint 和 apiKey 可临时覆盖环境变量。

测试

cd mcp-server
node test.mjs

冒烟测试会验证 MCP 协议通信、数据隔离、工具调用等核心功能。

画布数据格式

<project>/canvas/
├── canvas.json             画布索引（页面、shape 列表、资源）
├── selection.json          当前选区
├── view-state.json         视口状态（相机位置、当前页）
└── shapes/                 独立 shape 文件（每个 .json）

三方鸣谢

tldraw — 前端编辑器基于 tldraw v5，提供专业级的无限画布交互体验
Model Context Protocol SDK — MCP 协议实现
React + Vite — 前端工程化
Replicate — Flux / SDXL 模型推理
OpenAI — DALL-E 3 图片生成

许可证

完整许可见 LICENSE。