Voice Brain MCP — 语音原型（NL Pearl v2）+ Brain（MCP）+ 渠道

基于 NL Pearl v2 的语音网关原型，带有按联系人统一上下文（与渠道无关）的 “Brain”，同时也作为 MCP 服务器 暴露，并提供一个 Angular 22 控制台 来操作流程。

无需任何凭据即可在 mock 模式下端到端运行。NL Pearl v2 的真实适配器已准备好接入。

功能

• 语音：NL Pearl v2 作为我们自有网关背后的引擎（不使用其控制台或文本渠道）。出站呼叫通过 addLead 触发；在说话之前，PreCallAPI 节点向 POST /precall 请求上下文；通话结束后，webhook POST /webhooks/nlpearl 带来通知，网关获取转录/摘要/情绪/数据。

• Brain：按联系人统一上下文（身份、跨渠道时间线、付款承诺类信号）。通过 REST 暴露给控制台，并作为带有 brain_* 工具的 MCP 服务器（stdio） 提供服务。

• 自有渠道：WhatsApp/SMS（为 WABA/SMS 供应商预留的桩实现）读写相同的上下文 → 后续跟进延续同一条线程。

Related MCP server: CRMy

流程图（演示）

 consola /demo ──POST /api/demo/run──▶ DemoService
   1. siembra contacto (promesa activa + WhatsApp previo)
   2. addLead (VoiceEnginePort → mock | NL Pearl v2)
        │
        ▼  (ciclo de llamada)
   3. POST /precall  ◀── nodo PreCallAPI      → variables (nombre, promesa, saldo, último resumen)
   4. ... conversación ...
   5. POST /webhooks/nlpearl (HMAC guard)     → getCall → Brain.recordCallContext
        │                                        · interacción voice + señal promesa
        ▼
   6. FollowupService → brain_suggest_followup → WhatsApp propio (stub)
        │                                        · interacción whatsapp outbound
        ▼
   7. consola: timeline del contacto con voz + WhatsApp en el mismo hilo

结构

voice-brain-mcp/
├─ apps/
│  ├─ api/        # NestJS 11 + Fastify: Brain, NL Pearl, canales, MCP, demo
│  └─ console/    # Angular 22 (signals + zoneless). Vistas:
│                 #   /home           inicio con avatar de voz
│                 #   /contacts       directorio de contactos
│                 #   /contacts/:id   chat + contexto en vivo (2 columnas)
│                 #   /conversations  módulo de conversaciones: lista de hilos
│                 #                   + chat + contexto en vivo (3 columnas)
│                 #   /demo           flujos end-to-end paso a paso
├─ scripts/run-demo.mjs
├─ data/brain.json   # respaldo de persistencia (se crea al correr)
└─ .env              # copiar de .env.example

如何运行

要求：Node 20+（已在 Node 24 上测试）。

cp .env.example .env     # MOCK=true por defecto
npm install

npm run dev              # api (3000) + consola (4200) juntos
# o por separado:
npm run dev:api
npm run dev:console

• 控制台：http://localhost:4200 → 流程演示 标签页 → “运行端到端流程”。最后会有指向联系人上下文的链接（语音 + WhatsApp 在同一个时间线中）。

• CLI 演示（需先启动 api）：npm run demo

• 测试：npm test · 构建：npm run build

已部署

https://voice-brain-mcp.vercel.app — 以 mock 模式运行，无需凭据。

在 Vercel 上部署（从 GitHub）

仓库已包含 vercel.json 和位于 api/index.js 的 serverless 函数。

git init && git add -A && git commit -m "Prototipo voz + Brain MCP"
git remote add origin git@github.com:<usuario>/<repo>.git
git push -u origin main

在 Vercel 中：Add New → Project → Import 该仓库并 Deploy。vercel.json 定义构建、将 Angular 控制台作为静态资源发布，并将 /api/*、/precall 和 /webhooks/* 路由到 Nest 函数。

单个项目，Root Directory 设为仓库根目录。 构建允许 Vercel 在某个 workspace 内启动，但 serverless 函数位于 api/index.js（根目录），只有 Root Directory 是根目录时 Vercel 才能检测到它。如果按 workspace 拆分为单独项目，控制台可以部署，但 /api/* 会返回 404。

为什么构建是一个脚本而不是 npm run --workspace（Vercel 对 npm monorepo 的两个陷阱，都已在 scripts/vercel-build.sh 中解决）：

• 根 package.json 中名为 vercel-build 的脚本不起作用：Vercel 会特殊对待它，npm 会把它传播到每个未定义它的 workspace → Missing script: "vercel-build"。

• 如果 Vercel 从子目录执行构建，npm run build --workspace apps/api 会因 No workspaces found 失败。该脚本自行定位 monorepo 根目录，并用 npx 调用 nest/ng，因此从任何位置都能工作。

如果部署再次失败，请查看日志的前几行：脚本会打印 cwd inicial 和 raíz del monorepo，它们会精确说明 Vercel 是从哪里启动的。

环境变量（Project → Settings → Environment Variables）：没有一个是必填的——不填任何值，部署就会以 mock 模式运行。要连接真实的 NL Pearl，请设置 MOCK=false、NLPEARL_ACCOUNT_ID、NLPEARL_API_KEY、NLPEARL_PEARL_ID 和 NLPEARL_WEBHOOK_SECRET，并将 Pearl 的 webhook 指向 https://<tu-deploy>.vercel.app/webhooks/nlpearl，将 PreCallAPI 节点指向 https://<tu-deploy>.vercel.app/precall。

serverless 中有什么变化（以及原因）

Vercel 在响应时会冻结进程，且只有 /tmp 可写，因此代码会自动适配（检测到 VERCEL）：

• 持久化：JSON 备份写入 /tmp。每个实例都有自己的副本，并在实例回收时丢失——足以用于演示，不适合生产（为此请将 BrainRepository 换成 SQLite/Postgres）。

• 冷启动播种：如果 Brain 以空状态启动，就会用固定 ID 播种演示目录，使 /contacts/:id 链接在实例之间仍然有效。

• 演示流程：在请求内完成（没有后台定时器），步骤随响应一起返回，因为轮询可能会落到另一个实例。

• Mock：使用进程内服务，而不是通过 HTTP 调用自身（部署保护会阻止这种自请求）。本地仍使用真实的 HTTP 请求 /precall 和 /webhooks/nlpearl。

• MCP：stdio 服务器不适用于 Vercel；本地用 npm run mcp 运行。

Brain 作为 MCP 服务器

npm run mcp                                    # servidor stdio
npx @modelcontextprotocol/inspector npm run mcp  # probarlo con el inspector

工具：brain_resolve_identity、brain_get_context、brain_upsert_contact、brain_append_interaction、brain_set_signal、brain_get_signals、brain_record_call_context、brain_suggest_followup。

与 HTTP 网关共享持久化（JSON 文件）。

连接真实的 NL Pearl

1. 在 .env 中：MOCK=false、NLPEARL_ACCOUNT_ID、NLPEARL_API_KEY 和 NLPEARL_PEARL_ID（语音外呼 Pearl）。文档中确认的认证方式：Authorization: Bearer {AccountId}:{SecretKey}。

2. 在 NL Pearl 中：将 Pearl 的流程配置为 PreCallAPI 节点指向 https://tu-host/precall，并启用指向 https://tu-host/webhooks/nlpearl 的呼叫 webhook。

   webhook 在哪里（它不是 workspace 级的，而是每个 Pearl 各自）：仪表盘（用 Go Back 退出 Settings）→ 打开你的 Pearl → PearlVibe 流程编辑器 → Outbound Settings 标签页（或 Inbound Settings）→ Campaign Settings 组 → 滚动到底部，Webhooks 部分 → 打开开关（URL 字段只有在启用后才会出现）→ Call Webhook URL。我们不用 Lead Webhook。

   注意：在 workspace 的 Settings 中，Agent(s) 是同时通话能力，不是 Pearls；Text Channels 也不使用（WhatsApp/SMS 是我们自己的）。

3. NLPEARL_WEBHOOK_SECRET：NL Pearl 不使用 HMAC 对 webhook 签名——配置 webhook 时，你可以附加一个 Credential（你自己创建的 token），它会随每次投递一起发送。把同样的值放到 NLPEARL_WEBHOOK_SECRET 中，守卫会验证它；留空 = 不要求。

4. 对照 v2 文档确认过的路径位于 apps/api/src/nlpearl/nlpearl.client.ts；未验证的已标记为 // TODO: confirmar con NL Pearl（webhook.controller.ts / precall.controller.ts 中 webhook 和 PreCallAPI 的确切结构也一样）。

决策 / 备注

• 将端口作为注入令牌（VoiceEnginePort、ChannelPort、BrainRepository）：mock/真实绑定根据 MOCK 存在于各个适配器模块中；Brain 从不导入具体客户端。

• mock 会真实调用网关的 HTTP 端点（对 /precall 和 /webhooks/nlpearl 的自 HTTP 请求，如果有 secret 则带 HMAC 签名），而不是内部捷径。

• 持久化：BrainRepository 底层是内存 + JSON 备份（可通过 provider 换成 SQLite/Postgres）。

• 不使用 NL Pearl 的文本渠道：WhatsApp/SMS 是我们自己的适配器（带日志的桩实现）。