Convocore MCP

ConvoCore MCP服务器

A. 模型上下文协议（MCP） 将AI助手（Claude Desktop、Cursor和其他MCP主机）连接到 ConvoCore HTTP API。主持人发起这个过程，与它进行讨论 标准 （标准输入/输出）和增益 24工具 用于代理、对话、知识库和单个URL抓取。

](https://www.npmjs.com/package/convocore-mcp) ](https://hub.docker.com/r/moe003/convocore-mcp) 

______________________________________________________________________

这个项目是什么

此存储库是 不 聊天UI。正是 桥 在MCP功能助手和ConvoCore之间。

______________________________________________________________________

服务器公开的内容（功能）

服务器声明 仅限工具 （代码中没有MCP资源或提示）。每次成功的工具调用都会返回MCP 内容 与单一 文本 身体部位 打印精美的JSON (JSON.stringify(result, null, 2))来自ConvoCore API响应。

______________________________________________________________________

它是如何运行的（运输和生命周期）

1. 这 主机 （Claude Desktop、Cursor等）将服务器作为子进程启动：例如。 npx -y convocore-mcp, docker run …，或 node dist/index.js.
2. 通信用途 StdioServerTransport：stdin/stdout上的JSON-RPC消息。 不要 将日志写入stdout；服务器登录到 标准错误 （例如。 ConvoCore MCP Server running on stdio).
3. 在启动时， getConfig() 读取env变量。如果 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

______________________________________________________________________

仓库布局

______________________________________________________________________

环境变量

服务器读取 WORKSPACE_SECRET, CONVOCORE_API_REGION，可选 CONVOCORE_API_BASE_URL，可选 CONVOCORE_INTERACT_WS_URL，可选 CONVOCORE_WORKSPACE_ID。除非您自己连接，否则组合文件或文档中的任何其他变量都将被忽略。

API区域和基本URL

对于本地开发，set CONVOCORE_API_BASE_URL=http://localhost:5000/v3 重定向REST和WebSocket，或设置 CONVOCORE_INTERACT_WS_URL=ws://localhost:5000/interact 仅重定向 /interact WebSocket，而REST继续使用区域主机。

______________________________________________________________________

认证

每一个请求 ConvoCoreClient 包括：

• Authorization: Bearer
• Content-Type: application/json

非OK响应：正文解析为JSON； message 如果存在，则作为错误抛出，否则为通用状态消息。保持 WORKSPACE_SECRET 没有提示、屏幕截图和共享配置；使用env-vars或主机的秘密机制。

______________________________________________________________________

快速启动

先决条件

• ConvoCore 工作区机密 (WORKSPACE_SECRET).
• 可选：正确 区域 (eu-gcp / na-gcp).
• Node.js 20+ （船舶与 npx).Docker是可选的，只需要用于容器工作流。

选项A:npx（推荐）

你不必安装任何东西。您的MCP主机（Claude Desktop、Cursor等）按需运行服务器：

npx -y convocore-mcp

集 WORKSPACE_SECRET （以及可选 CONVOCORE_API_REGION)在主人的 env block——见 Claude桌面示例 在......下面

第一次调用下载包（几秒钟）；后续运行由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 保持stdin打开，以便MCP主机可以向容器发送JSON-RPC。

选项C：本地节点（开发）

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主机

克劳德桌面版

配置路径：

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• 窗户： %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: ``json { "mcpServers": { "convocore": { "command": "cmd", "args": ["/c", "npx", "-y", "convocore-mcp"], "env": { "WORKSPACE_SECRET": "your_workspace_secret_here", "CONVOCORE_API_REGION": "eu-gcp" } } } } ``

保存配置后， 完全退出并重新启动Claude DesktopThe 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"
      ]
    }
  }
}

本地节点（开发）： 使用绝对路径 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和其他客户端

任何支持 标准 MCP服务器可以使用相同的 command + args + env 模式如上。推荐 command/args 是 npx + ["-y", "convocore-mcp"]Docker和本地Node也可以工作。设置相同的环境变量。

______________________________________________________________________

HTTP API映射（每个工具调用什么）

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

______________________________________________________________________

工具参考（参数和注释）

代理工具

create_agent_from_template — 首选从头开始聊天+语音代理。 工作区已在内部解决（否 workspaceId 输入）。推荐的显式字段： title, systemPrompt, voiceConfig （必须使用 speechGen.provider google-live 或 ultravox 仅使用 search_voices 在这些提供商上）， primaryColor （十六进制，从 scrape_url 颜色（如果可能的话）， widgetImageUrl （徽标URL，例如来自的favicon scrape_url).可选： voicePrompt （Gemini Live系统说明；省略→ reuse systemPrompt), description, themeType (light|dark，默认值 light), sourceUrl （可选的刮擦等待+摘录）， createKbUrlDoc (需要 sourceUrl 当为真时）， defaultLanguage （默认值 multilingual), proactiveMessage, branding, chatBgURL, additionalConfig.

• 人工智能的工作流程： scrape_url 第一→ 选择颜色+收藏夹URL→ search_voices 上 google-live / ultravox 口音→ 然后这个工具有明确的提示和完整的 voiceConfig.
• MCP构建 customThemeJSONString (nineColorPallet)从 primaryColor （与康康康公司相同的亮度渐变 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响应包含代理JSON；主提示在下面 nodes[0].instructions 当存在时。

update_agent --必填项： agentId.可选：与create相同的代理字段；补丁语义依赖于API。要更改主提示，请更新 nodes[0].instructions.

delete_agent --必填项： agentId.API方面的永久删除。

list_agents --可选： limit （当API支持时，获取上限 ?limit=).更喜欢 search_agents 或 CONVOCORE_WORKSPACE_ID 对于大型工作空间，而不是无限制地丢弃每个代理。

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.可选： page （默认值1）， limit （默认值为20）。

create_conversation --必填项： agentId, conversation.API要求至少 ts 对话对象中的时间戳；您可以添加 userName, userEmail等。根据您的ConvoCore设置。

get_conversation --必填项： agentId, convoId.

update_conversation --必填项： agentId, convoId, conversation （部分字段）。

delete_conversation --必填项： agentId, convoId.

export_all_conversations --必填项： agentId.可选： format — json （默认）或 csv.

export_conversation --必填项： agentId, convoId.可选： format — json 或 csv.

assign_conversation --必填项： agentId, convoId, assignToUserId.可选： delegatedBy.

知识库工具

代码注释中的工具描述 “仅限VG代理” --KB操作目标 /agents/{id}/kb 并且可能仅适用于ConvoCore侧支持的代理类型。

create_kb_doc --必填项： agentId, name, sourceType: doc | url | sitemap.

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

可选： metadata, tags, refreshRate — 6h | 12h | 24h | 7d | never （默认值 never 在模式中）。

list_kb_docs --必填项： agentId.可选： page （默认值1）， pageSize （默认值为20）。

get_kb_doc --必填项： agentId, docId.

update_kb_doc --必填项： agentId, docId.可选： name, content, metadata, tags, refreshRate, url.

delete_kb_doc --必填项： agentId, docId.

get_kb_stats --必填项： agentId.

报废工具

scrape_url --必填项： url工作空间由MCP内部解决（否 workspaceId 输入）。只抓取一个URL，不跟踪发现的链接，等待最多120秒完成，然后返回作业状态以及第一个抓取的页面有效载荷（如果可用）。

交互（WebSocket）工具

interact_with_agent 是唯一支持WebSocket的工具。它打开一个连接到 wss://{region}-gcp-api.vg-stuff.com/interact，发送一个 InteractObject，并聚合每个流 ChunkMessage (chunk / debug / action / metadata / sync_chat_history)成为一个MCP响应。身份验证使用相同的 Authorization: Bearer 头作为REST。

必修的： agentId, convoId.

常见可选：

• prompt --用户消息。特殊值： "start" （最初的问候）， "@cancel:", "@rewind:" （v2/节点代理）。
• bucket — voiceglow-eu 或 (default).汽车衍生自 CONVOCORE_API_REGION （欧盟gcp→ voiceglow-eu（笑声） (default))；只覆盖故意跨越区域。
• messageType + visualPayload --用于图像翻转。
• replyTo --前一条消息的回复上下文。
• lightConvoData — userName, userEmail, userPhone, origin, capturedVariables等等。在支持的地方显示到代理的系统提示中。
• agentData / workspaceData / turnsHistory --覆盖跳过Firestore加载。
• disableUiEngine, disableRecordHistory, v2, isTest, isLLMStudio, kbPreview, agentProfileId, toolTest, formSubmissionMetadata, initNodesOptions --与底层相同的标志 EWSInteractModel.
• timeoutMs （默认值 120000，最大值 600000)--MCP在强制关闭WebSocket之前等待流式转弯的时间。
• raw （默认值 false)--如果为true，则响应包括每个原始流式数据块；当为false时，只返回聚合的文本+动作+元数据+最终回合（令牌更便宜）。

响应形状（默认 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引擎处理

当代理人有 vg_enableUIEngine: true （请求没有通过 disableUiEngine: true)，服务器流 JSON字符串化 TurnProps 快照 而不是纯文本。UI引擎快照是 覆盖 （每个区块都是迄今为止机器人转向的完整快照）-- 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引擎消息类型是 text, choice, visual, cardV2, carousel, iFrame, form, input. form 和 input 仅在网络频道上发布 (web-chat / text 起源）。呼叫 get_ui_engine_spec 在测试或构建启用了UI引擎的代理以加载完整模式之前。

成本说明： 每次通话都会进行一次真正的代理回合（LLM+语音+工具），并像正常聊天一样消耗ConvoCore积分。这不是一场模拟赛。

UI引擎规范工具

get_ui_engine_spec --返回完整的Convocore UI引擎架构。静态知识，没有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引擎的代理。
2. 创建/更新一个代理，其系统提示应教导模型发出UI引擎消息——烘焙相关规则和 messageType 形状成 nodes[0].instructions.

______________________________________________________________________

ConvoCore概念：节点和提示

• 每 节点 可以表示工作流中的一个步骤。
• 这 第一节点 (nodes[0])持有 主要指令 (instructions 字段）定义默认代理行为。
• light 模式 （代理标志）：在工具中描述为不保留聊天历史以保护隐私。

______________________________________________________________________

错误和验证

• 无效的工具参数： Zod验证失败→ 错误与 Invalid arguments: ….
• 未知工具名称： 扔为 Unknown tool: ….
• API错误： 如果可用，则与JSON正文中的消息一起抛出。
• 启动： 缺失 WORKSPACE_SECRET → 服务器连接前发生配置错误。

______________________________________________________________________

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

配置后，用户可以向他们的助手询问以下问题：

• “列出我的所有ConvoCore代理商”→ list_agents
• “从头开始为此网站创建代理”→ create_agent_from_template （首选默认值）
• “将代理的所有对话导出为CSV”→ export_all_conversations
• “将URL源添加到代理的知识库中…”→ create_kb_doc 随着 sourceType: url
• “为工作区删除此URL…并返回结果”→ scrape_url

确切的工具选择和参数取决于宿主模型；这 工具说明 在 src/index.ts 这就是模型所看到的。

______________________________________________________________________

码头工人

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 使用以下命令运行图像 标准输入开启 用于MCP风格的使用。集 WORKSPACE_SECRET 并且可选 CONVOCORE_API_REGION 在您的环境或 .env 在编写文件旁边的文件。身份验证是 WORKSPACE_SECRET 仅 （服务器不读取单独的API密钥变量）。

______________________________________________________________________

发展

依赖关系： @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 装运（由 files 领域 package.json).

推送Docker镜像（维护者）

docker push moe003/convocore-mcp:latest

______________________________________________________________________

贡献和许可

欢迎通过pull请求捐款。

MIT许可证——见 LICENSE 文件。

______________________________________________________________________

链接

• ConvoCore API/产品文档
• 模型上下文协议
• 问题
• ConvoCore支持

______________________________________________________________________

专为ConvoCore社区打造。