内容
# Vikunja FastMCP V2
纯净室 **Vikunja `/api/v2` 独占** 模型上下文协议服务器。直接节点 24 LTS `fetch`，运行时依赖：`@modelcontextprotocol/sdk` 和 `zod`。
## 项目历史
该仓库最初是作为早期 Vikunja MCP 项目的分支，用于评估和实验。目前的 v2 产品随后从头开始重建，以适应 Vikunja 记录的 `/api/v2` 接口。原始实现中没有源代码、运行时模块、生成的输出、依赖项或兼容性包装保留在当前的代码树中。
## 需求
- Node.js 24 LTS+
- 具有访问您需要的项目的 Vikunja API令牌
## 安装
全局安装预构建的公共版本：
```bash
npm install -g vikunja-fastmcp
```
安装或更新后重启MCP客户端，以启动新进程。
### 可选代理技能
npm 包中包含一个中立的 `vikunja-fastmcp` 技能，其中包含作用域、任务标识、分页、写入安全、附件和错误规则，代理需要这些规则。`self_check.agentSkillPath` 报告其安装位置。
在 Windows PowerShell 上为 Codex 安装：
```powershell
$source = Join-Path (npm root -g) "vikunja-fastmcp\skills\vikunja-fastmcp"
$target = Join-Path $HOME ".codex\skills\vikunja-fastmcp"
New-Item -ItemType Directory -Force -Path (Split-Path $target) | Out-Null
Copy-Item -LiteralPath $source -Destination $target -Recurse -Force
```
对于 Claude，请使用 `$HOME\.claude\skills\vikunja-fastmcp` 作为目标。对于不支持技能文件夹的代理，请将 `SKILL.md` 的内容放在该代理的持久性代理指令或规则文件中。安装或更新技能后重启代理。
## 环境
| 变量名 | 是否必需 | 描述 |
| --- | --- | --- |
| `VIKUNJA_URL` | 是 | 服务器根目录或 `…/api/v2`（例如 `http://host:3456`） |
| `VIKUNJA_API_TOKEN` | 是 | Bearer令牌（`tk_…`） |
| `VIKUNJA_WEB_URL` | 否 | 任务/项目链接的浏览器基准 |
| `VIKUNJA_ATTACHMENT_DOWNLOAD_ROOT` | 否 | 沙箱下载根目录（默认为操作系统临时目录下） |
| `VIKUNJA_MAX_ATTACHMENT_BYTES` | 否 | 上传/下载大小上限（默认为100 MiB） |
| `VIKUNJA_TEMPLATE_FILE` | 否 | 机器本地模板JSON路径（默认为用户主目录下） |
永不提交令牌。拒绝 `/api/v1` URL。
## 配置
```json
{
"mcpServers": {
"vikunja": {
"command": "vikunja-mcp",
"args": [],
"env": {
"VIKUNJA_URL": "https://vikunja.example.com/api/v2",
"VIKUNJA_API_TOKEN": "<YOUR_TOKEN>"
}
}
}
}
```
在 Vikunja 的 **设置 -> API令牌** 下创建 API 令牌。使用您自己的 Vikunja 服务器的 `/api/v2` URL。将令牌仅存储在本地 MCP 配置或秘密存储中。
## 本地开发
```bash
npm install
npm run build
node dist/index.js
```
MCP 客户端应该通过 stdio 启动 `dist/index.js`，并带有上述环境变量。
## 紧急Python备用方案
支持的路径是 npm 安装的 MCP。对于 MCP 无法启动的一次性紧急情况，[`fallback/vikunja-cli.py`](fallback/vikunja-cli.py) 提供了一个独立的 `/api/v2` CLI，具有显式设置、安全限制和离线单元测试，记录在 [`fallback/README.md`](fallback/README.md) 中。不要将两者作为独立的跟踪器写入器运行。
## 工具
- `self_check` / `vikunja_auth` — 诊断和当前用户（无电子邮件）
- `vikunja_projects` — 列表 / 获取
- `vikunja_tasks` — CRUD，列表（默认为 **仅开放**），创建_if_absent，分配者，标签，关系，附件
- `vikunja_task_comments`
- `vikunja_labels` — 全局标签（标题或ID）
- `vikunja_users`
- `vikunja_teams` — 团队/成员（`userId` 是 Vikunja 用户ID）
- `vikunja_filters` — 创建/获取/更新/删除（**无列表**；API无集合GET）
- `vikunja_task_bulk` — 原生批量更新；有界组合创建/删除
- `vikunja_task_reminders` — 列表/添加/删除任务提醒
- `vikunja_batch_import` — 检测/预览/导入/状态，用于原生CSV迁移
- `vikunja_export_project` — 本地JSON/CSV任务导出
- `vikunja_request_user_export` / `vikunja_download_user_export`
- `vikunja_templates` — 机器本地模板和任务实例化
- `vikunja_webhooks` — 项目/用户网络钩子和事件发现
模板默认为 `~/.vikunja-fastmcp/templates.json`，可以通过 `VIKUNJA_TEMPLATE_FILE` 重新定位。下载和导出保留在 `VIKUNJA_ATTACHMENT_DOWNLOAD_ROOT` 内。组合批量创建/删除操作绑定到100个任务，并且不是原子的。
Vikunja 权限按操作应用。即使允许普通的任务更新，应用标签也可能被拒绝。某些 Vikunja 版本还要求用户数据导出路由使用 JWT/本地密码身份验证；MCP 保留真正的 `401` 而不是呈现虚假的 JWT 建议。
参见生成的 `MCP_API.md` 以获取输入。响应为 Markdown 摘要 + 一个 JSON 信封（`ok` / `error`）。任务列表默认为 25 个项目，每个项目页面上限为 100；使用 `countOnly` 获取总数，使用分页获取更大的结果集。
### 运行限制
- 批量更新/关闭：每次调用100个全局任务ID。
- 批量创建：每次调用100个任务；组合且非原子。
- 批量删除：每次调用100个任务ID；组合、非原子，需要 `confirm: true`。
- CSV导入和文件传输：默认为 `VIKUNJA_MAX_ATTACHMENT_BYTES` 的100 MiB；Vikunja 控制 CSV 行限制。
- 多项目列表独立分页每个项目。在只需要总计的情况下，请优先使用 `countOnly`。
## 开发
```bash
npm test
npm run typecheck
npm run docs:api
npm run docs:api:check
```
## 许可证
MIT — 参见 `LICENSE` 和 `AUTHORS.md`。
