# 小智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