YCloud WhatsApp 接口 MCP 枢纽

English | 中文

本组件是基于模型上下文协议 (MCP) 架构实现的 YCloud WhatsApp 服务代理。它的核心能力是从 YCloud WhatsApp 的 OpenAPI 描述文档中自动生成可供 AI 实体（例如 Claude）调用的工具集，从而实现对底层 API 的直接操作。

入门先决条件

部署本代理前，用户须完成以下准备工作：

在 YCloud 官方网站注册并激活账户。
检索并妥善保管您的专属 API 访问密钥（详见下文指引）。
确保已安装所有必需的软件依赖项（参见后续说明）。

运行环境要求

推荐 Node.js 版本不低于 v16.0.0
推荐 npm 版本不低于 v7.0.0
若计划与 Claude 桌面客户端集成，则需安装该应用。

核心功能特性

基于 OpenAPI 规范的工具定义自动化流程。
全面覆盖所有 YCloud 提供的 WhatsApp API 访问点。
内建 API 认证机制支持。
参数数据类型校验与输入验证自动化处理。
全面化的网络请求发起与结果响应解析能力。

部署流程

# 仓库克隆操作
git clone https://github.com/YCloud-Developers/ycloud-whatsapp-mcp-server.git
cd ycloud-whatsapp-mcp-server

# 依赖包安装
npm install

# 项目编译构建
npm run build

启动与配置指南

密钥获取流程

为授权访问 YCloud API，所有通讯必须携带认证凭证：

登录至 YCloud 管理控制台。
导航至“开发者设置”区域。
在该区域内，您的 API 密钥将被展示。

该密钥必须以请求头 X-API-Key 的形式附带于所有发往 API 的请求之中。

环境变量配置

服务器的行为可通过设置以下环境变量进行调控：

API_BASE_URL: YCloud API 的根访问地址（默认值：https://api.ycloud.com/v2）。
OPENAPI_SPEC_PATH: OpenAPI 规范文档的本地路径或远程 URL（默认值：https://docs.ycloud.com/openapi.json）。
API_HEADERS: 附加到 API 调用的额外 HTTP 标头（格式示例：key1:value1,key2:value2）。

Claude 桌面端集成配置

若需在 Claude 桌面应用中启用此代理服务，请编辑相应的配置文件：

确定或创建 Claude 桌面应用的配置文件位置：
macOS 系统路径：~/Library/Application Support/Claude/claude_desktop_config.json
Windows 系统路径：%APPDATA%\Claude\claude_desktop_config.json
在配置文件中加入如下 JSON 片段：

{
  "mcpServers": {
    "ycloud-whatsapp": {
      "command": "node",
      "args": ["path/to/ycloud-whatsapp-mcp-server/build/index.js"],
      "env": {
        "API_BASE_URL": "https://api.ycloud.com/v2",
        "API_HEADERS": "X-API-Key:your-api-key-here"
      }
    }
  }
}

请务必将配置中的 your-api-key-here 替换为您实际获取的 YCloud API 密钥。

直接运行模式

# 设置运行参数并启动服务
API_BASE_URL=https://api.ycloud.com/v2 \
API_HEADERS="X-API-Key:your-api-key-here" \
npm start

交互示例

在 Claude 界面中，可以采用如下自然语言提示来触发 API 调用：

请帮我查询我的 YCloud 账户余额。

系统将利用已生成的工具链，执行对应的 API 检索并返回处理结果。

故障排查与调试

在开发或运行时遇到问题，可采用以下方法进行诊断：

查阅运行时日志：服务器启动后会持续输出诊断信息。
使用 MCP 检查器：可利用 MCP Inspector 工具来实时监控代理服务的运行状态。
Claude 桌面端日志：桌面应用本身也提供了查看服务状态和日志的界面。

社区贡献

我们鼓励社区成员通过提交 Pull Request 或创建 Issue 的方式，参与到本项目的优化与迭代中。

许可声明

本项目采用 MIT 协议进行授权。

ycloud-whatsapp-gateway-server

Author

YCloud-Developers

Quick Info

Actions

Tags