MCP-BPMN サーバー

テスト済みのBPMN 2.0オーサリングサブセットのためのModel Context Protocol (MCP) サーバー。Mermaid変換、ローカル永続化、レイアウト、検証、XMLまたはSVGエクスポートを含みます。

🎯 概要

MCP-BPMNは、AIアシスタントが一度に1つのビジネスプロセス図を操作するためのステートフルなインターフェースを提供します。以下にリストされた構成要素に対して、整形式のBPMN 2.0 XMLを作成します。これは完全なBPMN 2.0エディタ、実行エンジン、またはデプロイメントクライアントではありません。ポータブルなBPMNコアがデフォルトのオーサリング契約であり、オプトインの型付きCamunda 7プロファイルはADR 0001に文書化されています。

主な機能

• 焦点を絞ったBPMNオーサリング: サポートされるイベント、アクティビティ、ゲートウェイ、データオブジェクト、注釈、プール、トップレベルレーン、シーケンスフロー、および関連付け

• Mermaid変換: 文書化されたフローチャートサブセットから図をブートストラップ

• 水平自動レイアウト: 決定的なプロセスおよびコラボレーション配置

• ローカル永続化: 設定されたディレクトリ内で図を原子的に保存および再オープン

• XMLおよびSVGエクスポート: XMLはプロセス内で生成され、SVGはPuppeteerとbpmn-jsを通じてレンダリングされます

• ポータブルおよびCamunda 7プロファイル: デフォルトでベンダーフリーの出力。明示的に選択された場合、3つの型付き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レンダリングはヘッドレスで、サーバーインスタンスごとに1つの同時レンダリングに制限され、20秒のレンダリングタイムアウトがあります。

ソースチェックアウトから実行

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

npm run buildは、正規のESM実行可能ファイルをdist/server/index.jsに生成します。サーバーは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

パッケージ化されたリリースアーティファクトのインストール

このリポジトリは現在、mcp-bpmn-serverが公開npmレジストリから利用可能であると仮定するのではなく、npm tarballインストールを文書化しています。リリースプロデューサーは、ソースチェックアウトから正規の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で明示的に置き換えが要求されない限り保持されます。1つのクライアントを対象にし、既存のインストールを更新し、または図を保持しながらアンインストールするには:

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

PREFIXを設定してプログラム場所を変更し、MCP_BPMN_DIAGRAMS_PATHを使用して異なる絶対図ディレクトリを使用します。プリビルドされたリリースtarballは、MCP_BPMN_PACKAGE_TARBALLとその必須のMCP_BPMN_PACKAGE_SHA256の両方を設定することで再現可能にインストールできます。完全なインターフェースについては./scripts/install-agent-integrations.sh --helpを実行してください。インストーラーはmacOSとLinuxをサポートしており、LinuxネイティブのNode.jsとクライアントCLIを備えたWSLも含みます。

Codexプラグインをローカルで開発

リリースアーティファクトはCodexプラグインでもあります。そのマニフェストは、正規のskills/bpmn-modelerスキルを発見し、プラグインキャッシュにコピーされたランチャーを通じて1つの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

実際のCodex設定を変更せずに、分離されたマーケットプレイス、キャッシュ、ディスカバリ、MCP起動、および削除のスモークテストを実行します:

npm run test:codex-plugin

Claude Codeプラグインをローカルで開発

リリースアーティファクトはClaude Codeプラグインでもあります。Claudeは、正規のskills/bpmn-modeler/SKILL.mdを名前空間付きの/mcp-bpmn:bpmn-modelerスキルとして発見し、プラグインキャッシュからインラインのmcp-bpmnサーバーを起動します。プラグインはskills/を使用します。レガシーのcommands/コピーは含まれません。

ソースチェックアウトから、依存関係をインストールし、ビルドし、検証し、1つの開発セッションのためにプラグインをロードします:

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に安全です: アクティベーション境界、スキルメタデータ、ツール名、クライアントパリティ、およびcreate/mutate/validate/layout/validate/exportシーケンスをモデルを呼び出さずに検証します:

npm run test:evaluations

認証済みモデル実行はオプトインです。まずビルドし、反復中に1つの境界ケースを選択します:

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

Codexアダプターは、正規のスキルとプロジェクトスコープのstdio MCP設定を含む一時プロジェクトでcodex execを実行します。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は、一度に1つの図を操作するステートフル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

Mermaidコードから新しいBPMNダイアグラムを作成し、現在のコンテキストとして設定します。

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

Mermaid変換は、意図的に焦点を絞ったフローチャートのサブセットをサポートしています:

サブグラフが存在する場合、すべてのノードは正確に1つのトップレベルサブグラフに属している必要があります。ネストされたサブグラフとデータノードへのシーケンスフロー接続は、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です。ポータブルモードは3つのベンダーフィールドを拒否し、ベンダーネームスペースを出力しません。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インスタンスを識別する必要があります。ポータブルスキーマはベンダー固有のcollection属性を出力しません。 ベンダー固有のバインディングまたはバージョン属性は、ポータブル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_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

現在のダイアグラムで2つの要素をシーケンスフローで接続します。

{
  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

互換性のあるプロセスまたはコラボレーションスコープ内の2つの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実行可能ファイルが必要であり、ライセンスで説明されている可視の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
}

レイアウトは、デフォルトの5秒の予算で強制終了可能なサブプロセスで実行されます。ベンチマーク由来の事前チェックは、最大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つのダイアグラムを操作するステートフルな設計を使用しています:

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からブートストラップする（トークン使用量を抑えるのに推奨）

// 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、2つの同時レイアウトサブプロセス、10,000のリスト候補、5,000 msです。レイアウトのデフォルトはローカルのスパース/デンスベンチマークに由来します: 2,000/1,999は約1.4秒で完了し、25/300は約4.8秒かかり、26/325は5秒を超えました。

SIGINT、SIGTERM、またはstdin EOFで、サーバーはツール呼び出しの受け入れを停止し、受け入れられた操作とその原子的な永続化が、レンダラー/レイアウトサブプロセスとstdioトランスポートを閉じる前に完了することを許可します。グレースフルシャットダウンにはハードな15秒の期限があり、それを超えると非ゼロの終了コードが強制されます。

新しいダイアグラムは、ファイル名 {ProcessId}_{ProcessName}.bpmn で始まります。各ダイアグラムにはアクティブなファイル名が1つだけあります。開く操作は開いたファイル名を採用し、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/ を読み取らないため、古いビルドが結果に影響することはありません。

• ユニットテスト: コア機能のテスト

• 統合テスト: ハンドラーとツールのテスト

• E2E テスト: 完全な 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 の9つの直接ランタイム依存関係とその推移的依存関係が解決されます。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 を必要とし、サーバーインスタンスごとに1つの同時レンダリングのみを許可します。XML ワークフローはブラウザ不要のままです。

• サーバーは BPMN プロセスを実行、シミュレート、またはデプロイしません。

🚧 ロードマップ

計画された作業と既知のギャップは、このリリースドキュメントで実装された機能として約束されるのではなく、Beads の問題として追跡されます。

🤝 貢献

貢献を歓迎します！ 以下の手順に従ってください:

1. リポジトリをフォークする

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. プルリクエストを開く

コードスタイル

• 厳格モードの TypeScript

• ESLint 設定が提供されています

• Jest を使用したテスト

• Conventional commits

📝 ライセンス

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 に触発されました

• MCP 開発に協力してくれた Anthropic チームに感謝します