WorkForceAI MCP 服务器

这是“内部机器人工具箱”——一个小型独立服务器，让聊天/语音机器人能够通过调用主应用所使用的同一后端，来查询和更新 WorkForceAI 平台上的内容（代理、活动、电话号码、通话记录、统计数据）。

它与 healthai-frontend 仓库完全分离——这里的内容不会推送到那里。它使用一种名为 MCP（模型上下文协议）的标准协议，该协议让 AI（Claude、ElevenLabs 的代理等）能够发现“我可以做哪些事情”并在对话中调用它们。

你不需要理解 MCP 的内部原理就能运行它——只需按照下面的步骤操作即可。

它目前能做什么

只读（安全、查询类工具）：

• list_voice_agents — 列出你的 CallFlow 语音代理

• list_campaigns — 列出活动，或获取单个活动的完整详情

• list_phone_numbers — 列出已配置的 Twilio 电话号码

• get_call_logs — 最近的通话记录/转录

• get_dashboard_stats — 通话量/使用统计

• get_current_account — 机器人当前登录的账户

一个操作类工具（会更改真实数据）：

• update_campaign — 更新活动的系统提示词、问候语、名称、目标等。需要提供 campaignId；只有你传入的字段才会被更改。

所有这些都限定在 你在 .env 中填入的账户 范围内——机器人只能看到该账户在平台上能看到的内容，仅此而已。

Related MCP server: @davoxi/mcp-server

一次性设置

1. 安装依赖

在此文件夹（E:\aiconnecthub\workforceai-mcp）中打开终端，然后运行：

npm install

（这台机器上已经安装了 Node.js——无需再安装其他东西。）

2. 配置你的 .env 文件

这里已经存在一个 .env 文件，其中已填好你的登录信息，并指向真实的 WorkForceAI 后端（https://workforceai.zapto.org）。如果你需要更改机器人登录的账户，请直接编辑 .env：

BACKEND_BASE_URL=https://workforceai.zapto.org
BOT_ACCOUNT_EMAIL=your-login-email
BOT_ACCOUNT_PASSWORD=your-login-password
MCP_PORT=8787

切勿在任何地方分享此文件或将其提交——其中包含真实的密码。.gitignore 已经将其排除，因此即使你以后将此文件夹变成 git 仓库，.env 也不会被意外提交。

3. 启动服务器

npm start

你应该会看到：

workforceai-mcp listening on http://localhost:8787
  MCP endpoint: http://localhost:8787/mcp
  Health check: http://localhost:8787/health

在测试或使用机器人时，请让它在独立的终端窗口中保持运行。按 Ctrl+C 即可停止。

4. 验证是否正常工作

快速检查（无需额外工具）： 在浏览器中打开 http://localhost:8787/health——它应该显示 {"ok":true}。

完整检查（查看实际工具并试用）： 使用官方的 MCP Inspector——这是一个基于浏览器的工具，用于手动测试 MCP 服务器。在第二个终端中（让第一个终端中的服务器保持运行）：

npx @modelcontextprotocol/inspector

这将打开一个浏览器标签页。在其中：

1. 将 Transport Type 设置为 Streamable HTTP

2. 将 URL 设置为 http://localhost:8787/mcp

3. 点击 Connect

4. 转到 Tools 标签页，点击类似 list_voice_agents 的工具，然后点击 Run——你应该会看到真实的代理数据以 JSON 格式返回。

如果这样能正常工作，说明服务器已完全验证通过，可以连接到机器人了。

关于身份验证的工作原理（让你心里有数）

后端目前没有单独的“机器人 API 密钥”系统——机器人使用普通的邮箱/密码登录，与网站登录表单完全一样，然后获得一个 JWT 令牌，并在每次请求时附带该令牌。它将该令牌保存在内存中（而非磁盘上），如果令牌过期或请求返回未授权，它会自动重新登录。这与前端应用中的 utils/apiClient.js 的做法一致，只是没有浏览器而已。

正因如此，机器人只能看到/更改该登录账户所能看到/更改的内容——即它自己的代理、活动、号码和通话记录。它无法查看或操作其他用户的账户。

项目结构

workforceai-mcp/
├── .env              ← your real credentials (gitignored, never share)
├── .env.example       ← template, safe to share
├── src/
│   ├── config.js      ← reads .env
│   ├── backendClient.js ← logs in, attaches auth token, retries on expiry
│   ├── tools.js        ← the actual tool definitions (add new ones here)
│   └── server.js       ← the MCP server itself (Express + Streamable HTTP)
└── README.md          ← this file

以后要添加新工具：在 src/tools.js 的 tools 数组中添加一个条目，遵循现有模式（名称、描述、输入字段、调用 http.get/post/put 请求后端的处理函数），然后重启服务器即可。

尚未完成的事项（下一阶段）

此服务器目前只能在你自己的机器（localhost）上运行——互联网无法访问它。要将其接入 ElevenLabs 语音代理，ElevenLabs 的服务器需要能够通过互联网访问此 MCP 端点，这意味着需要：

• 通过隧道临时暴露它（例如 ngrok），或者

• 将其部署到能够持续运行的地方（小型常驻服务器/VPS/托管服务）

这些工作，加上实际的 ElevenLabs 代理配置，将作为单独的下一阶段任务——不属于本次构建的范围。