chatrail-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ChatRail
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,137 @@
+# ChatRail MCP server
+
+Operate a [ChatRail](https://www.chatrail.dev) workspace from Claude, Cursor, VS Code and any other
+[Model Context Protocol](https://modelcontextprotocol.io) client. Check the health of your WhatsApp
+connections, look up groups, trace why a message failed, manage scheduled messages and replay
+webhook deliveries without leaving your editor.
+
+ChatRail is a WhatsApp API for developers: send and receive WhatsApp messages over HTTP from a number
+you already have. See the [MCP documentation](https://www.chatrail.dev/mcp) for the full reference.
+
+## Privacy by design
+
+- Message bodies, recipient phone numbers and credentials are never returned by any tool.
+- Tools that change state return a preview first and apply only when called again with
+  `confirm: true`.
+- Every call is scoped to one workspace and recorded in its audit log.
+
+## Two ways to connect
+
+### 1. Hosted server with OAuth (recommended)
+
+Point any client that supports remote MCP servers at:
+
+```
+https://www.chatrail.dev/v1/mcp
+```
+
+Your client opens a browser window where a workspace owner, admin or developer approves access.
+Nothing to install and no key to copy.
+
+**Claude Code**
+
+```bash
+claude mcp add --transport http chatrail https://www.chatrail.dev/v1/mcp
+```
+
+**Cursor** (`~/.cursor/mcp.json`)
+
+```json
+{
+  "mcpServers": {
+    "chatrail": { "url": "https://www.chatrail.dev/v1/mcp" }
+  }
+}
+```
+
+**VS Code** (`.vscode/mcp.json`)
+
+```json
+{
+  "servers": {
+    "chatrail": { "type": "http", "url": "https://www.chatrail.dev/v1/mcp" }
+  }
+}
+```
+
+### 2. Local stdio server with an API key
+
+For clients that only run local servers, or when you would rather use an API key. This package runs
+on your machine and forwards requests to the hosted server.
+
+1. In the [ChatRail dashboard](https://www.chatrail.dev/dashboard), create a workspace API key with
+   the `mcp:read` scope. Add `mcp:write` if the assistant may reschedule, cancel, react or replay.
+2. Add the server to your client.
+
+**Claude Desktop** (`claude_desktop_config.json`)
+
+```json
+{
+  "mcpServers": {
+    "chatrail": {
+      "command": "npx",
+      "args": ["-y", "github:chatrail/chatrail_mcp"],
+      "env": { "CHATRAIL_API_KEY": "cr_live_..." }
+    }
+  }
+}
+```
+
+**Docker**
+
+```bash
+docker build -t chatrail-mcp .
+docker run -i --rm -e CHATRAIL_API_KEY=cr_live_... chatrail-mcp
+```
+
+| Variable | Required | Description |
+| --- | --- | --- |
+| `CHATRAIL_API_KEY` | Yes, to call tools | Workspace API key with `mcp:read` (and optionally `mcp:write`). |
+| `CHATRAIL_MCP_URL` | No | Override the endpoint. Defaults to `https://www.chatrail.dev/v1/mcp`. |
+
+Without a key the server still starts and lists its tools, so you can inspect it before signing up.
+
+## Tools
+
+| Tool | Scope | What it does |
+| --- | --- | --- |
+| `list_connections` | read | Every WhatsApp connection in the workspace with its state and health. |
+| `get_connection` | read | One connection with its state, health and recent state history. |
+| `list_whatsapp_groups` | read | Groups visible to a connected number, with ids and participant counts. |
+| `get_whatsapp_group` | read | Name, description, settings and member counts for one group. |
+| `list_messages` | read | Recent messages with their delivery state. |
+| `get_message` | read | One message and its delivery timeline. |
+| `explain_message_failure` | read | A structured explanation of why a message failed. |
+| `list_scheduled_messages` | read | Messages waiting to be sent, soonest first. |
+| `list_webhook_deliveries` | read | Recent webhook deliveries and their outcomes. |
+| `reschedule_message` | write | Change when a scheduled message is sent. Previews first. |
+| `cancel_scheduled_message` | write | Cancel a message that has not been sent. Previews first. |
+| `react_to_message` | write | Set or remove an emoji reaction on a message. Previews first. |
+| `replay_webhook` | write | Requeue a dead or skipped webhook delivery. Previews first. |
+
+## Plans
+
+MCP access is included on the ChatRail **Core + AI** and **Team** plans. See
+[pricing](https://www.chatrail.dev/pricing).
+
+## Development
+
+```bash
+npm install
+npm run build
+CHATRAIL_API_KEY=cr_test_... node dist/index.js
+```
+
+`tools.json` is the tool catalog served when no API key is configured. It is exported from the
+hosted server and should be refreshed when the hosted tools change.
+
+## Links
+
+- Website: <https://www.chatrail.dev>
+- MCP docs: <https://www.chatrail.dev/mcp>
+- API reference: <https://www.chatrail.dev/api-reference>
+- Authentication: <https://www.chatrail.dev/auth.md>
+
+## License
+
+[MIT](LICENSE)

package/dist/index.js

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, McpError, } from '@modelcontextprotocol/sdk/types.js';
+/**
+ * A local stdio MCP server for ChatRail.
+ *
+ * It forwards every request to the hosted ChatRail MCP endpoint, authenticated with a workspace
+ * API key. The hosted endpoint is the single source of truth for what the tools do and who may
+ * call them; this process holds no business logic and stores nothing.
+ *
+ * Without an API key it still starts and lists the bundled tool catalog, so clients and
+ * directories can inspect it. Calling a tool then explains how to configure a key.
+ */
+const VERSION = '0.1.0';
+const DEFAULT_URL = 'https://www.chatrail.dev/v1/mcp';
+const catalog = JSON.parse(readFileSync(new URL('../tools.json', import.meta.url), 'utf8'));
+const apiKey = process.env.CHATRAIL_API_KEY?.trim() || undefined;
+const endpoint = new URL(process.env.CHATRAIL_MCP_URL?.trim() || DEFAULT_URL);
+const MISSING_KEY = 'CHATRAIL_API_KEY is not set. Create a workspace API key with the mcp:read scope ' +
+    '(add mcp:write to allow changes) at https://www.chatrail.dev/dashboard and pass it to ' +
+    'this server as the CHATRAIL_API_KEY environment variable.';
+/** Turn the hosted endpoint's HTTP refusals into messages a person can act on. */
+function explain(err) {
+    const status = err.code;
+    if (status === 401) {
+        return new McpError(ErrorCode.InvalidRequest, 'ChatRail rejected the API key. Check that CHATRAIL_API_KEY is a current workspace key.');
+    }
+    if (status === 403) {
+        return new McpError(ErrorCode.InvalidRequest, 'ChatRail refused the request. The API key needs the mcp:read scope (mcp:write for ' +
+            'changes), and MCP is included on the Core + AI and Team plans.');
+    }
+    return err;
+}
+let upstream;
+/** One connection to the hosted endpoint, opened on first use and reused afterwards. */
+function connectUpstream(key) {
+    upstream ??= (async () => {
+        const client = new Client({ name: 'chatrail-mcp', version: VERSION });
+        const transport = new StreamableHTTPClientTransport(endpoint, {
+            requestInit: {
+                headers: {
+                    Authorization: `Bearer ${key}`,
+                    'User-Agent': `chatrail-mcp/${VERSION}`,
+                },
+            },
+        });
+        await client.connect(transport);
+        return client;
+    })().catch((err) => {
+        // Let the next call try again instead of caching the failure.
+        upstream = undefined;
+        throw explain(err);
+    });
+    return upstream;
+}
+const server = new Server({ name: 'chatrail', version: VERSION }, { capabilities: { tools: {} }, instructions: catalog.instructions });
+server.setRequestHandler(ListToolsRequestSchema, async (request) => {
+    if (!apiKey)
+        return { tools: catalog.tools };
+    const client = await connectUpstream(apiKey);
+    return client.listTools(request.params).catch((err) => {
+        throw explain(err);
+    });
+});
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    if (!apiKey) {
+        return { content: [{ type: 'text', text: MISSING_KEY }], isError: true };
+    }
+    const client = await connectUpstream(apiKey);
+    return client.callTool(request.params).catch((err) => {
+        throw explain(err);
+    });
+});
+await server.connect(new StdioServerTransport());
+// The client owns this process: when it closes stdin, exit rather than let the open upstream
+// connection keep us alive.
+process.stdin.on('close', () => process.exit(0));

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "chatrail-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for ChatRail: inspect WhatsApp connections, groups, message delivery, schedules and webhook deliveries from Claude, Cursor and other MCP clients.",
+  "mcpName": "dev.chatrail/chatrail",
+  "type": "module",
+  "bin": {
+    "chatrail-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "tools.json"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepare": "npm run build",
+    "start": "node dist/index.js"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "whatsapp",
+    "whatsapp-api",
+    "chatrail",
+    "claude",
+    "cursor"
+  ],
+  "homepage": "https://www.chatrail.dev/mcp",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chatrail/chatrail_mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/chatrail/chatrail_mcp/issues"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.9.0"
+  }
+}

package/tools.json

@@ -0,0 +1,428 @@
+{
+  "instructions": "Operational tools for one ChatRail workspace: connections, WhatsApp groups, message delivery, schedules and webhook deliveries. Message bodies, recipient numbers and credentials are never returned. Tools that change state return a preview first and apply only when called again with confirm: true.",
+  "tools": [
+    {
+      "name": "list_connections",
+      "title": "List connections",
+      "description": "Every WhatsApp connection in the workspace with its current state and health. Phone numbers are not included.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "limit": {
+            "default": 20,
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 50
+          }
+        },
+        "$schema": "http://json-schema.org/draft-07/schema#"
+      },
+      "annotations": {
+        "readOnlyHint": true,
+        "destructiveHint": false,
+        "idempotentHint": true
+      },
+      "execution": {
+        "taskSupport": "forbidden"
+      }
+    },
+    {
+      "name": "get_connection",
+      "title": "Get a connection",
+      "description": "One connection, with its state, health and recent state history.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "connection": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 40
+          }
+        },
+        "required": [
+          "connection"
+        ],
+        "$schema": "http://json-schema.org/draft-07/schema#"
+      },
+      "annotations": {
+        "readOnlyHint": true,
+        "destructiveHint": false,
+        "idempotentHint": true
+      },
+      "execution": {
+        "taskSupport": "forbidden"
+      }
+    },
+    {
+      "name": "list_whatsapp_groups",
+      "title": "List WhatsApp groups",
+      "description": "A bounded page of groups visible to one connected WhatsApp number. Returns group names, stable group ids and participant counts when available; participant identities are never returned.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "connection": {
+            "type": "string",
+            "minLength": 2,
+            "maxLength": 40
+          },
+          "limit": {
+            "default": 20,
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 50
+          },
+          "offset": {
+            "default": 0,
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 100000
+          }
+        },
+        "required": [
+          "connection"
+        ],
+        "$schema": "http://json-schema.org/draft-07/schema#"
+      },
+      "annotations": {
+        "readOnlyHint": true,
+        "destructiveHint": false,
+        "idempotentHint": true
+      },
+      "execution": {
+        "taskSupport": "forbidden"
+      }
+    },
+    {
+      "name": "get_whatsapp_group",
+      "title": "Describe a WhatsApp group",
+      "description": "Name, description, settings and member counts for one group a connected number is in. Like list_whatsapp_groups, it never returns who the members are.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "connection": {
+            "type": "string",
+            "minLength": 2,
+            "maxLength": 40
+          },
+          "group_id": {
+            "type": "string",
+            "minLength": 5,
+            "maxLength": 40
+          }
+        },
+        "required": [
+          "connection",
+          "group_id"
+        ],
+        "$schema": "http://json-schema.org/draft-07/schema#"
+      },
+      "annotations": {
+        "readOnlyHint": true,
+        "destructiveHint": false,
+        "idempotentHint": true
+      },
+      "execution": {
+        "taskSupport": "forbidden"
+      }
+    },
+    {
+      "name": "list_messages",
+      "title": "List messages",
+      "description": "Recent messages with their delivery state. Message bodies and recipient numbers are deliberately excluded.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "connection": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 40
+          },
+          "status": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 20
+          },
+          "direction": {
+            "type": "string",
+            "enum": [
+              "inbound",
+              "outbound"
+            ]
+          },
+          "limit": {
+            "default": 20,
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 50
+          },
+          "cursor": {
+            "type": "string",
+            "maxLength": 200
+          }
+        },
+        "$schema": "http://json-schema.org/draft-07/schema#"
+      },
+      "annotations": {
+        "readOnlyHint": true,
+        "destructiveHint": false,
+        "idempotentHint": true
+      },
+      "execution": {
+        "taskSupport": "forbidden"
+      }
+    },
+    {
+      "name": "get_message",
+      "title": "Get a message",
+      "description": "One message and its delivery timeline. The body is not returned.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "message_id": {
+            "type": "string",
+            "format": "uuid",
+            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
+          }
+        },
+        "required": [
+          "message_id"
+        ],
+        "$schema": "http://json-schema.org/draft-07/schema#"
+      },
+      "annotations": {
+        "readOnlyHint": true,
+        "destructiveHint": false,
+        "idempotentHint": true
+      },
+      "execution": {
+        "taskSupport": "forbidden"
+      }
+    },
+    {
+      "name": "explain_message_failure",
+      "title": "Explain why a message failed",
+      "description": "A structured explanation derived from the failure classification recorded when the message failed. Deterministic — it does not summarise logs.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "message_id": {
+            "type": "string",
+            "format": "uuid",
+            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
+          }
+        },
+        "required": [
+          "message_id"
+        ],
+        "$schema": "http://json-schema.org/draft-07/schema#"
+      },
+      "annotations": {
+        "readOnlyHint": true,
+        "destructiveHint": false,
+        "idempotentHint": true
+      },
+      "execution": {
+        "taskSupport": "forbidden"
+      }
+    },
+    {
+      "name": "list_scheduled_messages",
+      "title": "List scheduled messages",
+      "description": "Messages waiting to be sent, soonest first.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "limit": {
+            "default": 20,
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 50
+          },
+          "cursor": {
+            "type": "string",
+            "maxLength": 200
+          }
+        },
+        "$schema": "http://json-schema.org/draft-07/schema#"
+      },
+      "annotations": {
+        "readOnlyHint": true,
+        "destructiveHint": false,
+        "idempotentHint": true
+      },
+      "execution": {
+        "taskSupport": "forbidden"
+      }
+    },
+    {
+      "name": "list_webhook_deliveries",
+      "title": "List webhook deliveries",
+      "description": "Recent customer webhook deliveries and their outcomes. Payloads and endpoint URLs are not returned.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "status": {
+            "type": "string",
+            "enum": [
+              "pending",
+              "delivered",
+              "failed",
+              "dead",
+              "skipped"
+            ]
+          },
+          "limit": {
+            "default": 20,
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 50
+          }
+        },
+        "$schema": "http://json-schema.org/draft-07/schema#"
+      },
+      "annotations": {
+        "readOnlyHint": true,
+        "destructiveHint": false,
+        "idempotentHint": true
+      },
+      "execution": {
+        "taskSupport": "forbidden"
+      }
+    },
+    {
+      "name": "reschedule_message",
+      "title": "Move a scheduled message",
+      "description": "Change when a scheduled message will be sent. Returns a preview of the change; pass confirm: true to apply it.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "message_id": {
+            "type": "string",
+            "format": "uuid",
+            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
+          },
+          "send_at": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 40
+          },
+          "confirm": {
+            "default": false,
+            "type": "boolean"
+          }
+        },
+        "required": [
+          "message_id",
+          "send_at"
+        ],
+        "$schema": "http://json-schema.org/draft-07/schema#"
+      },
+      "annotations": {
+        "readOnlyHint": false,
+        "destructiveHint": false,
+        "idempotentHint": false
+      },
+      "execution": {
+        "taskSupport": "forbidden"
+      }
+    },
+    {
+      "name": "cancel_scheduled_message",
+      "title": "Cancel a scheduled message",
+      "description": "Cancel a message that has not yet been sent. Returns a preview; pass confirm: true to apply it.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "message_id": {
+            "type": "string",
+            "format": "uuid",
+            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
+          },
+          "confirm": {
+            "default": false,
+            "type": "boolean"
+          }
+        },
+        "required": [
+          "message_id"
+        ],
+        "$schema": "http://json-schema.org/draft-07/schema#"
+      },
+      "annotations": {
+        "readOnlyHint": false,
+        "destructiveHint": false,
+        "idempotentHint": false
+      },
+      "execution": {
+        "taskSupport": "forbidden"
+      }
+    },
+    {
+      "name": "react_to_message",
+      "title": "React to a message",
+      "description": "Set this number's emoji reaction on a message it sent or received, or remove it with an empty emoji. The person in the chat sees it. Returns a preview; pass confirm: true to apply.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "message_id": {
+            "type": "string",
+            "format": "uuid",
+            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
+          },
+          "emoji": {
+            "type": "string",
+            "maxLength": 16
+          },
+          "confirm": {
+            "default": false,
+            "type": "boolean"
+          }
+        },
+        "required": [
+          "message_id",
+          "emoji"
+        ],
+        "$schema": "http://json-schema.org/draft-07/schema#"
+      },
+      "annotations": {
+        "readOnlyHint": false,
+        "destructiveHint": false,
+        "idempotentHint": false
+      },
+      "execution": {
+        "taskSupport": "forbidden"
+      }
+    },
+    {
+      "name": "replay_webhook",
+      "title": "Replay a failed webhook delivery",
+      "description": "Return a dead or skipped webhook delivery to the queue. Returns a preview; pass confirm: true to apply it.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "delivery_id": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 64
+          },
+          "confirm": {
+            "default": false,
+            "type": "boolean"
+          }
+        },
+        "required": [
+          "delivery_id"
+        ],
+        "$schema": "http://json-schema.org/draft-07/schema#"
+      },
+      "annotations": {
+        "readOnlyHint": false,
+        "destructiveHint": false,
+        "idempotentHint": false
+      },
+      "execution": {
+        "taskSupport": "forbidden"
+      }
+    }
+  ]
+}