内容
# 检查清单 MCP 服务器
用于 Checkvist API 集成MCP服务器，使 Claude 能够读取和写入 Checkvist 检查清单。
## 功能
- 完整的检查清单 CRUD 操作（列出、获取、创建、更新、删除）
- 完整的任务管理（创建、更新、关闭、重新打开、删除、使无效）
- 重复任务配置
- 任务分配给用户
- 一次导入多个任务
- 完整的备注/评论管理（获取、创建、更新、删除）
- 用户配置文件信息
- 完全支持 Checkvist 的智能语法（截止日期、标签、优先级）
- 具有可操作提示的有帮助的错误消息
## 安装
```bash
npm install
npm run build
```
## 配置
1. 从您的个人资料页面获取 Checkvist API 密钥：https://checkvist.com/auth/profile
2. 创建一个 `.env` 文件：
```bash
cp .env.example .env
```
3. 编辑 `.env` 并添加您的凭证：
```
CHECKVIST_USERNAME=your_email@example.com
CHECKVIST_API_KEY=your_api_key_here
```
## Claude 桌面配置
将以下内容添加到您的 Claude 桌面配置中（`~/Library/Application Support/Claude/claude_desktop_config.json` 在 macOS 上）：
```json
{
"mcpServers": {
"checkvist": {
"command": "node",
"args": [
"/Users/matsingerdal/Developer/GitHub/checkvist-mcp/dist/index.js"
]
}
}
}
```
## 可用工具
### 检查清单管理
- `checkvist_list_checklists` - 获取所有检查清单（只读）
- `checkvist_get_checklist` - 获取特定检查清单信息（只读）
- `checkvist_create_checklist` - 创建新的检查清单
- `checkvist_update_checklist` - 更新检查清单名称或可见性
- `checkvist_delete_checklist` - 删除检查清单（标记为删除）
### 任务管理
- `checkvist_get_tasks` - 获取所有任务的原始 JSON 数据（只读）
- `checkvist_get_tasks_summary` - 获取所有任务的可读文本格式（只读）
- `checkvist_get_tasks_paginated` - 获取分页任务以读取整个大型检查清单（推荐，只读）
- `checkvist_get_task` - 获取具有父级层次结构的特定任务的 JSON 数据（只读）
- `checkvist_get_task_tree` - 获取特定任务和所有子任务的可读文本（只读）
- `checkvist_create_task` - 创建新任务（支持 assignee_ids）
- `checkvist_update_task` - 更新现有任务（支持 assignee_ids）
- `checkvist_close_task` - 标记任务为完成
- `checkvist_reopen_task` - 重新打开已完成的任务
- `checkvist_delete_task` - 删除任务和子任务
- `checkvist_invalidate_task` - 标记任务为无效（状态=2）
- `checkvist_set_repeating_task` - 配置重复任务计划
- `checkvist_import_tasks` - 一次导入多个任务
### 备注/评论
- `checkvist_get_notes` - 获取任务的所有备注（只读）
- `checkvist_create_note` - 向任务添加备注
- `checkvist_update_note` - 更新现有备注
- `checkvist_delete_note` - 删除备注
### 用户信息
- `checkvist_get_current_user` - 获取身份验证用户配置文件（只读）
## 读取大型检查清单
对于具有许多任务的大型检查清单，请根据检查清单的大小使用正确的方法：
### 策略 1：快速预览（适用于非常大的检查清单）⭐
**`checkvist_get_tasks_summary` with `preview: true`**
- 仅显示**顶级任务**（无子任务）
- 数据最小，适用于巨大的检查清单（1000+任务）
- 自动使用紧凑模式
- 获取快速概览，然后使用 `get_task_tree` 进行深入查看
- 示例：
```
checkvist_get_tasks_summary(
checklist_id: 941803,
preview: true
)
```
- 输出：
```
📋 检查清单摘要（5 个顶级任务，847 个总任务）
⚡ 预览模式：仅显示顶级任务
[ ] 主项目 [12345]
[ ] 存档 [12350]
[ ] 备注 [12351]
[ ] 资源 [12352]
[ ] 模板 [12353]
💡 提示：使用 `checkvist_get_task_tree` 和特定的任务 ID 来探索子任务
```
### 策略 2：查看完整结构（适用于中大型检查清单）
**`checkvist_get_tasks_summary` with `compact: true`**
- 以超紧凑格式显示**整个检查清单**
- 仅显示：状态、标题和 ID（无元数据，无备注）
- 适用于数百个任务
- 示例：
```
checkvist_get_tasks_summary(
checklist_id: 941803,
compact: true,
max_depth: 2
)
```
### 策略 3：探索特定分支
**`checkvist_get_task_tree`** （用于一个分支的详细视图）
- 获取一个特定的任务和它的所有子任务，包含完整详细信息
- 显示元数据、备注、截止日期、优先级、标签
- 适用于在紧凑视图中找到感兴趣的任务
- 示例：`checkvist_get_task_tree(checklist_id: 941803, task_id: 71218558)`
### 策略 4：适用于小型检查清单的完整详细信息
**`checkvist_get_tasks_summary` with `compact: false`** （默认）
- 显示所有内容，包含完整的元数据和备注
- 仅适用于 <50 个任务的检查清单
- 对于较大的检查清单可能太大
**`checkvist_get_tasks`**
- 返回原始 JSON 结构
- 可能存储在较难阅读的文件中
- 仅在需要以编程方式处理 JSON 时使用
### 推荐工作流程
**选项 1：分页阅读所有内容** ⭐ （适用于阅读整个检查清单）
```
1. checkvist_get_tasks_paginated(checklist_id: X, page: 1)
→ 显示第一个 3 个顶级任务及其所有子任务
2. checkvist_get_tasks_paginated(checklist_id: X, page: 2)
→ 显示下一个 3 个顶级任务及其所有子任务
3. 继续直到您阅读了所有页面
```
Claude 可以通过这种方式阅读所有任务，而不会遇到大小限制！
**选项 2：预览 + 深入查看** （更快地查找特定信息）
```
1. checkvist_get_tasks_summary(checklist_id: X, preview: true)
→ 查看所有顶级任务（仅 5-10 个项目）
2. 在预览中找到感兴趣的任务
3. checkvist_get_task_tree(checklist_id: X, task_id: Y)
→ 获取该特定分支的所有详细信息
```
## 智能语法支持
Checkvist 在任务内容中支持智能语法：
- `^tomorrow` - 设置截止日期
- `#tag` - 添加标签
- `!3` - 设置优先级（0-9）
- `@username` - 分配给用户
通过 `parse_tasks: true` 或 `parse: true` 参数启用解析。
## 开发
```bash
# 监视模式
npm run dev
# 构建
npm run build
# 启动
npm start
```
## API 文档
完整的 Checkvist API 文档：https://checkvist.com/auth/api
