README.md•5.16 kB
# mi_note_mcp
`mi_note_mcp` 是一个基于 Model Context Protocol (MCP) 的小米云笔记服务器实现，可让支持 MCP 的助手（如 Claude、ChatGPT 桌面端等）直接读取、搜索、创建和管理你的云端笔记。项目在本地对接口结果做缓存，并提供 Markdown/XML 互转能力，让大语言模型能够无缝处理笔记内容。
## 功能特性
- 读取、搜索与缓存：支持列出、搜索、查看笔记详情并自动维护本地缓存，减轻重复网络请求。
- 完整的笔记编辑链路：提供创建、更新、删除、移动笔记等常见操作，并自动同步资源状态。
- 文件夹管理：支持列出、创建、重命名、删除文件夹及按文件夹查看笔记。
- 富文本转换：在 Markdown 与小米笔记内部 XML 之间相互转换，保留任务列表、图片、粗体等格式。
- 图片上传：可将本地图片上传至小米云端并返回 `minote://image/{fileId}` 形式的可复用链接。
- MCP 资源暴露：暴露笔记、文件夹相关资源 URI，方便上下文补全与导航。
## 环境要求
- [Bun](https://bun.sh) ≥ 1.1（开发测试使用 1.2.23）
- 一个可以访问 [https://i.mi.com/note](https://i.mi.com/note) 的小米账号
- Node.js TypeScript 生态（仅在开发/类型检查时需要）
## 快速开始
### 1. 安装依赖
```sh
bun install
```
### 2. 配置凭据
服务启动前需要准备配置文件，默认路径为 `~/.mi-note-mcp.json`，也可以通过环境变量 `MI_NOTE_MCP_CONFIG` 指定其他位置。
配置示例：
```json
{
"serviceToken": "YOUR_SERVICE_TOKEN",
"userId": "YOUR_USER_ID",
"passToken": "可选，增强登录稳定性",
"slh": "可选",
"ph": "可选",
"deviceId": "可选，用于与网页保持一致",
"cUserId": "可选",
"uLocale": "zh_CN",
"syncInterval": 30000,
"baseUrl": "https://i.mi.com"
}
```
获取方式建议在浏览器登录 [小米云笔记](https://i.mi.com/note) 后，通过开发者工具复制请求头中的 Cookie 字段（如 `serviceToken`、`userId`、`passToken` 等），并保证这些字段长期有效。`syncInterval` 以毫秒为单位，用于控制后台增量同步频率。
### 3. 启动 MCP 服务器
```sh
bun run index.ts
```
启动成功后，终端会输出 `mi-note-mcp server started`。随后即可在支持 MCP 的客户端中把 `mi_note_mcp` 注册为本地服务，按客户端指引填写命令与工作目录。
## MCP 工具与资源
### 工具（Tools）
| 工具 ID | 功能说明 | 关键参数 |
| --- | --- | --- |
| `list_notes` | 列出缓存中的全部笔记 | 无 |
| `get_note` | 按 ID 获取笔记 Markdown 内容 | `id` |
| `create_note` | 创建新笔记并返回资源链接 | `content`、`title?`、`folderId?` |
| `update_note` | 更新笔记内容与元数据 | `id`、`content`、`title?`、`folderId?` |
| `delete_note` | 删除或永久删除笔记 | `id`、`purge?` |
| `move_note` | 将笔记移动到指定文件夹 | `noteId`、`folderId` |
| `search_notes` | 关键词搜索标题与摘要 | `keyword`、`limit?` |
| `upload_image` | 上传图片并返回 `minote://image/{fileId}` | `path`、`mimeType?` |
| `list_folders` | 列出全部文件夹 | 无 |
| `create_folder` | 创建文件夹 | `subject`、`parentId?` |
| `update_folder` | 重命名文件夹 | `id`、`subject` |
| `delete_folder` | 删除或永久删除文件夹 | `id`、`purge?` |
### 资源（Resources）
| 资源 URI | 内容 | 说明 |
| --- | --- | --- |
| `minote://notes` | 所有笔记的概览列表 | 支持资源列表变更通知 |
| `minote://notes/{id}` | 指定笔记的 Markdown 内容 | 自动缓存并保持最新 |
| `minote://folders` | 文件夹概览 | 列表随同步自动刷新 |
| `minote://folders/{id}/notes` | 指定文件夹下的笔记列表 | 结合 `move_note` 可快速浏览整理 |
## 缓存与同步机制
- 首次启动会通过 `/note/full/page` 获取全量数据并缓存到内存。
- 之后按照 `syncInterval`（默认 30 秒）调用增量同步接口更新笔记与文件夹状态。
- 工具在执行写操作后会主动刷新缓存并触发资源更新，保证 MCP 客户端侧 UI 与上下文立即感知变化。
- 可以通过 `NotesCache` 的 `refresh()` 方法在代码中强制刷新（大部分工具已自动调用）。
## 开发与测试
- 类型检查（推荐在提交前运行）：
```sh
bun run tsc --noEmit --skipLibCheck
```
- 单元测试：
```sh
bun test
```
开发时建议遵循仓库内现有的代码风格与目录结构，必要时参考 `tests/` 下用例了解关键模块行为。
## 常见问题
- **提示配置文件不存在**：确认 `~/.mi-note-mcp.json` 是否创建成功，或设置正确的 `MI_NOTE_MCP_CONFIG`。
- **返回 401/403**：通常是 `serviceToken`、`userId` 等 cookie 过期，重新从网页端复制并更新配置后重试。
- **图片上传失败**：检查文件是否存在、MIME 类型是否正确，或网络是否可访问 `i.mi.com`。
如需扩展额外工具或资源，请优先复用现有客户端与缓存逻辑，遵守项目的 KISS/YAGNI 原则。