MCP 服务器

Voiceflow MCP Client

voiceflow-gallagan

开发者工具

访问服务器

README

Voiceflow MCP 客户端

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

功能

支持多个远程 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）
构建 weather MCP 服务器
构建 Google Calendar 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 Search 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 Calendar OAuth 令牌（可选）
- GCP_OAUTH_KEYS: Google Calendar OAuth 凭据（可选）

动态服务器配置

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

无需修改代码即可启用/禁用 Zapier 服务器
使用您的 API 密钥安全地配置 Zapier 服务器
无需代码更改即可添加 Zapier 服务器

动态服务器配置示例：

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

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

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

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

Google Calendar 设置

要使用 Google Calendar MCP 服务器，您需要设置 OAuth 2.0 凭据并将其添加到您的环境变量中：

转到 Google Cloud Console
创建一个新项目或选择一个现有项目
启用 Google Calendar 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": "What is the weather in New York?",
  "conversationId": "optional-conversation-id",
  "userId": "optional-user-id",
  "userEmail": "optional-user-email",
  "queryTimeoutMs": 30000,
  "llm_answer": false
}

响应：

{
  "query": "What is the weather in New York?",
  "answer": "The AI's response here",
  "conversationId": "conv-123456789",
  "userId": "user-123",
  "needsClarification": false,
  "noAnswer": false,
  "error": false,
  "toolResponses": [
    {
      "tool": "weather_getWeather",
      "input": { "location": "New York" },
      "response": "The current temperature is 72°F with sunny conditions.",
      "server": "weather"
    }
  ]
}

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

{
  "toolResponses": [
    {
      "tool": "time_getTime",
      "input": { "location": "New York" },
      "response": "The current time is 2:30 PM 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": "What is the weather in New York?",
      "lastMessage": "The current temperature is 72°F with sunny conditions.",
      "messageCount": 4
    }
  ]
}

清除对话

DELETE /api/conversation/:conversationId

清除特定对话。

参数：

conversationId (路径参数): 要清除的对话的 ID

响应：

{
  "success": true,
  "message": "Conversation conv-123456789 cleared successfully"
}

清除用户对话

DELETE /api/conversations/:userId

清除特定用户的所有对话。

参数：

userId (路径参数): 用户的 ID

响应：

{
  "success": true,
  "message": "All conversations for user user-123 cleared successfully"
}

获取可用服务器

GET /api/servers

检索有关所有配置的 MCP 服务器及其可用操作的信息。

响应：

{
  "success": true,
  "servers": {
    "weather-server": {
      "name": "weather-server",
      "actions": [
        {
          "name": "getWeather",
          "description": "Get current weather for a location",
          "inputSchema": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "City name or location"
              }
            },
            "required": ["location"]
          }
        }
      ],
      "enabled": true
    },
    "google-calendar": {
      "name": "google-calendar",
      "actions": [
        {
          "name": "listEvents",
          "description": "List calendar events",
          "inputSchema": {
            "type": "object",
            "properties": {
              "maxResults": {
                "type": "number",
                "description": "Maximum number of events to return"
              }
            }
          }
        }
      ],
      "enabled": true
    }
  }
}

响应包括：

success: 布尔值，指示请求是否成功
servers: 包含有关每个配置的服务器的信息的对象：
- name: 服务器的名称
- actions: 服务器的可用操作数组，每个操作包含：
  - name: 操作名称
  - description: 操作的功能描述
  - inputSchema: 描述预期输入参数的 JSON Schema
- enabled: 布尔值，指示服务器是否已启用
- error: 错误消息（仅当服务器未能提供其操作时才存在）

测试 API

您可以使用 curl 测试 API：

curl -X POST http://localhost:3000/api/query \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What is the weather in New York?",
    "llm_answer": false
  }'

或者使用包含的演示：

node demo.js

使用演示代理进行测试

要测试集成，您可以使用演示代理文件 MCP Agent Apr 1 2025.vf。此代理配置为与 MCP 客户端一起使用，并包含 MCP Tools 函数。

注意：演示代理旨在展示集成功能，可能需要使用您的特定 API 密钥和配置进行更新。

开发

在开发模式下运行：npm run dev

错误处理

客户端包括多种错误处理机制：

用于连接失败的重试机制
正确清理资源
用于调试的详细日志记录

许可证

ISC

Voiceflow MCP Client

README

Voiceflow MCP 客户端

功能

设置

前提条件

安装

动态服务器配置

Google Calendar 设置

Docker 设置

前提条件

使用 Docker 构建和运行

Docker 环境变量

Docker 卷

Docker 健康检查

Docker 命令

用法

运行客户端

配置远程 MCP 服务器

API 端点

健康检查

处理查询

获取用户对话

清除对话

清除用户对话

获取可用服务器

测试 API

使用演示代理进行测试

开发

错误处理

许可证

推荐服务器