Vikunja MCP Py

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:main

Claude代码配置

添加到您的 ~/.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工具

评论系统

评论系统可帮助您跟踪进度并维护任务的上下文：

添加评论

Use the add-comment tool with task_id and your comment text.

评论对以下方面有用：

• 记录长时间运行任务的进度
• 录音障碍或决定
• 为稍后返回任务时留下上下文

评论集成

• 日常焦点：显示推荐任务的评论计数和最近的评论预览
• 完成全部任务：返回所有带有完整详细信息的评论
• 追加销售任务：建议在标记任务完成时添加注释

ADHD工作流程提示

1. 使用上下文启动会话：查看您正在处理的任务的最新评论
2. 立即阻止文档：卡住时，在切换任务之前添加注释
3. 以笔记结束会话：使用评论来捕捉你离开的地方

依赖管理

服务器自动跟踪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建立依赖关系

1. 在Vikunja打开任务
2. 添加类型为“blocked by”或“blocks”的关系
3. MCP服务器自动读取这些关系

ADHD工作流程提示

• 专注于解锁任务：完成解锁他人的任务会产生动力
• 使用链进度：查看您在多步骤项目中的位置
• 信任过滤器：被阻止的任务被隐藏起来，这样你就不会分心

项目上下文系统

该服务器包括智能项目上下文感知，以最大限度地减少上下文切换带来的认知负荷。

运作原理

• 上下文切换成本：人工智能计算在项目之间切换的认知成本
• 任务分组：同一项目的任务在建议中分组在一起
• 当前项目连续性：使用 current_project_id 优先考虑继续当前的工作

使用当前项目

通过 current_project_id 到 daily-focus 要获得最小化上下文切换的建议：

daily-focus with energy="high", mode="deep", current_project_id=8

这告诉人工智能你目前正在进行项目8，因此它将：

1. 优先处理项目8中的任务
2. 将其他项目任务分组以尽量减少切换
3. 在排序任务时考虑上下文权重

上下文权重因素

在计算转换成本时，系统考虑了几个因素：

配置项目上下文

您可以通过三种方式（按优先级顺序）配置项目上下文：

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