AI导哈

AI任务控制平面服务器

一个面向生产的MCP服务器和本地编排工具包，用于将Vikunja作为AI任务控制平面。

  • by joanmarcriera
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 joanmarcriera/vikunja-mcp

使用说明

vikunja mcp服务器

面向生产的MCP服务器和本地编排工具包，用于将Vikunja用作AI任务控制平面。

这提供了什么

  • 一个公开核心工作流工具的Python MCP服务器：
    1. vikunja_list_tasks
    2. vikunja_get_task
    3. vikunja_create_task
    4. vikunja_update_task
    5. vikunja_transition_task
    6. vikunja_claim_next_task
    7. vikunja_add_execution_note
    8. vikunja_sync_fs_tasks
  • 用于表格/甘特图/看板的其他视图感知工具：
    1. vikunja_list_project_views
    2. vikunja_get_view_tasks
    3. vikunja_move_task_to_bucket
    4. vikunja_move_task_position
    5. vikunja_update_task 与 start_date/end_date 用于甘特时间线移动
  • 国家机器护栏使用 status:* 标签。
  • SQLite支持的幂等性、任务映射、同步元数据和声明锁。
  • 本地任务清单同步(tasks/*.yaml)以及工件路径报告(outputs/).
  • 用于索赔/执行/报告/归档工作流的辅助脚本。

堆栈

  • Python 3.11+
  • httpx, pydantic, typer, python-dotenv, tenacity, mcp, PyYAML

快速开始

uv venv
source .venv/bin/activate
uv pip install -e .[dev]
cp .env.example .env

编辑 .env 并设置您的令牌/项目。

重要的可选环境调优：

  • VIKUNJA_MAX_PAGE_SIZE （默认值 100)
  • VIKUNJA_MAX_FETCH_TASKS （默认值 500)

命令

# Start MCP server (stdio transport)
uv run vikunja-mcp serve

# Validate config and connectivity
uv run vikunja-mcp doctor

# Sync local task manifests with Vikunja
uv run vikunja-mcp sync --project-id 44 --dry-run

# Claim next eligible task for an agent
uv run vikunja-mcp claim-next --project-id 44 --agent coder.agent --accepted-label agent:coder

辅助脚本

# Claim + create local task YAML + outputs folder
uv run python scripts/claim_and_prepare.py --project-id 44 --agent coder.agent --accepted-label agent:coder

# Build prompt packet and run placeholder Aider command
uv run python scripts/run_task_with_aider.py tasks/TASK-123.yaml

# Report execution outcome back to Vikunja
uv run python scripts/report_task_result.py tasks/TASK-123.yaml --result success

# Move locally completed tasks to archive
uv run python scripts/close_completed_local_tasks.py

# Import Taskwarrior-style JSON into Vikunja
uv run python scripts/import_taskwarrior_json.py ./taskwarrior-export.json --project-id 44

# Capture README screenshots from Vikunja UI (Playwright)
uv run --extra dev python scripts/capture_vikunja_screenshots.py --headless

UI演练

列表视图

甘特图

表格视图

看板视图

过滤器

任务详情

生态系统参考（截至2026年3月8日）

详细说明和通过决定记录在 docs/ecosystem-implementations.md.

查看移动示例 docs/view-operations.md.

任务状态模型

允许的状态：

  • inbox
  • ready
  • claimed
  • in_progress
  • blocked
  • review
  • done
  • cancelled

允许的转换：

  • inbox -> ready, cancelled
  • ready -> claimed, blocked, cancelled
  • claimed -> in_progress, ready, blocked, cancelled
  • in_progress -> review, blocked, ready, cancelled
  • blocked -> ready, cancelled
  • review -> done, ready, in_progress, cancelled

真相来源分裂

  • Vikunja：作战任务控制飞机
  • tasks/*.yaml：本地执行清单
  • outputs/：执行工件
  • .orchestrator/vikunja_mcp.db：同步和控制元数据

测试

uv run pytest

涵盖的测试：

  • 状态机+标签提取/替换
  • 确定性索赔排序
  • 同步冲突检测
  • 创建任务幂等性
  • 客户端规范化助手

存储库布局

.
├─ .env.example
├─ src/vikunja_mcp/
├─ scripts/
├─ tests/
├─ examples/
├─ tasks/
├─ tasks_done/
├─ outputs/
└─ .orchestrator/

备注

  • 服务器是有意明确和可审计的。
  • Vikunja API怪癖可能因版本而异；客户端方法包括任务列表的兼容性回退。
  • 使用一个有纪律的变异层（此MCP服务器）来避免多代理状态漂移。

相关 MCP