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

在数据存储中创建一个新的数据源。