语音流-MCP服务器客户端

Name: 语音流-MCP服务器客户端
Author: voiceflow-community

作者：voiceflow-community2 星标更新：2025-06-24

安装使用来源：spider==github.com

项目介绍

Voiceflow MCP 客户端

一个用于模型上下文协议（MCP）的Node.js客户端，与远程MCP服务器集成，为您的Voiceflow代理提供工具。

功能

支持多个远程MCP服务器
使用HTTP传输进行服务器通信
工具发现并集成到Claude AI中
通过JSON配置服务器集成
自动错误处理和重试机制

设置

先决条件

Node.js 20.x或更高版本
npm

安装

克隆包含子模块的仓库：

git clone --recursive https://github.com/voiceflow-gallagan/voiceflow-mcp-server-client.git

或者如果您已经克隆了仓库，请初始化子模块：

git submodule update --init --recursive

安装依赖项：

npm install

构建MCP服务器：

npm run build

这将：

设置Playwright依赖项（包括Chrome和Chromium）
初始化并更新Git子模块（weather-mcp-server和google-calendar-mcp）
构建天气MCP服务器
构建Google日历MCP服务器

注意：构建过程需要root权限来安装Chrome。您可能会被提示输入密码。

设置环境变量：
- 复制.env.template以创建新的.env文件：
```
cp .env.template .env
```
- 更新.env文件中的实际值：
```
ANTHROPIC_API_KEY=your-anthropic-api-key
CLAUDE_MODEL=claude-3-7-sonnet-20250219
PORT=3000
BRAVE_API_KEY=your-brave-api-key
LAST_RESPONSE_ONLY=false
SERVER_DISCOVERY_TIMEOUT=20000
ZAPIER_MCP_URL=https://actions.zapier.com/mcp/your-api-key/sse
MAX_CONVERSATION_HISTORY=10
TRUNCATE_TOOL_RESPONSES=false
GCP_SAVED_TOKENS={"access_token":"your-access-token","scope":"https://www.googleapis.com/auth/calendar","token_type":"Bearer","expiry_date":1234567890,"refresh_token":"your-refresh-token"}
GCP_OAUTH_KEYS={"installed":{"client_id":"your-client-id","project_id":"your-project-id","auth_uri":"https://accounts.google.com/o/oauth2/auth","token_uri":"https://oauth2.googleapis.com/token","auth_provider_x509_cert_url":"https://www.googleapis.com/oauth2/v1/certs","client_secret":"your-client-secret","redirect_uris":["http://localhost"]}}
```
必需的环境变量：
- ANTHROPIC_API_KEY：用于Claude AI的Anthropic API密钥
- CLAUDE_MODEL：要使用的Claude模型（默认：claude-3-7-sonnet-20250219）
- PORT：服务器的端口号（默认：3000）
- BRAVE_API_KEY：用于搜索功能的Brave搜索API密钥
- LAST_RESPONSE_ONLY：当设置为“true”时，仅返回API响应中的最后一个工具响应（默认：false）
- SERVER_DISCOVERY_TIMEOUT：等待服务器发现的最大时间（单位：毫秒，默认：20000ms）
- ZAPIER_MCP_URL：可选的Zapier MCP服务器URL（例如：https://actions.zapier.com/mcp/your-api-key/sse）
- MAX_CONVERSATION_HISTORY：会话历史记录中保留的消息最大数量（默认：10）
- TRUNCATE_TOOL_RESPONSES：是否截断toolResponses数组中的工具响应（默认：false）
  - 当为true时，工具响应将被截断至1000个字符
  - 当为false时，toolResponses中将保留完整的响应
  - 注意：对话上下文中的工具响应始终会被截断，以防止超过令牌限制的问题
- MAX_FOLLOWUP_STEPS：允许的最大递归工具调用次数（默认：5）
  - 较高的值允许更复杂的任务，但可能增加处理时间
  - 较低的值可以防止无限循环，但可能限制任务完成
- PLAYWRIGHT_EXTENDED_STEPS：允许的Playwright工具的最大递归调用次数（默认：8）
  - 为网络浏览工具单独设置的限制，因为这些工具通常需要更多的步骤
  - 对于复杂的网络浏览场景，可以增加此值
可选的环境变量：
- GCP_SAVED_TOKENS：Google日历OAuth令牌（可选）
- GCP_OAUTH_KEYS：Google日历OAuth凭证（可选）

动态服务器配置

客户端支持通过环境变量进行动态服务器配置。目前，此功能仅适用于Zapier MCP服务器。这允许您：

在不修改代码的情况下启用/禁用Zapier服务器
安全地配置Zapier服务器的API密钥
在不更改代码的情况下添加Zapier服务器

动态服务器配置示例：

将Zapier服务器URL添加到您的.env文件中：

ZAPIER_MCP_URL=https://actions.zapier.com/mcp/your-api-key/sse

应用程序启动时，Zapier服务器将自动配置。
要禁用Zapier服务器，只需从环境变量中删除或注释掉ZAPIER_MCP_URL。

注意：虽然当前动态服务器配置功能仅限于Zapier服务器，但架构支持在未来添加更多动态服务器。

Google日历设置

要使用Google日历MCP服务器，您需要设置OAuth 2.0凭证并将它们添加到环境变量中：

访问Google Cloud控制台
创建一个新的项目或选择现有的项目
启用Google日历API
创建OAuth 2.0凭证：
- 前往“API和服务”>“凭据”
- 单击“创建凭据”>“OAuth客户端ID”
- 选择“桌面应用”作为应用程序类型
- 下载客户端配置文件

将这些环境变量添加到您的.env文件中：

GCP_SAVED_TOKENS={"access_token":"your-access-token","scope":"https://www.googleapis.com/auth/calendar","token_type":"Bearer","expiry_date":1234567890,"refresh_token":"your-refresh-token"}
GCP_OAUTH_KEYS={"installed":{"client_id":"your-client-id","project_id":"your-project-id","auth_uri":"https://accounts.google.com/o/oauth2/auth","token_uri":"https://oauth2.googleapis.com/token","auth_provider_x509_cert_url":"https://www.googleapis.com/oauth2/v1/certs","client_secret":"your-client-secret","redirect_uris":["http://localhost"]}}

注意：这些值应为整个JSON内容的一行。您可以从以下位置获取这些值：

GCP_SAVED_TOKENS：在第一次OAuth流程后，令牌将保存在.gcp-saved-tokens.json中
GCP_OAUTH_KEYS：从下载的客户端配置文件中获取

在根目录下创建一个servers-config.json文件以配置您的远程MCP服务器：

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest", "--headless"]
    },
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "${BRAVE_API_KEY}"
      }
    },
    "time-mcp": {
      "command": "npx",
      "args": ["-y", "time-mcp"]
    },
    "weather-server": {
      "command": "node",
      "args": ["mcp-servers/weather-mcp-server/build/index.js"],
      "env": {
        "OPENWEATHER_API_KEY": "${OPENWEATHER_API_KEY}"
      },
      "disabled": false,
      "autoApprove": []
    },
    "google-calendar": {
      "command": "node",
      "args": ["./mcp-servers/google-calendar-mcp/build/index.js"]
    }
  }
}

服务器配置支持：

基于命令的服务器（使用command和args）
环境变量替换（使用${VARIABLE_NAME}）
禁用服务器（使用disabled: true）
特定工具的自动批准（使用autoApprove）

对于每个服务器，工具将以前缀的形式出现，以避免冲突（例如：weather_getWeather）。

目前，通过环境变量的动态服务器配置仅支持Zapier服务器。这允许您通过ZAPIER_MCP_URL环境变量配置Zapier服务器的URL和API密钥。架构支持在未来添加更多动态服务器。

Docker设置

先决条件

您的系统上已安装Docker
Docker Compose（可选，用于更简单的管理）

使用Docker构建和运行

构建Docker镜像：

docker build -t mcp-client .

运行容器：

docker run -p 3000:3000 \
  --env-file .env \
  --name mcp-client \
  mcp-client

或者使用Docker Compose（创建一个docker-compose.yml文件）：

services:
  mcp-client:
    build: .
    ports:
      - "3135:3135"
    env_file:
      - .env
    volumes:
      - ./logs:/app/logs
    restart: unless-stopped

然后运行：

docker-compose up -d

Docker环境变量

Docker容器使用与本地设置相同的环境变量。确保在构建镜像之前正确配置了.env文件。

Docker卷

以下目录可用于挂载卷：

/app/logs：应用程序日志
/app/public：静态文件

Docker健康检查

容器在/health端点包含一个健康检查。您可以使用以下命令监控容器的健康状态：

docker inspect --format='{{.State.Health.Status}}' mcp-client

Docker命令

用于管理容器的常见Docker命令：

# 停止容器
docker stop mcp-client

# 启动容器
docker start mcp-client

# 查看日志
docker logs mcp-client

# 删除容器
docker rm mcp-client

# 使用新更改重建并重启
docker-compose up -d --build

使用

运行客户端

启动API服务器：

npm start

这将：

在端口3000（或.env文件中指定的端口）上启动API服务器
需要时自动连接到配置的远程MCP服务器

配置远程MCP服务器

该项目支持与远程MCP服务器集成。您可以通过项目根目录下的servers-config.json文件配置它们：

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest", "--headless"]
    },
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "${BRAVE_API_KEY}"
      }
    },
    "time-mcp": {
      "command": "npx",
      "args": ["-y", "time-mcp"]
    },
    "weather-server": {
      "command": "node",
      "args": ["mcp-servers/weather-mcp-server/build/index.js"],
      "env": {
        "OPENWEATHER_API_KEY": "${OPENWEATHER_API_KEY}"
      },
      "disabled": false,
      "autoApprove": []
    },
    "google-calendar": {
      "command": "node",
      "args": ["./mcp-servers/google-calendar-mcp/build/index.js"]
    }
  }
}

服务器配置支持：

基于命令的服务器（使用command和args）
环境变量替换（使用${VARIABLE_NAME}）
禁用服务器（使用disabled: true）
特定工具的自动批准（使用autoApprove）

对于每个服务器，工具将以前缀的形式出现，以避免冲突（例如：weather_getWeather）。

API端点

健康检查

GET /

返回API和可用MCP服务器的当前状态。

响应：

{
  "status": "ok",
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest", "--headless"],
      "disabled": false
    },
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "${BRAVE_API_KEY}"
      },
      "disabled": false
    },
    "time-mcp": {
      "command": "npx",
      "args": ["-y", "time-mcp"],
      "disabled": false
    },
    "weather-server": {
      "command": "node",
      "args": ["mcp-servers/weather-mcp-server/build/index.js"],
      "env": {
        "OPENWEATHER_API_KEY": "${OPENWEATHER_API_KEY}"
      },
      "disabled": false,
      "autoApprove": []
    },
    "google-calendar": {
      "command": "node",
      "args": ["./mcp-servers/google-calendar-mcp/build/index.js"],
      "disabled": false
    }
  }
}

处理查询

POST /api/query

使用可用的MCP工具和Claude AI处理用户查询。

请求正文：

{
  "query": "纽约的天气如何？",
  "conversationId": "可选对话ID",
  "userId": "可选用户ID",
  "userEmail": "可选用户电子邮件",
  "queryTimeoutMs": 30000,
  "llm_answer": false
}

响应：

{
  "query": "纽约的天气如何？",
  "answer": "AI的回答在这里",
  "conversationId": "conv-123456789",
  "userId": "user-123",
  "needsClarification": false,
  "noAnswer": false,
  "error": false,
  "toolResponses": [
    {
      "tool": "weather_getWeather",
      "input": { "location": "纽约" },
      "response": "当前温度是72°F，晴朗。",
      "server": "weather"
    }
  ]
}

当环境变量中设置了LAST_RESPONSE_ONLY=true时，仅返回最后一个工具响应。例如，如果调用了多个工具：

{
  "toolResponses": [
    {
      "tool": "time_getTime",
      "input": { "location": "纽约" },
      "response": "当前时间为下午2:30 EDT",
      "server": "time"
    }
  ]
}

可用参数：

query（必需）：用户的提问或请求
conversationId（可选）：维护对话上下文的ID。如果没有提供，将创建一个新的对话
userId（可选）：发出请求的用户的ID
userEmail（可选）：用户的电子邮件，用于与日历相关的工具
queryTimeoutMs（可选）：等待响应的最大时间（单位：毫秒）。默认为30000ms（30秒）
llm_answer（可选）：是否使用Claude生成最终答案。如果为false，则仅返回工具响应。默认为false。

API将返回一个JSON响应，其中包含：

query：原始查询
answer：AI的回答（如果llm_answer为false则为null）
conversationId：对话的ID（新对话或现有对话）
userId：用户的ID（如果提供）
needsClarification：布尔值，表示AI是否需要更多信息
noAnswer：布尔值，表示AI是否无法使用可用工具回答查询
error：布尔值，表示是否发生错误
toolResponses：工具响应的数组，每个响应包含：
- tool：调用的工具名称
- input：传递给工具的输入参数
- response：工具的响应
- server：提供工具的MCP服务器名称
- error：布尔值，表示工具调用是否失败（仅当为true时存在）

获取用户对话

GET /api/conversations/:userId

检索特定用户的全部对话。

参数：

userId（路径参数）：用户的ID

响应：

{
  "userId": "user-123",
  "conversations": [
    {
      "conversationId": "conv-123456789",
      "firstMessage": "纽约的天气如何？",
      "lastMessage": "当前温度是72°F，晴朗。",
      "messageCount": 4
    }
  ]
}

清除对话

DELETE /api/conversation/:conversationId

清除特定对话。

参数：

conversationId（路径参数）：要清除的对话的ID

响应：

{
  "success": true,
  "message": "对话conv-123456789已成功清除"
}

清除用户对话

DELETE /api/conversations/:userId

清除特定用户的全部对话。

参数：

userId