staruml-mcp

staruml-mcp

适用于 StarUML 的 Model Context Protocol（MCP）服务。可让 AI Agent（Claude Code、Cursor、VS Code Copilot、Codex）以编程方式驱动 StarUML——通过 Mermaid 生成 UML 图、执行任意内置命令、创建、读取、更新和删除元素、保存项目等。

工作原理

  AI Agent  ──MCP──►  staruml-mcp (this package)  ──HTTP──►  StarUML
                                                  :58321 (built-in, 4 tools)
                                                  :58322 (extension, 15 tools)

包	说明	运行位置
staruml-mcp（本仓库）	面向 AI Agent 的 MCP 服务	通过 npx -y staruml-mcp 在你的机器上运行
staruml-mcp-extension	添加 15 个 HTTP 端点的 StarUML 插件	在 StarUML 内运行（通过 Extension Manager 安装一次）

• 只使用基于 Mermaid 的图表工具？只需安装 staruml-mcp。4 个内置工具即可使用。
• 想要完整的 19 个工具（项目保存/打开、元素 CRUD、执行任意 StarUML 命令）？请同时安装两者。

前提条件

• StarUML v7.0.0+，并启用 API Server（见下文）
• 运行 AI Agent 的机器上安装 Node.js 20+
• **（可选）**在 StarUML 中安装 staruml-mcp-extension——15 个工具中的 15 个都需要它

启用 StarUML API Server

编辑以下位置的 settings.json：

• Windows： %APPDATA%\StarUML\settings.json
• macOS： ~/Library/Application Support/StarUML/settings.json
• Linux： ~/.config/StarUML/settings.json

添加或更新：

{
  "apiServer": true,
  "apiServerPort": 58321
}

重启 StarUML。

验证：

curl http://localhost:58321/
# → "Hello from StarUML API Server!"

安装与使用

Claude Code（推荐——HTTP 传输）

在终端中启动服务：

npx -y staruml-mcp --transport http
# listens on http://localhost:58323/mcp by default

向 Claude Code 注册：

claude mcp add --transport http staruml http://localhost:58323/mcp

端口 58323 是标准 HTTP 端口，选用该端口是为了与 StarUML 内置 API（58321）和 staruml-mcp-extension（58322）相邻。需要时可使用 --port <n> 覆盖。

重启 Claude Code。然后询问：

“你有哪些 StarUML 工具？”

Claude Desktop（stdio 传输）

编辑 %APPDATA%\Claude\claude_desktop_config.json（Windows）或 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）：

{
  "mcpServers": {
    "staruml": {
      "command": "npx",
      "args": ["-y", "staruml-mcp"]
    }
  }
}

重启 Claude Desktop。

Cursor / VS Code Copilot / Codex CLI

将 MCP 客户端指向 npx -y staruml-mcp（stdio）或 http://localhost:58323/mcp（HTTP）。

CLI

staruml-mcp [options]

  -t, --transport <type>   stdio | http              (default: stdio)
  -p, --port <number>      HTTP listen port          (default: 58323)
      --api-port <number>  StarUML built-in API port (default: 58321)
      --ext-port <number>  staruml-mcp-extension port(default: 58322)
      --api-host <url>     StarUML API host prefix   (default: http://localhost)
  -V, --version            Print version
  -h, --help               Show help

提供的工具

内置工具（始终可用，端口 58321）

工具	描述
generate_diagram	根据 Mermaid 代码生成 UML 图。
get_all_diagrams_info	列出当前项目中的所有图表（id、名称、类型）。
get_current_diagram_info	获取当前聚焦图表的元数据。
get_diagram_image_by_id	根据图表 ID 将图表导出为 PNG。

扩展工具（需要 staruml-mcp-extension，端口 58322）

工具	描述
get_all_commands	列出所有 138+ 个内置 StarUML 命令 ID。
execute_command	执行任意内置命令（例如 project:save、view:fit-to-window）。
get_project_info	当前项目的文件名和顶层元素。
save_project / save_project_as / new_project / open_project	项目文件生命周期管理。
get_element_by_id / find_elements	查询模型元素。
create_element / update_element / delete_element	元素 CRUD 操作。
create_diagram（类型化原生工具）/ switch_diagram / close_diagram	图表管理。

要启用扩展工具：在 StarUML 中安装 staruml-mcp-extension（Tools → Extension Manager → Install From URL → https://github.com/ezrabrilliant/staruml-mcp-extension）。

示例提示词

• “在 StarUML 中为 POS 数据库创建 ER 图：用户、菜单、交易及其关系。”
• “为 JWT 登录生成序列图：前端 → /api/auth/login → AuthService → DB → JWT 响应。”
• “显示 StarUML 中的当前图表。”
• “将 ID 为 xyz123 的图表导出为图像。”

开发

git clone https://github.com/ezrabrilliant/staruml-mcp.git
cd staruml-mcp
npm install
npm run dev          # tsx watch on src/
npm run build        # bundle to dist/
npm test             # vitest
npm run typecheck    # tsc --noEmit

架构

AI Agent (Claude Code / Cursor / VS Code / …)
        │
        │  MCP (stdio or Streamable HTTP)
        ▼
  staruml-mcp  (this package)
        │
        │  HTTP JSON-RPC
        ▼
StarUML API Server (port 58321)
        │
        ▼
  StarUML Application (v7+)

致谢

本项目的灵感来自 staruml/staruml-mcp-server（由 StarUML 创作者 Minkyu Lee 开发的官方纯 stdio 服务）。本项目以多传输支持和严格的 TypeScript 重新实现了它。

许可证

MIT © Ezra Brilliant Konterliem