Chatvolt MCP

Chatvolt MCP服务器：高级概述

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

项目目标

该项目的主要目标是作为人工智能模型和Chatvolt API之间的桥梁。它公开了一组AI代理可以调用的工具，以执行管理代理、查询数据存储和处理CRM场景等操作。这允许复杂工作流程的自动化，并为Chatvolt平台提供自然语言界面。

关键技术

• Node.js：服务器的运行时环境。
• TypeScript：主要的编程语言，提供静态类型和现代JavaScript功能。
• @模型上下文协议/sdk：用于构建MCP服务器的核心SDK，简化了定义工具、资源和处理来自AI模型的请求的过程。

主要组件

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。此请求由通用程序处理 CallToolRequestSchema 处理程序定义于 src/server.ts.
2. 处理人员派遣： 服务器从以下位置查找特定的工具处理程序 toolHandlers 其映射工具名称（例如。， "delete_agent")将它们对应的处理函数（例如。， handleDeleteAgent).此对象是从中心导入的 src/tools/ 索引文件。
3. 工具执行： 执行匹配的处理程序函数。例如， handleDeleteAgent 在……里面 src/tools/deleteAgent.ts 被称为。
4. 业务逻辑： 工具处理程序从请求中提取必要的参数，验证它们，然后从 src/services/ 层（例如。， deleteAgent(id)).
5. API交互： 服务功能负责对Chatvolt平台进行实际的API调用。
6. 响应格式： 工具处理程序从服务接收数据，将其字符串化（在本例中为JSON），并将其包装为MCP SDK所期望的格式。
7. 响应传输： 服务器将最终的格式化内容发送回发起呼叫的AI代理。

2.目录结构

该项目被组织为独立的关注点，使其模块化和可维护。

• src/：这是所有应用程序源代码的根目录。
• src/tools/：此目录包含服务器公开的每个工具的实现。

- 结构： 每个工具通常都有自己的文件（例如。， deleteAgent.ts). - 内容： 每个文件导出两个主要构造： 1. A. Tool 定义对象（例如。， deleteAgentTool)包含工具的 name, description，以及 inputSchema 根据MCP SDK的要求。 1. 处理器函数（例如。， handleDeleteAgent)它包含执行该工具的逻辑。 - 聚合： A中心 index.js 此目录中的文件负责导入所有单独的工具和处理程序，并将其导出为两个聚合对象： tools （所有工具定义的数组）和 toolHandlers （工具名称到其处理程序的映射）。

• src/services/：此目录旨在容纳与外部服务（主要是Chatvolt API）交互的业务逻辑和API客户端代码。

- 目的： 它充当工具处理程序和底层平台之间的桥梁。这种分离确保了工具处理程序只负责请求/响应处理和参数验证，而服务层管理API通信的细节。 - 例子： 这 deleteAgent 功能，从导入 ../services/chatvolt.js，将包含 fetch 发送所需的调用和逻辑 DELETE 向Chatvolt提出请求 /agents/:id 终点。

3.工具定义和注册

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

1. 工具定义： 每个工具都被定义为一个类型为的常量对象 Tool 从 @modelcontextprotocol/sdk/types.js 图书馆。该对象包括：

- name：工具的唯一机器可读名称（例如。， "delete_agent"). - description：工具功能及其参数的人类可读描述。而资源文件类似 TOOL_DESCRIPTIONS.md 存在为AI模型提供详细文档的功能 description 工具定义中的属性本身就是一个简洁的总结。 - inputSchema：一个JSON Schema对象，正式定义了工具接受的参数，包括它们的类型以及它们是否是必需的。

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

- 这 tools 阵列和 toolHandlers 地图从以下位置导入 src/tools/index.js 进入 src/server.ts. - 这 ListToolsRequestSchema 处理程序在 src/server.ts 使用导入的 tools 数组以响应对可用工具列表的请求。 - 这 CallToolRequestSchema 处理程序使用 toolHandlers 根据映射查找并执行正确的函数 name 传入请求中的参数。

这种架构创建了一个解耦的系统，通过在 src/tools/ 目录和更新中心 index.js 文件，无需修改中的核心服务器逻辑 src/server.ts.

______________________________________________________________________

系统提示文档

本文档解释了用于指导AI代理在与Chatvolt MCP（模型上下文协议）交互时的行为的系统提示的作用和内容。这些提示在 SYSTEM_PROMPTS.md 文件，并为AI提供一组基础指令。

系统提示的目的

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

关键说明和场景

这 SYSTEM_PROMPTS.md 该文件概述了三种主要场景，每种场景都有相应的系统提示来指导人工智能的行为。

1.工具操作简单

• 目的：处理可以通过单个工具调用完成的简单用户请求。
• AI角色：Chatvolt平台的人工智能专家助理。
• 核心指令:

1. 识别用户的意图。 1. 选择单个最合适的工具（例如。， list_agents). 1. 使用正确的参数执行工具。 1. 向用户报告结果。

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

• 目的：管理需要一系列工具调用才能实现更大目标的复杂任务。
• AI角色：负责编排工作流程的高级人工智能自动化工程师。
• 核心指令:

1. 解构：将用户的请求分解为更小的、连续的步骤。 1. 计划：制定一个循序渐进的计划，为每个步骤确定合适的工具。 1. 执行：按顺序调用工具，等待每个工具成功完成，然后再继续下一个。一个工具的输出可以用作另一个工具。 1. 合成：提供所采取的所有行动和结果的最终总结。

3.自我发现和学习

• 目的：使人工智能在执行任务之前能够足智多谋并了解自己的能力。
• AI角色：高度自主和主动的人工智能代理。
• 核心指令:

1. 自我发现优先：在尝试复杂任务之前，AI 必须 第一个电话 getDocumentation 该工具用于检索有关其所有可用工具的信息。 1. 分析：查看文档以了解其功能。 1. 计划根据新获得的工具知识制定计划。 1. 执行：执行计划并报告结果。

______________________________________________________________________

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

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