MCP-BPMN 服务器

一个用于经过测试的 BPMN 2.0 创作子集的模型上下文协议（MCP）服务器，包括 Mermaid 转换、本地持久化、布局、验证以及 XML 或 SVG 导出。

🎯 概述

MCP-BPMN 为 AI 助手提供有状态接口，使其能够一次处理一个业务流程图表。它为下列构造创作格式良好的 BPMN 2.0 XML；它不是完整的 BPMN 2.0 编辑器、执行引擎或部署客户端。可移植的 BPMN 核心是默认的创作契约，并带有可选的类型化 Camunda 7 配置文件，详见 ADR 0001。

主要特性

• 聚焦的 BPMN 创作：支持的事件、活动、网关、数据对象、注释、泳道、顶层泳道、顺序流和关联

• Mermaid 转换：从文档化的流程图子集引导图表

• 水平自动布局：确定性的流程和协作放置

• 本地持久化：在配置的目录中原子保存并重新打开图表

• XML 和 SVG 导出：XML 在进程内生成；SVG 通过 Puppeteer 和 bpmn-js 渲染

• 可移植和 Camunda 7 配置文件：默认输出无供应商依赖，显式选择时提供三个类型化的 Camunda 7 用户任务字段

Related MCP server: BPMN-MCP

🚀 快速开始

要求

• Node.js 22.12.0 或更高版本

• 支持 lockfile 的 npm

• 用于 export({ format: "svg" }) 的 Chrome 或 Chromium；正常的 Puppeteer 安装会下载兼容的浏览器

XML 创作、验证、布局、持久化和 XML 导出不会启动浏览器。SVG 导出会。如果故意跳过 Puppeteer 浏览器下载，请在启动服务器前将 PUPPETEER_EXECUTABLE_PATH 设置为兼容的 Chrome 或 Chromium 可执行文件。SVG 渲染是无头的，每个服务器实例限制为一次并发渲染，并有二十秒的渲染超时。

从源代码检出运行

git clone https://github.com/oisee/mcp-bpmn.git
cd mcp-bpmn
npm ci
npm run build
npm start

npm run build 在 dist/server/index.js 生成规范的 ESM 可执行文件。服务器使用 stdio，因此在终端中启动时通常看起来空闲，并旨在由 MCP 客户端启动。

配置

对于 Claude Desktop

添加到您的 Claude Desktop 配置文件：

macOS：~/Library/Application Support/Claude/claude_desktop_config.json
Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mcp-bpmn": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-bpmn/dist/server/index.js"]
    }
  }
}

对于其他 MCP 客户端

使用相同的 ESM 入口点，并带有绝对路径：

node /absolute/path/to/mcp-bpmn/dist/server/index.js

安装打包的发布工件

此仓库目前记录 npm tarball 安装，而不是假设 mcp-bpmn-server 可从公共 npm 注册表获得。发布生产者可以从源代码检出构建规范的仅 CLI 工件：

artifact_dir=$(mktemp -d)
npm pack --pack-destination "$artifact_dir"

将该 tarball 安装到专用的消费者目录中，并运行其打包的可执行文件：

consumer_dir=$(mktemp -d)
npm install --prefix "$consumer_dir" "$artifact_dir"/mcp-bpmn-server-*.tgz
"$consumer_dir/node_modules/.bin/mcp-bpmn-server"

对于 MCP 客户端，使用 $consumer_dir/node_modules/.bin/mcp-bpmn-server 的绝对值作为 command，并使用空的 args 数组。该包是 CLI，不是可导入的 JavaScript 库。

为 Claude Code 和 Codex 安装

从源代码检出，安装程序将当前版本打包到稳定的用户拥有的位置，注册其 MCP 服务器，并为 PATH 上找到的每个受支持客户端安装 bpmn-modeler 技能：

make install
make doctor

默认程序位置是 ~/.local/share/mcp-bpmn，而图表保留在安装目录之外的 ~/mcp-bpmn 中。技能被复制到 Codex 的 ~/.codex/skills/bpmn-modeler 和 Claude Code 的 ~/.claude/skills/bpmn-modeler。安装后重启客户端，以便它们发现新技能和 MCP 服务器。

安装是幂等的：再次运行 make install 仅替换此安装程序拥有的文件和注册。除非显式请求替换（使用 FORCE=1），否则保留现有的第三方注册或技能目录。使用以下命令定位一个客户端、更新现有安装或卸载同时保留图表：

make install-codex
make install-claude
make update
make uninstall

设置 PREFIX 以更改程序位置，设置 MCP_BPMN_DIAGRAMS_PATH 以使用不同的绝对图表目录。通过同时设置 MCP_BPMN_PACKAGE_TARBALL 及其必需的 MCP_BPMN_PACKAGE_SHA256，可以可重复地安装预构建的发布 tarball。运行 ./scripts/install-agent-integrations.sh --help 获取完整接口。安装程序支持 macOS 和 Linux，包括带有 Linux 原生 Node.js 和客户端 CLI 的 WSL。

本地开发 Codex 插件

发布工件也是 Codex 插件。其清单发现规范的 skills/bpmn-modeler 技能，并通过复制到插件缓存中的启动器启动一个 mcp-bpmn stdio 服务器。启动器使用 make install-codex 安装的稳定私有版本；安装后不执行 TypeScript 或依赖检出。

构建发布工件，将此检出添加为临时仓库市场，并安装插件：

npm ci
npm run build
make install-codex
codex plugin marketplace add .
codex plugin list --available
codex plugin add mcp-bpmn@mcp-bpmn-local

安装后启动新的 Codex 对话，以便加载技能和 MCP 工具。捆绑的服务器默认为 writes 批准模式：标记为只读的工具可以自动运行，而图表变更保持可见以供批准。使用以下命令移除开发安装：

codex plugin remove mcp-bpmn@mcp-bpmn-local
codex plugin marketplace remove mcp-bpmn-local

运行隔离的市场、缓存、发现、MCP 启动和移除冒烟测试，而不更改真实的 Codex 配置：

npm run test:codex-plugin

本地开发 Claude Code 插件

发布工件也是 Claude Code 插件。Claude 将规范的 skills/bpmn-modeler/SKILL.md 发现为命名空间的 /mcp-bpmn:bpmn-modeler 技能，并从插件缓存启动内联的 mcp-bpmn 服务器。插件使用 skills/；它不携带旧的 commands/ 副本。

从源代码检出，安装依赖、构建、验证并加载插件以进行一个开发会话：

npm ci
npm run build
claude plugin validate .
claude --plugin-dir .

在 Claude Code 内部，使用 /mcp 确认插件提供的服务器，调用 /mcp-bpmn:bpmn-modeler 检查技能，并在更改清单或 MCP 配置后运行 /reload-plugins。检出包含根 CLAUDE.md 供仓库贡献者使用，因此源验证报告它不是插件上下文；命令仍然成功。打包的插件排除该仅仓库文件，并通过严格验证。

使用以下命令运行完整的本地市场冒烟测试：

npm run test:claude-plugin

该检查使用临时的 Claude 主目录和市场。它安装复制的发布工件，检查 Claude 的组件清单，启动缓存的 MCP 服务器，执行重新加载，然后禁用、启用和移除插件。它不会更改开发者的真实 Claude 配置。

图表永远不会写入 ${CLAUDE_PLUGIN_ROOT}。它们保留在 MCP_BPMN_DIAGRAMS_PATH（如果设置）或默认的 ~/mcp-bpmn 中，因此插件重新加载、更新、禁用和移除不会删除它们。在从手动 Claude MCP 注册切换到插件之前，检查 claude mcp list，如果旧 mcp-bpmn 注册的命令与插件端点不同，则移除它；Claude 仅对解析为相同命令的插件和用户服务器进行去重。

评估代理工作流

规范的机器可读语料库是 evals/bpmn-modeler/cases.json。两个客户端适配器都使用这些确切的提示和语义期望。确定性检查对于正常开发和 CI 是安全的：它验证激活边界、技能元数据、工具名称、客户端对等性以及创建/变更/验证/布局/验证/导出序列，而不调用模型：

npm run test:evaluations

经过身份验证的模型运行是选择加入的。先构建，然后在迭代时选择一个有界案例：

npm run build
npm run eval:codex -- --case direct-process-svg
npm run eval:claude -- --case direct-process-svg

Codex 适配器在临时项目中运行 codex exec，该项目包含规范技能和项目范围的 stdio MCP 配置。Claude 适配器将相同的案例物化为临时插件副本中的原生 claude plugin eval 案例。两者都将 MCP_BPMN_DIAGRAMS_PATH 设置为临时目录，仅将声明的设置夹具复制到那里，并在之后移除目录；它们从不读取、覆盖或删除用户真实存储中的图表。省略 --case 以运行完整语料库。这些命令可能消耗模型配额，并有意从 npm run check 和 CI 中排除。

可选的 CommonJS 捆绑包

CommonJS 捆绑包是单独的源代码检出构建，不由 npm run build 生成，也不包含在规范的 npm tarball 中：

npm run build:bundle
npm run start:bundle

📚 API 参考

有状态上下文管理

MCP-BPMN 使用有状态 API 设计，您一次处理一个图表。所有操作都应用于当前图表上下文，无需 processId 参数。

广告工具矩阵

此 API 参考中的标题枚举了 tools/list 返回的每个工具。可执行文件对等基线是 tests/contracts/engine-contract.test.ts，单元、集成和端到端套件中具有聚焦行为。

每个广告工具还包括标准的 MCP readOnlyHint、destructiveHint、idempotentHint 和 openWorldHint 注解。这些注解描述可观察的服务器行为：创作调用自动保存，替换和删除调用可能销毁现有状态，所有操作都保持在配置的本地图表存储中。MCP 注解是建议性提示，不是授权边界；客户端仍必须应用自己的信任和批准策略。

创建工具

new_bpmn

创建新的 BPMN 流程或协作图表，并将其设置为当前上下文。

{
  name: "Order Processing",
  type: "process" // or "collaboration" (optional, defaults to "process")
}

new_from_mermaid

Create a new BPMN diagram from Mermaid code and set it as the current context.

{
  name: "My Process",
  mermaidCode: "graph TD\n  A[Start] --> B[Task] --> C[End]"
}

Mermaid 转换有意支持一个聚焦的流程图子集：

当存在任何子图时，每个节点必须恰好属于一个顶级子图。嵌套子图和到数据节点的顺序流连接在 BPMN 导出前被拒绝。样式、点击处理程序、CSS 类和虚线边外观不在 BPMN 中表示；接受的损失性语法会返回转换警告。文本标签和子图名称经过 XML 转义，并通过 BPMN 往返保持不变。

文件操作

open_bpmn

打开现有的 BPMN 文件并将其设置为当前上下文。

{
  filename: "my-process.bpmn"
}

open_mermaid_file

打开并转换 Mermaid 文件为 BPMN，将其设置为当前上下文。

{
  filename: "my-flowchart.mmd"
}

save

将当前图表原子化保存到其活动文件。新建和打开的图表已有活动文件名，成功的变更会自动保存到同一文件。

{}

save_as

使用新文件名原子化保存当前图表，并将该文件名设为活动。后续变更仅更新新文件；原文件保持不变的快照。

{
  filename: "my-process.bpmn"
}

close

关闭当前图表并清除上下文。

{}

current

获取当前图表的信息。

{}

元素操作工具

add_event

向当前图表添加事件（开始、结束、中间、边界）。

{
  eventType: "start", // start, end, intermediate-throw, intermediate-catch, boundary
  name: "Order Received",
  eventDefinition: "message", // optional; only BPMN-legal event kind/definition pairs are accepted
  eventDefinitionPayload: {
    reference: { name: "Order received" } // root ID is generated when omitted
  },
  position: { x: 100, y: 200 } // optional
}

定时器定义需要 timer: { type: "timeDate" | "timeDuration" | "timeCycle", expression, language? }；条件定义需要 condition: { expression, language? }。错误和升级引用还可以包含 code。补偿抛出可以包含 activityRef 和 waitForCompletion；补偿边界事件是非中断的。

add_activity

向当前图表添加活动（任务、子流程）。

{
  activityType: "userTask", // task, userTask, serviceTask, scriptTask, etc.
  name: "Review Order",
  position: { x: 250, y: 200 }, // optional
  properties: { // optional; Camunda 7 profile only on userTask
    assignee: "reviewer",
    candidateGroups: ["operations", "approvers"],
    dueDate: "${dueDate}"
  }
}

新建的 BPMN 和 Mermaid 文档接受 extensionProfile: "portable" | "camunda7"；默认为 portable。Portable 模式拒绝三个供应商字段，且不输出供应商命名空间。Camunda 更新对其中任一字段接受 null 以移除相应的 XML 属性。候选组条目不能包含逗号。导入的 BPMN 会检测实际的 Camunda 命名空间使用情况，并透明地保留其他无警告的扩展。

调用活动序列化为 bpmn:callActivity。其可选的 properties.calledElement 是标识可调用元素的词法 BPMN QName；它不需要与当前图表中的流程 ID 匹配。

活动可以使用标准 BPMN 多实例循环特性。将 isSequential 设为 false 表示并行实例，设为 true 表示顺序实例：

{
  activityType: "serviceTask",
  name: "Process Batch",
  properties: {
    multiInstance: {
      isSequential: false,
      loopCardinality: {
        body: "requestedInstanceCount",
        language: "urn:example:expression-language"
      },
      completionCondition: {
        body: "completedInstanceCount >= requiredInstanceCount",
        language: "urn:example:expression-language"
      },
      loopDataInputRef: "DataObjectReference_Input",  // optional ItemAwareElement ID
      loopDataOutputRef: "DataObjectReference_Output" // optional ItemAwareElement ID
    }
  }
}

服务器原样保留表达式体，并将其序列化为 BPMN FormalExpression 值。它不解析或求值这些表达式，因此请选择将执行导出图表的 BPMN 引擎所支持的语言/配置文件。循环数据引用必须标识现有的 BPMN ItemAwareElement 实例；portable 模式不会输出供应商特定的 collection 属性。portable BPMN 方言不会输出供应商特定的绑定或版本属性。

{
  activityType: "callActivity",
  name: "Invoke fulfillment",
  properties: { calledElement: "FulfillmentProcess" }
}

add_gateway

向当前图表添加用于分支逻辑的网关。

{
  gatewayType: "exclusive", // exclusive, parallel, inclusive, eventBased, complex
  name: "Payment Check",
  position: { x: 400, y: 200 } // optional
}

add_data_object

添加可见的 bpmn:dataObjectReference 及其关联的、不渲染的 bpmn:dataObject。集合状态属于底层对象。可选的 itemSubjectRef 必须标识现有的 bpmn:itemDefinition，例如从导入图表中加载的项。

{
  name: "Order records",
  position: { x: 400, y: 320 }, // optional reference position
  isCollection: true, // optional, defaults to false
  itemSubjectRef: "ItemDefinition_Order" // optional existing definition ID
}

数据输入/输出关联是活动拥有的 BPMN 构造，不由 add_association 创建，后者仍是通用工件关联。

add_text_annotation

添加 BPMN 文本注释。文本被原样保留，包括换行符和 XML 元字符。textFormat 默认为 BPMN 的 text/plain；位置和大小默认为引擎的注释几何。提供 associatedElementId 还会创建一条从注释到该元素的独立、无向 BPMN 关联。

{
  text: "Review the exception path\nbefore approval",
  textFormat: "text/markdown", // optional
  position: { x: 400, y: 320 }, // optional
  size: { width: 220, height: 80 }, // optional
  associatedElementId: "UserTask_1" // optional
}

connect

在当前图表中用顺序流连接两个元素。

{
  sourceId: "ExclusiveGateway_1",
  targetId: "UserTask_1",
  label: "Start Flow", // optional
  condition: "amount > 1000", // optional, for conditional sequence flows
  conditionLanguage: "FEEL", // optional
  conditionType: "bpmn:FormalExpression", // optional
  isDefault: false // optional; default flows cannot have conditions
}

活动和排他、包含或复杂网关支持条件和默认流。默认流不能同时具有条件。

add_association

在兼容的流程或协作范围内，在两个 BaseElement 之间添加 BPMN 关联工件。这与顺序流和消息流不同。associationDirection 默认为 BPMN 的 None 值。

{
  sourceId: "TextAnnotation_1",
  targetId: "UserTask_1",
  associationDirection: "One" // None, One, or Both
}

add_pool

向协作图表添加泳池（参与者）。

{
  name: "Customer",
  position: { x: 100, y: 100 }, // optional
  size: { width: 600, height: 250 }, // optional
  blackBox: false // optional; true creates a participant without an owned process
}

add_lane

向白盒泳池添加泳道，并将直接流程节点分配给它。已分配给其他泳道的节点将移动到新泳道。

{
  poolId: "Participant_1",
  name: "Sales Department",
  flowNodeIds: ["StartEvent_1", "UserTask_1"],
  position: "bottom" // optional
}

查询与操作工具

list_elements

列出当前图表中按 ID 排序的稳定元素和关联工件页面。使用 elementType: "bpmn:Association" 过滤，仅列出关联。

{
  elementType: "bpmn:Task", // optional filter
  limit: 100, // optional, defaults to 100; maximum 500
  offset: 0 // optional, defaults to 0
}

响应为 { count, returnedCount, offset, limit, hasMore, elements }。兼容性说明：分页封装取代了早期的裸数组响应；针对该契约编写的客户端现在必须读取 elements。现有元素字段保留其含义；可能还会出现额外的元数据字段和泳道条目。

get_element

获取特定元素或关联的详细信息。

{
  elementId: "UserTask_1"
}

update_element

更新元素属性。

{
  elementId: "UserTask_1",
  name: "Updated Task Name",
  properties: { assignee: "john.doe", candidateGroups: ["reviewers"] },
  defaultFlow: "Flow_2" // outgoing flow ID, or null to clear
}

delete_element

删除元素及其关联连接。传入关联 ID 仅删除该关联，其端点保持不变；删除端点（包括文本注释）会级联删除其关联。

{
  elementId: "Task_1"
}

实用工具

export

将当前图表导出为 BPMN 2.0 XML 或渲染的 SVG。

{
  format: "xml", // "xml" or "svg"; defaults to "xml"
  formatted: true // optional; applies to XML and defaults to true
}

XML 导出返回文本，不启动浏览器。SVG 导出通过 Puppeteer 启动无头浏览器，使用 bpmn-js 渲染，清理结果，并返回嵌入的 image/svg+xml 资源。它需要可用的 Chrome/Chromium 可执行文件，并保留 License 中所述的可见 bpmn.io 署名。

validate

验证当前图表结构。

{
  level: "full" // "syntax", "semantic", or "full"; defaults to "full"
}

验证级别是累积的。syntax 解析 XML 并解析引用；semantic 添加感知所有者的事件、流、子流程、泳道和协作规则；full 还添加可执行配置文件的开始/结束/连通性指导。

auto_layout

应用自动布局以定位当前图表中的元素。

{
  algorithm: "horizontal" // currently only horizontal is supported
}

布局在可终止的子进程中运行，默认预算为五秒。基于基准的预检最多接受 2,000 个元素、2,000 条连接和每个元素 10 条连接；超过任何限制的输入在布局前被拒绝。对于协作，每个参与者流程独立排序，因此消息流不会改变其顺序流顺序。自动布局会替换手动节点和容器坐标，但请求/导入的参与者和泳道尺寸仍为下限。泳池随后无重叠堆叠；泳道和所属节点保持包含关系，消息流仅在最终泳池放置后路由。断开连接的节点在其所属流程中确定性打包，嵌套子流程保留语义包含关系，黑盒参与者保持其请求的最小尺寸，不生成虚构的流程内容。

文件管理工具

list_diagrams

列出按文件名排序的已保存 BPMN 图表的稳定页面。

{
  limit: 100, // optional, defaults to 100; maximum 500
  offset: 0 // optional, defaults to 0
}

现有的 { count, diagrams, path } 响应字段仍然可用；returnedCount、offset、limit 和 hasMore 描述所选页面。仅读取所选页面上的文件以获取嵌入的 BPMN 元数据，默认情况下聚合元数据读取上限为 5 MiB。

delete_diagram_file

删除已保存的图表文件。

{
  filename: "old-process.bpmn"
}

get_diagrams_path

获取图表的存储路径。

{}

🔄 上下文管理

MCP-BPMN 服务器采用有状态设计，一次处理一个图表：

1. 创建或打开：先创建新图表（new_bpmn、new_from_mermaid）或打开现有图表（open_bpmn、open_mermaid_file）

2. 操作：所有操作（add_event、connect 等）都应用于当前图表

3. 保存：使用 save 或 save_as 保存工作

4. 关闭：使用 close 关闭当前图表

如果尝试在没有当前上下文的情况下执行操作，将收到有用的错误消息：

No current context. Please create a diagram first with:
  - new_bpmn(name) to create a new BPMN diagram
  - new_from_mermaid(name, mermaidCode) to convert from Mermaid
  - open_bpmn(filename) to open an existing BPMN file
  - open_mermaid_file(filename) to convert a Mermaid file

💡 示例

示例 1：从头创建审批流程

// Step 1: Create a new process (sets it as current context)
await new_bpmn({ name: "Approval Workflow" });

// Step 2: Add elements (all operations apply to current diagram)
await add_event({ eventType: "start", name: "Request Received" });
await add_activity({ activityType: "userTask", name: "Review Request" });
await add_gateway({ gatewayType: "exclusive", name: "Approved?" });
await add_activity({ activityType: "serviceTask", name: "Process Approval" });
await add_activity({ activityType: "userTask", name: "Handle Rejection" });
await add_event({ eventType: "end", name: "Complete" });

// Step 3: Connect elements
await connect({ sourceId: "StartEvent_1", targetId: "UserTask_1" });
await connect({ sourceId: "UserTask_1", targetId: "ExclusiveGateway_1" });
await connect({ sourceId: "ExclusiveGateway_1", targetId: "ServiceTask_1", label: "Yes" });
await connect({ sourceId: "ExclusiveGateway_1", targetId: "UserTask_2", label: "No" });
await connect({ sourceId: "ServiceTask_1", targetId: "EndEvent_1" });
await connect({ sourceId: "UserTask_2", targetId: "EndEvent_1" });

// Step 4: Apply auto-layout for proper positioning
await auto_layout();

// Step 5: Save and export the diagram
await save_as({ filename: "approval-workflow.bpmn" });
const xml = await export();

示例 2：从 Mermaid 引导（推荐以降低 Token 使用量）

// Step 1: Create from Mermaid syntax (much more concise!)
await new_from_mermaid({ 
  name: "Approval Workflow",
  extensionProfile: "camunda7",
  mermaidCode: `
    graph TD
      A((Request Received)) --> B[Review Request]
      B --> C{Approved?}
      C -->|Yes| D[Process Approval]
      C -->|No| E[Handle Rejection]
      D --> F((Complete))
      E --> F
  `
});

// Step 2: Apply auto-layout (Mermaid conversion includes basic layout)
await auto_layout();

// Step 3: Make additional edits if needed
await update_element({ 
  elementId: "UserTask_1", 
  properties: { assignee: "reviewer" }
});

// Step 4: Save and export
await save_as({ filename: "approval-workflow.bpmn" });
const xml = await export();

示例 3：处理多个图表

// Create first diagram
await new_bpmn({ name: "Process A" });
await add_event({ eventType: "start" });
await add_activity({ activityType: "task", name: "Task A" });
await save_as({ filename: "process-a.bpmn" });

// Create second diagram (automatically closes the first)
await new_bpmn({ name: "Process B" });
await add_event({ eventType: "start" });
await add_activity({ activityType: "task", name: "Task B" });
await save_as({ filename: "process-b.bpmn" });

// Go back to first diagram
await open_bpmn({ filename: "process-a.bpmn" });
await add_event({ eventType: "end" });
await save();

// Check current diagram info
const info = await current();
console.log(info); // Shows: { name: "Process A", filename: "process-a.bpmn", ... }

🗂️ 文件存储

BPMN 图表自动保存到本地文件系统：

• Unix/Linux/Mac：~/mcp-bpmn/

• Windows：%USERPROFILE%\mcp-bpmn\

通过环境变量自定义路径：

export MCP_BPMN_DIAGRAMS_PATH=/custom/path

资源限制可通过 MCP_BPMN_MAX_IMPORT_BYTES、MCP_BPMN_MAX_MERMAID_BYTES、MCP_BPMN_MAX_LAYOUT_ELEMENTS、MCP_BPMN_MAX_LAYOUT_CONNECTIONS、MCP_BPMN_MAX_LAYOUT_DENSITY、MCP_BPMN_MAX_LAYOUT_BYTES、MCP_BPMN_MAX_CONCURRENT_LAYOUTS、MCP_BPMN_MAX_LISTING_ITEMS、MCP_BPMN_MAX_LISTING_METADATA_BYTES 和 MCP_BPMN_LAYOUT_TIMEOUT_MS 调整。优雅关闭截止时间可通过 MCP_BPMN_SHUTDOWN_TIMEOUT_MS 覆盖。默认值为每个导入/布局输入和每个列表元数据页面 5 MiB、2,000 个布局元素/连接、密度 10、两个并发布局子进程、10,000 个列表候选和 5,000 毫秒。布局默认值来自本地稀疏/密集基准：2,000/1,999 约 1.4 秒完成，25/300 约 4.8 秒，26/325 超过五秒。

在 SIGINT、SIGTERM 或 stdin EOF 时，服务器停止接受工具调用，并允许已接受的操作及其原子持久化完成，然后关闭渲染器/布局子进程和 stdio 传输。优雅关闭有 15 秒的硬性截止时间；超过该时间将强制以非零状态退出。

新图表的文件名以 {ProcessId}_{ProcessName}.bpmn 开头。每个图表只有一个活动文件名：打开操作会采用打开的文件名，save_as 会在新文件成功写入后切换文件名。添加、更新、删除、连接和布局操作会序列化并原子化自动保存活动文件；序列化或写入失败时，内存和磁盘都会保持在最后一次成功状态。

🏗️ 架构

技术栈

• TypeScript - 类型安全的开发

• Node.js - 运行时环境

• MCP SDK - Model Context Protocol 实现

• Jest - 测试框架

核心组件

• SimpleBpmnEngine - 规范的 BPMN 文档变更、持久化和 XML 导出

• BpmnSvgRenderer - 隔离的、基于浏览器的 bpmn-js SVG 渲染

• DiagramContext - 当前图表的有状态上下文管理

• BpmnAutoLayoutV2Adapter - BPMN 自动布局集成

• BpmnRequestHandler - MCP 请求处理

• MermaidConverter - Mermaid 到 BPMN 的转换

• TypeMappings - BPMN 元素类型转换

• IdGenerator - 一致的 ID 生成

项目结构

mcp-bpmn/
├── src/
│   ├── core/           # Core BPMN engine
│   ├── server/         # MCP server implementation
│   ├── utils/          # Utilities (layout, ID generation)
│   ├── types/          # TypeScript type definitions
│   └── config/         # Configuration
├── tests/
│   ├── unit/          # Unit tests
│   ├── integration/   # Integration tests
│   └── e2e/           # End-to-end tests
├── dist/              # Compiled output
└── docs/              # Documentation

🧪 开发

可用脚本

npm run build        # Build TypeScript
npm run build:bundle # Build CommonJS bundle
npm run build:watch  # Build with watch mode
npm run check        # Complete clean contributor/CI quality gate
npm test            # Run source-level tests (no build output required)
npm run test:all    # Clean, build, and run every test including e2e
npm run test:unit   # Run unit tests only
npm run test:integration # Run integration tests only
npm run test:e2e    # Run end-to-end tests
npm run lint        # Run ESLint
npm run dev         # Development mode with hot reload
npm start           # Start the MCP server

测试

项目包含全面的测试覆盖。源码级命令不读取 dist/，因此旧构建不会影响其结果：

• 单元测试：核心功能测试

• 集成测试：处理器和工具测试

• 端到端测试：完整的 MCP 协议测试

使用以下命令运行测试：

npm test                    # Source-level tests
npm run test:all            # Clean build plus all tests
npm run check               # Complete clean contributor/CI quality gate
npm run test:coverage       # Source-level tests with coverage
npm run test:watch          # Source-level tests in watch mode

📈 性能

规范发布产物于 2026-08-22 使用 Node 25.9.0 和 npm 11.12.1 测量，使用：

npm pack --dry-run --json

该命令报告压缩后约为 195 kB，解压后为 1104270 字节。这些数字描述的是 npm 压缩包，而非已安装的服务器：该压缩包不捆绑任何生产依赖，而安装时会解析 package.json 中九个直接运行时依赖及其传递依赖。Puppeteer 管理的 Chrome 下载也不在压缩包测量范围内。请对当前产物重新运行该命令，而不是将此过时快照视为永久的大小保证。

可选的 CommonJS 捆绑包不是发布产物，不承担任何大小声明。布局输入限制以及用于选择其默认值的过时基准观测记录在文件存储下。

🐛 已知限制

• 创作 API 是聚焦的 BPMN 2.0 子集，而非完整的 BPMN 2.0 覆盖。不支持的导入结构可能被拒绝，而非无损编辑。

• connect 不提供直接的消息流创作。Mermaid 协作子集可以在子图之间创建消息流。

• add_lane 在白盒泳道池中创作顶层泳道；它无法扩展导入的嵌套泳道层级。

• 自动布局仅支持水平布局。垂直和径向算法不提供。

• 验证提供文档所述的语法、语义和完整指导级别；它不是 BPMN XSD 认证，也不是针对部署引擎的验证。

• Camunda 7 创作配置文件仅限于用户任务上的 assignee、candidateGroups 和 dueDate。它不是通用的 Camunda 建模器覆盖。

• SVG 导出需要通过 Puppeteer 使用 Chrome/Chromium，并且每个服务器实例只允许一个并发渲染。XML 工作流保持无浏览器。

• 服务器不执行、模拟或部署 BPMN 流程。

🚧 路线图

计划的工作和已知的缺口作为 Beads 问题跟踪，而非在本发布文档中承诺为已实现的功能。

🤝 贡献

欢迎贡献！请：

1. Fork 仓库

2. 创建功能分支（git checkout -b feature/amazing-feature）

3. 运行完整的质量门禁（npm run check）

4. 提交更改（git commit -m 'Add amazing feature'）

5. 推送到分支（git push origin feature/amazing-feature）

6. 打开 Pull Request

代码风格

• 严格模式的 TypeScript

• 提供 ESLint 配置

• 使用 Jest 进行测试

• 常规提交

📝 许可证

MIT 许可证 - 详情请参阅 LICENSE 文件。

SVG 导出使用 bpmn-js@17.11.1。每个导出的 SVG 都包含一个可见的、链接到 https://bpmn.io 的"Powered by bpmn.io"徽标；客户端不应裁剪、覆盖或移除该署名。有关该依赖的许可条款，请参阅 THIRD_PARTY_NOTICES.md，有关发布决策，请参阅 ADR 0002。

📞 支持

• 问题：GitHub Issues

• 文档：详细指南请参阅 /docs 文件夹

🙏 致谢

• 基于 Model Context Protocol 规范构建

• BPMN 标准受 bpmn-js 启发

• 感谢 Anthropic 团队对 MCP 的开发