mcp公司
使用Vikunja和Vertex AI（Gemini）的AI驱动的MCP服务器进行ADHD优化任务管理。
特性
- 每日焦点会议：基于能量水平和工作模式的人工智能任务排名
- 依赖意识：排除已阻止的任务，优先解除阻止的任务
- 项目上下文切换：通过智能地对任务进行分组，最大限度地减少认知负荷
- 智能过滤：自然语言到Vikunja过滤器表达式转换
- 任务丰富：ADHD工作流程的自动元数据生成
- 完全MCP集成：适用于Claude、OpenAI和其他MCP兼容客户端
快速开始
环境变量
export VIKUNJA_URL=https://tasks.example.com
export VIKUNJA_TOKEN=your-api-token
# Optional: Vertex AI for AI features
export GCP_PROJECT=your-project
export GCP_LOCATION=us-central1
export GEMINI_MODEL=gemini-2.0-flash使用Docker运行
docker pull ghcr.io/belkirill/vikunja-mcp-py:main
docker run --rm -i \
-e VIKUNJA_URL=https://tasks.example.com \
-e VIKUNJA_TOKEN=your-token \
ghcr.io/belkirill/vikunja-mcp-py:mainClaude代码配置
添加到您的 ~/.claude.json 或项目 .mcp.json:
{
"mcpServers": {
"vikunja-mcp": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"-e", "VIKUNJA_URL",
"-e", "VIKUNJA_TOKEN",
"ghcr.io/belkirill/vikunja-mcp-py:main"
],
"env": {
"VIKUNJA_URL": "https://tasks.example.com",
"VIKUNJA_TOKEN": "your-api-token"
}
}
}
}MCP工具
| 工具 | 说明 |
|---|---|
daily-focus | 根据能量/模式获取AI推荐的焦点会话任务 |
get-full-task | 获取一个任务的所有详细信息，包括元数据和注释 |
get-filtered-tasks | 使用筛选表达式或自然语言检索任务 |
upsert-task | 创建新任务或更新现有任务 |
add-comment | 向任务添加注释 |
bulk-update-tasks | 一次更新多个任务（已完成、优先级、颜色） |
export-project-json | 将任务导出到具有丰富元数据的本地JSON文件 |
评论系统
评论系统可帮助您跟踪进度并维护任务的上下文：
添加评论
Use the add-comment tool with task_id and your comment text.评论对以下方面有用：
- 记录长时间运行任务的进度
- 录音障碍或决定
- 为稍后返回任务时留下上下文
评论集成
- 日常焦点：显示推荐任务的评论计数和最近的评论预览
- 完成全部任务：返回所有带有完整详细信息的评论
- 追加销售任务：建议在标记任务完成时添加注释
ADHD工作流程提示
- 使用上下文启动会话：查看您正在处理的任务的最新评论
- 立即阻止文档：卡住时，在切换任务之前添加注释
- 以笔记结束会话：使用评论来捕捉你离开的地方
依赖管理
服务器自动跟踪Vikunja的related_tasks API中的任务依赖关系：
运作原理
- 已阻止的任务已排除：被不完整依赖项阻止的任务将自动排除在
daily-focus建议 - 解除锁定优先级：取消阻止其他任务的任务会根据AI排名进行突出显示和优先级排序
- 链上下文:
get-full-task显示依赖链进度（例如，“2/5已完成”）
响应中的依赖字段
日常焦点 任务包括：
is_blocked：任务是否被不完整的依赖关系阻止blocked_by_ids：阻止任务ID列表blocking_ids：此任务阻止的任务ID列表unlocks_tasks：如果完成此任务会解除对其他任务的阻止，则为True
完成全部任务 包含完整的依赖关系上下文：
{
"dependencies": {
"is_blocked": false,
"blocked_by": [{"id": 99, "title": "Setup infra", "done": true}],
"blocking": [{"id": 101, "title": "Deploy app", "done": false}],
"chain_context": {
"progress": "2/5",
"progress_percent": 40.0,
"next_actionable_ids": [100]
}
}
}在Vikunja建立依赖关系
- 在Vikunja打开任务
- 添加类型为“blocked by”或“blocks”的关系
- MCP服务器自动读取这些关系
ADHD工作流程提示
- 专注于解锁任务：完成解锁他人的任务会产生动力
- 使用链进度：查看您在多步骤项目中的位置
- 信任过滤器：被阻止的任务被隐藏起来，这样你就不会分心
项目上下文系统
该服务器包括智能项目上下文感知，以最大限度地减少上下文切换带来的认知负荷。
运作原理
- 上下文切换成本：人工智能计算在项目之间切换的认知成本
- 任务分组：同一项目的任务在建议中分组在一起
- 当前项目连续性：使用
current_project_id优先考虑继续当前的工作
使用当前项目
通过 current_project_id 到 daily-focus 要获得最小化上下文切换的建议：
daily-focus with energy="high", mode="deep", current_project_id=8这告诉人工智能你目前正在进行项目8，因此它将：
- 优先处理项目8中的任务
- 将其他项目任务分组以尽量减少切换
- 在排序任务时考虑上下文权重
上下文权重因素
在计算转换成本时，系统考虑了几个因素：
| 因素 | 影响 |
|---|---|
| 上下文权重 | 繁重的项目（复杂的代码库）具有较高的转换成本 |
| 相关项目 | 共享上下文的项目具有较低的转换成本 |
| 同一域 | 同一领域（例如“infra”）中的项目更容易切换 |
| 工作类型匹配 | 在编码/管理/研究之间切换会产生开销 |
| 工具要求 | 不同的工具要求增加了转换成本 |
配置项目上下文
您可以通过三种方式（按优先级顺序）配置项目上下文：
1.JSON配置文件
集 PROJECT_CONTEXT_CONFIG 环境变量到JSON文件路径：
export PROJECT_CONTEXT_CONFIG=/path/to/projects.json示例 projects.json:
{
"projects": [
{
"project_id": 8,
"name": "Vikunja MCP",
"work_type": "coding",
"domain": "vikunja-mcp",
"typical_energy": "high",
"typical_mode": "deep",
"context_weight": 8,
"requires_tools": ["vscode", "docker"],
"related_projects": [9, 10]
}
]
}2.项目描述中嵌入的元数据
在Vikunja的项目描述中添加元数据块：
3.项目标题/描述中的默认值
如果找不到配置，项目将获得默认值（context_weight=5，work_type=“general”）。
ADHD工作流程提示
- 设置当前项目：总是通过
current_project_id当你深入一个项目时 - 按项目分批：切换前在一个项目中完成多个任务
- 尊重分组：AI将任务分组以保护您的注意力
- 大型项目需要时间：高背景权重项目受益于更长的焦点会议
发展
# Create virtual environment
uv venv && source .venv/bin/activate
# Install dev dependencies
uv pip install -e ".[dev]"
# Run linter
ruff check src/
ruff format src/
# Run tests
pytest -v
# Build Docker image
docker build -t vikunja-mcp-py:latest .许可证
阿帕奇-2.0