Decision MCP Server

IBM ODM决策MCP服务器文档

概述

IBM ODM决策MCP服务器将IBM ODM与现代AI助手和编排平台连接起来。\ 它使您能够：

• 将决策作为AI助手的工具公开
• 在工作流中动态自动化决策
• 轻松与Watson Orchestrate、Claude Desktop和Cursor AI集成
• 将业务逻辑集中并公开给最终用户和机器人

______________________________________________________________________

特性

• 工具集成： 添加和调用ODM决策（也称为规则集）作为工具
• 决策存储： 使用本地存储系统管理资源
• 身份验证： Zen API密钥、基本验证和OpenID连接
• 多平台： 与Watson Orchestrate、Claude Desktop和Cursor AI配合使用

______________________________________________________________________

快速入门：Claude桌面集成

有关设置和使用Claude Desktop与决策MCP服务器的详细说明，请参阅 Claude桌面集成指南.

演示视频

观看我们的演示视频，了解Claude Desktop集成的实际情况：

https://github.com/user-attachments/assets/53e9f887-6972-40d9-81c0-51dd4b31b165

IBM Watsonx编排集成

得益于决策MCP服务器，IBM Watson x Orchestrate可以通过在IBM运营决策管理器（ODM）中实施的决策来增强。

有关详细说明，请参阅 IBM Watson编排集成指南.

______________________________________________________________________

先决条件和安装

先决条件

• Python 3.13或更高版本 -此MCP服务器是用Python编写的，需要Python 3.13+
• 紫外线 -一个快速的Python包安装程序和解析器（推荐）

安装uv

运行决策MCP服务器的最简单方法是使用 uv，它处理包的安装和执行：

macOS和Linux：

curl -LsSf https://astral.sh/uv/install.sh | sh

窗户：

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

替代方案（通过pip）：

pip install uv

有关更多安装选项，请参阅 紫外线文件.

运行服务器

曾经 uv 安装后，您可以直接运行决策MCP服务器，而无需手动安装：

uvx --from git+https://github.com/DecisionsDev/ibm-odm-decision-mcp-server start --url http://localhost:9060/res

这 uvx 命令自动执行：

• 下载并安装软件包
• 管理依赖关系
• 运行服务器

______________________________________________________________________

配置

1.ODM容器环境和身份验证

根据您的IBM ODM部署，使用适当的身份验证/授权方法：

1.1. Cloud Pak上的业务自动化ODM

• 环境： 商业自动化云包（CP4BA）
• 身份验证： Zen API密钥

- CLI： --zenapikey - 环境： ZENAPIKEY=

1.2. Kubernetes上的ODM

• 环境： 部署在Kubernetes上的IBM ODM（包括OpenShift）
• 身份验证：

- 基本身份验证： - CLI： --username --password - 环境： ODM_USERNAME= ODM_PASSWORD= - OpenID连接（使用客户端密码）： - CLI： --client-id --client-secret --token-url 并且可选 --scope - 环境： CLIENT_ID= CLIENT_SECRET= TOKEN_URL= 并且可选 SCOPE= - OpenID连接（使用私钥JWT）： - CLI： --client-id --pkjwt-key-path --pkjwt-cert-path --token-url 并且可选 --scope 和 --pkjwt-key-password 如果私钥受密码保护。 - 环境： CLIENT_ID= PKJWT_KEY_PATH= PKJWT_CERT_PATH= TOKEN_URL= 并且可选 SCOPE= 和 PKJWT_KEY_PASSWORD= 如果私钥受密码保护。 > 注： PKJWT身份验证需要私钥及其证书。私钥用于对JWT（JsonWeb令牌）进行签名，而证书用于计算x5t指纹。可以使用受密码保护的私钥。在这种情况下，必须指定密码。

1.3. 面向开发人员的ODM（Docker/Local）

• 环境： 本地Docker或开发者版
• 身份验证： 基本认证

- CLI： --username --password - 环境： ODM_USERNAME= ODM_PASSWORD=

2.不同的身份验证类型：控制台与运行时

决策MCP服务器实际上与两个不同的ODM组件/服务器通信：

• RES控制台
• 决策服务器运行时

当这两个ODM组件被配置为使用不同的身份验证类型时，可以通过以下方式相应地配置决策MCP服务器：

• 指定向两个ODM组件进行身份验证所需的所有参数，
• 并使用以下附加参数：

- CLI： --console-auth-type --runtime-auth-type

- 环境： CONSOLE_AUTH_TYPE= RUNTIME_AUTH_TYPE=

> 哪里 ` 和 ` 必须采用以下值之一： > |auth_type |描述。 | > | ----------|--------------------------------------------------------- | > |BASIC |基本身份验证| > |ZEN | ZEN API密钥验证。 | > |SECRET|OpenID使用客户端密钥连接身份验证| > |PKJWT|OpenID使用私钥连接身份验证（PKJWT）| > |无|无身份验证/授权|

注： - 决策MCP服务器不支持使用具有不同凭据的相同身份验证类型 - 例如，具有两个不同用户名的Basic Auth（一个用于RES控制台，一个用于Runtime） - 这不受支持。 - 必须配置唯一的用户/服务帐户以访问两个ODM组件（请参阅 3.授权 在......下面

3.授权

3.1.Cloud Pak上的业务自动化ODM

如果ODM部署在IBM Cloud Pak for Business Automation中，则使用的用户/服务帐户必须分配一个角色，该角色授予以下Zen权限，以便能够访问RES控制台和决策服务器运行时：

|Zen权限| |-----------------| |ODM-监控决策服务器中的决策服务| |ODM-在决策服务器中执行决策服务|

阅读更多 管理用户权限.

3.2.Kubernetes上的ODM

如果ODM部署在Kubernetes上，则使用的用户/服务帐户必须具有以下角色：

|ODM角色| |---------------| |res监视器| |决议执行人|

3.3.云端ODM

如果ODM部署在云端的托管产品ODM中，则必须将以下角色分配给所使用的用户/服务帐户（适用于适当的环境（开发/测试/生产））：

|ODM在云端的角色| |-------------------| |监视器|

阅读更多 创建和管理服务帐户.

4.安全连接

4.1.服务器证书

为了与服务器建立SSL/TLS安全连接，Decision MCP服务器必须能够访问用于签署服务器证书的证书。

如果使用公共CA证书对服务器证书进行签名，则决策MCP服务器可以在系统受信任的证书中找到它。

如果这是自签名证书，可以指定：

• CLI： --ssl-cert-path
• 环境： SSL_CERT_PATH=

或者，在开发/测试环境中，可以忽略服务器的真实性：

• CLI： --verifyssl "False"
• 环境： VERIFY_SSL="False"

4.2.mTLS（双向TLS）

服务器可以被配置为检查尝试建立安全连接的客户端的真实性。

在这种情况下，Decision MCP服务器（充当客户端）必须配置私钥及其相关证书（并且服务器必须配置为在建立安全连接时信任提供该证书的客户端）。

可以指定以下参数：

• CLI： `--mtls-key-path

--mtls-cert-path 并且可选 --mtls-key-password ` 如果私钥受密码保护。

• 环境： `MTLS_KEY_PATH=

MTLS_CERT_PATH= 并且可选 MTLS_KEY_PASSWORD= ` 如果私钥受密码保护。

______________________________________________________________________

配置参数表

在远程模式下启动MCP服务器的参数（允许来自远程MCP客户端的连接） |CLI参数|环境变量|描述|默认值| |--------------|----------------------|-------------|---------| | --transport| TRANSPORT | stdio, streamable-http 或 sse ：决策MCP服务器的通信方式：本地(stdio)或远程(streamable-http 或 sse)) | stdio | | --host | HOST |MCP服务器在远程模式下监听的IP或主机名。 | 0.0.0.0 | | --port | PORT |MCP服务器在远程模式下监听的端口。 | 3000 | | --mount-path| MOUNT_PATH |MCP服务器在远程模式下监听的路径。 | /mcp |

决策MCP服务器配置文件

您可以使用JSON配置文件为Claude Desktop或Cursor AI等客户端配置MCP服务器，该文件可以包含环境变量和命令行参数。

提示：

• 使用CLI参数进行快速覆盖或非敏感参数。
• 使用环境变量作为机密。
• 如果需要，您可以混合使用这两种方法。CLI参数覆盖环境变量。

下面的示例显示了一个典型的用例，其中敏感信息（此处为密码）作为环境变量传递（这样它就不会显示在进程的参数中），其他参数作为CLI参数传递：

{
  "mcpServers": {
    "ibm-odm-decision-mcp-server": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/DecisionsDev/ibm-odm-decision-mcp-server",
        "start",
        "--url", "https://odm-res-console-url",
        "--ssl-cert-path", "certificate-file",
        "--username", "your-username"
      ],
      "env": {
        "ODM_PASSWORD": "odmAdmin"
      }
    }
  }
}

以下示例根据部署类型（开发/测试或生产）和环境（CloudPak等）演示了各种用例。

______________________________________________________________________

示例1：地方发展的基本授权

对于本地开发和测试，请使用Basic Auth。

"args": [
  "--from",
  "git+https://github.com/DecisionsDev/ibm-odm-decision-mcp-server",
  "start",
  "--url", "http://localhost:9060/res",
  "--username", "odmAdmin"
],
"env": {
  "ODM_PASSWORD": "odmAdmin"
}

______________________________________________________________________

示例2：对于Cloud Pak（Zen API密钥）

对于Cloud Pak上的生产部署，请使用Zen API密钥。

"args": [
  "--from",
  "git+https://github.com/DecisionsDev/ibm-odm-decision-mcp-server",
  "start",
  "--url",           "https://odm-res-console-url",
  "--ssl-cert-path", "certificate-file",
  "--username",      "YOUR_ZENUSERNAME"
],
"env": {
  "ZENAPIKEY": "YOUR_ZEN_API_KEY"
}

______________________________________________________________________

示例3:OpenID连接

对于Cloud Pak以外的其他环境上的生产部署，如果ODM配置为使用OpenID Connect，则可以使用它。

决策MCP服务器可以使用客户端凭据流向配置了OpenID Connect的ODM进行身份验证。

可能存在两种身份验证变体：

1. 使用客户端密码

"args": [
  "--from",
  "git+https://github.com/DecisionsDev/ibm-odm-decision-mcp-server",
  "start",
  "--url",           "https://odm-res-console-url",
  "--runtime-url",   "https://odm-runtime-url",
  "--ssl-cert-path", "certificate-file",
  "--token-url",     "https://your-openid-connect_provider-token-endpoint-url",
  "--scope",         "the_scope_to_be_used_for_client_credentials"
],
"env": {
  "CLIENT_ID":      "YOUR_CLIENT_ID",
  "CLIENT_SECRET":  "YOUR_CLIENT_SECRET"
}

1. 使用私钥（PKJWT）

"args": [
  "--from",
  "git+https://github.com/DecisionsDev/ibm-odm-decision-mcp-server",
  "start",
  "--url",           "https://odm-res-console-url",
  "--runtime-url",   "https://odm-runtime-url",
  "--ssl-cert-path", "certificate-file",
  "--token-url",     "https://your-openid-connect_provider-token-endpoint-url",
  "--scope",         "the_scope_to_be_used_for_client_credentials"
],
"env": {
  "CLIENT_ID":       "YOUR_CLIENT_ID",
  "PKJWT_KEY_PATH":  "PKJWT_PRIVATE_KEY_FILENAME",
  "PKJWT_CERT_PATH": "PKJWT_CERTIFICATE_FILENAME"
}

______________________________________________________________________

示例4:mTLS（双向TLS）身份验证

Decision MCP服务器还支持mTLS（双向TLS）身份验证，进一步保护SSL连接。

当需要授权时（评估访问服务的权限（RES控制台和/或决策服务运行时），mTLS必须辅以另一种身份验证/授权方式，例如下面示例中的基本身份验证：

"args": [
  "--from",
  "git+https://github.com/DecisionsDev/ibm-odm-decision-mcp-server",
  "start",
  "--url",           "https://odm-res-console-url",
  "--runtime-url",   "https://odm-runtime-url",
  "--ssl-cert-path", "certificate-file",
  "--username",      "SERVICE_ACCOUNT"
],
"env": {
  "PASSWORD":       "SERVICE_ACCOUNT_PASSWORD",
  "MTLS_KEY_PATH":  "MTLS_PRIVATE_KEY_FILENAME",
  "MTLS_CERT_PATH": "MTLS_CERTIFICATE_FILENAME"
}

______________________________________________________________________

示例5：不同的身份验证类型：控制台与运行时

以下示例显示了如何在以下情况下配置决策MCP服务器：

• RES控制台使用OpenID Connect和PKJWT，以及
• 决策服务器运行时已配置为使用mTLS并禁用授权

"args": [
  "--from",
  "git+https://github.com/DecisionsDev/ibm-odm-decision-mcp-server",
  "start",
  "--url",           "https://odm-res-console-url",
  "--runtime-url",   "https://odm-runtime-url",
  "--ssl-cert-path", "certificate-file",

  "--console-auth-type", "PKJWT",
  "--token-url",         "https://your-openid-connect_provider-token-endpoint-url",
  "--scope",             "the_scope_to_be_used_for_client_credentials",

  "--runtime-auth-type", "NONE"
],
"env": {
  "CLIENT_ID":       "YOUR_CLIENT_ID",
  "PKJWT_KEY_PATH":  "PKJWT_PRIVATE_KEY_FILENAME",
  "PKJWT_CERT_PATH": "PKJWT_CERTIFICATE_FILENAME",

  "MTLS_KEY_PATH":   "PRIVATE_KEY_FILENAME",
  "MTLS_CERT_PATH":  "CERTIFICATE_FILENAME"
}

______________________________________________________________________

为远程连接配置决策MCP服务器

默认情况下，决策MCP服务器与MCP客户端（AI代理）在同一台计算机上运行。

但是，您也可以在服务器上运行决策MCP服务器，并将其配置为通过网络与MCP客户端通信。

执行以下操作：

• 使用命令行参数 --transport 具有以下任一值 streamable-http （最好）或 sse.
• 当Decision MCP服务器在远程模式下启动时，它会监听

- 默认情况下所有网络接口(0.0.0.0).您可以使用参数指定特定接口 --host. - 港口 3000。您可以使用参数指定其他端口 --port. - URL http://: /mcp。您可以指定与以下路径不同的路径 /mcp 使用论点 --mount-path.

______________________________________________________________________

决策MCP服务器的规则集属性

您可以通过在IBM ODM中设置特定的规则集属性来配置如何将Decision Server规则集作为MCP工具公开。这些属性控制规则集是否可用作工具，以及如何将其呈现给AI助手。

添加规则集属性

您可以使用以下任何方法添加规则集属性：

1. 在规则设计器中：

- 打开规则集项目 - 右键单击规则集>属性>规则集属性 - 添加所需的属性及其值 - 保存并部署您的规则集

1. 在决策中心：

- 打开规则集>设置>属性 - 添加所需的属性及其值 - 保存并部署您的规则集

1. 在决策服务器控制台中：

- 登录决策服务器控制台 - 导航到资源管理器>规则集 - 选择您的规则集 - 点击“属性”选项卡 - 添加所需的属性及其值 - 点击“保存”

MCP配置属性

示例

agent.enabled=true
agent.description=This tool calculates vacation days based on employee tenure and position

注： 更新规则集属性后，您需要重新部署规则集以使更改生效。

______________________________________________________________________

LLM微调工具说明

当将决策服务作为LLM的工具公开时，工具描述的质量会显著影响LLM如何有效地利用它们。以下是优化工具描述的最佳实践：

详细服务说明

对服务的功能和预期参数值进行详细描述，可以指导LLM在触发工具时更加精确。

例子：

Allow to compute the beauty advise. This takes as parameters:
- age: should be between 0 and 110
- sex: Value should be Male or Female
- skin color: should be one of these values: Dark, Ebony, Ivory, Light, Medium or Unknown
- hair color: should be one of these values: Black, Blonde, Brown, Gray, Red, White or Unknown

For the hair color or skin color, you can suggest possible values.

此详细描述有助于LLM理解：

• 服务的目的（“计算美容建议”）
• 有效的参数范围和约束
• 可接受的枚举值
• 关于如何处理某些参数的指导

用Swagger注释增强OpenAPI

当单独的服务描述不足以完全描述API签名时，您可以通过向Java类添加Swagger注释来增强OpenAPI生成：

package miniloan;

import io.swagger.v3.oas.annotations.media.Schema;

/**
 * This class models a borrower.
 * A borrower is created with a name, a credit score, and a yearly income.
 */
@Schema(description = "This class models a borrower. A borrower is created with a name, a credit score, and a yearly income.")
public class Borrower {
    @Schema(description = "The name of the borrower.")
    private String name;
    
    @Schema(description = "The credit score of the borrower.", format = "int32")
    private int creditScore;
    
    @Schema(description = "The yearly income of the borrower.", format = "int32")
    private int yearlyIncome;

    
    public Borrower() {
    }
}

这些注释提供：

• 每个字段的详细说明
• 格式规范
• 可以包含在生成的OpenAPI规范中的其他元数据

注： 没有必要将Swagger JAR文件打包在XOM（执行对象模型）中，因为它已经是IBM ODM产品的一部分。您可以直接使用注释，而无需向项目添加其他依赖项。

通过将丰富的服务描述与正确注释的模型类相结合，您可以创建LLM可以高精度理解和使用的工具定义，从而减少错误并提高交互质量。

更多信息

• 有关IBM运营决策管理器（ODM），请参阅 IBM文档.
• 有关IBM Watsonx Orchestrate，请参阅 入门指南.
• 关于Claude Desktop，请参见 克劳德文件.

______________________________________________________________________

开发检查表

• \[x\] 在文档中添加示例场景-正在进行中
• \[x\] 使用Coverage进行密集的单元测试
• \[x\] 调查XOM注释
• \[x\] 调查如何从决策中心注入描述
• \[x\] 将决策跟踪执行作为MCP资源存储和公开
• \[x\] 管理ODM证书
• \[\]声明结构化输出
• \[x\] 确定规则集属性的命名约定前缀。（工具->代理/决策助理）
• \[x\] 验证OpenID连接身份验证
• \[\]展示一个解释决策的工具
• \[x\] 录制Claude Desktop集成演示视频
• \[x\] 添加一个docker compose来注入以部署ruleapps。
• \[x\] 支持通过CLI和环境变量进行配置
• \[x\] 验证Zen身份验证支持
• \[x\] 支持多个决策服务器端点
• \[x\] 测试并记录Claude Desktop集成
• \[x\] 测试Cursor AI集成
• \[\]实现通知上下文
• \[\]支持远程MCP服务器标准