@joyjit/vikunja-mcp 0.3.2 → 0.3.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +24 -0
- package/README.md +46 -29
- package/package.json +3 -2
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,29 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## Unreleased
|
|
4
|
+
|
|
5
|
+
## 0.3.3 — 2026-09-07
|
|
6
|
+
|
|
7
|
+
### Reliability
|
|
8
|
+
|
|
9
|
+
- Add `scripts/smoke-dist.sh` — post-build gate that starts the compiled server and
|
|
10
|
+
asserts it answers a real MCP `initialize` (catches crash-on-import and stale
|
|
11
|
+
`dist/`; Vikunja #682 / #715)
|
|
12
|
+
- Add `scripts/run-mcp.sh` — launcher auto-builds when `dist/` is missing or older
|
|
13
|
+
than `src/`, smoke-tests before exec, rebuilds once on smoke failure
|
|
14
|
+
|
|
15
|
+
### Platform
|
|
16
|
+
|
|
17
|
+
- Pin MCP integration CI to Vikunja 2.5.0 (canary already green on `latest`)
|
|
18
|
+
- Describe the fork as Vikunja 2.5-ready (README, npm, MCP registry blurb)
|
|
19
|
+
- Bump nested deps (`browserslist`, `fast-uri`, `@humanfs/node`, `qs`, …) so
|
|
20
|
+
weekly `npm audit` / Security Scan stays clean
|
|
21
|
+
|
|
22
|
+
### Docs
|
|
23
|
+
|
|
24
|
+
- README: document focused task tools, build smoke gate / `run-mcp.sh`,
|
|
25
|
+
and shorten the old v0.2.0 architecture section
|
|
26
|
+
|
|
3
27
|
## 0.3.2 — 2026-08-11
|
|
4
28
|
|
|
5
29
|
### Fixes
|
package/README.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
Maintained **fork** of [`democratize-technology/vikunja-mcp`](https://github.com/democratize-technology/vikunja-mcp), published as [`@joyjit/vikunja-mcp`](https://www.npmjs.com/package/@joyjit/vikunja-mcp).
|
|
4
4
|
|
|
5
|
-
Upstream is slow to merge and release. This fork ships Vikunja **2.
|
|
5
|
+
Upstream is slow to merge and release. This fork ships Vikunja **2.5**-ready fixes on a faster cadence while still sending PRs upstream. Prefer upstream once equivalent fixes are released there.
|
|
6
6
|
|
|
7
7
|
### Fork highlights (vs upstream npm `0.2.0`)
|
|
8
8
|
|
|
@@ -17,7 +17,9 @@ Upstream is slow to merge and release. This fork ships Vikunja **2.3**-ready fix
|
|
|
17
17
|
- **Filtered lists paginate correctly**: `done` / `filter` go to the server before paging (with client-side fallback)
|
|
18
18
|
- **Bulk writes vs SQLite**: default one write at a time, retry lock/5xx; raise with `VIKUNJA_BULK_WRITE_CONCURRENCY` on Postgres
|
|
19
19
|
- **Vikunja 2.x**: `getAllTasks` uses `GET /tasks`; list responses include all items (no silent drop after 10)
|
|
20
|
-
- **
|
|
20
|
+
- **Focused task tools**: smaller tools (`vikunja_task_crud`, `vikunja_task_bulk`, …) alongside the all-in-one `vikunja_tasks` (same behavior; prefer focused tools for agents)
|
|
21
|
+
- **Build smoke gate**: every `npm run build` starts `dist/` and checks a real MCP `initialize` reply so a broken build cannot ship silently
|
|
22
|
+
- **Node.js 24** + Dockerized MCP integration CI against Vikunja 2.5
|
|
21
23
|
|
|
22
24
|
A Model Context Protocol (MCP) server that enables AI assistants to interact with Vikunja task management instances. This fork treats the server as a **thin Vikunja API wrapper**: tool args are validated for shape (IDs, dates, enums), credentials are masked in logs, and DoS limits still apply — but **content policy for titles/descriptions belongs to Vikunja**, not a regex reject list in this process.
|
|
23
25
|
|
|
@@ -42,30 +44,9 @@ A Model Context Protocol (MCP) server that enables AI assistants to interact wit
|
|
|
42
44
|
- **Memory protection** with pagination limits and usage monitoring
|
|
43
45
|
- **Simplified architecture** with 90% code reduction for maintainability
|
|
44
46
|
|
|
45
|
-
##
|
|
47
|
+
## Architecture notes (since v0.2.0)
|
|
46
48
|
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
### Storage Architecture Refactoring (90% Code Reduction)
|
|
50
|
-
- **Before**: 33 files, 9,803 lines of over-engineered storage system
|
|
51
|
-
- **After**: 4 files, essential functionality only
|
|
52
|
-
- **Eliminated**: Complex orchestrators, health monitors, statistics tracking, migration systems
|
|
53
|
-
- **Result**: Same external API with dramatically improved maintainability
|
|
54
|
-
|
|
55
|
-
### Zod-Based Filter System (850+ Lines Removed)
|
|
56
|
-
- **Before**: Custom tokenizer, parser, and validator with security vulnerabilities
|
|
57
|
-
- **After**: Secure Zod schema validation with production-ready parsing
|
|
58
|
-
- **Enhanced**: DoS protection and comprehensive error handling
|
|
59
|
-
- **Result**: Faster parsing, better security, and enterprise-grade reliability
|
|
60
|
-
|
|
61
|
-
### Production-Ready Retry System (580+ Lines Replaced)
|
|
62
|
-
- **Before**: Custom retry logic with maintenance overhead
|
|
63
|
-
- **After**: Battle-tested opossum circuit breaker library
|
|
64
|
-
- **Features**: Circuit breaker state sharing, automatic recovery, comprehensive monitoring
|
|
65
|
-
- **Result**: Production resilience with battle-tested patterns
|
|
66
|
-
|
|
67
|
-
### Zero Breaking Changes
|
|
68
|
-
All improvements maintain **100% backward compatibility** with existing implementations while providing enhanced reliability and security.
|
|
49
|
+
The server uses a small in-memory filter store, Zod-validated filters (with DoS limits), and an opossum circuit breaker for API retries. External tool behavior stayed compatible across that cleanup.
|
|
69
50
|
|
|
70
51
|
## Requirements
|
|
71
52
|
|
|
@@ -94,7 +75,7 @@ All improvements maintain **100% backward compatibility** with existing implemen
|
|
|
94
75
|
|
|
95
76
|
Requires **Node.js 24+**. Use an API token (`tk_…`) or JWT from your Vikunja instance.
|
|
96
77
|
|
|
97
|
-
Pin a version if you want (example): `"args": ["-y", "@joyjit/vikunja-mcp@0.3.
|
|
78
|
+
Pin a version if you want (example): `"args": ["-y", "@joyjit/vikunja-mcp@0.3.3"]`.
|
|
98
79
|
|
|
99
80
|
### Option 2: Install from GitHub (no npm needed)
|
|
100
81
|
|
|
@@ -122,6 +103,8 @@ npm install
|
|
|
122
103
|
npm run build
|
|
123
104
|
```
|
|
124
105
|
|
|
106
|
+
`npm run build` runs a **post-build smoke check** (`scripts/smoke-dist.sh`): it starts `dist/index.js` and requires a valid MCP `initialize` reply. A crash-on-import or stale `dist/` fails the build instead of shipping a silent empty tool list.
|
|
107
|
+
|
|
125
108
|
Then configure your MCP client:
|
|
126
109
|
|
|
127
110
|
```json
|
|
@@ -139,6 +122,8 @@ Then configure your MCP client:
|
|
|
139
122
|
}
|
|
140
123
|
```
|
|
141
124
|
|
|
125
|
+
For a local checkout that should rebuild itself when `dist/` is missing or older than `src/`, use `scripts/run-mcp.sh` as the MCP `command` (see comments in that script).
|
|
126
|
+
|
|
142
127
|
## Configuration
|
|
143
128
|
|
|
144
129
|
### Logging Configuration
|
|
@@ -263,7 +248,25 @@ vikunja_auth.disconnect()
|
|
|
263
248
|
|
|
264
249
|
### Task Management Examples
|
|
265
250
|
|
|
251
|
+
Prefer the focused tools (`vikunja_task_crud`, `vikunja_task_bulk`, …) when an agent is choosing tools. The all-in-one `vikunja_tasks` tool below still works and covers the same operations.
|
|
252
|
+
|
|
266
253
|
```typescript
|
|
254
|
+
// Focused tools (recommended for agents)
|
|
255
|
+
vikunja_task_crud({ operation: "list", allProjects: true })
|
|
256
|
+
vikunja_task_crud({
|
|
257
|
+
operation: "create",
|
|
258
|
+
title: "Ship README update",
|
|
259
|
+
projectId: 1,
|
|
260
|
+
priority: 3,
|
|
261
|
+
})
|
|
262
|
+
vikunja_task_bulk({
|
|
263
|
+
operation: "bulk-update",
|
|
264
|
+
taskIds: [1, 2, 3],
|
|
265
|
+
field: "done",
|
|
266
|
+
value: true,
|
|
267
|
+
})
|
|
268
|
+
|
|
269
|
+
// All-in-one tool (same behavior via subcommand)
|
|
267
270
|
// List all tasks across all projects
|
|
268
271
|
vikunja_tasks.list({ allProjects: true })
|
|
269
272
|
|
|
@@ -1072,8 +1075,22 @@ This standardized format ensures:
|
|
|
1072
1075
|
- `status` - Check authentication status
|
|
1073
1076
|
- `refresh` - Refresh authentication token
|
|
1074
1077
|
|
|
1075
|
-
### Task
|
|
1076
|
-
|
|
1078
|
+
### Focused Task Tools ✅ (preferred for agents)
|
|
1079
|
+
|
|
1080
|
+
Smaller single-purpose tools with an `operation` field. Same Vikunja behavior as the matching `vikunja_tasks` subcommands.
|
|
1081
|
+
|
|
1082
|
+
- `vikunja_task_crud` — `create`, `get`, `update`, `delete`, `list`
|
|
1083
|
+
- `vikunja_task_bulk` — `bulk-create`, `bulk-update`, `bulk-delete`
|
|
1084
|
+
- `vikunja_task_assignees` — `assign`, `unassign`, `list-assignees`
|
|
1085
|
+
- `vikunja_task_comments` — `comment`
|
|
1086
|
+
- `vikunja_task_reminders` — `add-reminder`, `remove-reminder`, `list-reminders`
|
|
1087
|
+
- `vikunja_task_labels` — `apply-label`, `remove-label`, `list-labels`
|
|
1088
|
+
- `vikunja_task_relations` — `relate`, `unrelate`, `relations`
|
|
1089
|
+
|
|
1090
|
+
Manual walkthrough: [`docs/MCP-TEST-CHECKLIST.md`](docs/MCP-TEST-CHECKLIST.md).
|
|
1091
|
+
|
|
1092
|
+
### Task Management ✅ (all-in-one)
|
|
1093
|
+
- `vikunja_tasks` - Task operations (fully implemented; prefer focused tools above when available)
|
|
1077
1094
|
- `list` - List tasks with filters
|
|
1078
1095
|
- Filter by project or get all tasks
|
|
1079
1096
|
- Support for pagination, search, sorting
|
|
@@ -1400,7 +1417,7 @@ For detailed rate limiting configuration, see [`docs/RATE_LIMITING.md`](docs/RAT
|
|
|
1400
1417
|
- [x] ✅ **Test coverage** - 98.91% function coverage achieved
|
|
1401
1418
|
- [x] ✅ **Architecture simplification** - 90% code reduction with enhanced maintainability
|
|
1402
1419
|
- [x] ✅ **Production-ready resilience** - Opossum circuit breaker and Zod validation
|
|
1403
|
-
- [x] ✅ **Integration tests** - Dockerized MCP tests against Vikunja 2.
|
|
1420
|
+
- [x] ✅ **Integration tests** - Dockerized MCP tests against Vikunja 2.5 (`npm run test:mcp`)
|
|
1404
1421
|
- [ ] Add webhook subscriptions for real-time updates
|
|
1405
1422
|
- [ ] Add caching for frequently accessed data
|
|
1406
1423
|
- [ ] Implement persistent storage for saved filters (optional - in-memory works well)
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@joyjit/vikunja-mcp",
|
|
3
|
-
"version": "0.3.
|
|
4
|
-
"description": "Maintained fork of the Vikunja MCP server — Model Context Protocol tools for Vikunja task management (Vikunja 2.
|
|
3
|
+
"version": "0.3.3",
|
|
4
|
+
"description": "Maintained fork of the Vikunja MCP server — Model Context Protocol tools for Vikunja task management (Vikunja 2.5-ready fixes)",
|
|
5
5
|
"main": "dist/index.js",
|
|
6
6
|
"types": "dist/index.d.ts",
|
|
7
7
|
"bin": {
|
|
@@ -16,6 +16,7 @@
|
|
|
16
16
|
"scripts": {
|
|
17
17
|
"dev": "tsx watch src/index.ts",
|
|
18
18
|
"build": "node --max-old-space-size=4096 ./node_modules/typescript/bin/tsc",
|
|
19
|
+
"postbuild": "./scripts/smoke-dist.sh",
|
|
19
20
|
"test": "jest --silent",
|
|
20
21
|
"test:watch": "jest --watch --silent",
|
|
21
22
|
"test:coverage": "jest --coverage --silent",
|