ACTIWARE BLP (ELO Sidebar)

说明

English: 这是一个用于 ACTIWARE Business Logic Provider（BLP）的 MCP 服务，它是 ELO 侧边栏的设计器。它可以读取流程、业务对象、选项卡和磁贴、角色、选择树以及图像包，并通过两步预览/批准流程进行修改，同时自动备份、像 Designer 一样执行签出/提交，并在保存后进行检查。流程可以导出为 JSON 蓝图，并据此创建流程（新建、复制或替换）。发布仍需在 Designer 中手动完成。它是一个单独的 PowerShell 7 脚本，可由任何 MCP 客户端通过 stdio 启动。由于 BLP 的用户群主要位于 DACH 地区，文档使用德语；也欢迎用英语提交问题。

这是一个用于 BLP（ACTIWARE Business Logic Provider） 的 MCP 服务，也就是用来构建 ELO 客户端侧边栏的工具：选项卡、磁贴、流程、业务对象、角色。你可以用日常语言告诉 AI 你想做什么，例如：

• “会计选项卡有哪些磁贴，哪个流程关联到了‘发票’磁贴？”
• “在会计选项卡中创建一个‘催款’磁贴，仿照‘发票’磁贴，但使用‘录入催款’流程。”
• “按字母顺序排列采购区域的选择树。”
• “上传这三个图标，并将它们添加到新磁贴。”
• “构建一个流程：包含姓名和部门的表单，然后是一个判断步骤，接着调用 ELOas 规则 X。”

AI 会通过与 Web Designer 相同的 REST API 读取这些组件，并在每次更改前向你展示更改前后的内容，只有在你同意后才会执行更改。你需要自行在 Designer 中发布——在此之前，侧边栏不会看到任何更改。

概览

• **读取：**查看包含节点、构件名称和连接的流程；包含字段、填充规则和磁贴的业务对象；侧边栏选项卡、角色和场景、字段管理、数据查询、选择树、图片包以及发布状态。
• **有针对性地修改：**通过小型路径语言而非整个 JSON 文档进行修改——例如修改流程节点中的一个参数、磁贴颜色、某个角色中选项卡的可见性，或选择树中的顺序。
• **新建：**将现有流程复制为新流程、新建空白侧边栏选项卡、将磁贴复制为模板磁贴、创建业务对象（可创建带字段的空对象或复制现有对象）。
• **构建流程：**将流程导出为蓝图（包含构件名称的节点、已解包且易读的参数、连接），修改或重写蓝图，并据此构建新流程、复制流程或替换现有流程——同时检查起点、出口和可达性。
• **图片：**将 PNG 图标上传到图片包，关联到磁贴和选项卡，也可移除。
• **两步操作：**首次调用会返回检查结果、预览和批准码。只有使用相同参数进行第二次调用才会执行——有效期为 5 分钟、仅可使用一次，且仅当构件自那之后未发生更改时有效。
• **安全保障：**每次修改前都会备份；像设计器一样执行 checkout/commit；发生错误时执行 undo；保存后进行检查，并记录日志、屏蔽密码和 Token。默认情况下，生产环境仅可读取。
• **在同一服务中支持测试和生产环境：**使用 -Umgebung test,produktiv 时，每个工具都有 umgebung 参数；每个环境都有独立的登录信息和修改开关。
• **无需服务或安装：**一个 PowerShell 脚本，由你们的 MCP 客户端按需启动。此外，还提供可双击安装的 Claude Desktop 安装包。

兼容性

	已测试或要求
BLP	Business Logic Provider 6，包含 Web 设计器和 REST API（/api/v1/…）
账户	有权在 BLP 项目中编辑构件的账户。我们这边只有 BLP 自带的 admin 账户可用；Windows 账户即使拥有设计器权限，仍会收到“User is not authorized”
PowerShell	7.5 或更高版本（pwsh，因需使用 ConvertFrom-Json -DateKind），不支持 Windows PowerShell 5.1
系统	Windows：使用 DPAPI 加密凭据。其他系统通过 BLP_USER/BLP_PASSWORD 设置凭据，未经测试
MCP	stdio（JSON-RPC 2.0），协议版本 2025-06-18
AI 客户端	docs/CLIENTS.md 中提供 Claude Code、Claude Desktop、VS Code/GitHub Copilot、Cursor、Codex CLI 和 Gemini CLI 的模板

快速开始

A) 让 AI 帮你设置

克隆仓库或将 ZIP 解压到文件夹中，在该文件夹内启动 AI Agent（Claude Code、Codex CLI、Agent 模式下的 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，并显示环境、项目、用户以及是否已启用修改权限。

要在同一个条目中配置测试和生产环境，请追加 -Umgebung test,produktiv。之后每个工具都有 umgebung 参数；未指定时使用第一个环境。每个环境下的 allowChanges 会标明是否允许修改。要为第二个环境设置凭据，请运行：.\Set-BlpCredential.ps1 -Umgebung produktiv。

C) Claude Desktop：软件包

1. 从 Release 下载 blp-mcp-<version>.mcpb 并双击（或在 Claude Desktop 中选择 设置 → 扩展 → 高级设置 → 安装扩展）。
2. 在扩展设置中填写环境 1（例如测试环境）：Identity 服务及其端口和项目 ID。如果项目服务和客户端服务的端口分别比 Identity 服务高一个或八个，则留空（…01 → …02、…09）。可选填写环境 2（例如生产环境）。每个环境都有“启用更改”选项，默认关闭。
3. 启用扩展，然后向 AI 提问：“我在 BLP 中是谁？”如果缺少凭据，回答会给出准确的命令（pwsh -File "…\Set-BlpCredential.ps1" -Umgebung test）。每个环境都需要在控制台中手动运行一次该命令。或者，也可以在设置中选择现有的凭据文件。

该软件包每次启动时都会将设置写入 %LOCALAPPDATA%\blp-mcp\mcpb-config.json（不含机密信息）。仍需安装 PowerShell 7，并确保 pwsh 位于 PATH 中。

配置

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 有意覆盖，且只能用于单个环境
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）时，blp_change 使用 baustein: module，且 objekt = 模块名称。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 会显示查询及其路径；使用 blp_change 并设置 baustein: dataquery、objekt = 插件（SQL、GroupQueries 等）即可更改查询：

{ "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]	列表元素，必须恰好匹配一个	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]，可选地以第四个值添加注释。port 是构件的一个输出（output、output_true/output_false；对于开始节点则为 START）。
• **构建：**不带 prozess 时，根据蓝图在文件夹中创建新流程；带 name 时创建副本；带 prozess 时替换现有流程（名称和文件夹保持不变，现有节点保留其 ID）。可直接通过 datei 恢复备份文件。
• **保存前检查：**必须恰好有一个开始节点；每个构件和输出都必须存在；每个输出必须恰好有一个目标；所有节点都必须能从开始节点到达；参数必须是文本；列表中不能有 null；不能包含来自响应的掩码值（***）。保存后会将流程与蓝图进行比较。

格式、示例和注意事项：docs/USAGE.md。

安全

• **只在允许的范围内更改：**每个环境分别设置 allowChanges；模板中仅为测试环境启用。生产环境保持只读，直到有人有意开启更改权限。
• **未经批准不执行任何操作：**更改工具会先提供预览。批准码有效期为五分钟，只能使用一次，且仅适用于相同参数；构件的版本和时间戳未发生变化时才有效。
• **发布由人工负责：**服务无法发布。只有在 Designer 中发布后，侧边栏才会看到更改。
• **备份和日志：**每次更改前都将整个构件保存为 JSON；每次执行的参数和结果都会记录在日志中。
• **不回写掩码值：**包含 ***（来自掩码响应）的蓝图会被拒绝；要复制这类流程，请使用蓝图文件。
• **掩码处理：**包含 pass/pwd/secret/token/credential/apikey 的键（包括嵌入式 JSON 文本中的键），以及连接字符串中的 Password=…，在所有响应中都会被替换为 ***。
• **凭据：**使用 DPAPI 加密，仅自己的 Windows 帐户可读取。绝不放入配置或聊天中。
• 仅限自有服务：blp_get 只接受路径，不接受地址。
• 请勿将安全漏洞作为公开 Issue 报告；请按照 SECURITY.md 中的说明进行报告。

文档

文件	内容
AGENTS.md	AI Agent 的设置说明，包括故障排查
docs/CLIENTS.md	常见 MCP 客户端的配置条目
docs/USAGE.md	提示词示例和更改指南
docs/BLP-API.md	我们所了解的 Designer 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

参与贡献

欢迎提交 Issues 和 Pull Requests。请勿在 Issues 中发布包含主机名、项目 ID、用户名或令牌的日志；发布前请先进行脱敏。blp_change 的新组件请先在测试环境中验证，并在 Pull Request 中说明操作流程（checkout、保存、commit）。

许可证

MIT。由 herzog GmbH 为其自用的 ELO 侧边栏开发。非 ACTIWARE GmbH 或 ELO Digital Office GmbH 的官方产品；该接口未经官方文档说明，可能会随每个 BLP 版本发生变化。Business Logic Provider 是 ACTIWARE GmbH 的产品，ELO 是 ELO Digital Office GmbH 的商标。