# 小智MCP闹钟和待办事项服务
为小智AI提供闹钟和待办事项管理功能的MCP服务。
## 版本说明
**🎉 V2 主动通知版本已发布！**
- **V2 (当前默认)**: 支持资源订阅和主动通知，后台自动检查到期提醒
- **V1 (稳定版)**: 仅被动响应，需要客户端主动调用工具
详细测试指南请查看: [V2_TEST_GUIDE.md](V2_TEST_GUIDE.md)
## 功能特性
- 语音设定闹钟，到点提醒
- 语音添加待办事项，设置提醒时间
- 语音完成待办，自动更新状态
- 支持自然语言时间解析（如"明天下午3点"、"30分钟后"）
- 数据持久化存储
- ✨ **V2新增**: Resource订阅机制，支持主动推送通知
## 安装
### 1. 克隆或下载项目
```bash
cd mcp-reminder
```
### 2. 安装依赖
项目使用UV管理依赖：
```bash
uv sync
```
## 使用方法
### 快速启动（推荐）
项目已包含 `mcp_pipe.py` 和启动脚本，开箱即用。默认启动V2版本（支持主动通知）。
**Linux/Mac:**
```bash
chmod +x start.sh
./start.sh
```
**Windows PowerShell (推荐):**
```powershell
.\start.ps1
```
如果提示无法运行脚本，先执行：
```powershell
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
```
**Windows CMD:**
```cmd
start.bat
```
⚠️ **Windows用户注意:**
- 推荐使用PowerShell运行 `.\start.ps1`
- 不要在PowerShell中运行.bat文件（会出现编码问题）
- 详细的Windows启动说明请查看: [WINDOWS_SETUP.md](WINDOWS_SETUP.md)
这将自动连接到配置好的小智MCP接入点并启动服务。
### 手动启动
如需自定义配置，可以手动设置环境变量：
**Linux/Mac:**
```bash
export MCP_ENDPOINT="wss://api.xiaozhi.me/mcp/?token=YOUR_TOKEN"
uv run python mcp_pipe.py run_server.py
```
**Windows (PowerShell):**
```powershell
$env:MCP_ENDPOINT = "wss://api.xiaozhi.me/mcp/?token=YOUR_TOKEN"
uv run python mcp_pipe.py run_server.py
```
**Windows (CMD):**
```cmd
set MCP_ENDPOINT=wss://api.xiaozhi.me/mcp/?token=YOUR_TOKEN
uv run python mcp_pipe.py run_server.py
```
### 使用配置文件（可选）
复制配置文件模板：
```bash
cp mcp_config.json.example mcp_config.json
```
编辑 `mcp_config.json` 自定义配置，然后运行：
```bash
export MCP_ENDPOINT="wss://api.xiaozhi.me/mcp/?token=YOUR_TOKEN"
uv run python mcp_pipe.py
```
### 本地测试（stdio模式）
用于本地测试MCP工具功能（不连接小智）：
```bash
uv run python -m mcp_reminder.server
```
然后可以使用MCP Inspector或其他MCP客户端连接测试。
## MCP工具说明
### 闹钟管理
#### add_alarm - 添加闹钟
设置一个闹钟。
参数：
- `time` (必填): 闹钟时间，支持自然语言
- 示例: "下午2点30分"、"明天上午10点"、"2025-09-02 14:30"
- `description` (可选): 闹钟描述
示例：
```
语音："小智，帮我设置一个下午2点30分的闹钟"
语音："小智，明天上午9点提醒我开会"
```
#### get_pending_alarms - 查询到期闹钟
获取所有已到期且未关闭的闹钟（小智会定期自动调用）。
#### dismiss_alarm - 关闭闹钟
关闭指定的闹钟。
参数：
- `alarm_id` (必填): 闹钟ID
### 待办事项管理
#### add_todo - 添加待办事项
创建一个新的待办事项。
参数：
- `title` (必填): 待办事项标题
- `remind_time` (可选): 提醒时间，支持自然语言
- `description` (可选): 待办事项描述
示例：
```
语音："小智，提醒我明天下午3点完成项目文档"
语音："小智，添加待办：给客户发送报价单"
```
#### get_pending_todos - 查询到期待办
获取所有到期且未完成的待办事项（小智会定期自动调用）。
#### complete_todo - 完成待办
标记待办事项为已完成，支持通过标题模糊匹配。
参数：
- `title` (必填): 待办事项标题或关键词
示例：
```
语音："小智，我已经完成项目文档了"
语音："小智，报价单发完了"
```
#### list_todos - 列出待办事项
查看所有待办事项。
参数：
- `status` (可选): 筛选状态
- `"pending"`: 未完成（默认）
- `"completed"`: 已完成
- `"all"`: 全部
示例：
```
语音："小智，我有哪些待办事项"
语音："小智，列出所有已完成的任务"
```
### 综合查询
#### check_all_reminders - 检查所有提醒（新增）✨
一次性检查所有到期的闹钟和待办事项。
**重要：提醒机制说明**
- MCP服务是被动响应的，不能主动推送提醒
- 需要小智AI定期调用此工具来检查是否有到期项
- 建议配置每1分钟自动调用一次
参数：
- 无
返回：
- 所有到期的闹钟和待办列表
- 提醒消息列表（可直接语音播报）
示例：
```
语音："小智，检查一下有没有到期的提醒"
语音："小智，看看有什么要提醒我的"
```
**详细说明请查看：** [REMINDER_MECHANISM.md](REMINDER_MECHANISM.md)
## 数据存储
数据以JSON格式存储在 `data/` 目录下：
- `data/alarms.json` - 闹钟数据
- `data/todos.json` - 待办事项数据
## 开发说明
### 项目结构
```
mcp-reminder/
├── src/mcp_reminder/
│ ├── __init__.py
│ ├── models.py # 数据模型
│ ├── storage.py # JSON持久化
│ └── server.py # MCP服务入口
├── data/ # 数据存储目录
├── pyproject.toml # UV项目配置
└── README.md
```
### 运行测试
添加测试数据：
```bash
# 在Python REPL中测试
uv run python
```
```python
from mcp_reminder.storage import JSONStorage
from mcp_reminder.models import Alarm, Todo, parse_time
storage = JSONStorage()
# 添加闹钟
alarm = Alarm(time=parse_time("2分钟后"), description="测试闹钟")
storage.add_alarm(alarm)
# 添加待办
todo = Todo(title="测试待办", remind_time=parse_time("1分钟后"))
storage.add_todo(todo)
```
## 扩展功能
未来可以考虑添加：
- 重复闹钟（每天/每周）
- 待办事项分类和标签
- 优先级设置
- 数据导出/导入
## 许可
MIT License
