BotBell MCP Server

Instructions

Implementation Reference

• src/index.ts:321-363 (handler)

  Handler for 'botbell_send' in PAT mode (using bot_id or alias).

  server.tool(
    "botbell_send",
    "Send a push notification to the user's iPhone/Mac via BotBell. " +
    (hasExtras
      ? "Use bot_id for your own bots or alias for external bots. Use botbell_list_bots to see all available targets. "
      : "Use botbell_list_bots first to find the bot_id. ") +
    "You can include action buttons for quick replies. Use type 'input' to let the user type a custom response.",
    sendSchema,
    async (args) => {
      try {
        const { bot_id, alias, ...msgArgs } = args as {
          bot_id?: string; alias?: string;
          message: string; title?: string; url?: string;
          image_url?: string; summary?: string; format?: string;
          actions_description?: string; actions?: unknown[];
          reply_mode?: string;
        };
        const body = buildMessageBody(msgArgs);
  
        // Route via alias (extra token)
        if (alias) {
          const btToken = resolveAlias(alias);
          if (!btToken) return errorResult(`Unknown alias "${alias}". Available: ${aliasNames.join(", ")}`);
          return await sendViaBotToken(btToken, apiBase, body);
        }
  
        // Route via bot_id (PAT)
        if (!bot_id) return errorResult("Provide either bot_id or alias.");
        const result = await api("POST", `/bots/${bot_id}/push`, body);
        if (!result.ok) return errorResult(`Failed to send: ${handleApiError(result)}`);
  
        const data = result.data.data as Record<string, unknown>;
        return textResult(
          `Notification sent successfully.\n` +
          `Message ID: ${data.message_id}\n` +
          `Delivered: ${data.delivered}\n` +
          `Timestamp: ${data.timestamp}`
        );
      } catch (error) {
        return errorResult(`Error: ${error instanceof Error ? error.message : String(error)}`);
      }
    }
  );

• src/index.ts:385-415 (handler)

  Handler for 'botbell_send' in Bot token mode (using default token or alias).

  server.tool(
    "botbell_send",
    "Send a push notification to the user's iPhone/Mac via BotBell. " +
    (hasExtras ? `You can also send via external bots: ${aliasNames.join(", ")}. ` : "") +
    "You can include action buttons for quick replies. Use type 'input' to let the user type a custom response.",
    sendSchema,
    async (args) => {
      try {
        const { alias, ...msgArgs } = args as {
          alias?: string;
          message: string; title?: string; url?: string;
          image_url?: string; summary?: string; format?: string;
          actions_description?: string; actions?: unknown[];
          reply_mode?: string;
        };
        const body = buildMessageBody(msgArgs);
  
        // Route via alias (extra token)
        if (alias) {
          const btToken = resolveAlias(alias);
          if (!btToken) return errorResult(`Unknown alias "${alias}". Available: ${aliasNames.join(", ")}`);
          return await sendViaBotToken(btToken, apiBase, body);
        }
  
        // Default: primary bot token
        return await sendViaBotToken(token, apiBase, body);
      } catch (error) {
        return errorResult(`Error: ${error instanceof Error ? error.message : String(error)}`);
      }
    }
  );