Convocore

Convocore MCP Server

一个 Model Context Protocol (MCP) 服务，可将 AI 助手（Claude Desktop、Cursor 和其他 MCP 主机）连接到 Convocore HTTP API。主机启动此进程，通过 stdio（标准输入／输出）与其通信，从而获取多种工具，用于处理 Agent、对话、知识库（包括批量导入 URL）和单个 URL 抓取。

---

本项目是什么

部分	作用
MCP	一种协议，客户端（例如 Claude）可借此列出并调用带有结构化参数的工具，并获取文本（或其他）结果。
本服务	一个使用 @modelcontextprotocol/sdk 的小型 Node.js 应用：它注册工具，使用 Zod 验证参数，并通过你的工作区 bearer token代理调用 Convocore REST API。
Convocore API	位于 https://{region}-api.vg-stuff.com/v3 的后端（参见区域）。你的 WORKSPACE_SECRET 将作为 Authorization: Bearer … 发送。

此代码库不是聊天界面，而是支持 MCP 的助手与 Convocore 之间的桥梁。

---

服务公开的能力

该服务仅声明工具（代码中没有 MCP 资源或提示词）。每次成功调用工具都会返回 MCP 内容，其中包含一个 text 部分，正文是 Convocore API 响应的美化格式 JSON（JSON.stringify(result, null, 2)）。

区域	工具	用途
Agents	~12	CRUD、列表、搜索、导出/导入、克隆、使用情况、CSS、修补提示词
Conversations	~12	CRUD、列表、导出、分配、批量/查询、渠道发送
知识库	~14	CRUD、修补、批量获取/创建/删除、URL 导入、搜索、图片、配额
组织 / 代理机构 / 客户	6	orgs_read/write、agency_read/write、clients_read/write
Leads CRM	2	leads_read / leads_write（列表、导出、导入、智能导入，…）
Agent HTTP 工具	5	列出/获取/创建/更新/删除 Convocore Agent 工具（不是 MCP 工具）
Agent 变量	5	列出/获取/创建/更新/删除 Agent 变量
渠道	4	get_agent_channels、create_channel_connect_link、get_connect_link_status、disconnect_meta_page — 通过免登录链接连接 WhatsApp / Messenger / Instagram
WhatsApp AI 规则	3	get_whatsapp_ai_rules、update_whatsapp_ai_rules、update_whatsapp_number_settings — 控制 AI 在 WhatsApp 上何时回复
Campaigns	2	campaigns_read / campaigns_write — 外呼活动（创建、编辑、启动/停止、重启、删除）
通话日志	2	call_logs_read / call_logs_write — 列表、获取、导出、创建、编辑、删除
外呼和 SMS	4	get_agent_phone、start_outbound_call、send_sms、contact_leads
自定义指标	2	custom_metrics_read / custom_metrics_write — 定义指标并读取其数据
Leads 分组	2	lead_groups_read / lead_groups_write — 列表、创建、分配、重命名、删除
文件夹	2	folders_read / folders_write — Agent 文件夹
Agent 附加功能	5	get_agent_audit_log、send_handoff_reminder、generate_conversation_summaries、agent_gallery_templates、notification_email
WhatsApp 管理	6	whatsapp_numbers_read/write、whatsapp_templates_read/write、whatsapp_campaigns_read/write
Meta 页面、SMS、电子邮件	5	meta_pages_read、sms_numbers_read/write、email_channel_read/write
集成	3	integrations_read / integrations_write / integrations_test — 管理每项连接（Google Calendar、Outlook Calendar、Google Sheets、Airtable、Shopify、Calendly、Zoho CRM、Gmail、Outlook 邮件、Zoho Mail、Google Drive），在 Agent 上分配/更新/移除连接，诊断 Agent 的设置，并检查或运行 Agent 的实际集成工具
Zoho CRM 记录	2	zoho_crm_records_read / zoho_crm_records_write — 列表、搜索、COQL、获取；创建、更新、插入或更新、删除、备注
联系人	2	contacts_read / contacts_write — 跨渠道身份
Agent 备份	2	agent_backups_read / agent_backups_write — 备份、恢复、还原提示词、提示词缓存
代码工具和共享	2	code_tools、tool_sharing
工作区	3	workspace_read / workspace_write、generate_lead_funnel
测试	3	test_agent_tool、test_agent_tool_request、run_agent_auto_test
发现	1	search_mcp_tools — 无需猜测即可找到合适的工具
抓取 / 嵌入 / 语音	多个	抓取、嵌入代码、语音、Twilio 实用工具
交互（WS）	1	驱动一个 Agent 轮次；支持 toolTest + variablesOverrides
规格	3	UI Engine、渠道集成、定价

---

轻量模式

从“Campaigns”到“Agent extras”各行中的工具（以及所有列表工具）都接受 mode：

• compact（默认）：包含每条记录和字段，但会截断较长文本，并用大小标记替代较大的数据块（转录内容、页面内容、历史记录）。
• full：完整的 API 响应。

运行方式（传输和生命周期）

1. 宿主端（Claude Desktop、Cursor 等）将服务器作为子进程启动：例如 npx -y convocore-mcp、docker run … 或 node dist/index.js。
2. 通信使用 StdioServerTransport：通过 stdin/stdout 传输 JSON-RPC 消息。不要将日志写入 stdout；服务器将日志写入 stderr（例如 Convocore MCP Server running on stdio）。
3. 启动时，getConfig() 会读取环境变量。如果缺少 WORKSPACE_SECRET，进程会抛出异常并退出。
4. 宿主端会发送 tools/list 和 tools/call。每次调用都会经过验证，然后由 ConvocoreClient 使用 fetch() 调用 REST API。

flowchart LR
  Host[MCP host]
  MCP[convocore-mcp stdio]
  API[Convocore REST API v3]
  Host <--> MCP
  MCP --> API

---

仓库结构

路径	用途
src/index.ts	MCP 服务、工具定义（供宿主端使用的 JSON Schema）、Zod 验证、工具分发
src/convocore-client.ts	HTTP 客户端：路径、方法、查询字符串、JSON 请求体
src/agent-theme-palette.ts	hexToHsl / handleAutoGenPallet — 为 customThemeJSONString 构建 nineColorPallet
src/config.ts	WORKSPACE_SECRET、CONVOCORE_API_REGION、可选的 CONVOCORE_WORKSPACE_ID、解析后的 baseUrl
src/types.ts	配置和 Agent 负载的共享 TypeScript 类型
dist/	编译输出（pnpm run build / tsc）——npm 发布的内容
Dockerfile	多阶段镜像：使用 pnpm 构建，通过 node dist/index.js 运行（另一种分发方式）
docker-compose.yml	服务示例（参见 Docker Compose 说明）
claude_desktop_config.example.json	Claude Desktop MCP 配置示例
openapi.json	OpenAPI 规范（API 结构参考）

---

环境变量

变量	必需	默认值	含义
WORKSPACE_SECRET	是	—	Convocore 工作区的 Bearer 令牌（与你在控制面板中获取的 API 密钥/密钥相同）。
CONVOCORE_API_REGION	否	eu-gcp	eu-gcp 或 na-gcp；用于选择 API 主机（见下文）。
CONVOCORE_API_BASE_URL	否	—	可选的完整 REST 基础 URL 覆盖值。适用于本地开发，例如 http://localhost:5000/v3。设置后会覆盖 CONVOCORE_API_REGION。除非同时设置 CONVOCORE_INTERACT_WS_URL，否则 /interact WebSocket URL 将根据此值生成（将协议替换为 ws/wss，路径替换为 /interact）。
CONVOCORE_INTERACT_WS_URL	否	—	仅用于覆盖 /interact WebSocket URL 的可选显式值，例如 ws://localhost:5000/interact。如果希望 REST 流量使用生产环境，而 WebSocket 流量使用本地调试服务（或反之），请设置此变量。该值将原样使用——请提供协议、主机、端口和路径。
CONVOCORE_WORKSPACE_ID	否	—	工作区/组织 UUID（agent.ownerID）。设置后，MCP 将避免执行仅用于推断工作区 ID 的高开销 GET /agents 扫描。
CONVOCORE_TELEMETRY	否	on	设置为 0 可关闭匿名使用情况遥测。参见遥测。

服务器会读取 WORKSPACE_SECRET、CONVOCORE_API_REGION、可选的 CONVOCORE_API_BASE_URL、可选的 CONVOCORE_INTERACT_WS_URL、可选的 CONVOCORE_WORKSPACE_ID，以及可选的 CONVOCORE_TELEMETRY / CONVOCORE_TELEMETRY_DEBUG / DO_NOT_TRACK。除非你自行接入，否则 compose 文件或文档中的其他变量都会被忽略。

API 区域和基础 URL

CONVOCORE_API_REGION	基础 URL
eu-gcp	https://eu-gcp-api.vg-stuff.com/v3
na-gcp	https://na-gcp-api.vg-stuff.com/v3

本地开发时，设置 CONVOCORE_API_BASE_URL=http://localhost:5000/v3 可同时重定向 REST 和 WebSocket 流量；或者设置 CONVOCORE_INTERACT_WS_URL=ws://localhost:5000/interact，仅重定向 /interact WebSocket，而 REST 仍使用区域主机。

---

身份验证

ConvocoreClient 发出的每个请求都包含：

• Authorization: Bearer <WORKSPACE_SECRET>
• Content-Type: application/json

对于非 OK 响应：会将响应正文解析为 JSON；如果存在 message，则将其作为错误抛出，否则抛出通用状态消息。请勿将 WORKSPACE_SECRET 放入提示词、屏幕截图或共享配置中；请使用环境变量或宿主的机密管理机制。

灰标客户端连接

代理机构可让白标客户通过中立主机（https://mcp-project.vg-stuff.com/mcp，可通过 GRAY_LABEL_MCP_HOSTS 添加额外主机）将 Claude、ChatGPT 或 Cursor 连接到仅分配给该客户的 Agent，并使用代理机构的品牌。

• 代理机构为客户启用AI 助手访问权限（在客户上设置 mcpAccess）。客户在其仪表板中点击连接 AI；API 会生成一个 gl_… 连接令牌，并以哈希形式存储在代理机构工作区中（users/{workspaceId}/mcpClientConnections）。
• 代理机构主机仅接受 gl_ 令牌，且 gl_ 令牌仅在该主机上有效。API 会将每次调用限定为该客户的 Agent（实时读取 client.widgetIDs ∪ org.widgetIDs），并拒绝工作区级路由；此服务还会缩小工具列表范围并检查 Agent ID。
• 服务名称、说明、工具文本、结果、错误和 OAuth 连接页面均使用代理机构品牌（{Agency} - {Client}），绝不显示平台品牌。打开的会话每分钟刷新一次权限范围和品牌；撤销连接或关闭访问权限后，连接即会停止。

---

快速开始

前置条件

• Convocore 工作区密钥（WORKSPACE_SECRET）。
• 可选：正确的区域（eu-gcp / na-gcp）。
• Node.js 20+（附带 npx）。Docker 为可选项，仅容器工作流需要。

选项 A：npx（推荐）

无需安装任何内容。MCP 宿主（Claude Desktop、Cursor 等）会按需运行服务：

npx -y convocore-mcp

在宿主的 env 块中设置 WORKSPACE_SECRET（以及可选的 CONVOCORE_API_REGION）——请参阅下方的 Claude Desktop 示例。

首次调用时会下载软件包（耗时几秒）；之后的运行会由 npm 缓存。

选项 B：Docker

docker run -i --rm \
  -e WORKSPACE_SECRET="your_workspace_secret_here" \
  -e CONVOCORE_API_REGION="eu-gcp" \
  moe003/convocore-mcp:latest

-i 会保持标准输入打开，以便 MCP 宿主能够通过 JSON-RPC 与容器通信。

选项 C：本地 Node（开发）

git clone https://github.com/moe003/convocore-mcp.git
cd convocore-mcp
pnpm install
pnpm run build
export WORKSPACE_SECRET="your_workspace_secret_here"
export CONVOCORE_API_REGION="eu-gcp"
node dist/index.js

---

连接 MCP 宿主

Claude Desktop

配置文件路径：

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows： %APPDATA%\Claude\claude_desktop_config.json
• Linux： ~/.config/Claude/claude_desktop_config.json

npx（推荐）：

{
  "mcpServers": {
    "convocore": {
      "command": "npx",
      "args": ["-y", "convocore-mcp"],
      "env": {
        "WORKSPACE_SECRET": "your_workspace_secret_here",
        "CONVOCORE_API_REGION": "eu-gcp"
      }
    }
  }
}

Windows 注意事项： 如果 Claude Desktop 无法直接启动 npx，请使用 cmd 包装：

{
  "mcpServers": {
    "convocore": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "convocore-mcp"],
      "env": {
        "WORKSPACE_SECRET": "your_workspace_secret_here",
        "CONVOCORE_API_REGION": "eu-gcp"
      }
    }
  }
}

保存配置后，完全退出并重新启动 Claude Desktop。convocore 服务应会出现在 MCP 服务列表中，聊天中也会提供相应工具。

Docker（替代方案）： 请先拉取镜像，以避免宿主首次运行超时：

docker pull moe003/convocore-mcp:latest

{
  "mcpServers": {
    "convocore": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "WORKSPACE_SECRET=your_workspace_secret_here",
        "-e", "CONVOCORE_API_REGION=eu-gcp",
        "moe003/convocore-mcp:latest"
      ]
    }
  }
}

本地 Node（开发）： 请使用 dist/index.js 的绝对路径：

{
  "mcpServers": {
    "convocore": {
      "command": "node",
      "args": ["/absolute/path/to/convocore-mcp/dist/index.js"],
      "env": {
        "WORKSPACE_SECRET": "your_workspace_secret_here",
        "CONVOCORE_API_REGION": "eu-gcp"
      }
    }
  }
}

Cursor 和其他客户端

任何支持 stdio MCP 服务的客户端都可以使用与上述相同的 command + args + env 模式。推荐的 command/args 为 npx + ["-y", "convocore-mcp"]；Docker 和本地 Node 也可使用。请设置相同的环境变量。

仪表板一键安装（托管式 MCP）

对于工作区仪表板按钮，请调用托管式辅助服务，并传入 MCP URL、区域和工作区密钥：

curl -sS -X POST https://mcp.convocore.ai/v1/install-links \
  -H 'Content-Type: application/json' \
  -d '{
    "mcpUrl": "https://mcp.convocore.ai/mcp",
    "workspaceSecret": "vg_…",
    "region": "na-gcp",
    "workspaceName": "Acme Agency"
  }'

响应重点 — 对于 Claude、Cursor 和其他宿主，连接器 / 安装 name 默认为 Convocore {workspaceName}（例如 Convocore Acme Agency）：

字段	用途
name	显示名称，用于 Claude connectorName、Cursor deeplink name 和 Claude Desktop 密钥
cursor.deeplink	添加到 Cursor — 真正的一键安装（cursor://…/mcp/install，配置中包含 URL、Authorization 和 X-Convocore-Region，并以 base64 编码）
cursor.webFallback	如果尚未注册协议处理程序，则使用 https://cursor.com/en/install-mcp?…
claude.installUrl	添加到 Claude — 打开预填内容的官方自定义连接器弹窗
claude.connectorUrl	/t/<base64url(secret)>/mcp?region=…（Claude 会从 OAuth resource 中移除 ?token=，因此路径中保留密钥）
claudeDesktop	可选的本地 mcp-remote JSON，供 Claude Desktop 配置文件使用

为什么 Claude 需要 ?token=（以及宿主上的 OAuth）

• Cursor deeplink 会将标头嵌入 base64 — 密钥随安装链接一同传递。
• Claude 的安装 URL 只会预填 名称和连接器 URL。不支持标头查询参数。
• 随后，Claude 会向 MCP 宿主执行 OAuth Dynamic Client Registration。如果没有 /oauth/register 和 authorize/token，就会出现 “无法在 Convocore 的登录服务中注册”。
• 托管式 MCP 实现了该 OAuth AS。Claude 通常会从 OAuth resource 中移除 ?token=，因此密钥位于路径中（/t/…/mcp）。授权页面会显示一键式 连接 页面（自动提交）— 无需粘贴。访问令牌就是工作区密钥，expires_in 约为 10 年，并支持刷新。
• 默认情况下，MCP 传输会话在空闲约 1 年后被清除（CONVOCORE_HOSTED_SESSION_IDLE_MS=0 可禁用清除）。重新连接会使用相同密钥创建新会话。

安全提示： 在 Claude 连接器 URL 中使用 ?token= 是一种务实的权衡（日志 / 历史记录）。尽可能优先使用 Cursor 标头；如果链接泄露，请轮换工作区密钥。

你也可以在客户端使用 dist/install-links.js 中的 buildInstallLinks 构建相同的 URL，无需调用 API。

---

HTTP API 映射（各工具调用的接口）

所有路径均相对于 baseUrl（例如 https://eu-gcp-api.vg-stuff.com/v3）。

工具	方法	路径 / 模式
create_agent	POST	/agents 请求体 { agent: { … } }（旧版 / 原始模式）
create_agent_from_template	POST 工作流	首选：明确指定 systemPrompt / 品牌信息 / 合并后的 voiceConfig；可选执行 sourceUrl 抓取和知识库操作；然后调用 POST /agents；响应通过后续的 get_agent 调用返回完整 Agent
get_agent	GET	/agents/{agentId}
update_agent	PATCH	/agents/{agentId} 请求体 { agent: { … } }
patch_agent_prompt	GET+PATCH	先调用 get_agent，再对提示词 / CSS 字段执行精确的 old_string→new_string 替换（Cursor StrReplace 风格）；PATCH 仅包含已更改的字段
delete_agent	DELETE	/agents/{agentId}
list_agents	GET	/agents 支持时可选添加 ?limit=
search_agents	GET	/agents/search?workspaceId=…&page&limit&sortBy&starredOnly&search?（根据 MCP 配置 / 工作区密钥上下文在内部解析工作区）
export_agent	GET	/agents/{agentId}/export-template
import_agent	POST	/agents/import-template
get_agent_usage	POST	/agents/{agentId}/usage 请求体 { range }
list_conversations	GET	/agents/{agentId}/convos?limit&cursor（游标分页；不带游标时会拒绝 page>1）
get_conversations_bulk	GET×N	扇出调用 GET /agents/{agentId}/convos/{convoId}（最多 50 个 ID，并发池）
query_conversations	MCP	游标列表 + 批量筛选（非服务端 SQL；受 maxScan 限制）
get_agent_usage_bulk	POST×N	扇出调用 POST /agents/{agentId}/usage（最多 20 个 Agent）
get_kb_docs_bulk	GET×N	扇出调用 GET /agents/{agentId}/kb/{docId}（最多 30 个文档）
create_conversation	POST	/agents/{agentId}/convos 请求体 { conversation }
get_conversation	GET	/agents/{agentId}/convos/{convoId}
update_conversation	PATCH	/agents/{agentId}/convos/{convoId} 请求体 { conversation }
list_conversation_notes	GET	/agents/{agentId}/convos/{convoId}/notes
add_conversation_note	POST	/agents/{agentId}/convos/{convoId}/notes 请求体 { text, authorName? }
update_conversation_note	PATCH	/agents/{agentId}/convos/{convoId}/notes/{noteId} 请求体 { text, authorName? }
delete_conversation_note	DELETE	/agents/{agentId}/convos/{convoId}/notes/{noteId}
delete_conversation	DELETE	/agents/{agentId}/convos/{convoId}
export_all_conversations	GET	/agents/{agentId}/convos/export?format=&limit=&cursor=&…（需要付费工作区 / hasEverPaid）
export_conversation	GET	/agents/{agentId}/convos/{convoId}/export?format=
assign_conversation	POST	/agents/{agentId}/convos/{convoId}/assign 请求体 { assignToUserId, delegatedBy? }
create_kb_from_urls	POST×N 或 1	扇出 / 批量调用 POST /agents/{agentId}/kb，并设置 sourceType=url + scrapeContent
create_kb_doc	POST	/agents/{agentId}/kb 请求体：知识库字段
list_kb_docs	GET	/agents/{agentId}/kb?page&pageSize
get_kb_doc	GET	/agents/{agentId}/kb/{docId}
update_kb_doc	PATCH	/agents/{agentId}/kb/{docId}
patch_kb_doc	GET+PATCH	先调用 get_kb_doc，再对 content / name 执行精确的 old_string→new_string 替换（Cursor StrReplace 风格）
delete_kb_doc	DELETE	/agents/{agentId}/kb/{docId}
get_kb_stats	GET	/agents/{agentId}/kb/stats
scrape_url	HTTP ping 或爬虫	mode=check（默认）：快速检查最多 20 个 URL / 图片的状态；mode=scrape：完整抓取页面（1 个 URL）
interact_with_agent	WSS	wss://{region}-gcp-api.vg-stuff.com/interact（输入单个 InteractObject，流式输出 ChunkMessage）
get_ui_engine_spec	n/a	静态参考 — 不调用 API

---

工具参考（参数和说明）

Agent 工具

create_agent_from_template——从零创建聊天 + 语音 Agent 的首选方式。 工作区由内部解析（无需输入 workspaceId）。建议显式提供以下字段：title、systemPrompt、voiceConfig（必须仅使用 google-live 或 ultravox 作为 speechGen.provider——在这些提供商上使用 search_voices）、primaryColor（十六进制颜色值；尽可能采用 scrape_url 获取的颜色）、widgetImageUrl（徽标 URL，例如 scrape_url 获取的 favicon）。可选字段：voicePrompt（Gemini Live systemInstruction；省略时 → 复用 systemPrompt）、description、themeType（light|dark，默认为 light）、sourceUrl（可选的抓取等待时间 + 摘录）、createKbUrlDoc（设为 true 时必须提供 sourceUrl）、defaultLanguage（默认为 multilingual）、proactiveMessage、branding、chatBgURL、additionalConfig。

• AI 工作流：先运行 scrape_url → 选择颜色和 favicon URL → 在 google-live / ultravox 上运行 search_voices 查找口音 → 然后使用明确的提示词和完整的 voiceConfig 调用此工具。
• MCP 根据 primaryColor 构建 customThemeJSONString（nineColorPallet，采用与 Convocore handleAutoGenPallet 相同的亮度渐变）。
• 创建后，MCP 会调用 get_agent，并将 data.agent 作为完整文档返回（另附 agentId）。
• 优先设置环境变量 CONVOCORE_WORKSPACE_ID，以便 MCP 无需从 list_agents 推断工作区。

create_agent——高级／手动控制负载的旧版直接模式。必填：title。可选：description、theme、disabled、light、enableVertex、autoOpenWidget、voiceConfig、nodes、additionalConfig。

• 除非确实需要低级别的手动字段控制，否则优先使用 create_agent_from_template。
• nodes： Convocore 的多步骤图；nodes[0].instructions 是主要系统提示词。
• additionalConfig： 合并到 agent 负载中的普通对象（与其他字段处于同一层级）。用于设置未显式列出的字段。

get_agent——必填：agentId。响应包含 Agent JSON；如存在，主要提示词位于 nodes[0].instructions 下。

update_agent——必填：agentId。可选：与创建时相同的 Agent 字段；补丁语义取决于 API。若要更改主要提示词，请更新 nodes[0].instructions。对于较长的提示词，优先使用 patch_agent_prompt。

patch_agent_prompt——类似光标操作的精准编辑。必填：agentId、old_string、new_string。可选：replace_all、target（auto|nodes0|vg_instructions|vg_systemPrompt|proactiveMessage|customCSS——vg_* 仍会写入 nodes[0].instructions）、sync_mirrors（默认为 false；绝不会 PATCH vg_instructions）。若找不到 old_string 或其匹配项不唯一，则操作失败（除非设置了 replace_all）。

AI 漏斗／潜在客户评分——在创建／更新时使用 funnelConfig + leadCollectionRules，或在 create_agent_from_template 中使用 ownerNotifyEmails。运行时会向销售人员发送有关高意向潜在客户的邮件。不要附加自定义 HTTP“通知销售”Webhook 工具。

delete_agent——必填：agentId。在 API 端永久删除。

list_agents——可选：limit（当 API 支持 ?limit= 时限制获取数量）。对于大型工作区，优先使用 search_agents 或 CONVOCORE_WORKSPACE_ID，而不是不设上限地列出所有 Agent。

search_agents——无需必填参数。可选：search、page（默认为 1）、limit（默认为 50）、sortBy（newest | oldest | alphabetical，默认为 newest）、starredOnly（默认为 false）。工作区由 MCP 内部解析。

export_agent——必填：agentId。返回用于备份／迁移的模板 JSON。

import_agent——必填：agentTemplate、agentName。可选：fromAgentId。

get_agent_usage——必填：agentId。可选：range: { from, to } ISO 日期字符串。

对话工具

list_conversations — 必填：agentId。选填：limit（默认值为 20，最大值为 20）、cursor（来自上一次响应的 nextCursor）。响应：data、hasMore、nextCursor、limit。获取第 2 页及之后的页面时，请传入 cursor——不要只增加 page（API 会拒绝不带 cursor 的 page>1 请求）。列表从 Postgres 镜像读取；列表行通常缺少 summary / capturedVariables。

get_conversations_bulk — 必填：agentId、convoIds（1–50）。扇出发送 GET 请求；返回精简的 { ID, summary, ts, capturedVariables, userName, origin } 以及 failed[]。较大规模的审计请分批处理。

query_conversations — 必填：agentId。选填筛选条件：origin、tsFrom/tsTo、capturedVariableExists、capturedVariableEquals、summaryContains、hasUserName，以及 limit / maxScan。由 MCP 端扫描（而非 SQL）。

get_agent_usage_bulk — 必填：agentIds（1–20）。选填：共享的 range。

get_kb_docs_bulk — 必填：agentId、docIds（1–30）。选填：includeContent（默认值为 false）。

create_conversation — 必填：agentId、conversation。API 要求对话对象中至少包含一个 ts（时间戳）；可根据你的 Convocore 配置添加 userName、userEmail 等字段。

get_conversation — 必填：agentId、convoId。

update_conversation — 必填：agentId、convoId、conversation（部分字段）。

对话备注 — 每个对话的人为审核备注时间线（reviewNotes，按时间从早到晚排列；get_conversation 也会返回）。add_conversation_note / update_conversation_note / delete_conversation_note 需要 agentId、convoId、text / noteId；authorName（选填）用于标记 API 密钥调用者，例如“Claude via MCP”。无法通过 update_conversation 修改备注。每次更改都会记录在工作区 Logs 中（包括操作者、IP、时间）。query_conversations 支持 hasNotes 和 noteContains。

delete_conversation — 必填：agentId、convoId。

export_all_conversations — 必填：agentId。选填：format（json|csv）、limit、sort、fromTs、toTs、cursor、convoIds。需要付费工作区（hasEverPaid === true）；费用计入每月导出配额。通过 nextCursor / hasMore 使用游标分页。

export_conversation — 必填：agentId、convoId。选填：format——json 或 csv。需要付费工作区（hasEverPaid === true）。

assign_conversation — 必填：agentId、convoId、assignToUserId。选填：delegatedBy。

知识库工具

代码中的工具描述注明 “仅限 VG agents”——知识库操作以 /agents/{id}/kb 为目标，且可能仅适用于 Convocore 端支持的 Agent 类型。

create_kb_from_urls — 多页面场景的首选。 必填：agentId、urls（最多 50 个）。可选：mode（默认 per_url | batch）、name、tags、refreshRate（3d|7d|never）、scrapeContent（默认 true）、skipExisting（默认 true）。使用知识库路由进行抓取——不要先用 scrape_url / 网页抓取进行预抓取。抓取为异步操作；请轮询 list_kb_docs / get_kb_doc。

create_kb_doc — 必填：agentId、name、sourceType：doc | url | sitemap。

• doc： 文本使用 content。
• url： 使用 urls（数组），可选 scrapeContent。
• sitemap： 使用 sitemapUrl，可选 maxPages。

可选：metadata、tags、refreshRate — 3d | 7d | never（默认 never；与 Convocore API 一致）。

list_kb_docs — 必填：agentId。可选：page（默认 1）、pageSize（默认 20）。

get_kb_doc — 必填：agentId、docId。

update_kb_doc — 必填：agentId、docId。可选：name、content、metadata、tags、refreshRate、url。对于较大的请求正文，优先使用 patch_kb_doc。

patch_kb_doc — 采用光标式的精准编辑。必填：agentId、docId、old_string、new_string。可选：replace_all、field（content|name，默认 content）。

delete_kb_doc — 必填：agentId、docId。

get_kb_stats — 必填：agentId。

抓取工具

scrape_url — 提供 url 和/或 urls（最多 20 个）。

• mode: "check"（默认）： 快速 HTTP ping——返回状态（200/404/…）、ok、内容类型，以及重定向后的最终 URL。在将图片、徽标和页面链接接入 Agent 之前，可用它们进行验证。
• mode: "scrape"： 对一个 URL 执行完整的 Convocore 爬虫抓取（等待时间最长约 120 秒），以获取文本/颜色/favicon。工作区将在内部解析。不要用于知识库导入（create_kb_from_urls）。

交互（WebSocket）工具

interact_with_agent 是唯一由 WebSocket 支持的工具。它会与 wss://{region}-gcp-api.vg-stuff.com/interact 建立单个连接，发送一个 InteractObject，并将所有流式传输的 ChunkMessage（chunk / debug / action / metadata / sync_chat_history）汇总为一个 MCP 响应。身份验证使用与 REST 相同的 Authorization: Bearer <WORKSPACE_SECRET> 标头。

必填： agentId、convoId。

常见可选项：

• prompt — 用户消息。特殊值："start"（初始问候语）、"@cancel:<reason>"、"@rewind:<nodeId>"（v2/node Agent）。
• bucket — voiceglow-eu 或 (default)。根据 CONVOCORE_API_REGION 自动推导（eu-gcp → voiceglow-eu，na-gcp → (default)）；只有在需要有意跨区域时才覆盖。
• messageType + visualPayload — 用于图片轮次。
• replyTo — 对先前消息的回复上下文。
• lightConvoData — userName、userEmail、userPhone、origin、capturedVariables 等。支持时，这些内容会显示在 Agent 的系统提示词中。
• agentData / workspaceData / turnsHistory — 用于覆盖并跳过 Firestore 加载。
• disableUiEngine、disableRecordHistory、v2、isTest、isLLMStudio、kbPreview、agentProfileId、toolTest、formSubmissionMetadata、initNodesOptions — 与底层 EWSInteractModel 使用相同的标志。
• timeoutMs（默认 120000，最大 600000）— MCP 等待流式轮次的时长；超时后会强制关闭 WebSocket。
• raw（默认 false）— 为 true 时，响应会包含每个原始流式分块；为 false 时，只返回汇总后的文本、操作、元数据和最终轮次（更省 token）。

响应结构（默认 raw: false）：

{
  "assistantText": "...",
  "uiEngineEnabled": false,
  "uiEngineSnapshot": null,
  "uiEngineSummary": [],
  "actions": [],
  "metadata": { "inputTokens": 0, "outputTokens": 0, "llmUsed": "...", "sources": [], "turns": [] },
  "turns": [],
  "closeCode": 1000,
  "closeReason": "",
  "durationMs": 1234,
  "timedOut": false,
  "chunkCount": 17
}

UI Engine 处理

当 Agent 设置了 vg_enableUIEngine: true（且请求未传入 disableUiEngine: true）时，服务会流式传输 JSON 字符串化的 TurnProps 快照，而不是纯文本。UI Engine 快照采用覆盖式更新（每个数据块都是截至目前的完整机器人回合快照）——interact_with_agent 会解析这些快照，仅保留最新快照作为 uiEngineSnapshot，并生成简洁的 uiEngineSummary，便于快速浏览：

{
  "assistantText": "",
  "uiEngineEnabled": true,
  "uiEngineSnapshot": {
    "from": "bot",
    "ts": 1719931200,
    "messages": [
      { "from": "bot", "type": "text",   "item": { "type": "text",   "payload": { "message": "Pick one:" } } },
      { "from": "bot", "type": "choice", "item": { "type": "choice", "payload": { "buttons": [ { "name": "Pricing", "request": { "type": "text", "payload": { "message": "Tell me about pricing" } } } ] } } }
    ]
  },
  "uiEngineSummary": [
    { "index": 0, "type": "text",   "summary": "Pick one:",                 "webChannelOnly": false },
    { "index": 1, "type": "choice", "summary": "1 button: Pricing",         "webChannelOnly": false }
  ],
  "...": "..."
}

UI Engine 有八种消息类型：text、choice、visual、cardV2、carousel、iFrame、form、input。form 和 input 仅在 Web 渠道上发送（来源为 web-chat / text）。在测试或构建启用了 UI Engine 的 Agent 之前，请先调用 get_ui_engine_spec，以加载完整架构。

费用说明： 每次调用都会运行一次真实的 Agent 回合（大模型 + 语音 + 工具），并像普通聊天一样消耗 Convocore 额度。这不是试运行。

UI Engine 架构工具

get_ui_engine_spec — 返回完整的 Convocore UI Engine 架构。静态知识，不调用 API，也不消耗额度。

• 必填：无。
• 可选：section — "all"（默认）| "meta" | "envelopes" | "message_types" | "shared" | "rules" | "checklist" | "primer"。
• 可选：messageType — "text" | "choice" | "visual" | "cardV2" | "carousel" | "iFrame" | "form" | "input"。设置后，仅返回该消息类型的架构（优先于 section）。

请在以下操作之前使用此工具：

1. 验证 interact_with_agent 的输出是否符合启用了 UI Engine 的 Agent 的要求。
2. 创建或更新 Agent，使其系统提示词能够教会模型发送 UI Engine 消息——将相关规则和 messageType 结构写入 nodes[0].instructions。

---

Convocore 概念：节点和提示词

• 每个节点都可以表示工作流中的一个步骤。
• 第一个节点（nodes[0]）包含定义 Agent 默认行为的主要指令（instructions 字段）。
• light 模式（Agent 标志）：工具内说明称，该模式不会保留聊天记录，以保护隐私。

---

错误和验证

• 工具参数无效： Zod 验证失败 → 返回错误 Invalid arguments: …。
• 未知工具名称： 抛出 Unknown tool: …。
• API 错误： 如果 JSON 正文中有错误消息，则使用该消息抛出错误。
• 启动： 缺少 WORKSPACE_SECRET → 服务连接前发生配置错误。

---

自然语言示例（面向终端用户）

完成配置后，用户可以向助手提出类似请求：

• “列出我的所有 Convocore Agent” → list_agents
• “从头开始为这个网站创建一个 Agent” → create_agent_from_template（首选默认方式）
• “将 Agent … 的所有对话导出为 CSV” → export_all_conversations
• “将许多酒店／网站页面添加到知识库” → create_kb_from_urls（知识库路由器会抓取内容；不要先用 Web 获取内容）
• “将一个 URL／站点地图添加到知识库” → create_kb_doc，并设置 sourceType: url|sitemap + scrapeContent: true
• “这些图片／页面链接失效了吗？” → scrape_url，并设置 mode: "check" + urls: [...]
• “抓取一个 URL，以获取品牌信息（颜色／网站图标）” → scrape_url，并设置 mode: "scrape"

具体选择哪个工具以及传入哪些参数由宿主模型决定；模型看到的是 src/index.ts 中的工具描述。

---

Docker

docker pull moe003/convocore-mcp:latest

常见标签（当前列表请参阅 Docker Hub）：latest、维护者发布的版本标签，例如 2.0.0 / 1.0.x。

本地构建：

docker build -t moe003/convocore-mcp:latest .

Docker Compose

附带的 docker-compose.yml 会以 stdin 保持打开的方式运行镜像，以便用于 MCP。请在环境或 compose 文件旁的 .env 文件中设置 WORKSPACE_SECRET，并可选设置 CONVOCORE_API_REGION。身份验证仅使用 WORKSPACE_SECRET（服务不会读取单独的 API 密钥变量）。

---

开发

命令	操作
pnpm install	安装依赖
pnpm run build	运行 tsc → dist/ 并为二进制文件添加执行权限
pnpm run dev	tsc --watch

依赖：@modelcontextprotocol/sdk、zod，以及文件读取工具链（mammoth、pdf-parse、xlsx、sharp、mime-types）。开发依赖：typescript、@types/node、shx。

发布到 npm（维护者）

pnpm install
pnpm run build
pnpm pack --dry-run     # sanity check the tarball
pnpm publish --access public

prepublishOnly 会自动重新运行构建。发布的内容仅包括 dist/、README.md 和 LICENSE（由 package.json 中的 files 字段控制）。

推送 Docker 镜像（维护者）

docker push moe003/convocore-mcp:latest

---

遥测

与 Next.js 一样，convocore-mcp 会收集匿名使用数据，以了解哪些工具正在使用以及它们在哪些情况下会失败。默认情况下已启用。

**每次工具调用发送的数据：**工具名称、是否成功、简短的错误类别（例如 input_validation_error）；仅在失败时，还会发送一条简短错误消息（其中的电子邮件地址、URL、ID 和数字会被移除）；基于操作的工具的 action（例如 assign_to_agent）、耗时、MCP 客户端名称和版本（例如 Claude Desktop、Cursor）、convocore-mcp 版本、Node.js 版本、操作系统平台，以及当前服务进程的随机 ID。

**绝不会发送的数据：**工具参数、工具结果、提示词、Agent 内容、联系人、对话或任何文件内容。

事件会批量发送到你所在区域的 Convocore API（<base URL>/mcp/telemetry），并使用你的工作区密钥进行身份验证，因此这些事件仅与你的工作区关联。发送操作会在后台进行，不会拖慢工具调用，也不会导致工具调用失败。

选择退出：在 MCP 配置的 env 中设置以下任一变量：

"env": {
  "WORKSPACE_SECRET": "...",
  "CONVOCORE_TELEMETRY": "0"
}

DO_NOT_TRACK=1 也会生效。如需查看将要发送的确切内容，但不实际发送，请设置 CONVOCORE_TELEMETRY_DEBUG=1；事件会打印到 stderr。

托管在 mcp.convocore.ai 的服务运行于 Convocore 基础设施上，并记录相同的事件。

---

贡献与许可证

欢迎通过拉取请求贡献代码。

MIT 许可证——请参阅 LICENSE 文件。

---

链接

• Convocore API / 产品文档
• Model Context Protocol
• npm — convocore-mcp
• Docker Hub — moe003/convocore-mcp
• 问题
• Convocore 支持

---

为 Convocore 社区打造。