MCP Reminder Service

# MCP 消息提醒服务 基于 Model Context Protocol (MCP) 的消息发送和定时提醒服务，使用官方 MCP Python SDK 实现，支持 Telegram、飞书等多种消息平台。 ## ✨ 功能特点 - 🔌 **MCP 协议**: 基于官方 MCP Python SDK，完全符合 MCP 规范 - 🌐 **多传输支持**: stdio、HTTP、SSE 三种传输方式，适应不同客户端 - 🚀 **FastMCP**: 使用官方 FastMCP 提供高性能 API 接口 - 📱 **多平台消息**: 支持 Telegram、飞书等多种消息平台 - ⏰ **定时任务**: 基于 Cron 表达式的定时消息发送 - 🎯 **最佳实践**: 符合 Python 项目最佳实践和 MCP Server 规范 - 🐳 **容器化部署**: 完整的 Docker 支持，一键部署 - 📝 **完善日志**: 结构化日志记录，支持日志轮转 - 🔄 **自动重试**: 智能错误处理和重试机制 - ⚡ **异步处理**: 高性能异步架构，支持并发发送 - 🛠️ **开发友好**: 完整的开发工具链和测试支持 ## 快速开始 ### 1. 配置 Telegram（可选） 1. 在 Telegram 中找到 [@BotFather](https://t.me/botfather) 2. 发送 `/newbot` 命令创建新机器人 3. 按提示设置机器人名称和用户名 4. 获取 Bot Token 5. 在 Telegram 中找到 [@userinfobot](https://t.me/userinfobot) 6. 发送任意消息获取你的 Chat ID ### 2. 配置飞书（可选） 1. 在飞书群聊中添加自定义机器人 2. 获取 Webhook URL 3. 如果配置了签名验证，获取签名密钥 ### 3. 配置环境变量 复制 `env.example` 文件并填入你的配置： ```bash cp env.example .env ``` 编辑 `.env` 文件： ```bash # Telegram 配置（可选） TELEGRAM_BOT_TOKEN=你的机器人Token TELEGRAM_CHAT_ID=你的Chat ID # 飞书配置（可选） FEISHU_WEBHOOK_URL=https://open.feishu.cn/open-apis/bot/v2/hook/your_webhook_url FEISHU_SECRET=your_feishu_secret_here # 可选 ``` **注意**: 至少需要配置一个消息发送平台（Telegram 或飞书），程序才能正常运行。 ### 4. 本地运行 #### 本地模式（用于 Cursor MCP） ```bash # 安装依赖 pip install -r requirements.txt # 设置环境变量 export TELEGRAM_BOT_TOKEN="你的机器人Token" export TELEGRAM_CHAT_ID="你的Chat ID" export SERVER_MODE="local" # 运行 MCP 服务器 python mcp_main.py ``` #### HTTP API 模式 ```bash # 安装依赖 pip install -r requirements.txt # 设置环境变量 export TELEGRAM_BOT_TOKEN="你的机器人Token" export TELEGRAM_CHAT_ID="你的Chat ID" export SERVER_MODE="http" export SERVER_HOST="0.0.0.0" export SERVER_PORT="8000" # 运行 HTTP API 服务器 python mcp_main.py ``` #### 测试 HTTP API ```bash # 获取工具列表 curl http://localhost:8000/tools # 发送消息 curl -X POST http://localhost:8000/tools/send_message \ -H "Content-Type: application/json" \ -d '{"provider": "telegram", "message": "测试消息"}' # 测试连接 curl -X POST http://localhost:8000/tools/test_connection ``` ### 5. Docker 运行 ```bash # 构建镜像 docker build -t telegram-reminder . # 运行容器 docker run -d \ --name telegram-reminder \ --env-file .env \ --restart unless-stopped \ telegram-reminder ``` ### 6. Docker Compose 运行 创建 `docker-compose.yml` 文件： ```yaml version: '3.8' services: telegram-reminder: build: . container_name: telegram-reminder env_file: - .env restart: unless-stopped volumes: - ./logs:/app/logs ``` 运行： ```bash docker-compose up -d ``` ## 配置说明 ### 环境变量 | 变量名 | 说明 | 必需 | |--------|------|------| | `TELEGRAM_BOT_TOKEN` | Telegram Bot Token | 否* | | `TELEGRAM_CHAT_ID` | 接收消息的 Chat ID | 否* | | `FEISHU_WEBHOOK_URL` | 飞书机器人 Webhook URL | 否* | | `FEISHU_SECRET` | 飞书机器人签名密钥 | 否 | *至少需要配置 Telegram 或飞书中的一个平台 ### 自定义消息 如需修改提醒消息，可以编辑 `telegram_reminder.py` 文件中的 `self.message` 变量： ```python self.message = "你的自定义消息 💊" ``` ## 日志 脚本会生成详细的日志文件 `telegram_reminder.log`，包含： - 服务启动/停止信息 - 下次提醒时间计算 - 消息发送状态 - 错误信息和重试记录 ## 故障排除 ### 常见问题 1. **消息发送失败** - 检查 Bot Token 是否正确 - 确认 Chat ID 是否正确 - 确保机器人已添加到对话中 2. **时间不准确** - 脚本使用北京时间（UTC+8） - 容器时区已设置为 Asia/Shanghai 3. **容器无法启动** - 检查环境变量是否正确设置 - 查看容器日志：`docker logs telegram-reminder` ### 查看日志 ```bash # 查看容器日志 docker logs telegram-reminder # 查看应用日志文件 docker exec telegram-reminder cat /app/telegram_reminder.log ``` ## 🏗️ 系统架构 ``` mcp_reminder/ ├── server/ # MCP 服务器 │ ├── simple_mcp_server.py # 简化的 MCP 服务器（基于官方 SDK） │ ├── fast_mcp_server.py # FastMCP HTTP 服务器 │ └── http_server.py # 传统 HTTP 模式服务器 ├── tools/ # MCP 工具 │ ├── message_tools.py # 消息发送工具 │ └── scheduler_tools.py # 定时任务工具 ├── providers/ # 消息提供商 │ ├── message_sender.py # 消息发送管理器 │ ├── telegram.py # Telegram 提供商 │ └── feishu.py # 飞书提供商 ├── config/ # 配置管理 │ └── settings.py # 配置类 ├── utils/ # 工具模块 │ └── logger.py # 日志工具 └── __init__.py # 包初始化 ``` ### 核心组件 - **SimpleMCPServer**: 基于官方 MCP SDK 的简化服务器，处理工具调用（本地模式） - **FastMCPServer**: 基于官方 FastMCP 的 HTTP 服务器，提供高性能 API 接口 - **HTTPServer**: 传统 HTTP 模式服务器，提供 RESTful API - **MessageTools**: 消息发送工具，支持单平台和全平台发送 - **SchedulerTools**: 定时任务工具，基于 Cron 表达式 - **MessageSender**: 消息发送管理器，管理多个提供商 ## 🛠️ 开发指南 ### 本地开发 ```bash # 安装依赖 make install # 运行测试 make test # 代码检查 make lint # 代码格式化 make format # 本地运行（HTTP 模式） make run-http # 本地运行（本地模式） make run-local ``` ### 添加新的消息提供商 1. 在 `reminder/providers/` 目录下创建新的提供商文件 2. 继承 `MessageProvider` 基类 3. 实现 `send_message` 和 `is_configured` 方法 4. 在 `MessageSender` 中添加初始化逻辑 示例： ```python from .base import MessageProvider class CustomProvider(MessageProvider): def __init__(self, api_key: str): super().__init__("Custom") self.api_key = api_key async def send_message(self, message: str, **kwargs) -> bool: # 实现发送逻辑 pass def is_configured(self) -> bool: return bool(self.api_key) ``` ## 🚀 部署 ### 使用 Makefile 一键部署 ```bash make deploy ``` ### 手动部署 ```bash # 构建镜像 docker build -t reminder-system . # 运行容器 docker run -d \ --name reminder-system \ --env-file .env \ --restart unless-stopped \ reminder-system ``` ## 📊 监控和日志 - **日志文件**: 支持日志轮转，默认保留 5 个备份文件 - **日志级别**: 可通过 `LOG_LEVEL` 环境变量配置 - **连接测试**: 使用 `python main.py test` 测试所有提供商连接 ## 🧪 测试 ```bash # 运行所有测试 make test # 运行特定测试 python -m pytest tests/test_config.py -v # 生成覆盖率报告 python -m pytest --cov=reminder tests/ ``` ## 技术实现 - **异步处理**: 使用 `asyncio` 和 `aiohttp` 实现高性能异步处理 - **时区处理**: 正确处理北京时间时区 - **错误处理**: 完善的异常处理和重试机制 - **日志记录**: 结构化日志记录，支持日志轮转 - **配置管理**: 基于 dataclass 的类型安全配置 - **测试覆盖**: 完整的单元测试和集成测试 ## 许可证 MIT License