小智MCP闹钟和待办事项服务

为小智AI提供闹钟和待办事项管理功能的MCP服务。

版本说明

🎉 V2 主动通知版本已发布！

• V2 (当前默认): 支持资源订阅和主动通知，后台自动检查到期提醒
• V1 (稳定版): 仅被动响应，需要客户端主动调用工具

详细测试指南请查看: V2_TEST_GUIDE.md

功能特性

• 语音设定闹钟，到点提醒
• 语音添加待办事项，设置提醒时间
• 语音完成待办，自动更新状态
• 支持自然语言时间解析（如"明天下午3点"、"30分钟后"）
• 数据持久化存储
• ✨ V2新增: Resource订阅机制，支持主动推送通知

安装

1. 克隆或下载项目

cd mcp-reminder

2. 安装依赖

项目使用UV管理依赖：

uv sync

使用方法

快速启动（推荐）

项目已包含 mcp_pipe.py 和启动脚本，开箱即用。默认启动V2版本（支持主动通知）。

Linux/Mac:

chmod +x start.sh
./start.sh

Windows PowerShell (推荐):

.\start.ps1

如果提示无法运行脚本，先执行：

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

Windows CMD:

start.bat

⚠️ Windows用户注意:

• 推荐使用PowerShell运行 .\start.ps1
• 不要在PowerShell中运行.bat文件（会出现编码问题）
• 详细的Windows启动说明请查看: WINDOWS_SETUP.md

这将自动连接到配置好的小智MCP接入点并启动服务。

手动启动

如需自定义配置，可以手动设置环境变量：

Linux/Mac:

export MCP_ENDPOINT="wss://api.xiaozhi.me/mcp/?token=YOUR_TOKEN"
uv run python mcp_pipe.py run_server.py

Windows (PowerShell):

$env:MCP_ENDPOINT = "wss://api.xiaozhi.me/mcp/?token=YOUR_TOKEN"
uv run python mcp_pipe.py run_server.py

Windows (CMD):

set MCP_ENDPOINT=wss://api.xiaozhi.me/mcp/?token=YOUR_TOKEN
uv run python mcp_pipe.py run_server.py

使用配置文件（可选）

复制配置文件模板：

cp mcp_config.json.example mcp_config.json

编辑 mcp_config.json 自定义配置，然后运行：

export MCP_ENDPOINT="wss://api.xiaozhi.me/mcp/?token=YOUR_TOKEN"
uv run python mcp_pipe.py

本地测试（stdio模式）

用于本地测试MCP工具功能（不连接小智）：

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

数据存储

数据以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

运行测试

添加测试数据：

# 在Python REPL中测试
uv run 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