botmsg 0.1.0

package/README.md

@@ -0,0 +1,984 @@
+# botmsg
+
+> Universal MCP Server for multi-platform bot messaging — one interface, seven platforms.
+
+[![npm version](https://img.shields.io/npm/v/botmsg.svg)](https://www.npmjs.com/package/botmsg)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org)
+
+Send messages to **DingTalk (钉钉)**, **WeCom (企业微信)**, **Feishu (飞书)**, **Lark**, **Slack**, **Discord**, and **Telegram** through a unified MCP (Model Context Protocol) interface. Configure bots via environment variables or YAML/JSON config files, then let AI assistants send notifications, alerts, and reports across all your team channels.
+
+---
+
+## Table of Contents
+
+- [Features](#features)
+- [How It Works](#how-it-works)
+- [Installation](#installation)
+- [MCP Client Configuration](#mcp-client-configuration)
+  - [Claude Desktop](#claude-desktop)
+  - [VS Code (Copilot)](#vs-code-copilot)
+  - [Cursor](#cursor)
+  - [Windsurf](#windsurf)
+  - [Cline](#cline)
+  - [Generic / stdio](#generic--stdio)
+- [Configuration](#configuration)
+  - [Mode A: Environment Variables](#mode-a-environment-variables)
+  - [Mode B: External Config File (YAML/JSON)](#mode-b-external-config-file-yamljson)
+  - [Bot Naming Convention](#bot-naming-convention)
+  - [Global Settings](#global-settings)
+- [Platform Setup Guides](#platform-setup-guides)
+  - [DingTalk (钉钉)](#dingtalk-钉钉)
+  - [WeCom (企业微信)](#wecom-企业微信)
+  - [Feishu (飞书)](#feishu-飞书)
+  - [Lark (International)](#lark-international)
+  - [Slack](#slack)
+  - [Discord](#discord)
+  - [Telegram](#telegram)
+- [MCP Tools Reference](#mcp-tools-reference)
+  - [send_message](#send_message)
+  - [send_file](#send_file)
+  - [send_broadcast](#send_broadcast)
+  - [send_batch](#send_batch)
+  - [list_bots](#list_bots)
+  - [message_status](#message_status)
+  - [render_template](#render_template)
+- [Message Types & Platform Mapping](#message-types--platform-mapping)
+- [Template Engine](#template-engine)
+  - [Built-in Helpers](#built-in-helpers)
+  - [Conditional Logic](#conditional-logic)
+  - [Partials](#partials)
+- [Rate Limiting & Retry](#rate-limiting--retry)
+- [Audit Logging](#audit-logging)
+- [Dry Run Mode](#dry-run-mode)
+- [Error Handling](#error-handling)
+- [Development](#development)
+- [Troubleshooting](#troubleshooting)
+- [License](#license)
+
+---
+
+## Features
+
+- **7 platforms, 1 interface** — Unified message API across DingTalk, WeCom, Feishu, Lark, Slack, Discord, and Telegram
+- **7 message types** — `text`, `markdown`, `link`, `image`, `card`, `news`, `file` with automatic cross-platform adaptation
+- **Template engine** — Handlebars templates with 12+ custom helpers (`{{date}}`, `{{uppercase}}`, `{{if_eq}}`, `{{now}}`, etc.)
+- **Broadcast** — Send one message to multiple bots across different platforms simultaneously
+- **Batch send** — Send to multiple targets (e.g., Telegram groups) through a single bot
+- **Rate limiting** — Per-platform Bottleneck limiters matching each API's rate limits, with exponential backoff retry
+- **Audit logging** — In-memory ring buffer + optional JSONL file persistence for full message tracking
+- **Dual configuration** — Environment variables for quick setup, YAML/JSON files for complex deployments
+- **Dry run mode** — Preview message payloads without actually sending
+- **Zero-config binary** — Runs via `npx botmsg`, no global installation needed
+
+## How It Works
+
+```
+┌──────────────┐     MCP (stdio)     ┌──────────┐     HTTP/HTTPS     ┌─────────────────┐
+│  AI Assistant │ ◄────────────────► │  botmsg   │ ────────────────► │  Bot Platforms   │
+│  (Claude,     │   JSON-RPC tools   │  MCP      │   Webhook APIs    │  DingTalk, WeCom │
+│   VS Code,    │                    │  Server   │                   │  Feishu, Slack.. │
+│   Cursor...)  │                    │           │                   │                  │
+└──────────────┘                     └──────────┘                   └─────────────────┘
+                                          │
+                                          ▼
+                                     ┌──────────┐
+                                     │  Audit    │
+                                     │  Log      │
+                                     └──────────┘
+```
+
+1. Your AI assistant (Claude, VS Code Copilot, Cursor, etc.) discovers `botmsg` via MCP protocol
+2. It calls tools like `send_message`, `send_broadcast`, etc. with structured arguments
+3. `botmsg` applies template rendering, rate limiting, and routes to the correct platform adapter
+4. The platform adapter translates the unified message format into the platform-specific API payload
+5. Audit logger records every send attempt with status, latency, and error details
+
+---
+
+## Installation
+
+No installation needed — just use `npx`:
+
+```bash
+npx -y botmsg
+```
+
+Or install globally:
+
+```bash
+npm install -g botmsg
+```
+
+**Requirements:** Node.js >= 18.0.0
+
+---
+
+## MCP Client Configuration
+
+### Claude Desktop
+
+Edit your Claude Desktop config file:
+
+- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "botmsg": {
+      "command": "npx",
+      "args": ["-y", "botmsg"],
+      "env": {
+        "BOTMSG_DINGTALK_OPS_WEBHOOK": "https://oapi.dingtalk.com/robot/send?access_token=YOUR_TOKEN",
+        "BOTMSG_WECOM_DEV_WEBHOOK": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY",
+        "BOTMSG_FEISHU_ALERT_WEBHOOK": "https://open.feishu.cn/open-apis/bot/v2/hook/YOUR_HOOK",
+        "BOTMSG_SLACK_GENERAL_WEBHOOK": "https://hooks.slack.com/services/T00/B00/xxx",
+        "BOTMSG_DISCORD_GAMING_WEBHOOK": "https://discord.com/api/webhooks/123456/TOKEN",
+        "BOTMSG_TELEGRAM_BOT_TOKEN": "123456:ABC-DEF...",
+        "BOTMSG_TELEGRAM_BOT_CHAT_ID": "-1001234567890"
+      }
+    }
+  }
+}
+```
+
+> **Windows Note:** If `npx` is not found, wrap with `cmd`:
+> ```json
+> {
+>   "mcpServers": {
+>     "botmsg": {
+>       "command": "cmd",
+>       "args": ["/c", "npx", "-y", "botmsg"],
+>       "env": { "..." : "..." }
+>     }
+>   }
+> }
+> ```
+
+### VS Code (Copilot)
+
+Create `.vscode/mcp.json` in your project root:
+
+```json
+{
+  "servers": {
+    "botmsg": {
+      "command": "npx",
+      "args": ["-y", "botmsg"],
+      "env": {
+        "BOTMSG_DINGTALK_OPS_WEBHOOK": "${env:DINGTALK_WEBHOOK}",
+        "BOTMSG_SLACK_GENERAL_WEBHOOK": "${env:SLACK_WEBHOOK}"
+      }
+    }
+  }
+}
+```
+
+### Cursor
+
+Open Settings > MCP > Add new MCP server, or edit `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "botmsg": {
+      "command": "npx",
+      "args": ["-y", "botmsg"],
+      "env": {
+        "BOTMSG_DINGTALK_OPS_WEBHOOK": "https://oapi.dingtalk.com/robot/send?access_token=xxx"
+      }
+    }
+  }
+}
+```
+
+### Windsurf
+
+Add to your Windsurf MCP config:
+
+```json
+{
+  "mcpServers": {
+    "botmsg": {
+      "command": "npx",
+      "args": ["-y", "botmsg"],
+      "env": {
+        "BOTMSG_CONFIG": "/path/to/bots.yaml"
+      }
+    }
+  }
+}
+```
+
+### Cline
+
+Add to Cline MCP settings:
+
+```json
+{
+  "mcpServers": {
+    "botmsg": {
+      "command": "npx",
+      "args": ["-y", "botmsg"],
+      "env": {
+        "BOTMSG_TELEGRAM_BOT_TOKEN": "123456:ABC...",
+        "BOTMSG_TELEGRAM_BOT_CHAT_ID": "-1001234"
+      }
+    }
+  }
+}
+```
+
+### Generic / stdio
+
+`botmsg` speaks MCP over stdio. Any MCP-compatible client can launch it:
+
+```bash
+node node_modules/botmsg/dist/index.js
+```
+
+Or directly:
+
+```bash
+npx -y botmsg
+```
+
+---
+
+## Configuration
+
+### Mode A: Environment Variables
+
+The simplest way. Pattern: `BOTMSG_{PLATFORM}_{INSTANCE}_{FIELD}`
+
+Each bot is identified by a **name** composed of `{platform}-{instance}`. For example, `dingtalk-ops` creates a DingTalk bot named "ops".
+
+#### DingTalk (钉钉)
+
+```bash
+BOTMSG_DINGTALK_OPS_WEBHOOK=https://oapi.dingtalk.com/robot/send?access_token=YOUR_TOKEN
+BOTMSG_DINGTALK_OPS_SECRET=SEC...                          # Optional: for HMAC-SHA256
+BOTMSG_DINGTALK_OPS_SECURITY=sign                          # keyword (default) | ip | sign
+```
+
+#### WeCom (企业微信)
+
+```bash
+BOTMSG_WECOM_DEV_WEBHOOK=https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY
+```
+
+#### Feishu (飞书)
+
+```bash
+BOTMSG_FEISHU_ALERT_WEBHOOK=https://open.feishu.cn/open-apis/bot/v2/hook/YOUR_HOOK
+BOTMSG_FEISHU_ALERT_SECRET=YOUR_SECRET                     # Optional: HMAC-SHA256
+```
+
+#### Lark (International Feishu)
+
+```bash
+BOTMSG_LARK_GLOBAL_WEBHOOK=https://open.larksuite.com/open-apis/bot/v2/hook/YOUR_HOOK
+BOTMSG_LARK_GLOBAL_SECRET=YOUR_SECRET                      # Optional
+```
+
+#### Slack
+
+```bash
+BOTMSG_SLACK_GENERAL_WEBHOOK=https://hooks.slack.com/services/T00000/B00000/xxxxx
+```
+
+#### Discord
+
+```bash
+BOTMSG_DISCORD_GAMING_WEBHOOK=https://discord.com/api/webhooks/WEBHOOK_ID/TOKEN
+BOTMSG_DISCORD_GAMING_USERNAME=MyBot                       # Optional: override username
+BOTMSG_DISCORD_GAMING_AVATAR_URL=https://...               # Optional: override avatar
+```
+
+#### Telegram
+
+```bash
+BOTMSG_TELEGRAM_BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
+BOTMSG_TELEGRAM_BOT_CHAT_ID=-1001234567890                 # Group/channel ID
+BOTMSG_TELEGRAM_BOT_PARSE_MODE=MarkdownV2                  # MarkdownV2 | HTML | (empty)
+```
+
+#### Multiple Instances
+
+You can configure multiple bots per platform by using different instance names:
+
+```bash
+BOTMSG_DINGTALK_OPS_WEBHOOK=https://oapi.dingtalk.com/...?access_token=TOKEN_A
+BOTMSG_DINGTALK_ALERTS_WEBHOOK=https://oapi.dingtalk.com/...?access_token=TOKEN_B
+BOTMSG_SLACK_ENGINEERING_WEBHOOK=https://hooks.slack.com/services/...
+BOTMSG_SLACK_MARKETING_WEBHOOK=https://hooks.slack.com/services/...
+```
+
+This creates 4 bots: `dingtalk-ops`, `dingtalk-alerts`, `slack-engineering`, `slack-marketing`.
+
+### Mode B: External Config File (YAML/JSON)
+
+For complex deployments, point `BOTMSG_CONFIG` to a config file:
+
+```json
+{
+  "mcpServers": {
+    "botmsg": {
+      "command": "npx",
+      "args": ["-y", "botmsg"],
+      "env": {
+        "BOTMSG_CONFIG": "/path/to/bots.yaml"
+      }
+    }
+  }
+}
+```
+
+#### YAML Format (`bots.yaml`)
+
+```yaml
+bots:
+  dingtalk-ops:
+    platform: dingtalk
+    webhook: "https://oapi.dingtalk.com/robot/send?access_token=xxx"
+    secret: "SEC..."
+    security: sign
+
+  wecom-dev:
+    platform: wecom
+    webhook: "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx"
+
+  feishu-alert:
+    platform: feishu
+    webhook: "https://open.feishu.cn/open-apis/bot/v2/hook/xxx"
+    secret: "xxx"
+
+  lark-global:
+    platform: lark
+    webhook: "https://open.larksuite.com/open-apis/bot/v2/hook/xxx"
+
+  slack-general:
+    platform: slack
+    webhook: "https://hooks.slack.com/services/T.../B.../xxx"
+
+  discord-gaming:
+    platform: discord
+    webhook: "https://discord.com/api/webhooks/xxx/yyy"
+    username: "GameBot"
+
+  telegram-bot:
+    platform: telegram
+    token: "123456:ABC..."
+    chat_id: "-1001234567"
+    parse_mode: "MarkdownV2"
+
+settings:
+  log_level: info
+  audit_log: "/tmp/botmsg-audit.jsonl"
+  max_retries: 3
+  dry_run: false
+```
+
+#### JSON Format (`bots.json`)
+
+```json
+{
+  "bots": {
+    "dingtalk-ops": {
+      "platform": "dingtalk",
+      "webhook": "https://oapi.dingtalk.com/robot/send?access_token=xxx",
+      "secret": "SEC...",
+      "security": "sign"
+    },
+    "telegram-bot": {
+      "platform": "telegram",
+      "token": "123456:ABC...",
+      "chat_id": "-1001234567"
+    }
+  },
+  "settings": {
+    "log_level": "info",
+    "max_retries": 3
+  }
+}
+```
+
+#### Mixed Mode
+
+File config takes priority, env vars supplement:
+
+```bash
+BOTMSG_CONFIG=/path/to/bots.yaml
+BOTMSG_SLACK_EXTRA_WEBHOOK=https://hooks.slack.com/...   # Added on top of file config
+```
+
+### Bot Naming Convention
+
+Bot names are auto-generated as `{platform}-{instance}`:
+
+| Env Variable | Bot Name |
+|---|---|
+| `BOTMSG_DINGTALK_OPS_WEBHOOK` | `dingtalk-ops` |
+| `BOTMSG_WECOM_DEV_WEBHOOK` | `wecom-dev` |
+| `BOTMSG_TELEGRAM_BOT_TOKEN` | `telegram-bot` |
+| `BOTMSG_SLACK_GENERAL_WEBHOOK` | `slack-general` |
+
+Use these names when calling tools: `{ "bot": "dingtalk-ops", ... }`
+
+### Global Settings
+
+| Variable | Default | Description |
+|---|---|---|
+| `BOTMSG_LOG_LEVEL` | `info` | Log level: `debug`, `info`, `warn`, `error` |
+| `BOTMSG_AUDIT_LOG` | _(none)_ | Path to JSONL audit log file for persistent message tracking |
+| `BOTMSG_MAX_RETRIES` | `3` | Maximum retry attempts on transient failures (0-10) |
+| `BOTMSG_DRY_RUN` | `false` | When `true`, build payloads but don't send (useful for testing) |
+
+---
+
+## Platform Setup Guides
+
+### DingTalk (钉钉)
+
+1. Open the target group chat > Group Settings > Smart Group Assistant > Add Robot
+2. Select "Custom (via Webhook)" robot type
+3. Set security mode (recommended: **Sign** for HMAC-SHA256)
+4. Copy the webhook URL (contains `access_token`)
+5. If using sign mode, copy the `SEC...` secret
+
+**API Docs:** https://open.dingtalk.com/document/orgapp/custom-robots-send-group-messages
+
+### WeCom (企业微信)
+
+1. Open the target group chat > Group Settings > Group Bots > Add Bot
+2. Select "Webhook Bot"
+3. Copy the webhook URL (contains `key=...`)
+
+**API Docs:** https://developer.work.weixin.qq.com/document/path/99110
+
+### Feishu (飞书)
+
+1. Open the target group chat > Settings > Bots > Add Bot
+2. Select "Custom Bot"
+3. Copy the webhook URL (contains `/hook/...`)
+4. Optionally enable signature verification and copy the secret
+
+**API Docs:** https://open.feishu.cn/document/uktmuktmuktm/uctm5yjl3eto24ynxkjn
+
+### Lark (International)
+
+Same process as Feishu, but on the Lark (international) platform. The webhook URL will use `open.larksuite.com` instead of `open.feishu.cn`.
+
+**API Docs:** https://open.larksuite.com/document/client-docs/bot-v3/add-custom-bot
+
+### Slack
+
+1. Go to https://api.slack.com/apps > Create New App
+2. Select "From scratch", give it a name and workspace
+3. Enable "Incoming Webhooks" in the sidebar
+4. Click "Add New Webhook to Workspace" and select a channel
+5. Copy the webhook URL (`https://hooks.slack.com/services/...`)
+
+**API Docs:** https://docs.slack.dev/messaging/sending-messages-using-incoming-webhooks
+
+### Discord
+
+1. Open your Discord server > Server Settings > Integrations > Webhooks
+2. Click "New Webhook", name it, select a channel
+3. Copy the webhook URL (`https://discord.com/api/webhooks/...`)
+
+**API Docs:** https://discord.com/developers/docs/resources/webhook
+
+### Telegram
+
+1. Open Telegram, search for `@BotFather`
+2. Send `/newbot`, follow the prompts to create a bot
+3. Copy the bot token (`123456:ABC-DEF...`)
+4. Add the bot to your target group/chat
+5. Get the chat ID (for groups, it starts with `-100`; you can use `@userinfobot` or the `getUpdates` API)
+
+**API Docs:** https://core.telegram.org/bots/api
+
+---
+
+## MCP Tools Reference
+
+### `send_message`
+
+Send a message to a configured bot. This is the primary tool.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `bot` | string | Yes | Bot instance name (e.g., `dingtalk-ops`) |
+| `type` | string | Yes | Message type: `text`, `markdown`, `link`, `image`, `card`, `news`, `file` |
+| `content` | string | Yes | Message body. Supports Handlebars templates: `{{variable}}` |
+| `title` | string | No | Title for markdown/link/card messages |
+| `variables` | object | No | Template variables as key-value pairs |
+| `at` | object | No | @mention config: `{ users: [...], mobiles: [...], all: bool }` |
+| `link_url` | string | No | URL for link-type messages |
+| `pic_url` | string | No | Thumbnail/picture URL |
+| `buttons` | array | No | Buttons for card messages: `[{ title, url }]` |
+| `single_button_text` | string | No | Single button text (DingTalk actionCard) |
+| `single_button_url` | string | No | Single button URL |
+| `news_items` | array | No | News items: `[{ title, description?, url, pic_url? }]` |
+| `image_url` | string | No | Image URL for image-type messages |
+| `image_base64` | string | No | Base64-encoded image (WeCom only) |
+
+**Example — Text with @mention:**
+
+```json
+{
+  "bot": "dingtalk-ops",
+  "type": "text",
+  "content": "Server CPU exceeded 90%",
+  "at": { "mobiles": ["13800138000"], "all": false }
+}
+```
+
+**Example — Markdown with template variables:**
+
+```json
+{
+  "bot": "slack-engineering",
+  "type": "markdown",
+  "content": "## Deploy Report\n*Service:* {{service}}\n*Status:* {{status}}\n*Duration:* {{duration}}",
+  "variables": { "service": "user-api", "status": "Success", "duration": "3m 24s" },
+  "title": "Deploy Notification"
+}
+```
+
+**Example — Link card:**
+
+```json
+{
+  "bot": "wecom-dev",
+  "type": "link",
+  "content": "PR #142 merged to main branch",
+  "title": "PR Merged",
+  "link_url": "https://github.com/org/repo/pull/142",
+  "pic_url": "https://github.githubassets.com/images/modules/logos_page/GitHub-Mark.png"
+}
+```
+
+**Example — Interactive card with buttons:**
+
+```json
+{
+  "bot": "feishu-alert",
+  "type": "card",
+  "content": "A deployment requires your approval.",
+  "title": "Deploy Approval",
+  "buttons": [
+    { "title": "Approve", "url": "https://example.com/approve/123" },
+    { "title": "Reject", "url": "https://example.com/reject/123" }
+  ]
+}
+```
+
+**Example — News feed:**
+
+```json
+{
+  "bot": "dingtalk-ops",
+  "type": "news",
+  "content": "",
+  "news_items": [
+    { "title": "Weekly Report: Q2 Summary", "url": "https://example.com/reports/q2", "pic_url": "https://example.com/img/q2.png" },
+    { "title": "New Feature: Bot Broadcast", "url": "https://example.com/blog/broadcast" },
+    { "title": "Incident Postmortem: June 20", "url": "https://example.com/postmortem/0620" }
+  ]
+}
+```
+
+### `send_file`
+
+Send a file or image through a bot. Support varies by platform.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `bot` | string | Yes | Bot instance name |
+| `file_path` | string | Yes | Absolute path to the file |
+| `caption` | string | No | Caption for the file |
+
+**Platform support:**
+
+| Platform | File Support |
+|---|---|
+| WeCom | Full support via media_id upload (max 20MB) |
+| Discord | Full support via multipart upload (max 25MB) |
+| Telegram | Full support via sendDocument (max 50MB) |
+| DingTalk | Not supported (degrades to link) |
+| Feishu/Lark | Not supported via webhook |
+| Slack | Not supported via webhook |
+
+```json
+{
+  "bot": "wecom-dev",
+  "file_path": "/home/user/reports/monthly.pdf",
+  "caption": "Monthly Report - June 2025"
+}
+```
+
+### `send_broadcast`
+
+Send the same message to multiple bots simultaneously. Ideal for cross-platform alerts.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `bots` | string[] | Yes | List of bot names to broadcast to |
+| `type` | string | Yes | Message type |
+| `content` | string | Yes | Message content (supports templates) |
+| `title` | string | No | Message title |
+| `variables` | object | No | Template variables |
+| _(all send_message params)_ | | | Same parameters as send_message |
+
+**Example — Emergency alert to all platforms:**
+
+```json
+{
+  "bots": ["dingtalk-ops", "wecom-dev", "feishu-alert", "slack-engineering"],
+  "type": "markdown",
+  "content": "## P0 Incident\n**Service:** payment-gateway\n**Impact:** All payments failing\n**Started:** {{time}}\n\n[Status Page](https://status.example.com)",
+  "variables": { "time": "2025-06-24 16:30:00" },
+  "title": "P0 Alert"
+}
+```
+
+**Response:**
+
+```json
+{
+  "total": 4,
+  "success": 3,
+  "failed": 1,
+  "results": [
+    { "bot": "dingtalk-ops", "success": true, "platform": "dingtalk", "latency_ms": 245 },
+    { "bot": "wecom-dev", "success": true, "platform": "wecom", "latency_ms": 312 },
+    { "bot": "feishu-alert", "success": true, "platform": "feishu", "latency_ms": 189 },
+    { "bot": "slack-engineering", "success": false, "error": "Slack error [403]: action_prohibited" }
+  ]
+}
+```
+
+### `send_batch`
+
+Send the same message to multiple targets through one bot. Primarily useful for Telegram (multiple chat IDs).
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `bot` | string | Yes | Bot instance name |
+| `targets` | string[] | Yes | Target IDs (e.g., Telegram chat_ids) |
+| `type` | string | Yes | Message type |
+| `content` | string | Yes | Message content |
+| _(all send_message params)_ | | | Same parameters as send_message |
+
+```json
+{
+  "bot": "telegram-bot",
+  "targets": ["-1001111111", "-1002222222", "-1003333333"],
+  "type": "text",
+  "content": "Daily standup reminder: 10:00 AM"
+}
+```
+
+### `list_bots`
+
+List all configured bot instances with their platform, status, and queue info.
+
+**Parameters:** None
+
+**Response:**
+
+```json
+{
+  "total": 3,
+  "bots": [
+    { "name": "dingtalk-ops", "platform": "dingtalk", "enabled": true, "queue": { "queued": 0, "running": 0 } },
+    { "name": "wecom-dev", "platform": "wecom", "enabled": true, "queue": { "queued": 0, "running": 0 } },
+    { "name": "telegram-bot", "platform": "telegram", "enabled": true, "queue": { "queued": 0, "running": 0 } }
+  ],
+  "platforms": ["dingtalk", "wecom", "telegram"]
+}
+```
+
+### `message_status`
+
+Query the audit log for message delivery status.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `message_id` | string | No | Specific message ID to look up |
+| `audit_id` | string | No | Audit log entry ID |
+| `bot` | string | No | Filter by bot name |
+| `platform` | string | No | Filter by platform |
+| `status` | string | No | Filter: `success` or `failed` |
+| `since` | string | No | ISO timestamp — return entries after this time |
+| `limit` | number | No | Max entries to return (default: 20) |
+
+```json
+{
+  "bot": "dingtalk-ops",
+  "status": "failed",
+  "since": "2025-06-24T00:00:00Z",
+  "limit": 10
+}
+```
+
+### `render_template`
+
+Preview a Handlebars template rendering without sending. Useful for testing templates.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `template` | string | Yes | Handlebars template string |
+| `variables` | object | No | Variables to substitute |
+
+```json
+{
+  "template": "Service {{service}}: {{#if_eq status \"ok\"}}✅ Healthy{{else}}❌ Down{{/if_eq}}\nCPU: {{cpu}}% {{#if_gt cpu 90}}⚠️ CRITICAL{{/if_gt}}\nTime: {{now}}",
+  "variables": { "service": "api-gateway", "status": "ok", "cpu": "95" }
+}
+```
+
+**Response:**
+
+```json
+{
+  "template": "Service {{service}}: ...",
+  "variables_detected": ["service", "status", "cpu", "now"],
+  "variables_provided": ["service", "status", "cpu"],
+  "rendered": "Service api-gateway: ✅ Healthy\nCPU: 95% ⚠️ CRITICAL\nTime: 2025-06-24 16:30:00",
+  "has_expressions": true
+}
+```
+
+---
+
+## Message Types & Platform Mapping
+
+Each message type is automatically translated to the platform's native format:
+
+| Type | DingTalk | WeCom | Feishu/Lark | Slack | Discord | Telegram |
+|---|---|---|---|---|---|---|
+| `text` | text msgtype | text msgtype | text msg_type | plain text | content field | sendMessage |
+| `markdown` | markdown msgtype | markdown msgtype | interactive card (markdown element) | Block Kit (mrkdwn section) | embed description | MarkdownV2 / HTML |
+| `link` | link msgtype | news (1 article) | post (rich text with link) | section + button action | embed with URL | text with inline link |
+| `image` | markdown `![](url)` fallback | image (base64+md5) | image (image_key) | image block | embed image | sendPhoto |
+| `card` | actionCard (buttons) | template_card | interactive card (buttons) | Block Kit (actions) | embed + link buttons | inline_keyboard |
+| `news` | feedCard | news msgtype (articles) | post (multi-paragraph) | multiple sections + dividers | multiple embeds | concatenated message |
+| `file` | link fallback ↓ | file (media_id) | text fallback ↓ | text fallback ↓ | multipart upload | sendDocument |
+
+> ↓ = graceful degradation when the platform doesn't support this type natively.
+
+---
+
+## Template Engine
+
+`botmsg` uses [Handlebars](https://handlebarsjs.com/) as its template engine with `noEscape` mode (no HTML entity escaping, since messages are plain text).
+
+### Built-in Helpers
+
+| Helper | Syntax | Example | Output |
+|---|---|---|---|
+| **date** | `{{date value}}` | `{{date "2025-01-15T14:30:00Z"}}` | `2025-01-15 14:30:00` |
+| date (ISO) | `{{date value "iso"}}` | `{{date "2025-01-15T14:30:00Z" "iso"}}` | `2025-01-15T14:30:00.000Z` |
+| date (locale) | `{{date value "locale"}}` | `{{date "2025-01-15T14:30:00Z" "locale"}}` | `2025/1/15 14:30:00` |
+| **uppercase** | `{{uppercase value}}` | `{{uppercase "hello"}}` | `HELLO` |
+| **lowercase** | `{{lowercase value}}` | `{{lowercase "HELLO"}}` | `hello` |
+| **capitalize** | `{{capitalize value}}` | `{{capitalize "hello world"}}` | `Hello world` |
+| **truncate** | `{{truncate value len}}` | `{{truncate "Long text here" 8}}` | `Long tex...` |
+| **json** | `{{json value}}` | `{{json data}}` | `{"key":"value"}` |
+| **now** | `{{now}}` | `{{now}}` | `2025-06-24 16:30:00` |
+| now (ISO) | `{{now "iso"}}` | `{{now "iso"}}` | `2025-06-24T16:30:00.000Z` |
+| now (timestamp) | `{{now "timestamp"}}` | `{{now "timestamp"}}` | `1750783800` |
+| **join** | `{{join arr sep}}` | `{{join items ", "}}` | `a, b, c` |
+
+### Conditional Logic
+
+```handlebars
+{{#if_eq status "ok"}}
+  ✅ Service is healthy
+{{else}}
+  ❌ Service is DOWN: {{error}}
+{{/if_eq}}
+
+{{#if_gt cpu 90}}
+  ⚠️ CPU critical: {{cpu}}%
+{{else}}
+  CPU normal: {{cpu}}%
+{{/if_gt}}
+```
+
+### Partials
+
+Register reusable template fragments (via code, not MCP tools):
+
+```handlebars
+{{> header}}
+Service: {{service}}
+Status: {{status}}
+```
+
+---
+
+## Rate Limiting & Retry
+
+Each bot has an independent rate limiter using [Bottleneck](https://github.com/SGrondin/bottleneck), configured to stay safely below each platform's API limits:
+
+| Platform | API Limit | botmsg Default | Strategy |
+|---|---|---|---|
+| DingTalk | 20 msg/min | 18 msg/min, 3s spacing | Token bucket |
+| WeCom | 20 msg/min | 18 msg/min, 3s spacing | Token bucket |
+| Feishu | 100 msg/min, 5/sec | 90 msg/min, 250ms spacing | Token bucket |
+| Lark | 100 msg/min, 5/sec | 90 msg/min, 250ms spacing | Token bucket |
+| Slack | ~1 msg/sec | 55 msg/min, 1.1s spacing | Fixed interval |
+| Discord | 5 msg/2sec | 4 msg/2sec, 500ms spacing | Token bucket |
+| Telegram | 30 msg/sec | 25 msg/sec, 40ms spacing | Token bucket |
+
+**Retry behavior:** On HTTP 429 or 5xx errors, messages are retried with exponential backoff: 1s → 2s → 4s → 8s → 16s (configurable max via `BOTMSG_MAX_RETRIES`).
+
+**High water mark:** If the queue exceeds the platform-specific limit (50-200 pending messages), oldest messages are dropped to prevent memory exhaustion.
+
+---
+
+## Audit Logging
+
+Every message send attempt is recorded:
+
+```json
+{
+  "id": "msg_m1abc_2d3efg",
+  "messageId": "12345",
+  "bot": "dingtalk-ops",
+  "platform": "dingtalk",
+  "type": "markdown",
+  "contentHash": "## Deploy Alert\nService **user-ap...",
+  "status": "success",
+  "timestamp": "2025-06-24T16:30:00.000Z",
+  "latencyMs": 245,
+  "error": null
+}
+```
+
+**Storage:**
+
+- **In-memory:** Ring buffer holding the last 1,000 entries (always active)
+- **File persistence:** Set `BOTMSG_AUDIT_LOG=/path/to/audit.jsonl` for JSONL file output
+- **Query:** Use the `message_status` tool to search by bot, platform, status, time range
+
+---
+
+## Dry Run Mode
+
+Set `BOTMSG_DRY_RUN=true` to preview message payloads without actually sending. Perfect for testing configurations and templates.
+
+```json
+{
+  "mcpServers": {
+    "botmsg": {
+      "command": "npx",
+      "args": ["-y", "botmsg"],
+      "env": {
+        "BOTMSG_DINGTALK_OPS_WEBHOOK": "https://oapi.dingtalk.com/robot/send?access_token=xxx",
+        "BOTMSG_DRY_RUN": "true"
+      }
+    }
+  }
+}
+```
+
+In dry run mode, `send_message` returns the rendered content and the full platform-specific payload:
+
+```json
+{
+  "dry_run": true,
+  "bot": "dingtalk-ops",
+  "platform": "dingtalk",
+  "rendered_content": "Hello Team, deploy completed at 14:30",
+  "payload": {
+    "msgtype": "text",
+    "text": { "content": "Hello Team, deploy completed at 14:30" }
+  }
+}
+```
+
+---
+
+## Error Handling
+
+`botmsg` returns structured errors to the MCP client:
+
+```json
+{
+  "content": [{ "type": "text", "text": "Error: [PLATFORM_ERROR] [dingtalk] DingTalk error [310000]: keywords not in content" }],
+  "isError": true
+}
+```
+
+**Common error codes:**
+
+| Error | Cause | Solution |
+|---|---|---|
+| `BOT_NOT_FOUND` | Bot name not in config | Check `list_bots` for available names |
+| `VALIDATION_ERROR` | Invalid parameters | Check tool parameter types and required fields |
+| `PLATFORM_ERROR` | Platform API returned error | Check webhook URL, tokens, and security settings |
+| `RATE_LIMIT_ERROR` | Exceeded rate limit | Messages auto-retry; reduce send frequency |
+| `CONFIG_ERROR` | Config file parse error | Validate YAML/JSON syntax |
+
+---
+
+## Development
+
+```bash
+# Clone and install
+git clone https://github.com/user/botmsg.git
+cd botmsg
+npm install
+
+# Build (tsup + esbuild)
+npm run build
+
+# Run tests (vitest)
+npm test
+
+# Development mode (tsx hot-reload)
+npm run dev
+
+# Test MCP server locally
+echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | node dist/index.js
+```
+
+---
+
+## Troubleshooting
+
+**"npx: command not found"**
+Ensure Node.js >= 18 is installed: `node --version`
+
+**"Bot not found" errors**
+Run the `list_bots` tool to see all configured bot names. Names follow the pattern `{platform}-{instance}`.
+
+**Messages not delivered**
+1. Check webhook URL is correct and not expired
+2. For DingTalk: verify security mode matches your robot settings (keyword vs sign)
+3. For signed webhooks: ensure system clock is accurate (within 1 hour)
+4. Use `BOTMSG_DRY_RUN=true` to inspect payloads without sending
+5. Check `message_status` tool for recent failures
+
+**Rate limit errors (429)**
+botmsg auto-retries with exponential backoff. If persistent, reduce send frequency or split across multiple bot instances.
+
+**Windows: "npx not found" in MCP config**
+Use `cmd` wrapper:
+```json
+{ "command": "cmd", "args": ["/c", "npx", "-y", "botmsg"] }
+```
+
+---
+
+## License
+
+MIT