ACTIWARE BLP (ELO Sidebar)

メモ

英語： ACTIWARE Business Logic Provider（BLP）用の MCP サーバーです。ELO サイドバーを設計するツールです。プロセス、ビジネスオブジェクト、タブとタイル、ロール、選択ツリー、画像パッケージを読み取り、自動バックアップ、Designer と同様のチェックアウト／コミット、保存後の検証を備えた、プレビューと承認の2段階フローで変更します。プロセスは JSON 設計図としてエクスポートでき、その設計図から新規作成、コピー、置換ができます。公開は Designer で手動で行います。任意の MCP クライアントが stdio 経由で起動する、単一の PowerShell 7 スクリプトです。BLP のユーザーの多くが DACH 地域にいるため、ドキュメントはドイツ語です。英語での issue も歓迎します。

多言語コンテキストプロトコル（MCP）サーバーです。BLP（ACTIWARE Business Logic Provider）、つまり ELO クライアントのサイドバーを構築するツールを操作します。タブ、タイル、プロセス、ビジネスオブジェクト、ロールを扱います。AI に普段の言葉で、たとえば次のように指示できます。

• 「Buchhaltung タブにはどのタイルがありますか？また、Rechnungen タイルにはどのプロセスが関連付けられていますか？」
• 「Buchhaltung タブに『Mahnungen』タイルを作成してください。『Rechnungen』タイルと同じにして、プロセスは『Mahnung erfassen』にしてください。」
• 「選択ツリーの Einkauf セクションをアルファベット順に並べ替えてください。」
• 「この3つのアイコンをアップロードして、新しいタイルに追加してください。」
• 「プロセスを構築してください。名前と部署の入力フォーム、続いて判断処理、最後に ELOas ルール X を呼び出します。」

AI は Web Designer と同じ REST API を使って構成要素を読み取り、変更の前に必ず変更前と変更後を表示します。皆さんが承認してから変更を適用します。公開は Designer で手動で行います。公開するまでは、サイドバーには何も反映されません。

概要

• 読み取る： ノード、ブロック名、接続を含むプロセス、フィールド、入力規則、タイルを含むビジネスオブジェクト、サイドバーのタブ、ロールと状況、フィールド管理、データクエリ、選択ツリー、画像パッケージ、公開状況。
• 対象を絞って変更する： JSON ドキュメント全体ではなく、小さなパス言語を使って変更します。たとえば、プロセスノードのパラメーター、タイルの色、ロールにおけるタブの表示、選択ツリー内の順序などです。
• 新規作成する： 既存のプロセスをコピーしてプロセスを作成、空のサイドバータブを作成、テンプレートタイルをコピーしてタイルを作成、ビジネスオブジェクトを作成（フィールド付きの空のオブジェクト、またはコピー）。
• プロセスを構築する： プロセスを設計図としてエクスポートします（ブロック名付きノード、読みやすく展開されたパラメーター、接続）。それを変更または新たに記述し、新しいプロセス、コピー、または既存のプロセスの置き換えを構築します。開始点、出力、到達可能性も検証します。
• 画像： PNG アイコンを画像パッケージに読み込み、タイルやタブに関連付け、後から削除します。
• 2 段階方式： 最初の呼び出しで検証結果、プレビュー、承認コードが返されます。同じ引数で 2 回目の呼び出しを行うと、初めて実行されます。承認コードの有効期限は 5 分で、1 回のみ使用でき、以降にブロックが変更されていない場合に限り有効です。
• 安全対策： 変更の前に毎回バックアップを取り、Designer と同様に checkout/commit を行い、エラー時には undo を実行し、保存後に確認します。ログを記録し、パスワードとトークンをマスキングします。本番環境はデフォルトで読み取り専用です。
• テスト環境と本番環境を 1 つのサーバーで利用： -Umgebung test,produktiv を指定すると、すべてのツールに umgebung パラメーターが追加されます。各環境には個別のログイン情報と変更用のスイッチがあります。
• サービス不要、インストール不要： MCP クライアントが必要に応じて起動する PowerShell スクリプトです。Claude Desktop 向けには、ダブルクリックで使えるパッケージも用意されています。

互換性

	テスト済み、または前提条件
BLP	Business Logic Provider 6 と Web Designer および REST API（/api/v1/…）
アカウント	BLP プロジェクトでブロックを編集できるアカウント。こちらでは BLP 専用の admin だけが使用できました。Windows アカウントは Designer の権限があっても「User is not authorized」と表示されました
PowerShell	7.5 以降（ConvertFrom-Json -DateKind を使用するため pwsh が必要）。Windows PowerShell 5.1 は対象外です
システム	Windows：認証情報を DPAPI で暗号化。他のシステムでは BLP_USER/BLP_PASSWORD を使用しますが、テストしていません
MCP	stdio（JSON-RPC 2.0）、プロトコルバージョン 2025-06-18
AI クライアント	Claude Code、Claude Desktop、VS Code/GitHub Copilot、Cursor、Codex CLI、Gemini CLI 用のテンプレートは docs/CLIENTS.md にあります

クイックスタート

A) AI にセットアップを任せる

リポジトリをクローンするか ZIP を展開し、そのフォルダーで AI エージェント（Claude Code、Codex CLI、エージェントモードの GitHub Copilot、Gemini CLI、Cursor など）を起動して、次のように入力します。

Richte diesen BLP-MCP-Server auf diesem Rechner ein. Folge AGENTS.md Schritt für Schritt
und frag mich nie nach Passwörtern im Chat.

AGENTS.md に手順全体とトラブルシューティングが記載されています。Claude Code（CLAUDE.md）、Gemini CLI（GEMINI.md）、GitHub Copilot（.github/copilot-instructions.md）向けの参照ファイルも用意されています。

B) 手動で設定する

1. 設定を作成し、アドレスを入力します（各環境の Identity、プロジェクトサービス、クライアントサービス）。

   Copy-Item config.example.json config.local.json
   notepad config.local.json
   

2. 認証情報を登録します。 スクリプトがユーザー名とパスワードを尋ねて暗号化して保存し、ログイン後、プロジェクトとその ID を表示します。正しい ID を config.local.json の projectId に設定してください。

   .\Set-BlpCredential.ps1
   

3. MCP クライアントに登録します。 たとえば Claude Code の場合：

   claude mcp add blp --scope user -- pwsh -NoProfile -NoLogo -NonInteractive -File "C:\Tools\blp-mcp\blp-mcp.ps1"
   

4. テストします：「BLP での自分のユーザー情報は？」と尋ねます。AI が blp_whoami を呼び出し、環境、プロジェクト、ユーザー、変更が許可されているかどうかを表示します。

テスト環境と本番環境を 1 つのエントリで設定するには、-Umgebung test,produktiv を追加します。各ツールに umgebung パラメーターが追加され、省略した場合は最初の環境が使われます。変更が許可されているかどうかは、各環境の allowChanges で設定します。2 つ目の環境の認証情報を登録するには、.\Set-BlpCredential.ps1 -Umgebung produktiv を実行します。

C) Claude Desktop：パッケージ

1. リリースからblp-mcp-<version>.mcpbをダウンロードしてダブルクリックします（またはClaude Desktopで設定 → 拡張機能 → 詳細設定 → 拡張機能をインストールを選択します）。
2. 拡張機能の設定で環境 1（例：テスト）を入力します：ポートとプロジェクト ID を指定したIdentityサービスです。プロジェクトサービスとクライアントサービスがIdentityサービスよりそれぞれ1つまたは8つ大きいポートを使う場合（…01 → …02、…09）、これらは空欄のままにします。任意で環境 2（例：本番）も設定できます。「変更を許可」は環境ごとに設定でき、初期状態では無効です。
3. 拡張機能を有効にして、AI に「BLP では私は誰ですか？」と尋ねます。認証情報が見つからない場合、回答に正確なコマンド（pwsh -File "…\Set-BlpCredential.ps1" -Umgebung test）が表示されます。このコマンドは、環境ごとに1回、自分でコンソールから実行します。または、設定で既存の認証情報ファイルを選択します。

このパッケージは、起動するたびに設定を%LOCALAPPDATA%\blp-mcp\mcpb-config.jsonに書き込みます（秘密情報は含まれません）。引き続き、PowerShell 7と、PATHに含まれるpwshが必要です。

設定

config.local.jsonはblp-mcp.ps1と同じ場所に置きます（または-ConfigかBLP_MCP_CONFIGでパスを指定します）。説明付きのテンプレートはconfig.example.jsonです。

キー	意味
environments.<name>	環境ごとのauthUrl（Identity）、projectUrl（プロジェクトサービス）、clientUrl（クライアントサービス）、projectId、credentialFile、allowChanges、任意のlabelとskipCertificateCheck
defaultEnvironment	起動オプションを指定しない場合の環境。他の環境は-Umgebung <name>で、複数の環境は-Umgebung test,produktivで指定します
allowChanges	変更を行うツールを有効にします（テンプレートの既定値：テストは有効、本番は無効）。-AendernErlaubenで上書きできるのは、意図的に指定した場合のみで、環境を1つ指定した場合に限ります
skipCertificateCheck	コンピューターが認識しない自己署名証明書の場合にのみ使用します
images	画像パッケージ名、独自のアイコンフォルダー（<farbe>\<motiv>_<24|32|64>.png）、および各コンテナーに対応する色
organization、extraInstructions	AI への指示に表示されます（会社、社内ルール）
dataDir	バックアップ、ログ、エクスポートした設計図の保存フォルダー。既定値は%LOCALAPPDATA%\blp-mcpです

認証情報は設定ファイルには決して保存されません。Set-BlpCredential.ps1で作成するDPAPIファイル、またはBLP_USER／BLP_PASSWORDに保存されます。

ツール

読み取り

ツール	目的
blp_whoami	環境、プロジェクト、ユーザー、デザイナー権限、変更が有効になっているか
blp_processes	すべてのプロセスをフラットに表示（サーバー、クライアント、サブ、テンプレート）。フォルダー、バージョン、最終変更日時を含む。フィルター対応
blp_process	ノード（ブロック名、説明、短縮したパラメーター）と接続を含むプロセス。knoten = 入出力を含むノードの全パラメーター、roh = JSON 全体
blp_objects / blp_object	ビジネスオブジェクト。詳細にはフィールド、入力規則、検索、タイルを含む
blp_tabs / blp_tab	サイドバーのタブ。詳細にはすべてのタイル（アクション、プロセス、色、表示設定、条件）を含む
blp_roles	タブの有効・無効設定を含むロールと状況。rolle を指定すると、タブごとのタイルを表示
blp_fields	フィールド管理：パラメーター、変数、データフィールド
blp_dataqueries	データクエリ（名前、モジュール、条件フィールドと結果フィールド。接続情報は含まない）
blp_dataquery	内容を含むデータクエリ：SQL テキスト、フィールドマッピング、スイッチ、ソース、ログインプロファイル（SQL/OleDb）、サブクエリ、列（GroupQueries）。変更用パスを含む。abfrage を指定しない場合は、アドインごとの概要を表示。接続文字列は非表示
blp_selection	クライアントの選択ツリー（client/selection）：領域 › ドキュメント › プロセス › フィールド。各領域がソートされているかも表示
blp_images	画像パッケージ：画像を含むコンテナー。bild を指定すると、画像の使用箇所も表示
blp_published	クライアントサービスでの最終公開日時
blp_read_path	パスの値を読み取る（変更の準備用）
blp_get	プロジェクトサービスまたはクライアントサービスに対する任意の読み取り GET（パスのみ。外部アドレスは不可）
blp_process_export	プロセスを設計図として出力（JSON）。大きな設計図はファイルとして出力。prozess を指定しない場合は、各出力を含むブロックの一覧（すべてのモジュールのプロセッサー）を表示
blp_modules	ソフトウェアバージョンとプロジェクト内のモジュール設定を含むモジュール（バージョン、最終変更日時、パラメーターキーとサイズ、ロック）
blp_module	モジュールの設定。埋め込み JSON を展開して表示。Validation（ドキュメントタイプ、ブロック、フィールド、ルール）と AI.Foundation（プロンプト、モデルプロファイル、プロバイダー）は簡易表示。それ以外は階層構造で表示。voll = すべて。大きな設定はファイルとして出力（マスク済み）

サーバーは名前を柔軟に検索します：ID、完全一致する名前または表示テキスト、次に「名前（追加情報）」、最後に名前の一部。複数の一致がある場合は一覧を返します。

変更（二段階）

ツール	目的
blp_change	ブロックを指定して変更：{pfad, wert, aktion} のリスト。processengine、objectmanager、client/sidebar/tab/action、smartsearch、role、client/selection、module（モジュール設定を参照）、dataquery（データクエリを参照）が対象
blp_module_restore	モジュール設定またはアドインのデータクエリのバックアップを復元（復元前の状態もバックアップされます）
blp_create_process	既存のプロセスをコピーして新しいプロセスを作成。コピーへのパス変更は任意
blp_create_tab	空のサイドバータブを新規作成
blp_add_tile	テンプレートタイル（アクション、画像、色）をコピーして、タブまたはビジネスオブジェクトに新しいタイルを追加。独自の名前と変更内容を指定
blp_process_build	設計図からプロセスを構築：新規作成、別名でコピー（name）、または既存のものと置き換え（prozess）。バックアップの復元も可能
blp_create_object	ビジネスオブジェクトを新規作成。felder を指定して空のオブジェクトを作成するか、vorlage をコピー（フィールド、入力規則、検索を含む。タイルは含まない）
blp_image_upload	PNG を画像パッケージに読み込み、タイル（24/32/64 px）またはタブ（24 px）に同時に設定することも可能
blp_image_remove	コンテナーから画像を取り除く。使用中の画像がある場合は拒否されます。endgueltig を指定するとファイルも削除

意図的に対象外：公開、ブロック全体の削除。

モジュールの設定

プロジェクト内のモジュール（module/<Modul-ID>、例：Validation、AI.Foundation、AI OCR、PDF-Processor、elo）の設定は、baustein: module と objekt = モジュール名を指定して blp_change で変更します。parameters 以下の値はテキスト形式の JSON なので、# を使って中に入ります。

{ "baustein": "module", "objekt": "Validation",
  "aenderungen": [ { "pfad": "parameters/Module.Document.Processing.Config/#/validatorConfig/documentTypes/[key=purchase_invoice_data_f2v]/displayName", "wert": "Eingangsrechnung" } ] }

ほかのコンポーネントとは異なり、次の点に注意してください。

• checkout も undo もありません。 保存すると、すぐに確定されます（新しいメインバージョン）。その前にサーバーがバックアップを作成します。このファイルを使って blp_module_restore を実行すると、元に戻せます。
• 設定はプロジェクト全体に適用されるため、そのモジュールを使用するすべてのプロセスに影響します。
• *** を含む値は拒否されます。マスクされた応答を書き写して戻すと、認証情報やキーが破損するためです。変更箇所だけを含めるよう、パスをできるだけ限定してください。
• 大文字と小文字だけが異なるキーを持つ設定（例：Office）は blp_module で表示できますが、変更はデザイナーでのみ行えます。

データクエリ

SQL、OleDb、グループクエリ（および IX Query、OData、SAP SOAP アドインのクエリ）はモジュール設定ではなく、各アドインの dataquerymanager/<Modul-ID>/<Add-in-ID> にあります。blp_dataquery でパスを含むクエリを表示できます。baustein: dataquery と objekt = アドイン（SQL、GroupQueries、…）を指定して blp_change を実行すると、クエリを変更できます。

{ "baustein": "dataquery", "objekt": "SQL",
  "aenderungen": [ { "pfad": "parameters/Module.DataConnect.DataQuery.SQL.Config/#/Sources/[Name=ERP-Database]/DataQueries/[Name=ERP_Customer]/DataQueryString", "wert": "SELECT ..." } ] }

モジュール設定と同様、checkout と undo はありません。事前にバックアップが作成され、blp_module_restore で元に戻せます。*** を含む値は拒否されます。変更した SQL クエリは、それを使用するすべてのグループクエリとプロセスに反映されます（グループクエリは blp_dataquery に表示されます）。認証情報はログインプロファイルを通じて Credential Store に紐づけられており、ここで表示または変更されることはありません。

変更の流れ

Du:   Mach im Tab Buchhaltung die Kachel „Rechnungen“ grün.
KI:   (blp_change ohne freigabe)
      Vorschau – noch nichts geändert
      Tab Buchhaltung v3.0, Pfad tiles/[name=Rechnungen]/layout/color_id
      bisher "SkyBlue" → neu "Green"
      Wirksam erst nach Veröffentlichen im Designer. Soll ich?
Du:   Ja.
KI:   (blp_change mit denselben Argumenten + freigabe)
      Ausgeführt: v3.0 → v4.0, Kontrolle: alle Werte wie gewünscht.
      Sicherung: %LOCALAPPDATA%\blp-mcp\sicherung\client_sidebar_tab_action-…-vorher.json

実行時は、コンポーネントを読み取る → JSON としてバックアップする → checkout → 作業コピーを変更する → 検証する（リスト内に null がないこと、プロセスパラメーターがテキストのみであること）→ 保存する → commit → 再読み込みして各パスを確認する、という手順になります。checkout 後に問題が発生した場合、undo で作業コピーを破棄します。すべての実行は %LOCALAPPDATA%\blp-mcp\protokoll-JJJJ-MM.jsonl に記録されます。

パスの書式

/ で区切るセグメント：

セグメント	意味	例
名前	プロパティ（ピリオドも名前の一部です）	nodes、parameters、Module.Elo.ActionNode.EloAs
数字	リストのインデックス	tiles/0
[feld=wert]、[feld^=anfang]	リスト要素。該当する要素が1つだけの場合	tiles/[tile_id^=f8d0]、selections/[name=Einkauf]
[=wert]、[^=anfang]	値のみのリストの要素	tiles_order/[^=f8d0]
#	埋め込み JSON テキストの中に入る（パラメーター値はテキスト形式の JSON です）	…/Module.Core.Action.ProcessStarter.Config/#/ProcessName
-	新しいリスト要素（aktion: anhaengen を指定）	selections/[name=Einkauf]/childs/-

アクション：setzen（既定）、anhaengen、entfernen、sortieren（指定したパスのリストを de-DE の規則でアルファベット順に並べ替えます。wert でフィールドを指定し、既定値は display_text です）。

{ "baustein": "processengine", "objekt": "Rechnung prüfen",
  "aenderungen": [ { "pfad": "nodes/[id^=1a2b3c4d]/parameters/Module.Elo.ActionNode.EloAs/#/AsDefinitions/0/RuleSetName",
                     "wert": "Rechnung_pruefen_v2" } ] }

タブをロール内で非表示にする、選択ツリーにドキュメントを追加する、タイルを削除するなどの例は、docs/USAGE.md を参照してください。

設計図

大規模な再構築やまったく新しいプロセスを作成する場合、AI はパスではなく、プロセス全体を設計図として扱います。blp_process_export で設計図を取得し、blp_process_build でそこから構築します。

{ "name": "Gutschrift prüfen", "ordner": "Logik",
  "knoten": [
    { "key": "start", "baustein": "Start", "x": 0, "y": 0 },
    { "key": "frage", "baustein": "Decision", "x": 0, "y": 150,
      "parameter": { "Module.Core.Decision.Config": { "Content": "\"[VAR.Betrag]\" != \"\"" } } },
    { "key": "regel", "baustein": "ELO Direct - Start AS Task", "x": 0, "y": 300, "parameter": { "…": "…" } },
    { "key": "stopp", "baustein": "Abort Process (deprecated)", "x": 300, "y": 300, "parameter": { "…": "…" } } ],
  "verbindungen": [ ["start", "START", "frage"], ["frage", "output_true", "regel"], ["frage", "output_false", "stopp"] ] }

• ノード： key（短く、一意。エクスポートではノード ID の先頭部分が使われます）、baustein（プロセッサーの表示名。prozess を指定せずに blp_process_export を実行すると一覧を取得できます）、beschreibung、位置 x／y、展開済みの埋め込み JSON を含む parameter、felder（出力フィールド。例：入力フォームのフィールド名）。
• 接続： [von, port, nach]。4 つ目の値としてコメントを付けることもできます。port はブロックの出力です（output、output_true／output_false、開始ノードでは START）。
• 構築： prozess を指定しない場合は設計図から新規にフォルダーを作成します。name を指定するとコピーを作成し、prozess を指定すると既存のプロセスを置き換えます（名前とフォルダーはそのまま維持され、既存のノード ID も維持されます）。バックアップファイルは datei として直接復元できます。
• 保存前のチェック： 開始ノードは 1 つだけであること、すべてのブロックと出力が存在すること、各出力の接続先が 1 つだけであること、すべてのノードに開始ノードから到達できること、パラメーターがテキストであること、リストに null がないこと、応答から取得したマスク済みの値（***）がないことを確認します。保存後、プロセスと設計図を比較します。

形式、例、注意点については、docs/USAGE.md を参照してください。

セキュリティ

• 許可された場所でのみ変更： 環境ごとに allowChanges を設定します。テンプレートではテスト環境にのみ設定します。本番環境は、人が明示的に許可するまで読み取り専用です。
• 承認なしでは変更しない： 変更を行うツールは、まずプレビューを返します。承認コードの有効期間は 5 分間で、1 回限り使用でき、同じ引数の場合に限り、ブロックのバージョンとタイムスタンプが変更されていない間のみ有効です。
• 公開は人が行う： サーバーから公開することはできません。デザイナーで公開した後にのみ、サイドバーに変更が反映されます。
• バックアップとログ： 変更前にブロック全体を JSON として保存し、実行ごとに引数と結果をログに記録します。
• マスク済みの値は書き戻さない： ***（マスク済みの応答から取得した値）を含む設計図は拒否されます。このようなプロセスのコピーには、設計図ファイルを使用してください。
• マスキング： pass／pwd／secret／token／credential／apikey を含むキー（埋め込み JSON テキスト内も含む）と、接続文字列内の Password=… は、すべての応答で *** に置き換えられます。
• 認証情報： DPAPI で暗号化され、本人の Windows アカウントでのみ読み取れます。設定ファイルやチャットには絶対に含めないでください。
• 自分のサービスのみ： blp_get が受け付けるのはパスのみで、アドレスは受け付けません。
• セキュリティ上の脆弱性は公開 Issue として報告せず、SECURITY.md の説明に従って報告してください。

ドキュメント

ファイル	内容
AGENTS.md	AI エージェント向けのセットアップ（トラブルシューティングを含む）
docs/CLIENTS.md	主要な MCP クライアントすべてへの登録方法
docs/USAGE.md	プロンプトの例と変更手順
docs/BLP-API.md	デザイナー API について把握している内容：エンドポイント、checkout／commit、特性と注意点
config.example.json	コメント付きの設定例
SECURITY.md	セキュリティ上の脆弱性を非公開で報告する方法

開発

サーバーは、blp-mcp.ps1（プロトコル、ログイン、読み取りツール）と、ドットソーシングで読み込まれるファイル blp-mcp-konfig.ps1、blp-mcp-aendern.ps1（パス言語、変更、新規作成）、blp-mcp-bilder.ps1（画像パッケージ）、blp-mcp-bauen.ps1（ビルドプラン、ビジネスオブジェクトの作成）、blp-mcp-module.ps1（モジュール設定、データクエリ）で構成されています。MCP クライアントを使わずにテスト実行する場合：

python -I test-blp-mcp.py beispiel-aufrufe.json

MCP_ARGS はスイッチをサーバーに渡します（例：-Umgebung test,produktiv）。MCP_TEST_LIMIT は出力を短縮します。変更を伴う呼び出しはペアで行います。最初は freigabe なしで呼び出し、その後 "freigabe": "$TOKEN"（＝直前のプレビューのコード）を指定して呼び出します。コードを変更した後は、クライアントでサーバーを再読み込みしてください。

Claude Desktop 用のパッケージをビルドします（mcpb\manifest.json、blp-mcp.ps1、CHANGELOG.md のバージョンを確認し、SHA-256 とダウンロードアドレスを server.json に記録します）：

pwsh -NoProfile -File tools\build-mcpb.ps1

コントリビュート

Issue とプルリクエストを歓迎します。Issue には、ホスト名、プロジェクト ID、ユーザー名、トークンを含むログを決して投稿しないでください。投稿前に必ずマスキングしてください。blp_change 用の新しいコンポーネントは、まずテスト環境で試し、手順（チェックアウト、保存、コミット）をプルリクエストに記載してください。

ライセンス

MIT。herzog GmbH が自社の ELO サイドバー向けに開発しました。ACTIWARE GmbH または ELO Digital Office GmbH の公式製品ではありません。このインターフェースは公式に文書化されておらず、BLP の各バージョンで変更される可能性があります。Business Logic Provider は ACTIWARE GmbH の製品であり、ELO は ELO Digital Office GmbH の商標です。