金大哥 - cs-mcp-server MCP 详情

article

README

🚀 预览：核心内容服务MCP服务器

核心内容服务MCP服务器提供了一个标准化接口，使AI模型能够使用IBM FileNet Content Manager（FNCM）的功能。该MCP服务器使您能够：

通过AI代理管理存储在FNCM中的文档，包括文档的创建和删除。
对文档执行更新操作，如签入、签出和属性更新。
搜索文档和文件夹等对象。
管理文件夹，并在文件夹中归档/取消归档文档。
管理文档类、文件夹类等。

📋 工具列表

核心内容服务MCP服务器提供了以下与FileNet CPE交互的工具：

文档管理

get_document_versions：检索文档的版本历史，包括每个版本的主要和次要版本号以及文档ID。
get_document_text_extract：通过检索文档的文本提取注释来提取文档的文本内容。如果找到多个文本提取，则将它们连接起来。注意：此功能要求在您的对象存储中安装Persistent Text Extract附加组件。有关更多详细信息，请参阅先决条件部分。
create_document：在内容存储库中创建具有指定属性的新文档。如果提供了文件路径，则可以上传文件作为文档的内容。需要先调用determine_class和get_class_property_descriptions。
update_document_properties：更新现有文档的属性而不更改其类。需要先调用get_class_property_descriptions以获取文档当前类的有效属性。
update_document_class：更改内容存储库中文档的类。警告：如果新类没有与旧类相同的属性，更改文档的类可能会导致属性丢失。需要先调用determine_class以获取新的类标识符。
checkin_document：签入先前签出的文档。如果提供了文件路径，则可以在签入时上传新的内容文件。
checkout_document：签出文档以进行编辑。如果提供了指定的文件夹路径，则可以将文档内容下载到该路径。
cancel_document_checkout：取消内容存储库中的文档签出，释放保留。
get_document_properties：通过ID或路径从内容存储库中检索文档，返回带有其属性的文档对象。
get_class_specific_properties_name：根据文档的类定义检索文档的特定类属性名称列表。过滤掉系统属性和隐藏属性。
delete_document_version：使用文档ID删除内容存储库中的特定文档版本。
delete_version_series：使用版本系列ID删除内容存储库中的整个版本系列（文档的所有版本）。

文件夹管理

create_folder：在内容存储库中创建具有指定名称、父文件夹和可选类标识符的新文件夹。
delete_folder：使用文件夹的ID或路径从存储库中删除文件夹。
unfile_document：从文件夹中移除文档而不删除文档本身。
update_folder：更新现有文件夹的属性。需要先调用determine_class和get_class_property_descriptions。
get_folder_documents：获取文件夹中包含的文档。

元数据

list_root_classes：列出存储库中特定根类的所有类。
list_all_classes：列出存储库中特定根类的所有类。
determine_class：根据可用的类和用户消息或上下文文档的内容确定合适的类。
get_class_property_descriptions：检索指定类的所有属性的详细描述。

搜索

get_searchable_property_descriptions：检索可用于搜索操作的属性的描述。
repository_object_search：根据指定的条件搜索存储库对象。
lookup_documents_by_name：通过将关键字与文档名称匹配来搜索文档。返回带有置信度分数的匹配文档的排名列表。当您知道文档名称的一部分但不知道其确切ID或路径时很有用。
lookup_documents_by_path：根据文档在文件夹层次结构中的位置搜索文档。在每个路径级别将关键字与文件夹名称和文档包含名称进行匹配。当用户使用路径分隔符（例如，"/Folder1/Subfolder/document"）描述文档时特别有用。

注释

get_document_annotations：检索与文档关联的所有注释，包括其ID、名称、描述性文本和内容元素。

🧪 测试环境

核心内容服务MCP服务器已与以下MCP客户端和大语言模型组合进行了测试：

Claude Desktop：Sonnet 4.5、4、3.5和Haiku 4.5
Watsonx Orchestrate：Llama-3-2-90b-vision-instruct

虽然其他MCP客户端和大语言模型组合尚未经过测试，但它们可能与该服务器兼容。我们鼓励您自行进行实验和验证。

有关使用其他MCP客户端的设置说明，请参阅：

🛠️ MCP客户端限制

一些MCP客户端存在影响可使用工具的限制。下表显示了已知的兼容性问题：

| MCP客户端 | 限制 | 受影响的工具 | |------------|------------|----------------| | Watson Orchestrate | 不支持将复杂的Pydantic类作为输入 | • create_document
• update_document_properties
• checkout_document
• checkin_document
• update_folder
• repository_object_search |

⚠️ 重要提示

这些限制是由于MCP客户端的输入处理能力造成的，而不是MCP服务器本身。

⚙️ 设置与配置

先决条件

Python 3.13+
uv
- 在macOS上：brew install uv
- 在Windows上：请参阅上述链接
访问安装了Content Services GraphQL API（CS-GQL）的FileNet Content Platform Engine（CPE）服务器
如果您想使用文档内容检索功能，则必须在您的对象存储中安装Persistent Text Extract附加组件
- 此附加组件可实现从文档中提取和存储文本内容。
- 没有此附加组件，get_document_text_extract工具将不会返回文档内容。
- 有关安装说明，请参阅IBM关于安装Persistent Text附加组件的文档

配置

核心内容服务MCP服务器需要几个环境变量来连接到您的FileNet CPE服务器：

必需的环境变量

| 属性 | 详情 | |------|------| | SERVER_URL | 内容服务GraphQL API端点URL（必需） | | USERNAME | 认证用户名（必需） | | PASSWORD | 认证密码（必需） | | OBJECT_STORE | 对象存储标识符（必需） |

可选的环境变量

| 属性 | 详情 | |------|------| | SSL_ENABLED | 是否启用SSL。可以设置为true、证书文件的路径或false（不建议用于生产环境） | | TOKEN_SSL_ENABLED | 是否为令牌端点启用SSL。可以设置为true、证书文件的路径或false（不建议用于生产环境） | | TOKEN_REFRESH | 令牌刷新间隔（秒） | | TOKEN_URL | OAuth令牌URL | | GRANT_TYPE | OAuth授权类型 | | SCOPE | OAuth范围 | | CLIENT_ID | OAuth客户端ID | | CLIENT_SECRET | OAuth客户端密钥 | | REQUEST_TIMEOUT | 请求超时时间（秒） | | POOL_CONNECTIONS | 连接池连接数 | | POOL_MAXSIZE | 最大池大小 |

CP4BA环境变量

| 属性 | 详情 | |------|------| | ZENIAM_ZEN_URL | 用于将IAM令牌交换为Zen令牌的Zen URL，例如：<zen_host_route>/v1/preauth/validateAuth | | ZENIAM_ZEN_SSL_ENABLED | 是否为Zen交换路由启用SSL。可以设置为true、证书文件的路径或false（不建议用于生产环境） | | ZENIAM_IAM_URL | 用于将用户/密码或客户端ID/客户端密钥发送到IAM以获取IAM令牌的IAM URL，例如：<iam_host_route>/idprovider/v1/auth/identitytoken | | ZENIAM_IAM_SSL_ENABLED | 是否为IAM路由启用SSL。可以设置为true、证书文件的路径或false（不建议用于生产环境） | | ZENIAM_IAM_GRANT_TYPE | IAM授权类型 | | ZENIAM_IAM_SCOPE | IAM范围 | | ZENIAM_IAM_USER | 如果授权类型为密码，则指定IAM用户 | | ZENIAM_IAM_PASSWORD | 如果授权类型为密码，则指定IAM密码 | | ZENIAM_CLIENT_ID | 如果授权类型为客户端凭证，则指定IAM客户端ID | | ZENIAM_CLIENT_SECRET | 如果授权类型为客户端凭证，则指定IAM客户端密钥 |

SSL配置最佳实践

对于SSL配置（SSL_ENABLED、TOKEN_SSL_ENABLED、ZENIAM_ZEN_SSL_ENABLED和ZENIAM_IAM_SSL_ENABLED），您有三个选项：

使用系统证书（建议用于生产环境）：设置为true以使用系统的证书存储。
提供自定义证书路径：设置为证书的文件路径（例如，/path/to/certificate.pem）。
禁用SSL验证（不建议用于生产环境）：设置为false以禁用SSL验证。

⚠️ 重要提示

禁用SSL验证（false）仅应在测试环境中使用。对于生产部署，始终使用适当的证书验证以确保安全通信。

认证方法

服务器支持两种认证方法：

基本认证

设置以下环境变量：

SERVER_URL=https://your-graphql-endpoint
USERNAME=your_username
PASSWORD=your_password
OBJECT_STORE=your_object_store
SSL_ENABLED=your_path_to_graphql_certificate | true | false

OAuth认证

设置以下环境变量：

SERVER_URL=https://your-graphql-endpoint
USERNAME=your_username
PASSWORD=your_password
TOKEN_URL=https://your-oauth-server/token
GRANT_TYPE=password
SCOPE=openid
CLIENT_ID=your_client_id
CLIENT_SECRET=your_client_secret
OBJECT_STORE=your_object_store

Zen/IAM认证

使用用户/密码和SSL连接到所有外部服务器时，ZEN/IAM环境变量的示例：

SERVER_URL=https://your-graphql-endpoint
SSL_ENABLED=your_path_to_graphql_certificate| true | false
OBJECT_STORE=your_object_store
ZENIAM_ZEN_URL=https://your-zen-exchange-route
ZENIAM_ZEN_SSL_ENABLED=your_path_to_zen_exchange_route_certicate | true | false
ZENIAM_IAM_URL=https://your-IAM-route
ZENIAM_IAM_SSL_ENABLED=your_path_to_IAM_route_certicate | true | false
ZENIAM_IAM_GRANT_TYPE=password
ZENIAM_IAM_SCOPE=openid
ZENIAM_IAM_USER=your_user_name
ZENIAM_IAM_PASSWORD=your_user_password

与MCP客户端/代理框架集成

Claude Desktop配置

打开Claude Desktop设置：
- 在macOS上，点击顶部菜单栏中的Claude菜单并选择设置。
- 在Windows上，从Claude应用程序中访问设置。
导航到开发者选项卡并点击编辑配置：
- macOS：~/Library/Application Support/Claude/claude_desktop_config.json
- Windows：%APPDATA%\Claude\claude_desktop_config.json

将以下配置示例之一添加到claude_desktop_config.json文件中：

选项1：使用本地安装（如果您已克隆存储库）

{
  "mcpServers": {
    "core-cs-mcp-server": {
      "command": "/path/to/your/uvx",
      "args": [
        "--from",
        "/path/to/your/cs-mcp-server",
        "core-cs-mcp-server"
      ],
      "env": {
        "USERNAME": "your_username",
        "PASSWORD": "your_password",
        "SERVER_URL": "https://your-graphql-server/content-services-graphql/graphql",
        "OBJECT_STORE": "your_object_store"
      }
    }
  }
}

选项2：直接从GitHub安装（推荐）

{
  "mcpServers": {
    "core-cs-mcp-server": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/ibm-ecm/cs-mcp-server",
        "core-cs-mcp-server"
      ],
      "env": {
        "USERNAME": "your_username",
        "PASSWORD": "your_password",
        "SERVER_URL": "https://your-graphql-server/content-services-graphql/graphql",
        "OBJECT_STORE": "your_object_store"
      }
    }
  }
}

重启Claude Desktop：
- 仅关闭窗口是不够的，必须停止并重启Claude Desktop：
  - 在macOS上：Claude > 退出
  - 在Windows上：文件 > 退出
检查可用工具：
- 要查看Claude Desktop中的所有可用工具，请按以下步骤操作：
  - 首先点击设置图标，您应该会看到：
  - 然后点击core-cs-mcp-server，您应该会看到所有工具：

💡 使用建议

上述JSON配置示例仅显示了最低要求的环境变量。有关所有可能的配置选项的完整列表，请参阅上面的环境变量表。

Watson Orchestrate（WxO）配置

本节介绍如何使用核心内容服务MCP服务器增强IBM watsonx Orchestrate，使watsonx Orchestrate能够在聊天中的用户交互期间与IBM FileNet Content Management进行交互。

配置

1. 配置连接变量

对于SaaS或本地部署（UI）：

点击主菜单图标
导航到管理 > 连接
点击添加新连接
输入连接ID和显示名称
点击下一步
现在您将配置草稿连接详细信息（测试环境）
- 选择认证类型下拉菜单为键值对
- 输入每个必需的变量：
  - SERVER_URL：您的内容服务GraphQL API端点URL
  - USERNAME：认证用户名
  - PASSWORD：认证密码
  - OBJECT_STORE：对象存储标识符
- 根据需要输入任何可选变量（例如，SSL_ENABLED、TOKEN_REFRESH等）
- 完成后点击下一步
现在您将输入实时连接环境变量
- 选择认证类型下拉菜单为键值对
- 输入与上述相同的必需变量
- 根据需要输入任何可选变量
- 选择首选的凭证类型
- 点击添加连接

对于ADK（应用程序开发套件）：

有关使用ADK CLI创建连接的信息，请参阅官方文档。

2. 创建代理

点击主菜单图标
导航到构建 > 代理构建器
导航到所有代理
点击**创建代理 +**以添加新代理
选择从头开始创建
输入名称（例如，Core Content Services Agent）
输入描述（例如，此代理使您能够与FileNet Content Management进行交互。）
点击创建

3. 使用核心内容服务MCP服务器增强代理

导航到工具集部分，点击添加工具 +
点击导入
点击从MCP服务器导入
点击添加MCP服务器
输入服务器名称，不包含任何空格字符（例如，core-cs-mcp-server）
可选地输入描述（例如，此MCP服务器连接到FileNet Content Platform Engine，实现内容管理操作。）

输入安装命令：

uvx --from git+https://github.com/ibm-ecm/cs-mcp-server core-cs-mcp-server

点击连接
如果您看到“连接成功”，点击完成
将您要启用的工具的激活开关设置为开启
将您之前创建的连接与该代理关联

4. 部署代理

点击部署
在弹出窗口中，再次点击部署

5. 让代理在聊天中使用

点击主菜单图标
导航到聊天
点击新创建的代理

示例工作流程

配置完成后，您可以在watsonx Orchestrate聊天中通过自然语言与FileNet存储库进行交互，具体取决于您启用的工具。例如：

"查找文档标题中包含pdf的所有文档"
"创建一个名为Project Z的新文件夹"

点击任何响应中的显示推理以查看执行操作的详细信息。

聊天推理

💻 使用方法

直接运行服务器

如果您有存储库的本地副本，可以使用以下命令直接运行服务器：

USERNAME=your_username PASSWORD=your_password SERVER_URL=https://your-graphql-server/content-services-graphql/graphql OBJECT_STORE=your_object_store /path/to/your/uvx --from /path/to/your/cs-mcp-server core-cs-mcp-server

与AI代理集成

核心内容服务MCP服务器可以与支持MCP协议的AI代理集成。这允许AI代理：

访问和检索文档属性。
从文档中提取文本。
创建、更新、签入和签出文档。
管理文件夹和文档分类。
执行搜索。
获取文档注释。

示例工作流程

搜索和发现：
- 用户通常从描述性信息（名称、内容、关键字）而不是ID开始。
- AI代理首先使用搜索工具来定位相关对象：
  - get_searchable_property_descriptions以发现有效的搜索属性。
  - repository_object_search进行基于属性的搜索。
- 搜索结果包括后续操作所需的对象ID。
文档检索：
- 一旦通过搜索获得对象ID，AI代理可以检索：
  - 使用ID获取文档属性。
  - 版本历史。
  - 文本内容（需要安装Persistent Text Extract附加组件）。
  - 注释。
文档创建：用户可以要求AI代理创建具有特定属性和内容的新文档。
文档更新：
- 在通过搜索识别文档后，AI代理可以：
  - 使用文档ID签出文档。
  - 更新属性或内容。
  - 签入文档。
文件夹操作：
- 可以通过搜索结果中的路径或ID识别文件夹。
- 可以使用文档和文件夹ID对文档进行归档/取消归档。

💡 使用建议

大多数修改或访问特定对象的操作都需要对象ID，该ID通常首先通过搜索操作获得。这种工作流模式确保用户可以通过有意义的属性来处理对象，而无需事先知道技术标识符。

📄 许可证

有关详细信息，请参阅LICENSE文件。

许可材料 - IBM财产 (c) 版权所有IBM Corp. 2019,2025 保留所有权利。

美国政府用户受限权利 - 使用、复制或披露受与IBM Corp.的GSA ADP时间表合同限制。

免责声明：

允许复制和修改此示例代码，并分发修改后的版本，但前提是版权声明、此许可声明和保修免责声明必须出现在所有副本和修改后的版本中。

此示例代码按原样许可给您。IBM及其供应商和许可方在此示例代码中放弃所有明示或暗示的保证，包括不侵权保证和适销性或特定用途适用性的暗示保证。在任何情况下，IBM或其许可方或供应商均不对因使用或无法使用示例代码、分发示例代码或示例代码与任何其他代码的组合而产生的任何损害承担责任。在任何情况下，IBM或其许可方和供应商均不对任何损失的收入、利润或数据，或直接、间接、特殊、后果性、偶发性或惩罚性损害承担责任，无论损害是如何引起的，也无论责任理论如何，即使IBM或其许可方或供应商已被告知可能发生此类损害。

cs-mcp-server

README

🚀 预览：核心内容服务MCP服务器

📋 工具列表

文档管理

文件夹管理

元数据

搜索

注释

🧪 测试环境

🛠️ MCP客户端限制

⚙️ 设置与配置

先决条件

配置

必需的环境变量

可选的环境变量

CP4BA环境变量

SSL配置最佳实践

认证方法

基本认证

OAuth认证

Zen/IAM认证

与MCP客户端/代理框架集成

Claude Desktop配置

Watson Orchestrate（WxO）配置

配置

1. 配置连接变量

2. 创建代理

3. 使用核心内容服务MCP服务器增强代理

4. 部署代理

5. 让代理在聊天中使用

示例工作流程

💻 使用方法

直接运行服务器

与AI代理集成

示例工作流程

📄 许可证

运行方式说明

托管运行

本地运行 / 其它方式