使用说明
版本：1.3.1 最后修改日期：2026-02-02 状态：活动
🧠 Checkvist MCP：代理商的“生产力操作系统”
将Checkvist从简单的大纲图转变为代理神经网络。
此MCP服务器充当您的LLM（Claude、Gemini等）和Checkvist生活之间的桥梁。它不仅仅是“阅读列表”；它理解 上下文，管理 分诊，并发现 连接.
🚀 愿景
我们正在构建一个服务器，模拟顶级生产力工具中最好的“专业”工作流程：
- 线性风格分类：通过人工智能辅助分拣收件箱为零。
- GitHub风格描述：“阻断者”意识和依赖性管理。
- Readwise风格回顾：旧思想的偶然复兴。
- 超人风格焦点：智能打盹和上下文隐藏。
📚 文档
该项目是“文件优先”。所有参考资料都组织在我们的：
从那里开始探索 愿景、架构、用例，以及 代理PKM研究.
🛠️ 快速开始
先决条件
- Python 3.10+
- Checkvist帐户（和API密钥）
uv或pip
安装
# 1. Clone & Setup
git clone git@github.com:miziodel/checkvist-mcp.git
cd checkvist-mcp
python3.11 -m venv .venv
source .venv/bin/activate
# 2. Install Dependencies
pip install -r requirements.txt
# 3. Configure Environment
cp .env.example .env
# Edit .env and add your CHECKVIST_USERNAME and CHECKVIST_API_KEY
[！重要] 强制性虚拟环境：所有命令必须在虚拟环境激活的情况下运行。 反重力代理配置为始终使用
source .venv/bin/activate && <command>以确保一致性并避免“找不到命令”错误。
[！注意] AI代理测试：由于macOS沙盒限制，AI代理（如Antigravity）无法直接执行
pytest从内部.venv. 这是一个安全功能，而不是一个bug。建议的工作流程是：
- 用户：手动运行
pytest从您的终端- 代理：分析测试输出并提出修复方案
看 mac-dev卫生技能 了解技术细节。
运行服务器
# Development Mode (Active venv required)
source .venv/bin/activate && fastmcp dev src/server.py
🔌 客户端集成
要在中使用此服务器 反重力，您可以直接通过添加 设置>MCP 菜单。
看 客户端设置指南 获取即用型JSON代码段和详细说明。
🧩 功能（专业套房）
| 功能 | 状态 | 描述 |
|---|---|---|
| 操作智能 | ✅ 准备好了 | 高分辨率搜索：面包屑+[N]注释、[C]注释和[F]igli即时上下文指示器。 |
| 钻孔工具 | ✅ 准备好了 | get_task：统一获取笔记、评论和深度分支探索(include_children). |
| 认证 | ✅ 就绪 | 通过API密钥进行基本身份验证。 |
| 标准化反馈 | ✅ 准备就绪 | 所有工具都会返回结构化JSON，其中包含明确的失败原因和下一步行动。 |
| 优化 | ✅ Ready | Smart Fetch（单个调用中的注释/标签）可防止N+1延迟。 |
| 阅读列表 | ✅ 就绪 | 获取列表内容（平面）。 |
| 添加任务 | ✅ 就绪 | 智能解析和标记。 |
| 智能分类 | ✅ 就绪 | 层次感知移动和清单之间的移动。 |
| 树状视图 | ✅ 就绪 | 深度探索和元数据。 |
| 议程工具 | ✅ 就绪 | 跨所有列表对今天、明天或逾期任务进行统一查看(get_upcoming_tasks). |
| 每周回顾 | ✅ 准备就绪 | 为“生产力架构师”提供胜利、过时任务和受阻项目的战略总结。 |
| 维护 | ✅ 就绪 | 递归逻辑存档（#已删除标记），智能语法规范化（！->！），强大的标记处理。 |
| 技术稳定性 | ✅ 就绪 | 类型化异常层次结构和集中错误处理，用于强健的代理交互。 |
🛡️ “选择架构”与安全
此服务器遵循严格 代理协议:
- 速率限制：通过限制“急切”的代理来阻止API禁令。
- 面包屑：始终提供完整的上下文（“主页>厨房>牛奶”），以防止歧义。
- 循环中的人类：破坏性操作（删除/存档）始终需要确认。
建于 FastMCP 符合Anthropics MCP标准。
