visio-smartdraw-mcp-server

v2.0.0

Published

3 months ago

VisioSmartDraw MCP Server - 通过 MCP 协议控制本机 Visio 插件绘图（需配合 VisioSmartDraw Visio 加载项使用）

0High
0Medium
0Low

haibin666

mcp model-context-protocol visio diagram flowchart

VisioSmartDraw MCP Server

通过 MCP 协议控制 Visio 智能画图插件。

安装

已发布到 npm：visio-smartdraw-mcp-server。推荐直接用 npx，无需克隆代码：

npx -y visio-smartdraw-mcp-server

本地开发时也可以从源码运行：

cd src/tools/mcp-server
npm install
node index.js

文件结构

| 文件 | 职责 | |------|------| | index.js | MCP 工具注册（canonical 工具名 + Zod schema），入口 | | bridge.js | Bridge HTTP 客户端：callBridge、Visio 启动、就绪探测 | | response.js | 统一响应封装、TOOL_METADATA、metrics 记录 |

环境变量

| 变量 | 说明 | 默认值 | |------|------|--------| | VISIO_BRIDGE_URL | 插件 Bridge 地址 | http://127.0.0.1:38745 | | VISIO_BRIDGE_TOKEN | 认证令牌（与插件设置一致） | 空 |

在 Claude Desktop / Windsurf 中配置

推荐方式（npm 包，自动使用默认 http://127.0.0.1:38745，无需 env）：

{
  "mcpServers": {
    "visio-smartdraw": {
      "command": "npx",
      "args": ["-y", "visio-smartdraw-mcp-server"]
    }
  }
}

本地源码方式（开发调试用）：

{
  "mcpServers": {
    "visio-smartdraw": {
      "command": "node",
      "args": ["<工作区路径>/src/tools/mcp-server/index.js"]
    }
  }
}

远程使用（MCP server 与 Visio 不在同一台机器）

MCP server 通过 VISIO_BRIDGE_URL 连接插件 Bridge，因此可以跑在另一台机器上远程控制 Visio：

Visio 机器（Windows）：插件设置 %AppData%/VisioSmartDraw/settings.json 中把 mcpListenAddress 从 http://127.0.0.1:38745/ 改为 http://+:38745/（监听所有网卡），并设置 mcpAuthToken 作为访问令牌；放行防火墙 38745 端口。监听非 localhost 地址需要 URL 保留（管理员执行一次 netsh http add urlacl url=http://+:38745/ user=Everyone）。
MCP 客户端机器：配置中加 env 指向 Visio 机器：

{
  "mcpServers": {
    "visio-smartdraw": {
      "command": "npx",
      "args": ["-y", "visio-smartdraw-mcp-server"],
      "env": {
        "VISIO_BRIDGE_URL": "http://<Visio机器IP或域名>:38745",
        "VISIO_BRIDGE_TOKEN": "<与 mcpAuthToken 一致>"
      }
    }
  }
}

VISIO_BRIDGE_URL 支持任意可解析的地址：IP、局域网主机名（如 http://my-pc:38745）、内网 DNS 域名，也可以是 https:// 域名（把 38745 挂在反向代理 / Cloudflare Tunnel / frp 后面，由代理做 TLS 和转发，此时 URL 不用带端口）。插件端监听 http://+:38745/ 即接受任何 Host 访问，无需按域名额外配置。

注意：远程模式下 host.open 无法在远端启动 Visio（它只会启动本机进程），需要 Visio 机器上 Visio 已在运行；其余全部工具均可远程使用。仅建议在受信任的局域网内开放，公网使用请自行加 VPN/隧道。

主工具目录（共 24 个，先调 `help.usage` 获取完整使用指南与调用流程）

`help.*`

| 工具 | 说明 | |------|------| | help.usage | 返回全部工具分组说明、典型调用流程和关键约定 |

`host.*`

| 工具 | 说明 | |------|------| | host.open | 启动 Visio，并在需要时等待插件 Bridge 就绪；可选 createDocument: true 自动新建空白文档，或 filePath 直接打开现有 Visio 文件 | | host.status | 获取 Visio 和插件当前状态 |

`document.*`

| 工具 | 说明 | |------|------| | document.create | 创建新的 Visio 文档，可选指定模板 | | document.list | 列出当前已打开的所有文档（含路径、是否活动文档） | | document.switch | 切换到指定文档 | | document.close | 关闭指定文档，可选先保存 | | document.save | 保存当前/指定文档；all: true 保存全部已打开文档 | | document.open | 打开指定路径的 Visio 文件（Visio 未运行时自动启动） | | document.save_as | 将当前活动文档另存为到指定路径 |

`page.*`

| 工具 | 说明 | |------|------| | page.list | 列出当前文档所有页面（含活动页信息） | | page.switch | 切换到指定页面 | | page.export_image | 导出当前页面为图片（绘图后核验必用） |

`diagram.*`

| 工具 | 说明 | |------|------| | diagram.types | 列出支持的 9 种图类型 | | diagram.create | 创建指定类型的图（文本/JSON） | | diagram.structure | 获取当前页面所有形状和连接线结构 | | diagram.validate_layout | 校验当前页面布局（插件端执行），目前主要针对 UML 用例图 |

`freeform.*`

| 工具 | 说明 | |------|------| | freeform.validate | 校验自由形状 JSON（业务规则由插件端统一执行；Node 只做 MCP schema 校验） | | freeform.create | 创建自由形状绘图 | | freeform.check_layout | 检查当前页面自由形状布局质量 | | freeform.apply_edits | 【唯一编辑入口】批量执行 move_shape / update_shape / update_connector / reconnect_connector / delete_shape / delete_connector |

`catalog.*`

| 工具 | 说明 | |------|------| | catalog.stencils | 列出当前已加载的所有模具 | | catalog.shapes | 查询 Master 形状：传 query 关键词搜索，传 stencilName 列出指定模具全部形状 |

`inspect.*`

| 工具 | 说明 | |------|------| | inspect.page_context | 获取当前页面完整上下文 |

AI Skill

工作区已内置 skill: .agents/skills/visio-mcp-smartdraw/SKILL.md
该 skill 约束了 host -> document/page -> diagram/freeform -> inspect/export 的标准调用顺序
使用 freeform.*、document.*、diagram.* 写操作时，应遵循其中“写操作必须串行”的要求
修改 C# 插件后，仍需重新编译并重启 Visio，MCP 回归结果才有效

统一响应与 Metrics

所有工具现在统一返回 success / code / message / data / warnings / timing / meta
当前只注册主工具名，不再保留旧工具名兼容入口
Bridge action 与工具基本同名（namespace 风格）；少数合并工具在 Node 端分发到多个 Bridge action：document.save（→ document.save / document.save_all）、catalog.shapes（→ catalog.shapes / catalog.search_shapes）、freeform.apply_edits（覆盖原 update/reconnect/delete 单个工具的能力）。Bridge 端 action 全部保留，插件无需改动
Node 不再做数据类型修补，数字/布尔类型由插件端序列化保证
领域校验（数量上限、id 唯一性、引用合法性、禁用字段等）统一由插件端执行，Node 只保留 MCP 传输层 schema 校验
基础 metrics 会写入 %AppData%/VisioSmartDraw/mcp-metrics.jsonl

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

VisioSmartDraw MCP Server

安装

文件结构

环境变量

在 Claude Desktop / Windsurf 中配置

远程使用（MCP server 与 Visio 不在同一台机器）

主工具目录（共 24 个，先调 help.usage 获取完整使用指南与调用流程）

help.*

host.*

document.*

page.*

diagram.*

freeform.*

catalog.*

inspect.*