Loading... # MaiMaiBot：基于 MCP 协议的麦当劳优惠券自动领取 Telegram 机器人技术分析 # 一、项目概述 ## 1. 项目背景 MaiMaiBot 是一个开源的 Telegram 机器人项目，通过集成麦当劳 MCP（Model Context Protocol）服务器，实现了活动日历查询、优惠券列表获取以及一键自动领取等功能。该项目采用 Node.js 开发，利用 MCP Streamable HTTP 协议与麦当劳后端服务进行通信。 ## 2. 核心功能 ### A. 主要功能 - 活动日历查询：通过 Telegraph 文章形式展示，包含图片 - 可用优惠券列表：以 Telegraph 文章形式展示，包含图片 - 一键领取所有优惠券：自动绑定所有可领取的优惠券 - 我的优惠券列表：查看已领取的优惠券 - 每日自动领取：每个账号每天自动执行一次领取任务 - 多账号管理：支持每个 Telegram 用户管理多个 MCP 账号 ### B. 技术亮点 - MCP Streamable HTTP 协议集成（2025-06-18 版本协议） - Telegraph 自动化文章生成 - 智能缓存机制（5 分钟 TTL） - 分布式自动领取调度，避免请求突发 - 全局突发窗口机制，新优惠券出现时触发批量领取 # 二、系统架构 ## 1. 架构设计 ```mermaid graph TB User[Telegram 用户] --> TG[Telegram Bot API] TG --> Bot[MaiMaiBot 服务] Bot --> Cache[(缓存层)] Bot --> MCP[麦当劳 MCP 服务器] Bot --> Telegraph[Telegraph API] Bot --> Storage[(JSON 存储)] Bot --> Scheduler[定时调度器] Scheduler --> Bot Telegraph --> User ```  ## 2. 核心组件 ### A. index.js 主入口文件，负责 Telegram Bot 的初始化、命令路由和消息处理。 ### B. mcpClient.js MCP 客户端封装，处理与麦当劳 MCP 服务器的通信，包括 Streamable HTTP 协议的实现。 ### C. cache.js 缓存模块，为非用户特定的工具调用提供 5 分钟 TTL 缓存。 ### D. storage.js 数据持久化模块，使用 JSON 文件存储用户账号、统计数据等信息。 ### E. telegraph.js Telegraph 集成模块，自动创建访问令牌并将优惠券信息格式化为 Telegraph 文章。 ### F. time.js 时间调度模块，处理自动领取任务的分布式调度和突发窗口逻辑。 ## 3. 依赖关系 ```mermaid graph LR Bot[index.js] --> MCP[mcpClient.js] Bot --> Cache[cache.js] Bot --> Storage[storage.js] Bot --> Telegraph[telegraph.js] Bot --> Time[time.js] MCP --> Cache ```  # 三、技术实现 ## 1. MCP 协议集成 ### A. Streamable HTTP 项目使用 MCP Streamable HTTP 协议（2025-06-18 版本）与麦当劳服务器通信。该协议支持流式响应，适合处理大量优惠券数据。 ### B. 工具调用 支持以下 MCP 工具： - campaign-calender：活动日历查询 - available-coupons：可用优惠券列表 - auto-bind-coupons：自动绑定优惠券 - my-coupons：我的优惠券列表 ### C. 认证机制 所有工具调用需要 MCP Token，该 Token 从 https://open.mcd.cn/mcp 获取。 ## 2. Telegraph 集成 ### A. 自动令牌创建 首次运行时自动创建 Telegraph 访问令牌，存储在 data/telegraph.json 文件中。 ### B. 文章生成 将活动日历和优惠券列表转换为 Telegraph 文章格式，包含： - 富文本内容 - 图片嵌入 - 响应式布局 ### C. 优势 - 无需在 Telegram 消息中传输大量数据 - 文章永久链接，方便分享 - 支持复杂排版和图片展示 ## 3. 缓存策略 ### A. 缓存配置 - 默认 TTL：300 秒（5 分钟） - 可缓存工具：campaign-calender、available-coupons - 缓存键：基于工具名称和参数生成 ### B. 缓存价值 - 减少 MCP 服务器调用次数 - 降低响应延迟 - 节省网络带宽 ## 4. 自动领取调度 ### A. 调度策略 - 每个账号每天执行一次自动领取 - 默认执行时间：上午 9 点（Asia/Shanghai 时区） - 分散窗口：600 分钟（10 小时），避免请求集中 ### B. 突发窗口机制 当任何账号领取到之前未见的优惠券时，触发全局突发窗口： - 突发窗口时长：30 分钟 - 所有账号在此窗口内尝试领取 - 每轮最多处理 10 个账号 - 请求间隔：1.5 秒 ```mermaid sequenceDiagram participant S as 调度器 participant A1 as 账号1 participant A2 as 账号2 participant MCP as MCP 服务器 S->>A1: 执行自动领取 A1->>MCP: 获取可用优惠券 MCP-->>A1: 返回优惠券列表 A1->>MCP: 领取优惠券 A1->>A1: 发现新优惠券 A1->>S: 触发突发窗口 S->>A2: 立即执行领取 S->>A1: 再次执行领取 Note over S,A2: 突发窗口 30 分钟 ```  ## 5. 多账号管理 ### A. 账号操作命令 - /account add <name> <token>：添加或更新账号 - /account use <name>：切换当前活动账号 - /account list：列出所有账号 - /account del <name>：删除账号 - /cleartoken：清除所有账号 ### B. 数据隔离 每个 Telegram 用户的账号数据独立存储，互不干扰。 ## 6. 统计功能 ### A. 用户统计 - 个人领取统计：/stats - 管理员统计：/admin users（需要配置 ADMIN_TELEGRAM_IDS） ### B. 统计数据 - 领取成功次数 - 领取失败次数 - 总计领取次数 - 按账号统计 # 四、部署指南 ## 1. 环境要求 - Node.js 18+（推荐 Node.js 20+） - Telegram Bot Token（从 BotFather 获取） - MCP Token（从 https://open.mcd.cn/mcp 获取） ## 2. 安装步骤 ### A. 安装 Node.js ```bash sudo apt update sudo apt install -y git curl curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt install -y nodejs # 验证安装 node -v npm -v ``` ### B. 部署 Bot ```bash git clone https://github.com/ButaiKirin/MaiMaiBot.git cd MaiMaiBot cp .env.example .env # 编辑 .env 文件，配置必要参数 nano .env ``` ### C. 配置环境变量 ```bash # 必须配置 TELEGRAM_BOT_TOKEN=your_bot_token_here # 可选配置 MCD_MCP_URL=https://mcp.mcd.cn/mcp-servers/mcd-mcp CACHE_TTL_SECONDS=300 AUTO_CLAIM_HOUR=9 AUTO_CLAIM_TIMEZONE=Asia/Shanghai ADMIN_TELEGRAM_IDS=123456789,987654321 ``` ### D. 启动服务 ```bash npm install npm start ``` ## 3. Systemd 服务配置 ### A. 创建服务文件 ```bash sudo tee /etc/systemd/system/maimai-bot.service > /dev/null <<'SERVICE' [Unit] Description=MaiMai Telegram Bot After=network.target [Service] Type=simple WorkingDirectory=/opt/MaiMaiBot EnvironmentFile=/opt/MaiMaiBot/.env ExecStart=/usr/bin/node /opt/MaiMaiBot/src/index.js Restart=always RestartSec=5 User=ubuntu Group=ubuntu [Install] WantedBy=multi-user.target SERVICE ``` ### B. 移动文件并设置权限 ```bash sudo mkdir -p /opt sudo mv ~/MaiMaiBot /opt/MaiMaiBot sudo chown -R ubuntu:ubuntu /opt/MaiMaiBot ``` ### C. 启动服务 ```bash sudo systemctl daemon-reload sudo systemctl enable --now maimai-bot ``` ### D. 查看日志 ```bash journalctl -u maimai-bot -f ``` ## 4. 更新流程 ```bash cd /opt/MaiMaiBot git pull npm install sudo systemctl restart maimai-bot ``` # 五、技术亮点 ## 1. MCP 协议应用 该项目是 MCP 协议的实际应用案例，展示了如何使用 MCP Streamable HTTP 协议集成第三方服务。MCP（Model Context Protocol）是 2025 年新兴的模型上下文协议标准，支持 AI 应用与外部服务的标准化交互。 ## 2. 智能调度算法 分布式调度 + 突发窗口的组合策略，既保证了自动领取的及时性，又避免了请求集中导致的限流风险。 ## 3. Telegraph 深度集成 利用 Telegraph 作为内容展示层，解决了 Telegram 消息长度限制和图片展示问题，提供了更好的用户体验。 ## 4. 轻量级架构 - 无数据库依赖，使用 JSON 文件存储 - 核心依赖仅 2 个（dotenv、telegraf） - 单文件部署，易于维护 # 六、项目状态 ## 1. 基本信息 - 仓库地址：https://github.com/ButaiKirin/MaiMaiBot - 语言：JavaScript（100%） - Stars：49 - Forks：1 - 最新提交：2026-01-17 ## 2. 开发活跃度 项目近期活跃更新，主要更新包括： - 用户领取统计跟踪和报告功能 - 管理员命令和 Telegram 用户 ID 配置 - Telegraph 文章支持 - 自动领取扩散配置和细粒度报告 # 七、使用场景 ## 1. 个人使用 方便快捷地查看和领取麦当劳优惠券，无需手动操作官方 App 或小程序。 ## 2. 多账号管理 适合需要管理多个麦当劳账号的用户，可以集中管理所有账号的优惠券。 ## 3. 自动化领取 设置每日自动领取后，无需手动操作，确保不错过任何新优惠券。 # 八、安全考虑 ## 1. Token 管理 - MCP Token 应妥善保管，避免泄露 - 建议使用环境变量存储敏感信息 - 定期更新 Token ## 2. 访问控制 - 通过 ADMIN_TELEGRAM_IDS 配置管理员权限 - 每个用户只能访问自己的账号数据 ## 3. 请求限流 - 内置请求间隔控制（1.5 秒） - 突发窗口机制避免请求集中 - 缓存机制减少服务器调用 # 九、总结 MaiMaiBot 是一个设计精巧的 Telegram 机器人项目，展示了 MCP 协议在实际场景中的应用。项目采用轻量级架构，功能完善，代码简洁，是学习 MCP 协议集成和 Telegram Bot 开发的良好参考。 项目的核心价值在于： 1. 自动化优惠券领取，提升用户体验 2. 智能调度策略，避免服务限流 3. Telegraph 深度集成，优化内容展示 4. 多账号管理，满足复杂需求 该项目代表了 2025 年 MCP 协议生态发展的一个缩影，随着 MCP 协议的普及，预计会有更多类似的集成应用涌现。 *** ## 参考资料 1. [MaiMaiBot GitHub 仓库](https://github.com/ButaiKirin/MaiMaiBot) 2. [麦当劳 MCP 开放平台](https://open.mcd.cn/mcp) 3. [Telegraph API 文档](https://telegra.ph/api) 4. [Telegraf.js 文档](https://telegraf.js.org/) 5. [MCP 协议规范](https://modelcontextprotocol.io/) 最后修改：2026 年 01 月 18 日 © 允许规范转载 赞 如果觉得我的文章对你有用，请随意赞赏