vizcraft (Terminal Gravity)

VIZCRAFT

Claude代码的AI原生图

Claude生成JSON规范→ Vizcraft渲染交互式图表→ 用户可以编辑→ 更改同步回Claude

特性

• MCP 服务器 -克劳德代码集成的6个工具（创建、更新、描述、列出、删除、导出）
• 交互式画布 -tldraw驱动的无限画布，具有平移/缩放/编辑功能
• AI代理 -基于规则（dagre布局）、预设（主题）、LLM驱动的代理
• 出口 -PNG、SVG、PDF导出
• 版本历史记录 -类似Git的图表版本控制
• 缩略图 -侧边栏中的视觉预览
• 黑暗/光明主题 -系统偏好感知
• 移动响应 -适用于平板电脑/手机屏幕

Claude Code CLI的安装

选项1:Docker（推荐）

使用Claude Code CLI运行Vizcraft的最简单方法。

第一步：构建Docker镜像

git clone https://github.com/TerminalGravity/vizcraft.git
cd vizcraft
docker build -t vizcraft .

步骤2：启动Web UI

# Run the Web UI (for viewing/editing diagrams)
docker compose up -d

# Or manually:
docker run -d --name vizcraft-web -p 3420:3420 -v vizcraft-data:/app/data vizcraft web

Web UI将在 http://localhost:3420

步骤3：配置Claude代码CLI

添加到您的 ~/.claude.json （全球）或项目 .mcp.json:

{
  "mcpServers": {
    "vizcraft": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-v", "vizcraft-data:/app/data", "vizcraft", "mcp"]
    }
  }
}

重要：The -i MCP的stdio通信需要标志。这 -v vizcraft-data:/app/data 确保图表持久存在，并在MCP服务器和Web UI之间共享。

步骤4：重新启动Claude代码

# If using Claude Code CLI, restart your session
# The vizcraft tools should now be available

方案2：Bun（开发）

直接使用Bun进行开发，或者如果你不想使用Docker。

步骤1：安装并运行

git clone https://github.com/TerminalGravity/vizcraft.git
cd vizcraft
bun install

# Terminal 1: Web UI
bun run web:dev

# Terminal 2: (Optional) MCP server for testing
bun run dev

步骤2：配置Claude代码CLI

添加到您的 ~/.claude.json 或项目的 .mcp.json:

{
  "mcpServers": {
    "vizcraft": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/vizcraft/src/server.ts"],
      "env": {
        "WEB_URL": "http://localhost:3420"
      }
    }
  }
}

备注：使用绝对路径 server.tsThe WEB_URL 告诉MCP服务器Web UI运行的位置。

选项3:npx（即将推出）

# Future: Install globally via npm
npx vizcraft

验证安装

配置完Claude Code后，您可以验证安装：

You: List my vizcraft diagrams

Claude: I'll check your diagrams using the vizcraft MCP server.
[Uses mcp__vizcraft__list_diagrams tool]

如果您看到工具被调用，则安装成功。

MCP工具

安装后，Claude Code可以访问这些工具：

// Create new diagram
mcp__vizcraft__create_diagram({
  name: "Architecture",
  project: "my-project",
  spec: {
    type: "flowchart",
    nodes: [
      { id: "a", label: "Start", type: "circle" },
      { id: "b", label: "Process", type: "box" },
      { id: "c", label: "End", type: "circle" }
    ],
    edges: [
      { from: "a", to: "b" },
      { from: "b", to: "c" }
    ]
  }
})

// Update diagram
mcp__vizcraft__update_diagram({ id: "abc123", spec: {...} })

// Get diagram description for Claude
mcp__vizcraft__describe_diagram({ id: "abc123" })

// Export diagram
mcp__vizcraft__export_diagram({ id: "abc123", format: "svg" })

// List diagrams
mcp__vizcraft__list_diagrams({ project: "my-project" })

// Delete diagram
mcp__vizcraft__delete_diagram({ id: "abc123" })

示例用法

让Claude自然地创建图表：

You: Create an architecture diagram showing a web app with React frontend,
     Node.js API, and PostgreSQL database

Claude: I'll create that architecture diagram for you.
[Uses mcp__vizcraft__create_diagram]
Done! View your diagram at http://localhost:3420/diagram/abc123

图表规格格式

interface DiagramSpec {
  type: "flowchart" | "architecture" | "sequence" | "freeform";
  theme?: "dark" | "light" | "professional";
  nodes: Array;
  edges: Array;
}

代理系统

代理是YAML配置 data/agents/ 该转换图：

# Auto Layout (rule-based)
name: "Auto Layout"
type: "rule-based"
actions:
  - dagre_layout
  - snap_to_grid

# Theme Preset
name: "Professional Theme"
type: "preset"
styles:
  node_fill: "#1e293b"
  node_stroke: "#3b82f6"
  edge_color: "#64748b"

# LLM Agent (requires API key)
name: "Annotate"
type: "llm"
provider: "anthropic"
prompt: "Add helpful annotations to this diagram"

通过Web UI侧栏或API运行代理：

POST /api/diagrams/:id/run-agent/:agentId

网页用户界面

• 侧边栏：带缩略图的项目浏览器+代理面板
• 画布：使用平移/缩放/编辑绘制无限画布
• 面板：图表信息+导出按钮

键盘快捷键

API终点

Docker命令参考

# Build the image
docker build -t vizcraft .

# Run Web UI (with docker-compose)
docker compose up -d

# Run Web UI (manual)
docker run -d --name vizcraft-web -p 3420:3420 -v vizcraft-data:/app/data vizcraft web

# Run MCP server (for Claude Code CLI - configured in .mcp.json)
docker run -i --rm -v vizcraft-data:/app/data vizcraft mcp

# View logs
docker logs vizcraft-web

# Stop
docker compose down

# Remove data volume (caution: deletes all diagrams)
docker volume rm vizcraft-data

技术栈

• 运行时间： 包子
• MCP服务器： @模型上下文协议/sdk（stdio传输）
• 数据库： 面包：sqlite
• Web用户界面： React 19+tldraw 4.3
• API 荣誉
• 出口： jsPDF for PDF
• 布局： @dagrejs/dagre用于自动布局

发展

# Install
bun install

# Run tests
bun test

# Run Web UI (dev mode with hot reload)
bun run web:dev

# Run MCP server (dev mode)
bun run dev

# Build web UI
bun run web:build

# Build for production
bun run build

项目结构

vizcraft/
├── src/
│   ├── server.ts          # MCP server (stdio)
│   ├── web-server.ts      # Hono REST API + static files
│   ├── storage/db.ts      # SQLite layer
│   ├── agents/
│   │   ├── loader.ts      # YAML agent loader
│   │   └── runner.ts      # Agent executor
│   └── types/index.ts     # TypeScript types
├── web/
│   ├── app.tsx            # React app
│   ├── index.html         # Entry
│   └── styles.css         # Styling
├── data/
│   ├── diagrams/          # Diagram storage (SQLite)
│   ├── exports/           # Exported files
│   └── agents/            # Agent YAML configs
├── Dockerfile             # Multi-service Docker image
├── docker-compose.yml     # Web UI service
├── docker-entrypoint.sh   # Entrypoint script
└── package.json

故障排除

MCP服务器未连接

1. 确保Docker正在运行
2. 验证卷名是否匹配： vizcraft-data
3. 检查Claude代码配置路径是否正确
4. 配置更改后重新启动Claude Code CLI

Web UI中未显示图表

1. 确保MCP服务器和Web UI使用相同的卷
2. 检查卷是否存在： docker volume ls | grep vizcraft
3. 验证Web UI是否正在运行： curl http://localhost:3420/api/health

Docker构建失败

1. 确保您已安装Docker 20.10+
2. 尝试： docker build --no-cache -t vizcraft .

已完成的功能

• \[x\] 配备6个工具的MCP服务器
• \[x\] SQLite持久化与版本控制
• \[x\] 带有tldraw画布的Web UI
• \[x\] 导出为PNG/SVG/PDF
• \[x\] 代理系统（基于规则、预设、LLM）
• \[x\] Dagre汽车布局
• \[x\] 主题预设
• \[x\] 键盘快捷键
• \[x\] 暗/亮主题切换
• \[x\] 移动响应
• \[x\] 吐司通知
• \[x\] 图表缩略图
• \[x\] Docker支持
• \[x\] 集成测试

许可证

麻省理工学院

______________________________________________________________________

建于 克劳德代码