内容
# 流耀MCP
**流耀** 的MCP服务器：直接从Claude创建、编辑和导出架构图，操作在相同的`.fluyo.json`格式上，该格式由应用程序生成和消费。
不依赖于新的后端：它是`fluyo.html`使用的文档模型上的一个薄层（`serializeProject()`），1:1移植（语义调色板，GCP/AWS/Azure/General图标，按形状调整大小和SVG导出）。从此服务器生成的文档可以直接在**流耀**的**打开**按钮中打开。
---
# 解决问题
- **`create_diagram`** — 从节点和边的列表（文本 → 图表）创建完整的图表。如果未指定坐标（`x/y`），则应用分层自动布局。
- **`edit_diagram`** — 通过添加、删除或更新节点和边，改变主题或重新计算布局等操作修改现有文档。
- **`export_diagram`** — 使用与**流耀**相同的渲染器导出静态SVG页面。
- **`list_templates`** / **`create_from_template`** — 允许实例化预定义的架构模式（Kafka，RAG，微服务等）并替换标签。
- **`list_icons`** / **`list_colors`** — 公开图标和颜色的有效键，避免模型必须猜测它们。
---
# 安装
```bash
npm install
npm run build
```
这将`src/`编译到`dist/`。
要验证服务器在没有真正的MCP客户端的情况下是否正常工作：
```bash
npm run smoke-test
```
烟雾测试使用内存传输（`InMemoryTransport`）启动客户端和服务器，并执行完整的端到端流程。
---
# 连接到Claude
## Claude 代码 / Claude 桌面版
将以下服务器添加到MCP配置中：
```json
{
"mcpServers": {
"fluyo": {
"command": "node",
"args": [
"/绝对路径/到/fluyo-mcp/dist/index.js"
]
}
}
}
```
也可以作为全局可执行文件安装（`npm link` 或发布到npm）：
```json
{
"mcpServers": {
"fluyo": {
"command": "fluyo-mcp"
}
}
}
```
---
# 使用示例
### 提示
> 绘制一个管道图，其中一个API网关接收请求，发布事件到Kafka，两个消费者服务处理消息；其中一个服务持久化到Cloud SQL。
Claude将调用`create_diagram`，其结构类似于以下内容：
```json
{
"pageName": "事件管道",
"nodes": [
{
"key": "gw",
"shape": "rect",
"label": "API网关",
"color": "服务"
},
{
"key": "kafka",
"shape": "icon",
"icon": "kafka",
"label": "Kafka",
"pulse": true,
"color": "事件/Kafka"
},
{
"key": "svcA",
"shape": "rect",
"label": "服务A",
"color": "服务"
},
{
"key": "svcB",
"shape": "rect",
"label": "服务B",
"color": "服务"
},
{
"key": "db",
"shape": "cylinder",
"label": "Cloud SQL",
"color": "数据"
}
],
"edges": [
{
"from": "gw",
"to": "kafka",
"label": "事件",
"route": "ortho"
},
{
"from": "kafka",
"to": "svcA",
"label": "主题：A",
"route": "ortho"
},
{
"from": "kafka",
"to": "svcB",
"label": "主题：B",
"route": "ortho"
},
{
"from": "svcB",
"to": "db",
"label": "持久化",
"dashed": true
}
]
}
```
结果是一个完全有效的`.fluyo.json`文档，可以在**流耀**中打开或通过`edit_diagram`和`export_diagram`继续编辑。
---
# `edit_diagram`中可用的操作
操作作为`operations`字段中的列表发送，并按顺序执行。
| 操作 | 主要字段 | 描述 |
| --- | --- | --- |
| `add_node` | `key`，`shape`，`label`，`color?`，`icon?`，`x?`，`y?` | 添加新节点。`key`仅在调用期间存在，以便后续引用。 |
| `update_node` | `id`，... | 使用数字标识符更新现有节点。 |
| `remove_node` | `id` | 删除节点及其所有连接。 |
| `add_edge` | `from`，`to` | 创建连接。可以引用现有ID或在同一调用中创建的节点`key`。 |
| `update_edge` | `id`，... | 修改现有边。 |
| `remove_edge` | `id` | 删除边。 |
| `set_theme` | `theme` | 更改主题（`dark`，`crema`或`claro`）。 |
| `rename_page` | `name` | 更改页面名称。 |
| `relayout` | — | 自动重新计算所有节点的位置。 |
> **注意：** 要引用文档中现有的节点，必须始终使用其数字`id`。在`add_node`期间使用的`key`是临时的，不会存储在`.fluyo.json`中。
---
# 当前限制
- 导出器仅生成**SVG**。导出PNG或GIF需要集成像`sharp`，`resvg`或`node-canvas`这样的渲染器。
- `image`类型的节点无法通过MCP创建，因为它们依赖于手动导入**流耀**的二进制文件。但是，如果文档中已经存在，它们可以被编辑。
- 导出的SVG不包括动画（粒子流或渐进式外观），与**流耀**的原生导出器相同。
- 自动布局算法使用简单的分层方法（简化的Sugiyama）。它适用于管道和传统架构；对于复杂图，可能建议手动指定坐标或使用`relayout`后进行逐点调整。
---
# 项目结构
```text
src/
schema.ts # 从fluyo.html移植的调色板、主题、图标和大小
model.ts # Fluyo文档的Zod模式和类型
layout.ts # 分层自动布局（简化的Sugiyama）
diagram.ts # createDiagram / editDiagram
svg.ts # SVG导出器
templates.ts # 架构模板
server.ts # MCP工具注册
index.ts # 入口点（stdio）
scripts/
smoke-test.ts # 使用InMemoryTransport的客户端+服务器
```
