# Whatify MCP Server

An MCP (Model Context Protocol) server that exposes Whatify's WhatsApp API — sending
messages, templates, and Flows, plus reading contacts, conversations, campaigns, and
wallet balance — as tools for MCP-compatible AI clients (Claude Desktop, Claude Code, etc.).

It's a thin wrapper around the existing `v1/external` REST API
(`app/Http/Controllers/Api/ExternalApiController.php`), authenticated the same way:
an API key generated from **Settings → API Keys** in the Whatify dashboard.

## Tools

| Tool | Maps to | Notes |
|---|---|---|
| `whatify_ping` | `GET /ping` | Connectivity/auth check |
| `whatify_send_message` | `POST /send-message` | Free-form text |
| `whatify_send_template` | `POST /send-template` | Approved templates only |
| `whatify_send_flow` | `POST /send-flow` | WhatsApp Flow (interactive form) |
| `whatify_message_status` | `GET /messages/{id}` | Delivery status |
| `whatify_list_templates` | `GET /templates` | |
| `whatify_list_flows` | `GET /flows` | |
| `whatify_list_contacts` | `GET /contacts` | |
| `whatify_get_contact` | `GET /contacts/{id}` | |
| `whatify_create_contact` | `POST /contacts` | |
| `whatify_update_contact` | `PUT /contacts/{id}` | |
| `whatify_list_conversations` | `GET /conversations` | |
| `whatify_get_conversation_messages` | `GET /conversations/{id}/messages` | |
| `whatify_list_campaigns` | `GET /campaigns` | |
| `whatify_get_campaign` | `GET /campaigns/{id}` | Includes delivery/read rate |
| `whatify_wallet_balance` | `GET /wallet/balance` | |

`send_flow` and reading flows require the API key to have the `send_flow` /
`read_flows` permissions (added alongside this server — check the boxes when
generating a key in **Settings → API Keys**).

## Setup

1. Get an API key: log into Whatify → **Settings → API Keys** → generate a key with
   the permissions you want the AI tool to have (e.g. `send_message`, `send_template`,
   `send_flow`, `read_contacts`).
2. Install dependencies:
   ```
   cd mcp-server
   npm install
   ```
3. Configure environment variables:
   - `WHATIFY_API_KEY` — the key from step 1 (required)
   - `WHATIFY_API_BASE_URL` — defaults to `http://localhost/api/v1/external`; set this
     to your real app URL, e.g. `https://whatify.in/api/v1/external`

## Using with Claude Desktop / Claude Code

Add to your MCP client config (e.g. `claude_desktop_config.json`, or via
`claude mcp add` for Claude Code):

```json
{
  "mcpServers": {
    "whatify": {
      "command": "node",
      "args": ["C:/xampp/htdocs/whatify/mcp-server/src/index.js"],
      "env": {
        "WHATIFY_API_KEY": "wk_xxxxxxxxxxxxxxxx",
        "WHATIFY_API_BASE_URL": "https://whatify.in/api/v1/external"
      }
    }
  }
}
```

Restart the client, then ask it to send a message, e.g.:
> "Using Whatify, send a WhatsApp message to +91XXXXXXXXXX saying the order has shipped."

## Manual test

You can talk to the server directly over stdio for debugging:

```
npm start
```

then send newline-delimited JSON-RPC (`initialize`, `tools/list`, `tools/call`) on
stdin. Easier: use the [MCP Inspector](https://github.com/modelcontextprotocol/inspector):

```
npx @modelcontextprotocol/inspector node src/index.js
```