Chatvolt Mcp

🚀 Chatvolt MCP服务器：高层概述

本文件对Chatvolt模型上下文协议（MCP）服务器进行了高层概述。这是一个基于TypeScript的应用程序，旨在通过为AI智能体提供一套与Chatvolt平台交互的工具，扩展其功能。

🚀 快速开始

Chatvolt MCP服务器是AI模型与Chatvolt API之间的桥梁。它提供了一系列工具，AI智能体可以调用这些工具来执行诸如管理智能体、查询数据存储和处理CRM场景等操作。这实现了复杂工作流程的自动化，并为Chatvolt平台提供了自然语言接口。

✨ 主要特性

• 充当桥梁：连接AI模型和Chatvolt API。
• 工具丰富：提供管理智能体、处理CRM场景、查询数据存储等工具。
• 自然语言接口：允许通过自然语言与Chatvolt平台交互。

🔧 技术细节

关键技术

属性	详情
运行环境	Node.js
编程语言	TypeScript
核心SDK	@modelcontextprotocol/sdk

主要组件

1. MCP服务器 ()

应用程序的核心是MCP服务器，负责以下工作：

• 初始化服务器：设置服务器的名称、版本和功能。
• 处理请求：实现各种MCP请求类型的处理程序，包括ListTools、CallTool、ListResources和GetPrompt。
• 工具调度：接收CallTool请求，并将其分配给相应的工具处理程序。

2. 工具 ()

工具是AI智能体可以执行的操作。它们在src/tools/目录中定义，大致分为以下几类：

• 智能体管理：用于创建、更新、删除和列出Chatvolt智能体的工具。
• CRM管理：用于管理CRM场景和步骤的工具。
• 数据存储管理：用于与数据存储和数据源交互的工具。

3. 资源和提示

服务器通过资源和提示为AI模型提供额外的上下文：

• ：一个Markdown文件，提供所有可用工具及其参数的详细描述。
• ：可以与智能体一起使用的AI模型列表。
• ：包含指导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。此请求由在中定义的通用CallToolRequestSchema处理程序处理。
2. 处理程序调度：服务器从toolHandlers对象中查找特定的工具处理程序，该对象将工具名称（例如"delete_agent"）映射到相应的处理程序函数（例如handleDeleteAgent）。此对象从中央src/tools/索引文件导入。
3. 工具执行：执行匹配的处理程序函数。例如，调用中的。
4. 业务逻辑：工具处理程序从请求中提取必要的参数，验证它们，然后调用src/services/层中的相关函数（例如deleteAgent(id)）。
5. API交互：服务函数负责向Chatvolt平台发出实际的API调用。
6. 响应格式化：工具处理程序从服务接收数据，将其字符串化（在本例中为JSON），并将其包装在MCP SDK期望的格式中。
7. 响应传输：服务器将最终格式化的内容发送回发起调用的AI智能体。

2. 目录结构

项目的组织方式使关注点分离，使其具有模块化和可维护性。

• src/：这是所有应用程序源代码的根目录。
• src/tools/：该目录包含服务器公开的每个工具的实现。
  • 结构：每个工具通常有自己的文件（例如）。
  • 内容：每个文件导出两个主要构造：
    • 一个Tool定义对象（例如deleteAgentTool），包含MCP SDK要求的工具的name、description和inputSchema。
    • 一个处理程序函数（例如handleDeleteAgent），包含执行工具的逻辑。
  • 聚合：此目录中的中央index.js文件负责导入所有单个工具和处理程序，并将它们作为两个聚合对象导出：tools（所有工具定义的数组）和toolHandlers（工具名称到其处理程序的映射）。
• src/services/：该目录旨在存放与外部服务（主要是Chatvolt API）交互的业务逻辑和API客户端代码。
  • 目的：它充当工具处理程序和底层平台之间的桥梁。这种分离确保工具处理程序仅负责请求/响应处理和参数验证，而服务层管理API通信的细节。
  • 示例：从导入的函数将包含发送DELETE请求到Chatvolt /agents/:id端点所需的fetch调用和逻辑。

3. 工具定义和注册

工具是定义服务器功能的核心组件。它们的定义和注册遵循明确的模式：

1. 工具定义：每个工具被定义为@modelcontextprotocol/sdk/types.js库中Tool类型的常量对象。该对象包括：

• name：工具的唯一机器可读名称（例如"delete_agent"）。
• description：工具功能及其参数的人类可读描述。虽然像这样的资源文件存在，为AI模型提供详细文档，但工具定义本身的description属性作为简洁摘要。
• inputSchema：一个JSON Schema对象，正式定义工具接受的参数，包括它们的类型和是否必需。

2. 工具注册：服务器通过以下过程发现和注册工具：

• tools数组和toolHandlers映射从src/tools/index.js导入到。
• 中的ListToolsRequestSchema处理程序使用导入的tools数组来响应可用工具列表的请求。
• CallToolRequestSchema处理程序使用toolHandlers映射根据传入请求中的name参数查找并执行正确的函数。

这种架构创建了一个解耦的系统，通过在src/tools/目录中创建新文件并更新中央index.js文件，可以轻松添加新工具，而无需修改中的核心服务器逻辑。

系统提示文档

本文件解释了在与Chatvolt MCP（模型上下文协议）交互时，用于指导AI智能体行为的系统提示的作用和内容。这些提示在文件中定义，为AI提供了一组基本指令。

系统提示的目的

系统提示是高级指令，定义了AI的角色、目标和操作约束。它们通过建立一个清晰的框架，确保AI以可预测和有效的方式行事，该框架规定了AI应如何解释用户请求、使用其工具以及构建其响应。

关键指令和场景

文件概述了三种主要场景，每种场景都有相应的系统提示来指导AI的行为。

1. 简单工具操作

• 目的：处理可以通过单个工具调用完成的简单用户请求。
• AI角色：Chatvolt平台的专家AI助手。
• 核心指令：
  1. 识别用户意图。
  2. 选择最合适的单个工具（例如）。
  3. 使用正确的参数执行工具。
  4. 向用户报告结果。

2. 复杂的多步骤工作流程

• 目的：管理需要一系列工具调用才能实现更大目标的复杂任务。
• AI角色：负责编排工作流程的高级AI自动化工程师。
• 核心指令：
  1. 分解：将用户请求分解为更小的顺序步骤。
  2. 规划：创建一个分步计划，为每个步骤确定合适的工具。
  3. 执行：按顺序调用工具，等待每个工具成功完成后再进行下一步。一个工具的输出可以用作另一个工具的输入。
  4. 综合：提供所有操作和结果的最终摘要。

3. 自我发现和学习

• 目的：使AI在执行任务之前能够自我探索并了解自己的能力。
• AI角色：高度自主和主动的AI智能体。
• 核心指令：
  1. 先自我发现：在尝试复杂任务之前，AI 必须首先调用getDocumentation工具来检索有关其所有可用工具的信息。
  2. 分析：查看文档以了解其能力。
  3. 规划：根据新获得的工具知识制定计划。
  4. 执行：执行计划并报告结果。

📄 API和工具参考

本文件提供了可用于与服务器交互的可用工具的详细参考。

create_agent

创建一个新的Chatvolt智能体。

参数	类型	描述
name	字符串，必需	智能体的名称。这是智能体的人类可读标识符。
description	字符串，必需	智能体的目的和功能的详细描述。
modelName	字符串，必需	智能体将使用的特定AI模型（例如'gpt - 4'，'claude_3_sonnet'）。
systemPrompt	字符串，必需	提供给智能体的初始指令或上下文，用于定义其个性、角色和行为。
temperature	数字，可选	控制模型输出的随机性。接近0的值使输出更具确定性，而接近1的值使其更具创造性。
tools	数组，可选	智能体可以用来执行操作的工具列表。

update_agent

根据ID部分更新现有智能体。允许更新特定智能体的一个或多个字段。仅请求正文中提供的字段将被更新。

参数	类型	描述
id	字符串，必需	要更新的智能体的ID。
name	字符串，可选	智能体的新名称。
description	字符串，可选	智能体的新描述。
modelName	字符串，可选	智能体将使用的新大语言模型。
temperature	数字，可选	新的模型温度（最小值0.0，最大值1.0）。
systemPrompt	字符串，可选	智能体的新系统提示。
visibility	字符串，可选	智能体的新可见性（例如'public'，'private'）。
handle	字符串，可选	智能体的新唯一标识符（slug）。
interfaceConfig	对象，可选	此智能体的新聊天界面设置。
configUrlExternal	对象，可选	新的外部URL配置。
configUrlInfosSystemExternal	对象，可选	系统的新外部URL配置。

delete_agent

删除指定的智能体。

参数	类型	描述
id	字符串，必需	要删除的智能体的唯一标识符。

list_agents

检索所有可用智能体的列表。 此工具不接受参数。

get_agent

检索单个智能体的详细信息。

参数	类型	描述
id	字符串，必需	要检索的智能体的唯一标识符。

agent_query

向智能体发送查询或消息以进行处理。

参数	类型	描述
id	字符串，必需	将接收查询的智能体的唯一标识符。
query	字符串，必需	要发送给智能体的问题或命令的文本。
conversationId	字符串，可选	现有对话的标识符。如果提供，查询将成为该对话历史的一部分。

enable_disable_agent_integration

启用或禁用智能体的特定集成。

参数	类型	描述
id	字符串，必需	智能体的唯一标识符。
type	字符串，必需	要修改的集成类型（例如'whatsapp'，'telegram'）。
enabled	布尔值，必需	设置为true以启用集成，或设置为false以禁用它。

create_crm_scenario

在CRM中创建一个新场景。

参数	类型	描述
name	字符串，必需	新CRM场景的名称。
description	字符串，可选	场景目的的描述。

update_crm_scenario

更新现有的CRM场景。

参数	类型	描述
id	字符串，必需	要更新的场景的唯一标识符。
name	字符串，必需	场景的新名称。
description	字符串，可选	场景的新描述。

delete_crm_scenario

删除一个CRM场景。

参数	类型	描述
id	字符串，必需	要删除的场景的唯一标识符。

list_crm_scenarios

列出所有CRM场景。

参数	类型	描述
agentId	字符串，可选	如果提供，过滤列表以仅显示与此智能体ID关联的场景。

create_crm_step

在CRM场景中创建一个新步骤。

参数	类型	描述
scenarioId	字符串，必需	要添加此步骤的场景的唯一标识符。
name	字符串，必需	新步骤的名称。

update_crm_step

更新CRM场景中的现有步骤。

参数	类型	描述
id	字符串，必需	要更新的步骤的唯一标识符。
name	字符串，必需	步骤的新名称。

delete_crm_step

从CRM场景中删除一个步骤。

参数	类型	描述
id	字符串，必需	要删除的步骤的唯一标识符。

list_crm_steps

列出给定CRM场景的所有步骤。

参数	类型	描述
scenarioId	字符串，必需	要列出其步骤的场景的唯一标识符。

create_datastore

创建一个新的数据存储。

参数	类型	描述
type	字符串，必需	要创建的数据存储类型（例如'qdrant'）。
name	字符串，可选	数据存储的名称。
description	字符串，可选	数据存储的内容或目的的描述。

get_datastore

检索特定数据存储的信息。

参数	类型	描述
id	字符串，必需	要检索的数据存储的唯一标识符。
search	字符串，可选	用于在数据存储中查找特定数据的搜索词。

list_datastores

检索所有数据存储的列表。 此工具不接受参数。

create_datasource

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

参数	类型	描述
datastoreId	字符串，必需	将创建数据源的数据存储的唯一标识符。
name	字符串，必需	数据源的名称，通常用作文件名。
text	字符串，必需	数据源的实际文本内容。