@joyjit/vikunja-mcp 0.3.2 → 0.3.4

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.
Files changed (3) hide show
  1. package/CHANGELOG.md +33 -0
  2. package/README.md +46 -29
  3. package/package.json +10 -6
package/CHANGELOG.md CHANGED
@@ -1,5 +1,38 @@
1
1
  # Changelog
2
2
 
3
+ ## Unreleased
4
+
5
+ ## 0.3.4 — 2026-09-14
6
+
7
+ ### Platform
8
+
9
+ - Bump `@modelcontextprotocol/sdk` to ^1.30.0 and drop the `@hono/node-server`
10
+ override (Closes #15)
11
+ - Bump nested `hono` / `js-yaml` pins so weekly `npm audit` / Security Scan
12
+ stays clean
13
+
14
+ ## 0.3.3 — 2026-09-07
15
+
16
+ ### Reliability
17
+
18
+ - Add `scripts/smoke-dist.sh` — post-build gate that starts the compiled server and
19
+ asserts it answers a real MCP `initialize` (catches crash-on-import and stale
20
+ `dist/`; Vikunja #682 / #715)
21
+ - Add `scripts/run-mcp.sh` — launcher auto-builds when `dist/` is missing or older
22
+ than `src/`, smoke-tests before exec, rebuilds once on smoke failure
23
+
24
+ ### Platform
25
+
26
+ - Pin MCP integration CI to Vikunja 2.5.0 (canary already green on `latest`)
27
+ - Describe the fork as Vikunja 2.5-ready (README, npm, MCP registry blurb)
28
+ - Bump nested deps (`browserslist`, `fast-uri`, `@humanfs/node`, `qs`, …) so
29
+ weekly `npm audit` / Security Scan stays clean
30
+
31
+ ### Docs
32
+
33
+ - README: document focused task tools, build smoke gate / `run-mcp.sh`,
34
+ and shorten the old v0.2.0 architecture section
35
+
3
36
  ## 0.3.2 — 2026-08-11
4
37
 
5
38
  ### 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.3**-ready fixes on a faster cadence while still sending PRs upstream. Prefer upstream once equivalent fixes are released there.
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
- - **Node.js 24** + Dockerized MCP integration CI against Vikunja 2.3
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
- ## 🚀 Major Architectural Improvements (v0.2.0)
47
+ ## Architecture notes (since v0.2.0)
46
48
 
47
- This release represents a **massive architectural simplification** that eliminates technical debt while enhancing security and reliability:
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.2"]`.
78
+ Pin a version if you want (example): `"args": ["-y", "@joyjit/vikunja-mcp@0.3.4"]`.
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 Management ✅
1076
- - `vikunja_tasks` - Task operations (fully implemented)
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.3 (`npm run test:mcp`)
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.2",
4
- "description": "Maintained fork of the Vikunja MCP server — Model Context Protocol tools for Vikunja task management (Vikunja 2.3-ready fixes)",
3
+ "version": "0.3.4",
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",
@@ -62,7 +63,7 @@
62
63
  },
63
64
  "dependencies": {
64
65
  "@cfworker/json-schema": "^4.1.1",
65
- "@modelcontextprotocol/sdk": "^1.29.0",
66
+ "@modelcontextprotocol/sdk": "^1.30.0",
66
67
  "async-mutex": "^0.5.0",
67
68
  "better-sqlite3": "^12.4.1",
68
69
  "dotenv": "^17.2.3",
@@ -136,10 +137,13 @@
136
137
  "handlebars": "^4.7.9",
137
138
  "test-exclude": "^7.0.2",
138
139
  "fast-uri": "^4.1.2",
139
- "@hono/node-server": "^2.0.5",
140
140
  "brace-expansion": "5.0.9",
141
- "hono": "^4.12.34",
142
- "ip-address": "^10.4.0"
141
+ "hono": "^4.13.7",
142
+ "ip-address": "^10.4.0",
143
+ "js-yaml": "^4.3.2",
144
+ "@istanbuljs/load-nyc-config": {
145
+ "js-yaml": "3.15.2"
146
+ }
143
147
  },
144
148
  "engines": {
145
149
  "node": ">=24.0.0"