Chatvolt MCP服务器
用于Chatvolt AI的MCP（模型上下文协议）服务器，为管理代理、联系人、对话、CRM工作流等提供工具、资源、提示和完成。
特性
- 苏格兰和南方能源公司运输：使用服务器发送事件通过HTTP运行。
- 81工具：全面覆盖Chatvolt API端点。
- 工具注释：每个工具都有
readOnlyHint,destructiveHint,idempotentHint，以及openWorldHint用于安全AI执行的注释。 - 动态工具发现：自动将Chatvolt OpenAPI规范映射到MCP工具。
- 8工作流程提示：为常见任务预先定义的指导工作流程。
- 资源：访问代理配置、工具和提示作为MCP资源。
- 补全：自动建议模型名称、状态、通道等。
- 结构化错误：所有错误返回JSON
{error, status, message}为了便于解析。 - 基于Python：使用Python和
uv.
安装
- 安装uv:
curl -LsSf https://astral.sh/uv/install.sh | sh- 克隆和初始化:
cd chatvolt-mcp
uv venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
uv sync- 配置环境:
cp .env.example .env
# Edit .env and add your CHATVOLT_API_KEY运行服务器
uv run python run.py服务器将在以下时间启动 http://localhost:8000.
与MCP客户端一起使用
VS代码/GitHub副本
将以下内容添加到VS代码MCP设置中(.vscode/mcp.json 或用户设置）：
{
"servers": {
"MCP_Chatvolt": {
"url": "http://localhost:8000",
"type": "http"
}
}
}克劳德桌面/MCP检查器/光标
将您的MCP客户端（例如，Claude Desktop、Cursor、VS Code）指向SSE端点：
- 统一资源定位符:
http://localhost:8000/sse
使用OpenCode
- 启动Chatvolt MCP服务器:
uv run python run.py- 配置OpenCode:
将以下内容添加到您的 opencode.jsonc （如果它不存在，请在项目根目录中创建它）：
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"chatvolt": {
"type": "remote",
"url": "http://localhost:8000/sse",
"enabled": true
}
}
}- 启动OpenCode:
opencodeChatvolt MCP工具现在将在您的OpenCode会话中可用。
可用工具（共81个）
代理
query_agent-用消息查询代理get_agent-获取代理详细信息create_agent-创建新代理update_agent-更新代理配置delete_agent-删除代理get_models-列出可用的AI模型toggle_webhook-启用/禁用webhooksget_agent_tools-列出代理工具create_agent_tool-为代理创建工具update_agent_tool-更新代理工具delete_agent_tool-删除代理工具
对话
list_conversations-列出对话get_conversation-获取对话详细信息get_conversation_messages-获取对话消息get_message-获取单个消息set_conversation_ai-切换AI进行对话register_message_in_context-注册消息而不发送create_conversation-创建新对话resolve_conversation-标记为已解决delete_conversation-删除对话request_human_intervention-请求人工切换
联系人
list_contacts-列出联系人get_contact-获取联系方式create_contact-创建联系人update_contact-更新联系人delete_contact-删除联系人get_contact_conversations-获取联系人的对话
电讯
list_dispatches-列出调度活动get_dispatch-获取调度详细信息create_dispatch-创建调度活动update_dispatch-更新调度delete_dispatch-删除调度
人工制品
search_artifacts-搜索工件list_artifacts-列出工件get_artifact-获取工件详细信息create_artifact-创建工件update_artifact-更新工件delete_artifact-删除工件list_artifact_media-列出工件介质upload_artifact_media-上传媒体update_artifact_media-更新媒体delete_artifact_media-删除媒体list_artifact_categories-列出类别create_artifact_category-创建类别get_artifact_category-获取类别update_artifact_category-更新类别delete_artifact_category-删除类别
数据存储和数据源
list_datastores-列出数据存储get_datastore-获取数据存储create_datastore-创建数据存储update_datastore-更新数据存储delete_datastore-删除数据存储query_datastore-查询数据存储list_datasources-列出数据源get_datasource-获取数据源create_datasource-创建数据源update_datasource-更新数据源delete_datasource-删除数据源sync_datasource-触发器同步get_datasource_status-获取同步状态
CRM（Flux CRM）
list_crm_scenarios-列出CRM场景create_crm_scenario-创建场景get_crm_scenario-获取场景update_crm_scenario-更新场景delete_crm_scenario-删除场景list_crm_steps-列出CRM步骤create_crm_step-创建步骤update_crm_step-更新步骤delete_crm_step-删除步骤add_conversation_to_step-将对话添加到步骤move_conversation_to_step-移动对话list_crm_logs-列出CRM日志get_crm_log-获取CRM日志
Z-API（WhatsApp）
zapi_list_instances-列出Z-API实例zapi_send_text-发送短信zapi_send_media-发送媒体消息zapi_send_template-发送模板zapi_send_list-发送列表消息zapi_send_buttons-发送按钮消息
特工黑名单
list_blacklist-列出列入黑名单的用户add_to_blacklist-将用户添加到黑名单remove_from_blacklist-从黑名单中删除
可用提示（共8个）
onboard_new_user-创建联系人并发送欢迎消息broadcast_campaign-设置调度活动create_new_agent-设计和部署新的AI代理setup_datastore-创建数据存储并摄取数据create_crm_workflow-构建CRM场景和步骤whatsapp_outreach-通过Z-API发送WhatsApp消息contact_enrichment-查找和管理联系人agent_health_check-检查代理状态和对话
可用资源
chatvolt://models-可用AI模型信息chatvolt://tools-完整的工具目录chatvolt://prompts-可用提示chatvolt://agent/{agentId}-代理配置模板
Ralph Loop（自主开发）
该项目包括一个用于自主代码改进的Ralph Loop设置。
# Run until all checks pass
./ralph-loop.sh
# Run exactly 5 iterations
./ralph-loop.sh -n 5
# Dry run (see prompt without executing)
./ralph-loop.sh --dry-run循环：
- 运行测试和除尘
- 将结果提供给opencode
- opencode修复问题并提交
- 重复直到所有检查通过
- 空闲时，获取文档以查找改进
发展
# Install dev dependencies
uv sync --group dev
# Run tests
uv run pytest -v
# Run linting
uv run ruff check .
# Auto-fix lint
uv run ruff check --fix .
# Format code
uv run ruff format .项目结构
src/
├── server.py # MCP server with tools, prompts, resources, completions
├── config.py # Environment configuration
├── tools/
│ ├── loader.py # Tool registry with annotations
│ ├── all_definitions.py
│ └── definitions/ # Tool definition modules
│ ├── agents.py
│ ├── conversations.py
│ ├── contacts.py
│ ├── dispatches.py
│ ├── artifacts.py
│ ├── datastores.py
│ ├── datasources.py
│ ├── crm.py
│ ├── crm_scenarios.py
│ ├── crm_logs.py
│ ├── blacklist.py
│ ├── zapi.py
│ └── conversation_mgmt.py
└── prompts/
└── workflows.py # Workflow prompts
tests/
├── test_server.py
├── test_loader.py
└── test_new_features.py
ralph/
├── RALPH.md # Loop prompt
└── .ralph/
└── guardrails.md # Persistent memory
ralph-loop.sh # Loop runner script
TODO.md # Task tracking