金大哥 - chatvolt-mcp MCP 详情

article

README

🚀 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服务器 (`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

流程描述：

请求接收：MCP服务器接收CallToolRequest。此请求由在src/server.ts中定义的通用CallToolRequestSchema处理程序处理。
处理程序调度：服务器从toolHandlers对象中查找特定的工具处理程序，该对象将工具名称（例如"delete_agent"）映射到相应的处理程序函数（例如handleDeleteAgent）。此对象从中央src/tools/索引文件导入。
工具执行：执行匹配的处理程序函数。例如，调用src/tools/deleteAgent.ts中的handleDeleteAgent。
业务逻辑：工具处理程序从请求中提取必要的参数，验证它们，然后调用src/services/层中的相关函数（例如deleteAgent(id)）。
API交互：服务函数负责向Chatvolt平台发出实际的API调用。
响应格式化：工具处理程序从服务接收数据，将其字符串化（在本例中为JSON），并将其包装在MCP SDK期望的格式中。
响应传输：服务器将最终格式化的内容发送回发起调用的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. 工具定义和注册

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

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

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

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

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`

`update_agent`

`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`

`get_datastore`

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

`list_datastores`

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

`create_datasource`

chatvolt-mcp

README

🚀 Chatvolt MCP服务器：高层概述

🚀 快速开始

✨ 主要特性

🔧 技术细节

关键技术

主要组件

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

2. 工具 (src/tools/)

3. 资源和提示

📦 安装指南

📚 详细文档

Chatvolt MCP服务器：详细架构

1. 请求生命周期：CallTool

2. 目录结构

3. 工具定义和注册

系统提示文档

系统提示的目的

关键指令和场景

1. 简单工具操作

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

3. 自我发现和学习

📄 API和工具参考

create_agent

update_agent

delete_agent

list_agents

get_agent

agent_query

enable_disable_agent_integration

create_crm_scenario

update_crm_scenario

delete_crm_scenario

list_crm_scenarios

create_crm_step

update_crm_step

delete_crm_step

list_crm_steps

create_datastore

get_datastore

list_datastores

create_datasource

运行方式说明

托管运行

本地运行 / 其它方式