YCloud WhatsApp Platform Connector (MCP Server Implementation)

English Version Link | 中文文档

This package implements a dedicated server conforming to the Model Context Protocol (MCP). Its primary role is to dynamically provision AI tools based on the official YCloud WhatsApp OpenAPI specification, enabling large language models (LLMs) like Claude to invoke platform functionalities directly.

Prerequisites for Deployment

Before initiating the service, ensure the following prerequisites are satisfied:

1. Establish an authenticated account on the YCloud main portal.
2. Secure your unique API access credentials (detailed retrieval steps follow).
3. Install all requisite software dependencies listed below.

Technical Environment Requirements

• Runtime Environment: Node.js, minimum version 16.0.0 or superior.
• Package Manager: npm, minimum version 7.0.0 or superior.
• Integration Target (Optional): Claude Desktop Application (if leveraging local tool execution).

Core Capabilities

• Dynamic Toolset Generation derived instantly from the OpenAPI schema.
• Comprehensive support spanning the entire suite of YCloud API interfaces.
• Robust integration of API authentication mechanisms.
• Automated enforcement of data types and validation rules for input parameters.
• Transparent orchestration of all underlying HTTP transport operations (request/response).

Setup Procedure

bash

Acquire the repository source code

git clone https://github.com/YCloud-Developers/ycloud-whatsapp-mcp-server.git cd ycloud-whatsapp-mcp-server

Install required npm packages

npm install

Compile source assets

npm run build

Operational Guide

API Credential Acquisition

Authentication with the YCloud API necessitates an active key:

1. Access the YCloud Console Interface.
2. Navigate to the section designated for developer settings.
3. Your primary API authentication token is retrievable from this location.

The acquired credential must be transmitted within the X-API-Key header for every outbound service invocation.

Environment Variable Configuration

Service behavior can be tuned via environment variables:

• API_BASE_URL: The root endpoint for YCloud services (Default: https://api.ycloud.com/v2).
• OPENAPI_SPEC_PATH: Location (URI or filesystem path) of the OpenAPI descriptor (Default: https://docs.ycloud.com/openapi.json).
• API_HEADERS: Custom headers to inject into API calls (Format: key1:value1,key2:value2).

Configuration for Claude Desktop Client

To integrate this server directly within the Claude Desktop environment, modify the user configuration file:

1. Locate or establish the Claude desktop configuration file:

   • macOS Path: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows Path: %APPDATA%\Claude\claude_desktop_config.json

2. Incorporate the subsequent JSON object into the mcpServers block:

{ "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" } } } }

1. Substitute your-api-key-here with your actual YCloud access token.

Direct Execution Mode

Execute the service directly by setting necessary environment variables inline:

bash API_BASE_URL=https://api.ycloud.com/v2 \ API_HEADERS="X-API-Key:your-api-key-here" \ npm start

Interaction Example

Within a Claude session, an instruction like the following will trigger the appropriate tool execution:

Kindly retrieve the current ledger balance associated with my YCloud account.

Claude will internally map this request to the correct API invocation and present the response.

Diagnostics and Troubleshooting

For debugging connectivity or runtime issues, employ these methods:

1. Monitor Server Standard Output: The running service provides detailed operational telemetry.
2. Utilize the MCP Inspector: Examine the server's operational state using the official MCP Inspector interface.
3. Review Claude Desktop Logs: The local application often logs tool server interactions and failures.

Community Contribution

We welcome enhancements via feature branches (Pull Requests) or by reporting defects (Issues).

License Grant

MIT License