SendPulse Chatbots MCP Server

# MCP Server for SendPulse Chatbots This project is an implementation of a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server designed to work with the [SendPulse Chatbots API](https://sendpulse.com/swagger/chatbots/?lang=en). It allows Large Language Models (LLMs) like those from OpenAI to interact with the SendPulse API through a standardized set of tools. This server is built with TypeScript and runs on Node.js using the Express framework. ## Features The server exposes a combination of global and universal, channel-specific tools to the LLM. ### Global Tools These tools provide general, account-wide information. - `get_account_info`: Returns information about the current SendPulse account, including pricing plan, message counts, bots, contacts, etc. - `get_bots_list`: Returns a list of all connected chatbots with details for each. - `get_dialogs`: Returns a list of dialogs from all channels, with support for pagination and sorting. ### Universal Tools These tools perform actions on specific channels. They require a `channel` parameter to be specified. - **`send_message`**: Sends a text message to a contact. - **`channel`**: The channel to use. Supported values: `whatsapp`, `telegram`, `instagram`, `messenger`, `livechat`, `viber`. - **`contact_id`**: The ID of the recipient. - **`text`**: The message content. ## Authentication The server supports two flexible methods for authenticating requests to the SendPulse API, which are handled on a per-session basis. ### Method 1: API ID & Secret (Recommended) The client can provide SendPulse API credentials by sending two custom HTTP headers: - `x-sp-id`: Your SendPulse API ID. - `x-sp-secret`: Your SendPulse API Secret. Upon receiving these headers, the MCP server will automatically perform the OAuth 2.0 `client_credentials` flow to obtain a temporary access token from SendPulse. These tokens are cached in memory to improve performance for subsequent requests from the same user (same API ID). ### Method 2: Direct OAuth Token The client can provide a pre-existing, valid SendPulse OAuth 2.0 token directly. This is supported in two ways: 1. **Via `Authorization` Header (Standard):** - `Authorization: Bearer <your_oauth_token>` 2. **Via MCP `initialize` Request Body (Legacy/Compatibility):** - As part of the MCP JSON configuration. ## Getting Started ### Prerequisites - [Node.js](https://nodejs.org/) (v18 or later recommended) - [npm](https://www.npmjs.com/) (usually comes with Node.js) ### Installation 1. Clone the repository (if applicable). 2. Install the project dependencies: ```bash npm install ``` ### Build To build the project, run the following command. ```bash npm run build ``` ### Running the Server Once the project is built, you can start the server: ```bash npm start ``` You should see a confirmation message in your console: `SendPulse MCP HTTP Server running on http://localhost:3000/mcp` ### Exposing the TEST Server with ngrok To make your local server accessible to services like the OpenAI sandbox, you need to expose it to the internet. You can use [ngrok](https://ngrok.com/download) for this purpose. Open a **new terminal window** and run: ```bash ngrok http 3000 ``` Ngrok will provide you with a public `https://` URL (e.g., `https://random-string.ngrok-free.app`). Use this URL (`https://random-string.ngrok-free.app/mcp`) when configuring the MCP tool in your LLM client. **Note:** To bypass the ngrok browser warning page, you may need to configure your LLM client to send an additional header with every request, for example: `ngrok-skip-browser-warning: "true"`.