@mcpcn/mcp-notification/README.md

系统通知MCP服务器

# MCP 通知提醒服务器

一个基于 Model Context Protocol (MCP) 的通知提醒服务器，提供设置提醒、查询提醒列表、取消提醒三种工具，并通过后端接口对接统一的提醒调度与分发。

## 功能特性

- 🔔 设置提醒：支持一次性、固定间隔循环、每日循环
- 📋 查询列表：获取设备的待触发提醒列表（仅 `scheduled`）
- ❌ 取消提醒：按 `id` 取消指定提醒
- ⚡ MCP 协议集成：适配各类 MCP 客户端
- 🌐 可配置后端地址：通过环境变量 `REMINDER_API_BASE` 指定

## 安装

### 前置要求

- Node.js >= 18

### 安装依赖

```bash
npm install
```

### 构建项目

```bash
npm run build
```

## 使用方法

### 1. 直接运行

```bash
npm run start
# 或
node dist/index.js
```

### 2. 作为 MCP 服务器

在您的 MCP 客户端配置中添加：

```json
{
  "mcpServers": {
    "通知提醒": {
      "command": "node",
      "args": ["/path/to/通知提醒新/dist/index.js"],
      "env": {
        "REMINDER_API_BASE": "https://www.rapido.chat/api"
      }
    }
  }
}
```

或使用已发布命令名（全局安装后）：

```json
{
  "mcpServers": {
    "通知提醒": {
      "command": "notification-mcp",
      "args": [],
      "env": {
        "REMINDER_API_BASE": "https://www.mcpcn.cc/api"
      }
    }
  }
}
```

## 工具说明

### set_reminder

设置通知提醒，支持以下模式（请求需携带会话头 `chatSessionId`，详见下文“会话标识”）：

- 一次性（相对延时）
  ```json
  { "content": "开会", "repeat": "none", "delaySec": 300 }
  ```

- 一次性（绝对时间）
  ```json
  { "content": "开会", "repeat": "none", "triggerAt": "2025-11-15T20:00:00+08:00" }
  ```

- 间隔循环（每5分钟）
  ```json
  { "content": "喝水", "repeat": "interval", "intervalSec": 300 }
  ```

- 每日循环（每天18:00，北京时间）
  ```json
  { "content": "下班打卡", "repeat": "daily", "timeOfDay": "18:00", "tzOffsetMin": 480 }
  ```

参数：

- `content` (string, 必需)
- `repeat` (string, 必需)：`none|interval|daily`
- `delaySec` (number, 可选)：一次性延时触发
- `triggerAt` (string, 可选)：一次性绝对时间（RFC3339）
- `intervalSec` (number, 可选)：间隔循环秒数
- `timeOfDay` (string, 可选)：每日循环的时间（如 `18:00` 或 `18:00:00`）
- `tzOffsetMin` (number, 可选)：时区偏移分钟（北京为 `480`）

### list_reminders

查询待触发提醒列表（请求需携带会话头 `chatSessionId`）：

参数：无

返回：提醒条目数组（仅 `scheduled` 状态）

### cancel_reminder

取消指定提醒（请求需携带会话头 `chatSessionId`）：

参数：

- `id` (string, 必需)

## 会话标识

MCP 客户端需在调用工具时携带 `meta.chatSessionId`，服务端会自动解析并将其作为 HTTP 请求头 `chatSessionId` 传给后端接口：

- 解析来源：`request.meta.chatSessionId` 或 `request.params.meta.chatSessionId`
- 请求头：`chatSessionId: <meta.chatSessionId>`

## 后端接口

默认后端基地址为 `https://www.mcpcn.cc/api`（可通过 `REMINDER_API_BASE` 修改）。接口为：

- 设置提醒：`https://www.mcpcn.cc/api/reminder/set`
- 列表查询：`https://www.mcpcn.cc/api/reminder/list`
- 取消提醒：`https://www.mcpcn.cc/api/reminder/cancel`

## 项目结构

```
通知提醒新/
├── src/
│   └── index.ts       # MCP 服务器实现（工具与接口调用）
├── dist/
│   └── index.js       # 构建输出文件
├── package.json          # 项目配置（main/bin 脚本）
├── tsconfig.json         # TypeScript 配置
└── README.md            # 使用说明
```

## 技术栈

- **TypeScript**
- **Node.js**
- **@modelcontextprotocol/sdk**

## 许可证

MIT License

## 贡献

欢迎提交 Issue 和 Pull Request！