Chatvolt MCP

🚀 Chatvolt MCP服務器：高層概述

本文件對Chatvolt模型上下文協議（MCP）服務器進行了高層概述。這是一個基於TypeScript的應用程序，旨在通過為AI智能體提供一套與Chatvolt平臺交互的工具，擴展其功能。

🚀 快速開始

Chatvolt MCP服務器是AI模型與Chatvolt API之間的橋樑。它提供了一系列工具，AI智能體可以調用這些工具來執行諸如管理智能體、查詢數據存儲和處理CRM場景等操作。這實現了複雜工作流程的自動化，併為Chatvolt平臺提供了自然語言接口。

✨ 主要特性

• 充當橋樑：連接AI模型和Chatvolt API。
• 工具豐富：提供管理智能體、處理CRM場景、查詢數據存儲等工具。
• 自然語言接口：允許通過自然語言與Chatvolt平臺交互。

🔧 技術細節

關鍵技術

主要組件

1. MCP服務器 (src/server.ts)

應用程序的核心是MCP服務器，負責以下工作：

• 初始化服務器：設置服務器的名稱、版本和功能。
• 處理請求：實現各種MCP請求類型的處理程序，包括ListTools、CallTool、ListResources和GetPrompt。
• 工具調度：接收CallTool請求，並將其分配給相應的工具處理程序。

2. 工具 (src/tools/)

工具是AI智能體可以執行的操作。它們在src/tools/目錄中定義，大致分為以下幾類：

• 智能體管理：用於創建、更新、刪除和列出Chatvolt智能體的工具。
• CRM管理：用於管理CRM場景和步驟的工具。
• 數據存儲管理：用於與數據存儲和數據源交互的工具。

3. 資源和提示

服務器通過資源和提示為AI模型提供額外的上下文：

• TOOL_DESCRIPTIONS.md：一個Markdown文件，提供所有可用工具及其參數的詳細描述。
• MODELS.md：可以與智能體一起使用的AI模型列表。
• SYSTEM_PROMPTS.md：包含指導AI智能體的系統級指令。

📦 安裝指南

此MCP服務器通過客戶端的命令啟動。要進行連接，需要將客戶端配置為啟動chatvolt-mcp命令，並傳遞必要的環境變量。

以下是如何配置客戶端mcpServers設置的示例：

{
  "mcpServers": {
    "chatvolt-mcp": {
      "command": "npx",
      "args": [
        "chatvolt-mcp"
      ],
      "env": {
        "CHATVOLT_API_KEY": "{your_token}"
      }
    }
  }
}

⚠️ 重要提示

必須將"{your_token}"替換為實際的Chatvolt API密鑰。

📚 詳細文檔

Chatvolt MCP服務器：詳細架構

本文件提供了Chatvolt模型上下文協議（MCP）服務器的詳細技術架構。它在高層概述的基礎上進行了擴展，涵蓋了請求生命週期、目錄結構以及工具的定義和註冊過程。

1. 請求生命週期：CallTool

CallTool請求是AI智能體執行操作的主要機制。此請求的生命週期如下：

sequenceDiagram
    participant AI Agent
    participant MCP Server
    participant Tool Handler
    participant Chatvolt API

    AI Agent->>+MCP Server: Sends CallToolRequest (e.g., 'delete_agent', {id: '123'})
    MCP Server->>MCP Server: Receives request in CallTool handler
    Note over MCP Server: Finds handler for 'delete_agent' in `toolHandlers` map
    MCP Server->>+Tool Handler: Invokes handleDeleteAgent(request)
    Tool Handler->>Tool Handler: Validates arguments (e.g., checks for 'id')
    Tool Handler->>+Chatvolt API: Calls `deleteAgent('123')`
    Chatvolt API-->>-Tool Handler: Returns result (e.g., {success: true})
    Tool Handler-->>-MCP Server: Returns formatted content
    MCP Server-->>-AI Agent: Sends response with tool output

流程描述：

1. 請求接收：MCP服務器接收CallToolRequest。此請求由在src/server.ts中定義的通用CallToolRequestSchema處理程序處理。
2. 處理程序調度：服務器從toolHandlers對象中查找特定的工具處理程序，該對象將工具名稱（例如"delete_agent"）映射到相應的處理程序函數（例如handleDeleteAgent）。此對象從中央src/tools/索引文件導入。
3. 工具執行：執行匹配的處理程序函數。例如，調用src/tools/deleteAgent.ts中的handleDeleteAgent。
4. 業務邏輯：工具處理程序從請求中提取必要的參數，驗證它們，然後調用src/services/層中的相關函數（例如deleteAgent(id)）。
5. API交互：服務函數負責向Chatvolt平臺發出實際的API調用。
6. 響應格式化：工具處理程序從服務接收數據，將其字符串化（在本例中為JSON），並將其包裝在MCP SDK期望的格式中。
7. 響應傳輸：服務器將最終格式化的內容發送回發起調用的AI智能體。

2. 目錄結構

項目的組織方式使關注點分離，使其具有模塊化和可維護性。

• src/：這是所有應用程序源代碼的根目錄。
• src/tools/：該目錄包含服務器公開的每個工具的實現。
  • 結構：每個工具通常有自己的文件（例如deleteAgent.ts）。
  • 內容：每個文件導出兩個主要構造：
    • 一個Tool定義對象（例如deleteAgentTool），包含MCP SDK要求的工具的name、description和inputSchema。
    • 一個處理程序函數（例如handleDeleteAgent），包含執行工具的邏輯。
  • 聚合：此目錄中的中央index.js文件負責導入所有單個工具和處理程序，並將它們作為兩個聚合對象導出：tools（所有工具定義的數組）和toolHandlers（工具名稱到其處理程序的映射）。
• src/services/：該目錄旨在存放與外部服務（主要是Chatvolt API）交互的業務邏輯和API客戶端代碼。
  • 目的：它充當工具處理程序和底層平臺之間的橋樑。這種分離確保工具處理程序僅負責請求/響應處理和參數驗證，而服務層管理API通信的細節。
  • 示例：從../services/chatvolt.js導入的deleteAgent函數將包含發送DELETE請求到Chatvolt /agents/:id端點所需的fetch調用和邏輯。

3. 工具定義和註冊

工具是定義服務器功能的核心組件。它們的定義和註冊遵循明確的模式：

1. 工具定義：每個工具被定義為@modelcontextprotocol/sdk/types.js庫中Tool類型的常量對象。該對象包括：

• name：工具的唯一機器可讀名稱（例如"delete_agent"）。
• description：工具功能及其參數的人類可讀描述。雖然像TOOL_DESCRIPTIONS.md這樣的資源文件存在，為AI模型提供詳細文檔，但工具定義本身的description屬性作為簡潔摘要。
• inputSchema：一個JSON Schema對象，正式定義工具接受的參數，包括它們的類型和是否必需。

2. 工具註冊：服務器通過以下過程發現和註冊工具：

• tools數組和toolHandlers映射從src/tools/index.js導入到src/server.ts。
• src/server.ts中的ListToolsRequestSchema處理程序使用導入的tools數組來響應可用工具列表的請求。
• CallToolRequestSchema處理程序使用toolHandlers映射根據傳入請求中的name參數查找並執行正確的函數。

這種架構創建了一個解耦的系統，通過在src/tools/目錄中創建新文件並更新中央index.js文件，可以輕鬆添加新工具，而無需修改src/server.ts中的核心服務器邏輯。

系統提示文檔

本文件解釋了在與Chatvolt MCP（模型上下文協議）交互時，用於指導AI智能體行為的系統提示的作用和內容。這些提示在SYSTEM_PROMPTS.md文件中定義，為AI提供了一組基本指令。

系統提示的目的

系統提示是高級指令，定義了AI的角色、目標和操作約束。它們通過建立一個清晰的框架，確保AI以可預測和有效的方式行事，該框架規定了AI應如何解釋用戶請求、使用其工具以及構建其響應。

關鍵指令和場景

SYSTEM_PROMPTS.md文件概述了三種主要場景，每種場景都有相應的系統提示來指導AI的行為。

1. 簡單工具操作

• 目的：處理可以通過單個工具調用完成的簡單用戶請求。
• AI角色：Chatvolt平臺的專家AI助手。
• 核心指令：
  1. 識別用戶意圖。
  2. 選擇最合適的單個工具（例如list_agents）。
  3. 使用正確的參數執行工具。
  4. 向用戶報告結果。

2. 複雜的多步驟工作流程

• 目的：管理需要一系列工具調用才能實現更大目標的複雜任務。
• AI角色：負責編排工作流程的高級AI自動化工程師。
• 核心指令：
  1. 分解：將用戶請求分解為更小的順序步驟。
  2. 規劃：創建一個分步計劃，為每個步驟確定合適的工具。
  3. 執行：按順序調用工具，等待每個工具成功完成後再進行下一步。一個工具的輸出可以用作另一個工具的輸入。
  4. 綜合：提供所有操作和結果的最終摘要。

3. 自我發現和學習

• 目的：使AI在執行任務之前能夠自我探索並瞭解自己的能力。
• AI角色：高度自主和主動的AI智能體。
• 核心指令：
  1. 先自我發現：在嘗試複雜任務之前，AI 必須首先調用getDocumentation工具來檢索有關其所有可用工具的信息。
  2. 分析：查看文檔以瞭解其能力。
  3. 規劃：根據新獲得的工具知識制定計劃。
  4. 執行：執行計劃並報告結果。

📄 API和工具參考

本文件提供了可用於與服務器交互的可用工具的詳細參考。

create_agent

創建一個新的Chatvolt智能體。

update_agent

根據ID部分更新現有智能體。允許更新特定智能體的一個或多個字段。僅請求正文中提供的字段將被更新。

delete_agent

刪除指定的智能體。

list_agents

檢索所有可用智能體的列表。 此工具不接受參數。

get_agent

檢索單個智能體的詳細信息。

agent_query

向智能體發送查詢或消息以進行處理。

enable_disable_agent_integration

啟用或禁用智能體的特定集成。

create_crm_scenario

在CRM中創建一個新場景。

update_crm_scenario

更新現有的CRM場景。

delete_crm_scenario

刪除一個CRM場景。

list_crm_scenarios

列出所有CRM場景。

create_crm_step

在CRM場景中創建一個新步驟。

update_crm_step

更新CRM場景中的現有步驟。

delete_crm_step

從CRM場景中刪除一個步驟。

list_crm_steps

列出給定CRM場景的所有步驟。

create_datastore

創建一個新的數據存儲。

get_datastore

檢索特定數據存儲的信息。

list_datastores

檢索所有數據存儲的列表。 此工具不接受參數。

create_datasource

在數據存儲中創建一個新的數據源。