Cs MCP Server

🚀 預覽：核心內容服務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客戶端的設置說明，請參閱：

• Bob-IDE MCP服務器設置
• VS Code Copilot MCP服務器設置

🛠️ MCP客戶端限制

一些MCP客戶端存在影響可使用工具的限制。下表顯示了已知的兼容性問題：

⚠️ 重要提示

這些限制是由於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服務器：

必需的環境變量

可選的環境變量

CP4BA環境變量

SSL配置最佳實踐

對於SSL配置（SSL_ENABLED、TOKEN_SSL_ENABLED、ZENIAM_ZEN_SSL_ENABLED和ZENIAM_IAM_SSL_ENABLED），您有三個選項：

1. 使用系統證書（建議用於生產環境）：設置為true以使用系統的證書存儲。
2. 提供自定義證書路徑：設置為證書的文件路徑（例如，/path/to/certificate.pem）。
3. 禁用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配置

1. 打開Claude Desktop設置：

   • 在macOS上，點擊頂部菜單欄中的Claude菜單並選擇設置。
   • 在Windows上，從Claude應用程序中訪問設置。

2. 導航到開發者選項卡並點擊編輯配置：

   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows：%APPDATA%\Claude\claude_desktop_config.json

3. 將以下配置示例之一添加到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"
         }
       }
     }
   }
   

4. 重啟Claude Desktop：

   • 僅關閉窗口是不夠的，必須停止並重啟Claude Desktop：
     • 在macOS上：Claude > 退出
     • 在Windows上：文件 > 退出

5. 檢查可用工具：

   • 要查看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代理：

1. 訪問和檢索文檔屬性。
2. 從文檔中提取文本。
3. 創建、更新、簽入和簽出文檔。
4. 管理文件夾和文檔分類。
5. 執行搜索。
6. 獲取文檔註釋。

示例工作流程

1. 搜索和發現：

   • 用戶通常從描述性信息（名稱、內容、關鍵字）而不是ID開始。
   • AI代理首先使用搜索工具來定位相關對象：
     • get_searchable_property_descriptions以發現有效的搜索屬性。
     • repository_object_search進行基於屬性的搜索。
   • 搜索結果包括後續操作所需的對象ID。

2. 文檔檢索：

   • 一旦通過搜索獲得對象ID，AI代理可以檢索：
     • 使用ID獲取文檔屬性。
     • 版本歷史。
     • 文本內容（需要安裝Persistent Text Extract附加組件）。
     • 註釋。

3. 文檔創建： 用戶可以要求AI代理創建具有特定屬性和內容的新文檔。

4. 文檔更新：

   • 在通過搜索識別文檔後，AI代理可以：
     • 使用文檔ID簽出文檔。
     • 更新屬性或內容。
     • 簽入文檔。

5. 文件夾操作：

   • 可以通過搜索結果中的路徑或ID識別文件夾。
   • 可以使用文檔和文件夾ID對文檔進行歸檔/取消歸檔。

💡 使用建議

大多數修改或訪問特定對象的操作都需要對象ID，該ID通常首先通過搜索操作獲得。這種工作流模式確保用戶可以通過有意義的屬性來處理對象，而無需事先知道技術標識符。

📄 許可證

有關詳細信息，請參閱LICENSE文件。

許可材料 - IBM財產 (c) 版權所有IBM Corp. 2019,2025 保留所有權利。

美國政府用戶受限權利 - 使用、複製或披露受與IBM Corp.的GSA ADP時間表合同限制。

免責聲明：

允許複製和修改此示例代碼，並分發修改後的版本，但前提是版權聲明、此許可聲明和保修免責聲明必須出現在所有副本和修改後的版本中。

此示例代碼按原樣許可給您。IBM及其供應商和許可方在此示例代碼中放棄所有明示或暗示的保證，包括不侵權保證和適銷性或特定用途適用性的暗示保證。在任何情況下，IBM或其許可方或供應商均不對因使用或無法使用示例代碼、分發示例代碼或示例代碼與任何其他代碼的組合而產生的任何損害承擔責任。在任何情況下，IBM或其許可方和供應商均不對任何損失的收入、利潤或數據，或直接、間接、特殊、後果性、偶發性或懲罰性損害承擔責任，無論損害是如何引起的，也無論責任理論如何，即使IBM或其許可方或供應商已被告知可能發生此類損害。