@joyjit/vikunja-mcp 0.3.0

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 (424) hide show
  1. package/CHANGELOG.md +51 -0
  2. package/LICENSE +21 -0
  3. package/README.md +1377 -0
  4. package/dist/auth/AuthManager.d.ts +63 -0
  5. package/dist/auth/AuthManager.d.ts.map +1 -0
  6. package/dist/auth/AuthManager.js +137 -0
  7. package/dist/auth/AuthManager.js.map +1 -0
  8. package/dist/auth/index.d.ts +7 -0
  9. package/dist/auth/index.d.ts.map +1 -0
  10. package/dist/auth/index.js +14 -0
  11. package/dist/auth/index.js.map +1 -0
  12. package/dist/auth/permissions.d.ts +60 -0
  13. package/dist/auth/permissions.d.ts.map +1 -0
  14. package/dist/auth/permissions.js +173 -0
  15. package/dist/auth/permissions.js.map +1 -0
  16. package/dist/client/VikunjaClientFactory.d.ts +32 -0
  17. package/dist/client/VikunjaClientFactory.d.ts.map +1 -0
  18. package/dist/client/VikunjaClientFactory.js +66 -0
  19. package/dist/client/VikunjaClientFactory.js.map +1 -0
  20. package/dist/client.d.ts +57 -0
  21. package/dist/client.d.ts.map +1 -0
  22. package/dist/client.js +128 -0
  23. package/dist/client.js.map +1 -0
  24. package/dist/config/ConfigurationManager.d.ts +63 -0
  25. package/dist/config/ConfigurationManager.d.ts.map +1 -0
  26. package/dist/config/ConfigurationManager.js +243 -0
  27. package/dist/config/ConfigurationManager.js.map +1 -0
  28. package/dist/config/index.d.ts +8 -0
  29. package/dist/config/index.d.ts.map +1 -0
  30. package/dist/config/index.js +27 -0
  31. package/dist/config/index.js.map +1 -0
  32. package/dist/config/types.d.ts +434 -0
  33. package/dist/config/types.d.ts.map +1 -0
  34. package/dist/config/types.js +93 -0
  35. package/dist/config/types.js.map +1 -0
  36. package/dist/formatters/BatchImportResponseFormatter.d.ts +89 -0
  37. package/dist/formatters/BatchImportResponseFormatter.d.ts.map +1 -0
  38. package/dist/formatters/BatchImportResponseFormatter.js +125 -0
  39. package/dist/formatters/BatchImportResponseFormatter.js.map +1 -0
  40. package/dist/index.d.ts +20 -0
  41. package/dist/index.d.ts.map +1 -0
  42. package/dist/index.js +119 -0
  43. package/dist/index.js.map +1 -0
  44. package/dist/middleware/direct-middleware.d.ts +9 -0
  45. package/dist/middleware/direct-middleware.d.ts.map +1 -0
  46. package/dist/middleware/direct-middleware.js +49 -0
  47. package/dist/middleware/direct-middleware.js.map +1 -0
  48. package/dist/middleware/index.d.ts +8 -0
  49. package/dist/middleware/index.d.ts.map +1 -0
  50. package/dist/middleware/index.js +21 -0
  51. package/dist/middleware/index.js.map +1 -0
  52. package/dist/middleware/simplified-rate-limit.d.ts +147 -0
  53. package/dist/middleware/simplified-rate-limit.d.ts.map +1 -0
  54. package/dist/middleware/simplified-rate-limit.js +542 -0
  55. package/dist/middleware/simplified-rate-limit.js.map +1 -0
  56. package/dist/parsers/CSVParser.d.ts +36 -0
  57. package/dist/parsers/CSVParser.d.ts.map +1 -0
  58. package/dist/parsers/CSVParser.js +69 -0
  59. package/dist/parsers/CSVParser.js.map +1 -0
  60. package/dist/parsers/InputParserFactory.d.ts +17 -0
  61. package/dist/parsers/InputParserFactory.d.ts.map +1 -0
  62. package/dist/parsers/InputParserFactory.js +137 -0
  63. package/dist/parsers/InputParserFactory.js.map +1 -0
  64. package/dist/parsers/JSONParser.d.ts +74 -0
  65. package/dist/parsers/JSONParser.d.ts.map +1 -0
  66. package/dist/parsers/JSONParser.js +69 -0
  67. package/dist/parsers/JSONParser.js.map +1 -0
  68. package/dist/services/EntityResolver.d.ts +75 -0
  69. package/dist/services/EntityResolver.d.ts.map +1 -0
  70. package/dist/services/EntityResolver.js +176 -0
  71. package/dist/services/EntityResolver.js.map +1 -0
  72. package/dist/services/TaskCreationService.d.ts +96 -0
  73. package/dist/services/TaskCreationService.d.ts.map +1 -0
  74. package/dist/services/TaskCreationService.js +361 -0
  75. package/dist/services/TaskCreationService.js.map +1 -0
  76. package/dist/storage/SimpleFilterStorage.d.ts +110 -0
  77. package/dist/storage/SimpleFilterStorage.d.ts.map +1 -0
  78. package/dist/storage/SimpleFilterStorage.js +358 -0
  79. package/dist/storage/SimpleFilterStorage.js.map +1 -0
  80. package/dist/storage/index.d.ts +59 -0
  81. package/dist/storage/index.d.ts.map +1 -0
  82. package/dist/storage/index.js +117 -0
  83. package/dist/storage/index.js.map +1 -0
  84. package/dist/tools/auth.d.ts +9 -0
  85. package/dist/tools/auth.d.ts.map +1 -0
  86. package/dist/tools/auth.js +80 -0
  87. package/dist/tools/auth.js.map +1 -0
  88. package/dist/tools/batch-import.d.ts +5 -0
  89. package/dist/tools/batch-import.d.ts.map +1 -0
  90. package/dist/tools/batch-import.js +150 -0
  91. package/dist/tools/batch-import.js.map +1 -0
  92. package/dist/tools/export.d.ts +14 -0
  93. package/dist/tools/export.d.ts.map +1 -0
  94. package/dist/tools/export.js +232 -0
  95. package/dist/tools/export.js.map +1 -0
  96. package/dist/tools/filters.d.ts +8 -0
  97. package/dist/tools/filters.d.ts.map +1 -0
  98. package/dist/tools/filters.js +419 -0
  99. package/dist/tools/filters.js.map +1 -0
  100. package/dist/tools/index.d.ts +36 -0
  101. package/dist/tools/index.d.ts.map +1 -0
  102. package/dist/tools/index.js +87 -0
  103. package/dist/tools/index.js.map +1 -0
  104. package/dist/tools/labels.d.ts +9 -0
  105. package/dist/tools/labels.d.ts.map +1 -0
  106. package/dist/tools/labels.js +152 -0
  107. package/dist/tools/labels.js.map +1 -0
  108. package/dist/tools/projects/crud.d.ts +118 -0
  109. package/dist/tools/projects/crud.d.ts.map +1 -0
  110. package/dist/tools/projects/crud.js +389 -0
  111. package/dist/tools/projects/crud.js.map +1 -0
  112. package/dist/tools/projects/hierarchy.d.ts +68 -0
  113. package/dist/tools/projects/hierarchy.d.ts.map +1 -0
  114. package/dist/tools/projects/hierarchy.js +280 -0
  115. package/dist/tools/projects/hierarchy.js.map +1 -0
  116. package/dist/tools/projects/index.d.ts +17 -0
  117. package/dist/tools/projects/index.d.ts.map +1 -0
  118. package/dist/tools/projects/index.js +169 -0
  119. package/dist/tools/projects/index.js.map +1 -0
  120. package/dist/tools/projects/response-formatter.d.ts +46 -0
  121. package/dist/tools/projects/response-formatter.d.ts.map +1 -0
  122. package/dist/tools/projects/response-formatter.js +131 -0
  123. package/dist/tools/projects/response-formatter.js.map +1 -0
  124. package/dist/tools/projects/sharing.d.ts +89 -0
  125. package/dist/tools/projects/sharing.d.ts.map +1 -0
  126. package/dist/tools/projects/sharing.js +272 -0
  127. package/dist/tools/projects/sharing.js.map +1 -0
  128. package/dist/tools/projects/validation.d.ts +39 -0
  129. package/dist/tools/projects/validation.d.ts.map +1 -0
  130. package/dist/tools/projects/validation.js +129 -0
  131. package/dist/tools/projects/validation.js.map +1 -0
  132. package/dist/tools/projects.d.ts +10 -0
  133. package/dist/tools/projects.d.ts.map +1 -0
  134. package/dist/tools/projects.js +42 -0
  135. package/dist/tools/projects.js.map +1 -0
  136. package/dist/tools/task-assignees.d.ts +13 -0
  137. package/dist/tools/task-assignees.d.ts.map +1 -0
  138. package/dist/tools/task-assignees.js +62 -0
  139. package/dist/tools/task-assignees.js.map +1 -0
  140. package/dist/tools/task-bulk.d.ts +13 -0
  141. package/dist/tools/task-bulk.d.ts.map +1 -0
  142. package/dist/tools/task-bulk.js +113 -0
  143. package/dist/tools/task-bulk.js.map +1 -0
  144. package/dist/tools/task-comments.d.ts +13 -0
  145. package/dist/tools/task-comments.d.ts.map +1 -0
  146. package/dist/tools/task-comments.js +53 -0
  147. package/dist/tools/task-comments.js.map +1 -0
  148. package/dist/tools/task-crud.d.ts +13 -0
  149. package/dist/tools/task-crud.d.ts.map +1 -0
  150. package/dist/tools/task-crud.js +163 -0
  151. package/dist/tools/task-crud.js.map +1 -0
  152. package/dist/tools/task-labels.d.ts +13 -0
  153. package/dist/tools/task-labels.d.ts.map +1 -0
  154. package/dist/tools/task-labels.js +62 -0
  155. package/dist/tools/task-labels.js.map +1 -0
  156. package/dist/tools/task-relations.d.ts +13 -0
  157. package/dist/tools/task-relations.d.ts.map +1 -0
  158. package/dist/tools/task-relations.js +72 -0
  159. package/dist/tools/task-relations.js.map +1 -0
  160. package/dist/tools/task-reminders.d.ts +13 -0
  161. package/dist/tools/task-reminders.d.ts.map +1 -0
  162. package/dist/tools/task-reminders.js +63 -0
  163. package/dist/tools/task-reminders.js.map +1 -0
  164. package/dist/tools/tasks/assignees/AssigneeOperationsService.d.ts +31 -0
  165. package/dist/tools/tasks/assignees/AssigneeOperationsService.d.ts.map +1 -0
  166. package/dist/tools/tasks/assignees/AssigneeOperationsService.js +95 -0
  167. package/dist/tools/tasks/assignees/AssigneeOperationsService.js.map +1 -0
  168. package/dist/tools/tasks/assignees/AssigneeResponseFormatter.d.ts +32 -0
  169. package/dist/tools/tasks/assignees/AssigneeResponseFormatter.d.ts.map +1 -0
  170. package/dist/tools/tasks/assignees/AssigneeResponseFormatter.js +84 -0
  171. package/dist/tools/tasks/assignees/AssigneeResponseFormatter.js.map +1 -0
  172. package/dist/tools/tasks/assignees/AssigneeValidationService.d.ts +36 -0
  173. package/dist/tools/tasks/assignees/AssigneeValidationService.d.ts.map +1 -0
  174. package/dist/tools/tasks/assignees/AssigneeValidationService.js +63 -0
  175. package/dist/tools/tasks/assignees/AssigneeValidationService.js.map +1 -0
  176. package/dist/tools/tasks/assignees/index.d.ts +40 -0
  177. package/dist/tools/tasks/assignees/index.d.ts.map +1 -0
  178. package/dist/tools/tasks/assignees/index.js +72 -0
  179. package/dist/tools/tasks/assignees/index.js.map +1 -0
  180. package/dist/tools/tasks/bulk/BulkOperationValidator.d.ts +51 -0
  181. package/dist/tools/tasks/bulk/BulkOperationValidator.d.ts.map +1 -0
  182. package/dist/tools/tasks/bulk/BulkOperationValidator.js +149 -0
  183. package/dist/tools/tasks/bulk/BulkOperationValidator.js.map +1 -0
  184. package/dist/tools/tasks/bulk-operations-simplified.d.ts +39 -0
  185. package/dist/tools/tasks/bulk-operations-simplified.d.ts.map +1 -0
  186. package/dist/tools/tasks/bulk-operations-simplified.js +249 -0
  187. package/dist/tools/tasks/bulk-operations-simplified.js.map +1 -0
  188. package/dist/tools/tasks/bulk-operations.d.ts +8 -0
  189. package/dist/tools/tasks/bulk-operations.d.ts.map +1 -0
  190. package/dist/tools/tasks/bulk-operations.js +14 -0
  191. package/dist/tools/tasks/bulk-operations.js.map +1 -0
  192. package/dist/tools/tasks/comments/CommentOperationsService.d.ts +23 -0
  193. package/dist/tools/tasks/comments/CommentOperationsService.d.ts.map +1 -0
  194. package/dist/tools/tasks/comments/CommentOperationsService.js +37 -0
  195. package/dist/tools/tasks/comments/CommentOperationsService.js.map +1 -0
  196. package/dist/tools/tasks/comments/CommentResponseFormatter.d.ts +29 -0
  197. package/dist/tools/tasks/comments/CommentResponseFormatter.d.ts.map +1 -0
  198. package/dist/tools/tasks/comments/CommentResponseFormatter.js +69 -0
  199. package/dist/tools/tasks/comments/CommentResponseFormatter.js.map +1 -0
  200. package/dist/tools/tasks/comments/CommentValidationService.d.ts +33 -0
  201. package/dist/tools/tasks/comments/CommentValidationService.d.ts.map +1 -0
  202. package/dist/tools/tasks/comments/CommentValidationService.js +50 -0
  203. package/dist/tools/tasks/comments/CommentValidationService.js.map +1 -0
  204. package/dist/tools/tasks/comments/index.d.ts +38 -0
  205. package/dist/tools/tasks/comments/index.d.ts.map +1 -0
  206. package/dist/tools/tasks/comments/index.js +62 -0
  207. package/dist/tools/tasks/comments/index.js.map +1 -0
  208. package/dist/tools/tasks/constants.d.ts +17 -0
  209. package/dist/tools/tasks/constants.d.ts.map +1 -0
  210. package/dist/tools/tasks/constants.js +36 -0
  211. package/dist/tools/tasks/constants.js.map +1 -0
  212. package/dist/tools/tasks/crud/TaskCreationService.d.ts +26 -0
  213. package/dist/tools/tasks/crud/TaskCreationService.d.ts.map +1 -0
  214. package/dist/tools/tasks/crud/TaskCreationService.js +228 -0
  215. package/dist/tools/tasks/crud/TaskCreationService.js.map +1 -0
  216. package/dist/tools/tasks/crud/TaskDeletionService.d.ts +18 -0
  217. package/dist/tools/tasks/crud/TaskDeletionService.d.ts.map +1 -0
  218. package/dist/tools/tasks/crud/TaskDeletionService.js +89 -0
  219. package/dist/tools/tasks/crud/TaskDeletionService.js.map +1 -0
  220. package/dist/tools/tasks/crud/TaskReadService.d.ts +18 -0
  221. package/dist/tools/tasks/crud/TaskReadService.d.ts.map +1 -0
  222. package/dist/tools/tasks/crud/TaskReadService.js +58 -0
  223. package/dist/tools/tasks/crud/TaskReadService.js.map +1 -0
  224. package/dist/tools/tasks/crud/TaskResponseFormatter.d.ts +18 -0
  225. package/dist/tools/tasks/crud/TaskResponseFormatter.d.ts.map +1 -0
  226. package/dist/tools/tasks/crud/TaskResponseFormatter.js +244 -0
  227. package/dist/tools/tasks/crud/TaskResponseFormatter.js.map +1 -0
  228. package/dist/tools/tasks/crud/TaskUpdateService.d.ts +29 -0
  229. package/dist/tools/tasks/crud/TaskUpdateService.d.ts.map +1 -0
  230. package/dist/tools/tasks/crud/TaskUpdateService.js +231 -0
  231. package/dist/tools/tasks/crud/TaskUpdateService.js.map +1 -0
  232. package/dist/tools/tasks/crud/index.d.ts +16 -0
  233. package/dist/tools/tasks/crud/index.d.ts.map +1 -0
  234. package/dist/tools/tasks/crud/index.js +20 -0
  235. package/dist/tools/tasks/crud/index.js.map +1 -0
  236. package/dist/tools/tasks/filtering/FilterExecutor.d.ts +38 -0
  237. package/dist/tools/tasks/filtering/FilterExecutor.d.ts.map +1 -0
  238. package/dist/tools/tasks/filtering/FilterExecutor.js +200 -0
  239. package/dist/tools/tasks/filtering/FilterExecutor.js.map +1 -0
  240. package/dist/tools/tasks/filtering/FilterValidator.d.ts +56 -0
  241. package/dist/tools/tasks/filtering/FilterValidator.d.ts.map +1 -0
  242. package/dist/tools/tasks/filtering/FilterValidator.js +183 -0
  243. package/dist/tools/tasks/filtering/FilterValidator.js.map +1 -0
  244. package/dist/tools/tasks/filtering/TaskFilteringOrchestrator.d.ts +75 -0
  245. package/dist/tools/tasks/filtering/TaskFilteringOrchestrator.d.ts.map +1 -0
  246. package/dist/tools/tasks/filtering/TaskFilteringOrchestrator.js +193 -0
  247. package/dist/tools/tasks/filtering/TaskFilteringOrchestrator.js.map +1 -0
  248. package/dist/tools/tasks/filtering/evaluators.d.ts +38 -0
  249. package/dist/tools/tasks/filtering/evaluators.d.ts.map +1 -0
  250. package/dist/tools/tasks/filtering/evaluators.js +200 -0
  251. package/dist/tools/tasks/filtering/evaluators.js.map +1 -0
  252. package/dist/tools/tasks/filtering/index.d.ts +11 -0
  253. package/dist/tools/tasks/filtering/index.d.ts.map +1 -0
  254. package/dist/tools/tasks/filtering/index.js +26 -0
  255. package/dist/tools/tasks/filtering/index.js.map +1 -0
  256. package/dist/tools/tasks/index.d.ts +9 -0
  257. package/dist/tools/tasks/index.d.ts.map +1 -0
  258. package/dist/tools/tasks/index.js +245 -0
  259. package/dist/tools/tasks/index.js.map +1 -0
  260. package/dist/tools/tasks/labels.d.ts +39 -0
  261. package/dist/tools/tasks/labels.d.ts.map +1 -0
  262. package/dist/tools/tasks/labels.js +150 -0
  263. package/dist/tools/tasks/labels.js.map +1 -0
  264. package/dist/tools/tasks/reminders.d.ts +39 -0
  265. package/dist/tools/tasks/reminders.d.ts.map +1 -0
  266. package/dist/tools/tasks/reminders.js +147 -0
  267. package/dist/tools/tasks/reminders.js.map +1 -0
  268. package/dist/tools/tasks/types/filters.d.ts +121 -0
  269. package/dist/tools/tasks/types/filters.d.ts.map +1 -0
  270. package/dist/tools/tasks/types/filters.js +7 -0
  271. package/dist/tools/tasks/types/filters.js.map +1 -0
  272. package/dist/tools/tasks/validation.d.ts +44 -0
  273. package/dist/tools/tasks/validation.d.ts.map +1 -0
  274. package/dist/tools/tasks/validation.js +121 -0
  275. package/dist/tools/tasks/validation.js.map +1 -0
  276. package/dist/tools/tasks-relations.d.ts +24 -0
  277. package/dist/tools/tasks-relations.d.ts.map +1 -0
  278. package/dist/tools/tasks-relations.js +203 -0
  279. package/dist/tools/tasks-relations.js.map +1 -0
  280. package/dist/tools/tasks.d.ts +6 -0
  281. package/dist/tools/tasks.d.ts.map +1 -0
  282. package/dist/tools/tasks.js +10 -0
  283. package/dist/tools/tasks.js.map +1 -0
  284. package/dist/tools/teams.d.ts +9 -0
  285. package/dist/tools/teams.d.ts.map +1 -0
  286. package/dist/tools/teams.js +332 -0
  287. package/dist/tools/teams.js.map +1 -0
  288. package/dist/tools/templates.d.ts +9 -0
  289. package/dist/tools/templates.d.ts.map +1 -0
  290. package/dist/tools/templates.js +356 -0
  291. package/dist/tools/templates.js.map +1 -0
  292. package/dist/tools/users.d.ts +9 -0
  293. package/dist/tools/users.d.ts.map +1 -0
  294. package/dist/tools/users.js +239 -0
  295. package/dist/tools/users.js.map +1 -0
  296. package/dist/tools/webhooks.d.ts +11 -0
  297. package/dist/tools/webhooks.d.ts.map +1 -0
  298. package/dist/tools/webhooks.js +378 -0
  299. package/dist/tools/webhooks.js.map +1 -0
  300. package/dist/transforms/base.d.ts +178 -0
  301. package/dist/transforms/base.d.ts.map +1 -0
  302. package/dist/transforms/base.js +134 -0
  303. package/dist/transforms/base.js.map +1 -0
  304. package/dist/transforms/field-selector.d.ts +27 -0
  305. package/dist/transforms/field-selector.d.ts.map +1 -0
  306. package/dist/transforms/field-selector.js +91 -0
  307. package/dist/transforms/field-selector.js.map +1 -0
  308. package/dist/transforms/task.d.ts +207 -0
  309. package/dist/transforms/task.d.ts.map +1 -0
  310. package/dist/transforms/task.js +259 -0
  311. package/dist/transforms/task.js.map +1 -0
  312. package/dist/types/errors.d.ts +55 -0
  313. package/dist/types/errors.d.ts.map +1 -0
  314. package/dist/types/errors.js +44 -0
  315. package/dist/types/errors.js.map +1 -0
  316. package/dist/types/filters.d.ts +146 -0
  317. package/dist/types/filters.d.ts.map +1 -0
  318. package/dist/types/filters.js +22 -0
  319. package/dist/types/filters.js.map +1 -0
  320. package/dist/types/index.d.ts +151 -0
  321. package/dist/types/index.d.ts.map +1 -0
  322. package/dist/types/index.js +24 -0
  323. package/dist/types/index.js.map +1 -0
  324. package/dist/types/node-vikunja-extended.d.ts +36 -0
  325. package/dist/types/node-vikunja-extended.d.ts.map +1 -0
  326. package/dist/types/node-vikunja-extended.js +25 -0
  327. package/dist/types/node-vikunja-extended.js.map +1 -0
  328. package/dist/types/responses.d.ts +118 -0
  329. package/dist/types/responses.d.ts.map +1 -0
  330. package/dist/types/responses.js +26 -0
  331. package/dist/types/responses.js.map +1 -0
  332. package/dist/types/vikunja.d.ts +315 -0
  333. package/dist/types/vikunja.d.ts.map +1 -0
  334. package/dist/types/vikunja.js +7 -0
  335. package/dist/types/vikunja.js.map +1 -0
  336. package/dist/utils/auth-error-handler.d.ts +23 -0
  337. package/dist/utils/auth-error-handler.d.ts.map +1 -0
  338. package/dist/utils/auth-error-handler.js +162 -0
  339. package/dist/utils/auth-error-handler.js.map +1 -0
  340. package/dist/utils/error-handler.d.ts +38 -0
  341. package/dist/utils/error-handler.d.ts.map +1 -0
  342. package/dist/utils/error-handler.js +288 -0
  343. package/dist/utils/error-handler.js.map +1 -0
  344. package/dist/utils/filtering/ClientSideFilteringStrategy.d.ts +13 -0
  345. package/dist/utils/filtering/ClientSideFilteringStrategy.d.ts.map +1 -0
  346. package/dist/utils/filtering/ClientSideFilteringStrategy.js +63 -0
  347. package/dist/utils/filtering/ClientSideFilteringStrategy.js.map +1 -0
  348. package/dist/utils/filtering/FilteringContext.d.ts +27 -0
  349. package/dist/utils/filtering/FilteringContext.d.ts.map +1 -0
  350. package/dist/utils/filtering/FilteringContext.js +43 -0
  351. package/dist/utils/filtering/FilteringContext.js.map +1 -0
  352. package/dist/utils/filtering/HybridFilteringStrategy.d.ts +15 -0
  353. package/dist/utils/filtering/HybridFilteringStrategy.d.ts.map +1 -0
  354. package/dist/utils/filtering/HybridFilteringStrategy.js +55 -0
  355. package/dist/utils/filtering/HybridFilteringStrategy.js.map +1 -0
  356. package/dist/utils/filtering/ServerSideFilteringStrategy.d.ts +13 -0
  357. package/dist/utils/filtering/ServerSideFilteringStrategy.d.ts.map +1 -0
  358. package/dist/utils/filtering/ServerSideFilteringStrategy.js +64 -0
  359. package/dist/utils/filtering/ServerSideFilteringStrategy.js.map +1 -0
  360. package/dist/utils/filtering/TaskFilteringStrategy.d.ts +19 -0
  361. package/dist/utils/filtering/TaskFilteringStrategy.d.ts.map +1 -0
  362. package/dist/utils/filtering/TaskFilteringStrategy.js +10 -0
  363. package/dist/utils/filtering/TaskFilteringStrategy.js.map +1 -0
  364. package/dist/utils/filtering/index.d.ts +13 -0
  365. package/dist/utils/filtering/index.d.ts.map +1 -0
  366. package/dist/utils/filtering/index.js +20 -0
  367. package/dist/utils/filtering/index.js.map +1 -0
  368. package/dist/utils/filtering/types.d.ts +62 -0
  369. package/dist/utils/filtering/types.d.ts.map +1 -0
  370. package/dist/utils/filtering/types.js +6 -0
  371. package/dist/utils/filtering/types.js.map +1 -0
  372. package/dist/utils/filters.d.ts +97 -0
  373. package/dist/utils/filters.d.ts.map +1 -0
  374. package/dist/utils/filters.js +939 -0
  375. package/dist/utils/filters.js.map +1 -0
  376. package/dist/utils/logger.d.ts +26 -0
  377. package/dist/utils/logger.d.ts.map +1 -0
  378. package/dist/utils/logger.js +83 -0
  379. package/dist/utils/logger.js.map +1 -0
  380. package/dist/utils/memory.d.ts +71 -0
  381. package/dist/utils/memory.d.ts.map +1 -0
  382. package/dist/utils/memory.js +194 -0
  383. package/dist/utils/memory.js.map +1 -0
  384. package/dist/utils/performance/batch-processor.d.ts +77 -0
  385. package/dist/utils/performance/batch-processor.d.ts.map +1 -0
  386. package/dist/utils/performance/batch-processor.js +218 -0
  387. package/dist/utils/performance/batch-processor.js.map +1 -0
  388. package/dist/utils/performance/index.d.ts +42 -0
  389. package/dist/utils/performance/index.d.ts.map +1 -0
  390. package/dist/utils/performance/index.js +49 -0
  391. package/dist/utils/performance/index.js.map +1 -0
  392. package/dist/utils/performance/performance-monitor.d.ts +116 -0
  393. package/dist/utils/performance/performance-monitor.d.ts.map +1 -0
  394. package/dist/utils/performance/performance-monitor.js +307 -0
  395. package/dist/utils/performance/performance-monitor.js.map +1 -0
  396. package/dist/utils/response-factory.d.ts +81 -0
  397. package/dist/utils/response-factory.d.ts.map +1 -0
  398. package/dist/utils/response-factory.js +86 -0
  399. package/dist/utils/response-factory.js.map +1 -0
  400. package/dist/utils/retry.d.ts +146 -0
  401. package/dist/utils/retry.d.ts.map +1 -0
  402. package/dist/utils/retry.js +281 -0
  403. package/dist/utils/retry.js.map +1 -0
  404. package/dist/utils/security.d.ts +70 -0
  405. package/dist/utils/security.d.ts.map +1 -0
  406. package/dist/utils/security.js +358 -0
  407. package/dist/utils/security.js.map +1 -0
  408. package/dist/utils/simple-response.d.ts +75 -0
  409. package/dist/utils/simple-response.d.ts.map +1 -0
  410. package/dist/utils/simple-response.js +208 -0
  411. package/dist/utils/simple-response.js.map +1 -0
  412. package/dist/utils/storage-errors.d.ts +9 -0
  413. package/dist/utils/storage-errors.d.ts.map +1 -0
  414. package/dist/utils/storage-errors.js +20 -0
  415. package/dist/utils/storage-errors.js.map +1 -0
  416. package/dist/utils/unicode-fix.d.ts +19 -0
  417. package/dist/utils/unicode-fix.d.ts.map +1 -0
  418. package/dist/utils/unicode-fix.js +70 -0
  419. package/dist/utils/unicode-fix.js.map +1 -0
  420. package/dist/utils/validation.d.ts +103 -0
  421. package/dist/utils/validation.d.ts.map +1 -0
  422. package/dist/utils/validation.js +729 -0
  423. package/dist/utils/validation.js.map +1 -0
  424. package/package.json +148 -0
package/README.md ADDED
@@ -0,0 +1,1377 @@
1
+ # Vikunja MCP Server (`@joyjit/vikunja-mcp`)
2
+
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
+
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.
6
+
7
+ ### Fork highlights (vs upstream npm `0.2.0`)
8
+
9
+ - **No HTML-encoding** of titles/descriptions before API calls (real HTML task bodies work)
10
+ - **bulk-update** preserves fields it was not asked to change
11
+ - **Task `projectId` update** actually moves the task; labels apply on create
12
+ - **Project partial update** keeps title / parent instead of wiping them
13
+ - **Node.js 24** + Dockerized MCP integration CI against Vikunja 2.3
14
+
15
+ A Model Context Protocol (MCP) server that enables AI assistants to interact with Vikunja task management instances.
16
+
17
+ ## Features
18
+
19
+ - **Subcommand-based tools** for intuitive AI interactions
20
+ - **Session-based authentication** with automatic token management
21
+ - **Full task management** operations implemented
22
+ - **Complete project management** with CRUD operations
23
+ - **Label management** for organizing tasks
24
+ - **Team operations** for collaboration (get/update/members limited by API)
25
+ - **User management** with settings and search
26
+ - **Webhook management** for project automation
27
+ - **Batch import** tasks from CSV or JSON files
28
+ - **Input validation** for dates, IDs, and hex colors
29
+ - **Efficient diff-based updates** for assignees
30
+ - **TypeScript with strict mode** for type safety
31
+ - **Comprehensive error handling** with typed errors and centralized utilities
32
+ - **Production-ready retry logic** with opossum circuit breaker for resilience
33
+ - **Enhanced security** with Zod-based input validation and DoS protection
34
+ - **Rate limiting protection** against DoS attacks with configurable limits
35
+ - **Memory protection** with pagination limits and usage monitoring
36
+ - **Simplified architecture** with 90% code reduction for maintainability
37
+
38
+ ## 🚀 Major Architectural Improvements (v0.2.0)
39
+
40
+ This release represents a **massive architectural simplification** that eliminates technical debt while enhancing security and reliability:
41
+
42
+ ### Storage Architecture Refactoring (90% Code Reduction)
43
+ - **Before**: 33 files, 9,803 lines of over-engineered storage system
44
+ - **After**: 4 files, essential functionality only
45
+ - **Eliminated**: Complex orchestrators, health monitors, statistics tracking, migration systems
46
+ - **Result**: Same external API with dramatically improved maintainability
47
+
48
+ ### Zod-Based Filter System (850+ Lines Removed)
49
+ - **Before**: Custom tokenizer, parser, and validator with security vulnerabilities
50
+ - **After**: Secure Zod schema validation with production-ready parsing
51
+ - **Enhanced**: DoS protection, input sanitization, and comprehensive error handling
52
+ - **Result**: Faster parsing, better security, and enterprise-grade reliability
53
+
54
+ ### Production-Ready Retry System (580+ Lines Replaced)
55
+ - **Before**: Custom retry logic with maintenance overhead
56
+ - **After**: Battle-tested opossum circuit breaker library
57
+ - **Features**: Circuit breaker state sharing, automatic recovery, comprehensive monitoring
58
+ - **Result**: Production resilience with battle-tested patterns
59
+
60
+ ### Zero Breaking Changes
61
+ All improvements maintain **100% backward compatibility** with existing implementations while providing enhanced reliability and security.
62
+
63
+ ## Requirements
64
+
65
+ - Node.js 24+ (Active LTS)
66
+ - Vikunja instance with API access
67
+ - API token (starting with `tk_`) or JWT token for authentication
68
+
69
+ ## Installation
70
+
71
+ ### Option 1: Install from NPM (Recommended)
72
+
73
+ ```json
74
+ {
75
+ "mcpServers": {
76
+ "vikunja": {
77
+ "command": "npx",
78
+ "args": ["-y", "@joyjit/vikunja-mcp"],
79
+ "env": {
80
+ "VIKUNJA_URL": "https://your-vikunja-instance.com/api/v1",
81
+ "VIKUNJA_API_TOKEN": "your-api-token"
82
+ }
83
+ }
84
+ }
85
+ }
86
+ ```
87
+
88
+ Requires **Node.js 24+**. Use an API token (`tk_…`) or JWT from your Vikunja instance.
89
+
90
+ Pin a version if you want: `"args": ["-y", "@joyjit/vikunja-mcp@0.3.0"]`.
91
+
92
+ ### Option 2: Install from GitHub (no npm needed)
93
+
94
+ ```json
95
+ {
96
+ "mcpServers": {
97
+ "vikunja": {
98
+ "command": "npx",
99
+ "args": ["-y", "github:joyjit/vikunja-mcp"],
100
+ "env": {
101
+ "VIKUNJA_URL": "https://your-vikunja-instance.com/api/v1",
102
+ "VIKUNJA_API_TOKEN": "your-api-token"
103
+ }
104
+ }
105
+ }
106
+ }
107
+ ```
108
+
109
+ ### Option 3: Local Development
110
+
111
+ ```bash
112
+ git clone https://github.com/joyjit/vikunja-mcp.git
113
+ cd vikunja-mcp
114
+ npm install
115
+ npm run build
116
+ ```
117
+
118
+ Then configure your MCP client:
119
+
120
+ ```json
121
+ {
122
+ "mcpServers": {
123
+ "vikunja": {
124
+ "command": "node",
125
+ "args": ["/path/to/vikunja-mcp/dist/index.js"],
126
+ "env": {
127
+ "VIKUNJA_URL": "https://your-vikunja-instance.com/api/v1",
128
+ "VIKUNJA_API_TOKEN": "your-api-token"
129
+ }
130
+ }
131
+ }
132
+ }
133
+ ```
134
+
135
+ ## Configuration
136
+
137
+ ### Logging Configuration
138
+
139
+ The server includes a structured logging system. Configure it via environment variables:
140
+
141
+ ```bash
142
+ # Enable debug logging (default: false)
143
+ DEBUG=true
144
+
145
+ # Set specific log level (error, warn, info, debug)
146
+ # If not set, defaults to 'info' (or 'debug' if DEBUG=true)
147
+ LOG_LEVEL=debug
148
+ ```
149
+
150
+ Log output includes timestamps and log levels:
151
+ ```
152
+ [2025-05-25T17:00:00.000Z] [INFO] Vikunja MCP server started
153
+ [2025-05-25T17:00:00.100Z] [DEBUG] Executing tasks tool { subcommand: 'list', args: {...} }
154
+ ```
155
+
156
+ All logs are written to stderr to keep stdout reserved for MCP protocol communication.
157
+
158
+ ## Authentication Methods
159
+
160
+ The Vikunja MCP server supports two authentication methods, each with different capabilities:
161
+
162
+ ### API Token Authentication (Default)
163
+
164
+ API tokens are the standard authentication method for Vikunja:
165
+
166
+ - **How to obtain:** Go to Vikunja Settings → API Tokens → Create new token
167
+ - **Token format:** Starts with `tk_` (e.g., `tk_abc123def456`)
168
+ - **Capabilities:** Full access to tasks, projects, labels, teams, and webhooks
169
+ - **Limitations:** Cannot access user-specific endpoints (user profile, settings, export)
170
+ - **Best for:** Automation, CI/CD, and general task management
171
+
172
+ ### JWT Authentication (Advanced)
173
+
174
+ JWT (JSON Web Token) authentication provides full access to all Vikunja endpoints:
175
+
176
+ - **How to obtain:** Extract from your browser session (see instructions below)
177
+ - **Token format:** Long string starting with `eyJ` (standard JWT format)
178
+ - **Capabilities:** Full access to all endpoints including user management and export
179
+ - **Limitations:** Tokens expire (typically after 24 hours)
180
+ - **Best for:** User management, data export, and operations requiring user context
181
+
182
+ #### How to Extract Your JWT Token
183
+
184
+ 1. **Log into Vikunja** in your web browser
185
+ 2. **Open Developer Tools** (F12 or right-click → Inspect)
186
+ 3. **Go to the Application/Storage tab**
187
+ 4. **Find the JWT token:**
188
+ - Look in Local Storage → your Vikunja domain
189
+ - Find the key named `token` or similar
190
+ - The value is your JWT token
191
+ 5. **Copy the entire token value** (it's quite long)
192
+
193
+ #### Using JWT Authentication
194
+
195
+ ```typescript
196
+ // Connect with JWT token - automatically detected!
197
+ vikunja_auth.connect({
198
+ apiUrl: "https://your-vikunja-instance.com/api/v1",
199
+ apiToken: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
200
+ })
201
+ ```
202
+
203
+ **Important Notes:**
204
+ - JWT tokens expire; you'll need to extract a new one when it expires
205
+ - Token type is automatically detected based on format (no flag needed)
206
+ - Some tools (users, export) are only available with JWT authentication
207
+
208
+ ## Quick Start
209
+
210
+ 1. **Set up authentication (if not using environment variables):**
211
+ ```typescript
212
+ vikunja_auth.connect({
213
+ apiUrl: "https://your-vikunja-instance.com/api/v1",
214
+ apiToken: "your-api-token"
215
+ })
216
+ ```
217
+
218
+ 2. **Create your first task:**
219
+ ```typescript
220
+ vikunja_tasks.create({
221
+ projectId: 1,
222
+ title: "My first task via MCP!"
223
+ })
224
+ ```
225
+
226
+ 3. **List all your tasks:**
227
+ ```typescript
228
+ vikunja_tasks.list({ allProjects: true })
229
+ ```
230
+
231
+ ## Usage
232
+
233
+ The MCP server exposes tools with subcommands. All operations require authentication first (either via environment variables or manual connection).
234
+
235
+ ### Authentication
236
+
237
+ ```typescript
238
+ // Connect with API token (automatically detected)
239
+ vikunja_auth.connect({
240
+ apiUrl: "https://your-vikunja-instance.com/api/v1",
241
+ apiToken: "tk_your-api-token"
242
+ })
243
+
244
+ // Connect with JWT token (automatically detected, enables additional tools: users, export)
245
+ vikunja_auth.connect({
246
+ apiUrl: "https://your-vikunja-instance.com/api/v1",
247
+ apiToken: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
248
+ })
249
+
250
+ // Check authentication status
251
+ vikunja_auth.status()
252
+
253
+ // Disconnect and clean up resources
254
+ vikunja_auth.disconnect()
255
+ ```
256
+
257
+ ### Task Management Examples
258
+
259
+ ```typescript
260
+ // List all tasks across all projects
261
+ vikunja_tasks.list({ allProjects: true })
262
+
263
+ // List tasks for a specific project with pagination
264
+ vikunja_tasks.list({
265
+ projectId: 1,
266
+ page: 1,
267
+ perPage: 20,
268
+ sort: "due_date"
269
+ })
270
+
271
+ // List tasks with filters (high priority, not done)
272
+ vikunja_tasks.list({
273
+ filter: "(priority >= 4 && done = false)"
274
+ })
275
+
276
+ // List tasks with simple filter
277
+ vikunja_tasks.list({
278
+ filter: "priority >= 3"
279
+ })
280
+
281
+ // List tasks with complex filter conditions
282
+ vikunja_tasks.list({
283
+ filter: "(priority >= 3 && priority <= 5) || (done = true && updated > '2024-01-01')"
284
+ })
285
+
286
+ // Combine filter with search
287
+ vikunja_tasks.list({
288
+ filter: "priority >= 4",
289
+ search: "urgent"
290
+ })
291
+
292
+ // Create a new task with labels and assignees
293
+ vikunja_tasks.create({
294
+ projectId: 1,
295
+ title: "Complete documentation",
296
+ description: "Update README with examples",
297
+ dueDate: "2024-12-31T23:59:59Z",
298
+ priority: 3,
299
+ labels: [1, 2], // Label IDs
300
+ assignees: [1, 3] // User IDs
301
+ })
302
+
303
+ // Create a recurring task (repeats every week)
304
+ vikunja_tasks.create({
305
+ projectId: 1,
306
+ title: "Weekly team meeting",
307
+ description: "Sync up with the team",
308
+ dueDate: "2024-12-01T10:00:00Z",
309
+ repeatAfter: 7, // Number of units
310
+ repeatMode: "day" // Unit: "day", "week", "month", or "year"
311
+ })
312
+
313
+ // Create a monthly recurring task
314
+ vikunja_tasks.create({
315
+ projectId: 1,
316
+ title: "Monthly report",
317
+ repeatAfter: 1,
318
+ repeatMode: "month"
319
+ })
320
+
321
+ // Get detailed information about a task
322
+ vikunja_tasks.get({ id: 123 })
323
+
324
+ // Update a task (partial updates supported)
325
+ vikunja_tasks.update({
326
+ id: 123,
327
+ done: true,
328
+ priority: 5
329
+ })
330
+
331
+ // Move a task to another project (full-model merge; verified after update)
332
+ vikunja_tasks.update({
333
+ id: 123,
334
+ projectId: 5
335
+ })
336
+
337
+ // Update recurring settings on an existing task
338
+ vikunja_tasks.update({
339
+ id: 123,
340
+ repeatAfter: 14, // Change to bi-weekly
341
+ repeatMode: "day"
342
+ })
343
+
344
+ // Update task assignees (uses efficient diff-based approach)
345
+ vikunja_tasks.update({
346
+ id: 123,
347
+ assignees: [1, 2, 4] // Only adds/removes differences
348
+ })
349
+
350
+ // Delete a task
351
+ vikunja_tasks.delete({ id: 123 })
352
+
353
+ // Bulk assign users to a task
354
+ vikunja_tasks.assign({
355
+ id: 123,
356
+ assignees: [2, 3, 4]
357
+ })
358
+
359
+ // Remove users from a task
360
+ vikunja_tasks.unassign({
361
+ id: 123,
362
+ assignees: [2, 4] // Removes only these users
363
+ })
364
+
365
+ // List all assignees for a task
366
+ vikunja_tasks.list-assignees({ id: 123 })
367
+
368
+ // Add a comment to a task
369
+ vikunja_tasks.comment({
370
+ id: 123,
371
+ comment: "This task is now complete!"
372
+ })
373
+
374
+ // List all comments on a task
375
+ vikunja_tasks.comment({ id: 123 })
376
+
377
+ // Create a task relation (e.g., subtask, blocking, related)
378
+ vikunja_tasks.relate({
379
+ id: 123,
380
+ otherTaskId: 124,
381
+ relationKind: "subtask" // 124 is a subtask of 123
382
+ })
383
+
384
+ // Available relation kinds:
385
+ // - subtask: Other task is a subtask of this task
386
+ // - parenttask: Other task is the parent of this task
387
+ // - related: Tasks are related
388
+ // - duplicateof: This task is a duplicate of the other
389
+ // - duplicates: Other task is a duplicate of this one
390
+ // - blocking: This task blocks the other
391
+ // - blocked: This task is blocked by the other
392
+ // - precedes: This task precedes the other
393
+ // - follows: This task follows the other
394
+ // - copiedfrom: This task was copied from the other
395
+ // - copiedto: Other task was copied from this one
396
+
397
+ // Remove a task relation
398
+ vikunja_tasks.unrelate({
399
+ id: 123,
400
+ otherTaskId: 124,
401
+ relationKind: "subtask"
402
+ })
403
+
404
+ // Get all relations for a task
405
+ vikunja_tasks.relations({ id: 123 })
406
+
407
+ // Add a reminder to a task
408
+ vikunja_tasks.add-reminder({
409
+ id: 123,
410
+ reminderDate: "2024-12-25T10:00:00Z"
411
+ })
412
+
413
+ // List all reminders for a task
414
+ vikunja_tasks.list-reminders({ id: 123 })
415
+
416
+ // Remove a specific reminder from a task
417
+ vikunja_tasks.remove-reminder({
418
+ id: 123,
419
+ reminderId: 1
420
+ })
421
+
422
+ // Bulk create multiple tasks at once (max 100)
423
+ vikunja_tasks.bulk-create({
424
+ projectId: 1,
425
+ tasks: [
426
+ {
427
+ title: "Task 1",
428
+ description: "First task",
429
+ priority: 3,
430
+ labels: [1, 2]
431
+ },
432
+ {
433
+ title: "Task 2",
434
+ dueDate: "2024-12-31T23:59:59Z",
435
+ assignees: [1]
436
+ },
437
+ {
438
+ title: "Weekly standup",
439
+ repeatAfter: 7,
440
+ repeatMode: "day"
441
+ }
442
+ ]
443
+ })
444
+
445
+ // Bulk update multiple tasks with the same field value
446
+ // (fetch+merge per task — safe against Vikunja full-replace field wipes)
447
+ vikunja_tasks.bulk-update({
448
+ taskIds: [123, 124, 125],
449
+ field: "done", // Field to update
450
+ value: true // New value for all tasks
451
+ })
452
+
453
+ // Other bulk update examples
454
+ vikunja_tasks.bulk-update({
455
+ taskIds: [123, 124, 125],
456
+ field: "priority",
457
+ value: 5
458
+ })
459
+
460
+ vikunja_tasks.bulk-update({
461
+ taskIds: [123, 124],
462
+ field: "project_id",
463
+ value: 2 // Move tasks to different project
464
+ })
465
+
466
+ vikunja_tasks.bulk-update({
467
+ taskIds: [123, 124, 125],
468
+ field: "labels",
469
+ value: [1, 3, 5] // Set same labels on all tasks
470
+ })
471
+
472
+ // Bulk delete multiple tasks (max 100)
473
+ vikunja_tasks.bulk-delete({
474
+ taskIds: [123, 124, 125]
475
+ })
476
+
477
+ // Batch import tasks from CSV or JSON
478
+ vikunja_batch_import({
479
+ projectId: 1,
480
+ format: "json",
481
+ data: JSON.stringify([
482
+ {
483
+ title: "Task 1",
484
+ description: "First imported task",
485
+ priority: 3,
486
+ dueDate: "2024-12-31T23:59:59Z"
487
+ },
488
+ {
489
+ title: "Task 2",
490
+ labels: ["bug", "urgent"], // Will look up label IDs by name
491
+ assignees: ["john.doe"] // Will look up user IDs by username
492
+ }
493
+ ])
494
+ })
495
+
496
+ // Import from CSV with headers
497
+ vikunja_batch_import({
498
+ projectId: 1,
499
+ format: "csv",
500
+ data: `title,description,priority,dueDate,labels,assignees
501
+ "Task 1","Description with, comma",3,2024-12-31T23:59:59Z,"bug;feature","john.doe"
502
+ "Task 2","Another task",5,,"urgent","john.doe;jane.smith"`
503
+ })
504
+
505
+ // Dry run to validate without creating tasks
506
+ vikunja_batch_import({
507
+ projectId: 1,
508
+ format: "json",
509
+ data: JSON.stringify([...]),
510
+ dryRun: true // Only validates, doesn't create tasks
511
+ })
512
+
513
+ // Continue on errors instead of stopping
514
+ vikunja_batch_import({
515
+ projectId: 1,
516
+ format: "csv",
517
+ data: csvData,
518
+ skipErrors: true // Skip invalid tasks and continue with valid ones
519
+ })
520
+ ```
521
+
522
+ ### Data Export Examples
523
+
524
+ ```typescript
525
+ // Export a project with all its data
526
+ vikunja_export_project({
527
+ projectId: 1,
528
+ includeChildren: false // Only export the specified project
529
+ })
530
+
531
+ // Export a project including all child projects
532
+ vikunja_export_project({
533
+ projectId: 1,
534
+ includeChildren: true // Recursively export child projects
535
+ })
536
+
537
+ // The export returns JSON data with the following structure:
538
+ // {
539
+ // project: { ... }, // Project details
540
+ // tasks: [ ... ], // All tasks in the project
541
+ // labels: [ ... ], // All labels used in tasks
542
+ // child_projects: [ ... ], // Nested child project exports (if includeChildren: true)
543
+ // exported_at: "...", // ISO timestamp of export
544
+ // version: "1.0.0" // Export format version
545
+ // }
546
+
547
+ // Request a full user data export (sent via email)
548
+ vikunja_request_user_export({
549
+ password: "your-password" // Required for security
550
+ })
551
+
552
+ // Download a previously requested user data export
553
+ vikunja_download_user_export({
554
+ password: "your-password" // Required for security
555
+ })
556
+ ```
557
+
558
+ ### Project Management Examples
559
+
560
+ ```typescript
561
+ // List all projects
562
+ vikunja_projects.list()
563
+
564
+ // List projects with search and pagination
565
+ vikunja_projects.list({
566
+ search: "frontend",
567
+ page: 1,
568
+ perPage: 10,
569
+ isArchived: false
570
+ })
571
+
572
+ // Get a specific project
573
+ vikunja_projects.get({ id: 1 })
574
+
575
+ // Create a new project
576
+ vikunja_projects.create({
577
+ title: "New Frontend Project",
578
+ description: "React-based web application",
579
+ hexColor: "#4287f5"
580
+ })
581
+
582
+ // Update a project
583
+ vikunja_projects.update({
584
+ id: 1,
585
+ title: "Updated Project Name",
586
+ isArchived: true
587
+ })
588
+
589
+ // Archive a project
590
+ vikunja_projects.archive({ id: 1 })
591
+
592
+ // Unarchive a project
593
+ vikunja_projects.unarchive({ id: 1 })
594
+
595
+ // Delete a project
596
+ vikunja_projects.delete({ id: 1 })
597
+
598
+ // --- Project Hierarchy Management ---
599
+
600
+ // Create a child project
601
+ vikunja_projects.create({
602
+ title: "Frontend Module",
603
+ description: "React components",
604
+ parentProjectId: 1, // Will be a child of project 1
605
+ hexColor: "#3498db"
606
+ })
607
+
608
+ // Get all direct children of a project
609
+ vikunja_projects.get-children({ id: 1 })
610
+ // Returns: Array of projects that have parentProjectId = 1
611
+
612
+ // Get complete project hierarchy as a tree
613
+ vikunja_projects.get-tree({ id: 1 })
614
+ // Returns: Project with nested children structure
615
+ // {
616
+ // id: 1,
617
+ // title: "Main Project",
618
+ // children: [
619
+ // {
620
+ // id: 2,
621
+ // title: "Frontend Module",
622
+ // children: [
623
+ // { id: 4, title: "Components", children: [] },
624
+ // { id: 5, title: "Styles", children: [] }
625
+ // ]
626
+ // },
627
+ // {
628
+ // id: 3,
629
+ // title: "Backend Module",
630
+ // children: []
631
+ // }
632
+ // ]
633
+ // }
634
+
635
+ // Get breadcrumb path from root to a project
636
+ vikunja_projects.get-breadcrumb({ id: 5 })
637
+ // Returns: Array of projects from root to target
638
+ // [
639
+ // { id: 1, title: "Main Project" },
640
+ // { id: 2, title: "Frontend Module" },
641
+ // { id: 5, title: "Styles" }
642
+ // ]
643
+ // Also includes a formatted path: "Main Project > Frontend Module > Styles"
644
+
645
+ // Move a project to a new parent
646
+ vikunja_projects.move({
647
+ id: 5, // Project to move
648
+ parentProjectId: 3 // New parent
649
+ })
650
+ // Validates against circular references and depth limits
651
+
652
+ // Move a project to root level (no parent)
653
+ vikunja_projects.move({
654
+ id: 5,
655
+ parentProjectId: undefined
656
+ })
657
+
658
+ // --- Project Sharing ---
659
+
660
+ // Create a read-only share link
661
+ vikunja_projects.create-share({
662
+ id: 1,
663
+ right: 0, // 0=Read, 1=Write, 2=Admin
664
+ label: "Public read-only access"
665
+ })
666
+
667
+ // Create a password-protected share with write access
668
+ vikunja_projects.create-share({
669
+ id: 1,
670
+ right: 1,
671
+ password: "securepassword123",
672
+ label: "Team collaboration link"
673
+ })
674
+
675
+ // Create an expiring share link
676
+ vikunja_projects.create-share({
677
+ id: 1,
678
+ right: 0,
679
+ expires: "2025-12-31T23:59:59Z",
680
+ label: "Temporary access until year end"
681
+ })
682
+
683
+ // List all shares for a project
684
+ vikunja_projects.list-shares({ id: 1 })
685
+
686
+ // Get details of a specific share
687
+ vikunja_projects.get-share({
688
+ id: 1,
689
+ shareId: 123
690
+ })
691
+
692
+ // Delete a share link
693
+ vikunja_projects.delete-share({
694
+ id: 1,
695
+ shareId: 123
696
+ })
697
+
698
+ // Authenticate to access a shared project
699
+ vikunja_projects.auth-share({
700
+ shareHash: "abc123def456"
701
+ })
702
+
703
+ // Authenticate to a password-protected share
704
+ vikunja_projects.auth-share({
705
+ shareHash: "abc123def456",
706
+ password: "securepassword123"
707
+ })
708
+ ```
709
+
710
+ ### Label Management Examples
711
+
712
+ ```typescript
713
+ // List all labels
714
+ vikunja_labels.list()
715
+
716
+ // Search for labels
717
+ vikunja_labels.list({
718
+ search: "bug",
719
+ page: 1,
720
+ perPage: 20
721
+ })
722
+
723
+ // Get a specific label
724
+ vikunja_labels.get({ id: 1 })
725
+
726
+ // Create a new label
727
+ vikunja_labels.create({
728
+ title: "Critical",
729
+ description: "Critical priority issues",
730
+ hexColor: "#ff0000"
731
+ })
732
+
733
+ // Update a label
734
+ vikunja_labels.update({
735
+ id: 1,
736
+ title: "High Priority",
737
+ hexColor: "#ff6600"
738
+ })
739
+
740
+ // Delete a label
741
+ vikunja_labels.delete({ id: 1 })
742
+
743
+ // --- Label Assignment to Tasks ---
744
+
745
+ // Apply multiple labels to a task
746
+ vikunja_tasks.apply-label({
747
+ id: 123,
748
+ labels: [1, 2, 3] // Apply labels with IDs 1, 2, and 3
749
+ })
750
+
751
+ // Apply a single label
752
+ vikunja_tasks.apply-label({
753
+ id: 123,
754
+ labels: [1] // Apply just the "research" label
755
+ })
756
+
757
+ // Remove specific labels from a task
758
+ vikunja_tasks.remove-label({
759
+ id: 123,
760
+ labels: [2, 3] // Remove labels 2 and 3, keep others
761
+ })
762
+
763
+ // List all labels on a task
764
+ vikunja_tasks.list-labels({ id: 123 })
765
+ // Returns: Task info with detailed label data including colors and descriptions
766
+ ```
767
+
768
+ ### Team Management Examples
769
+
770
+ ```typescript
771
+ // List all teams
772
+ vikunja_teams.list()
773
+
774
+ // Search for teams
775
+ vikunja_teams.list({
776
+ search: "frontend",
777
+ page: 1,
778
+ perPage: 10
779
+ })
780
+
781
+ // Create a new team
782
+ vikunja_teams.create({
783
+ name: "Frontend Team",
784
+ description: "Responsible for UI/UX development"
785
+ })
786
+
787
+ // Delete a team
788
+ vikunja_teams.delete({ id: 1 })
789
+
790
+ // Note: get, update, and members operations are not yet
791
+ // implemented in the node-vikunja library
792
+ ```
793
+
794
+ ### User Management Examples
795
+
796
+ > ⚠️ **Known Issue**: User endpoints may fail with authentication errors even when using valid tokens. This is a known Vikunja API issue. The MCP server will provide helpful error messages when this occurs. If you encounter this issue, please contact your Vikunja server administrator.
797
+
798
+ ```typescript
799
+ // Get current user information
800
+ vikunja_users.current()
801
+
802
+ // Search for users
803
+ vikunja_users.search({
804
+ search: "john"
805
+ })
806
+
807
+ // Get current user settings
808
+ vikunja_users.settings()
809
+
810
+ // Update user settings
811
+ vikunja_users.update-settings({
812
+ name: "John Doe",
813
+ language: "en",
814
+ timezone: "America/New_York",
815
+ weekStart: 1 // Monday
816
+ })
817
+
818
+ // Update notification preferences
819
+ vikunja_users.update-settings({
820
+ emailRemindersEnabled: true, // Enable email reminders for tasks
821
+ overdueTasksRemindersEnabled: true, // Enable daily overdue task emails
822
+ overdueTasksRemindersTime: "09:00" // Time to send overdue task summary
823
+ })
824
+ ```
825
+
826
+ ### Webhook Management Examples
827
+
828
+ ```typescript
829
+ // List all available webhook events
830
+ vikunja_webhooks.list-events()
831
+ // Returns: ["task.created", "task.updated", "task.deleted", "task.assigned", ...]
832
+
833
+ // List webhooks for a project
834
+ vikunja_webhooks.list({ projectId: 1 })
835
+
836
+ // Create a webhook for task events
837
+ vikunja_webhooks.create({
838
+ projectId: 1,
839
+ targetUrl: "https://example.com/webhook",
840
+ events: ["task.created", "task.updated"],
841
+ secret: "my-secret-key" // Optional, for HMAC signing
842
+ })
843
+
844
+ // Create a webhook without secret
845
+ vikunja_webhooks.create({
846
+ projectId: 1,
847
+ targetUrl: "https://example.com/notifications",
848
+ events: ["task.assigned", "task.comment.created"]
849
+ })
850
+
851
+ // Get a specific webhook
852
+ vikunja_webhooks.get({
853
+ projectId: 1,
854
+ webhookId: 123
855
+ })
856
+
857
+ // Update webhook events
858
+ vikunja_webhooks.update({
859
+ projectId: 1,
860
+ webhookId: 123,
861
+ events: ["task.created", "task.updated", "task.deleted"]
862
+ })
863
+
864
+ // Delete a webhook
865
+ vikunja_webhooks.delete({
866
+ projectId: 1,
867
+ webhookId: 123
868
+ })
869
+ ```
870
+
871
+ ### Advanced Filtering Examples
872
+
873
+ ```typescript
874
+ // Create a saved filter for high priority tasks
875
+ vikunja_filters.create({
876
+ name: "High Priority Tasks",
877
+ description: "All undone tasks with priority 4 or 5",
878
+ filter: "done = false && priority >= 4",
879
+ isGlobal: true
880
+ })
881
+
882
+ // Alternative format using title and filters object
883
+ vikunja_filters.create({
884
+ title: "🔥 High Priority Tasks",
885
+ description: "All tasks with priority 4 or 5 that are not completed",
886
+ filters: {
887
+ filter_by: ["priority"],
888
+ filter_value: ["5"],
889
+ filter_comparator: [">="],
890
+ filter_concat: ""
891
+ },
892
+ is_favorite: true
893
+ })
894
+
895
+ // Create a filter with multiple conditions
896
+ vikunja_filters.create({
897
+ title: "Urgent & Incomplete",
898
+ filters: {
899
+ filter_by: ["priority", "done"],
900
+ filter_value: ["3", "false"],
901
+ filter_comparator: [">=", "="],
902
+ filter_concat: "&&"
903
+ }
904
+ })
905
+
906
+ // Create a project-specific filter
907
+ vikunja_filters.create({
908
+ name: "This Week's Tasks",
909
+ filter: "dueDate >= now && dueDate < now+7d",
910
+ projectId: 1,
911
+ isGlobal: false
912
+ })
913
+
914
+ // List all saved filters
915
+ vikunja_filters.list()
916
+
917
+ // List filters for a specific project
918
+ vikunja_filters.list({ projectId: 1 })
919
+
920
+ // Apply a saved filter to task listing
921
+ vikunja_tasks.list({
922
+ filterId: "550e8400-e29b-41d4-a716-446655440000"
923
+ })
924
+
925
+ // Build a filter programmatically
926
+ vikunja_filters.build({
927
+ conditions: [
928
+ { field: "done", operator: "=", value: false },
929
+ { field: "priority", operator: ">=", value: 3 },
930
+ { field: "assignees", operator: "in", value: ["user1", "user2"] }
931
+ ],
932
+ groupOperator: "&&"
933
+ })
934
+ // Returns: { filter: "(done = false && priority >= 3 && assignees in user1, user2)", valid: true }
935
+
936
+ // Update an existing filter
937
+ vikunja_filters.update({
938
+ id: "550e8400-e29b-41d4-a716-446655440000",
939
+ name: "Critical Tasks",
940
+ filter: "done = false && priority = 5"
941
+ })
942
+
943
+ // Validate a filter string
944
+ vikunja_filters.validate({
945
+ filter: "done = false && priority >= 3"
946
+ })
947
+ // Returns: { valid: true, errors: [] }
948
+ ```
949
+
950
+ #### Filter Syntax Reference
951
+
952
+ The Vikunja filter syntax supports SQL-like queries with the following:
953
+
954
+ **Fields:**
955
+ - `done` - Task completion status (boolean)
956
+ - `priority` - Task priority (1-5)
957
+ - `percentDone` - Completion percentage (0-100)
958
+ - `dueDate` - Task due date
959
+ - `assignees` - Task assignees
960
+ - `labels` - Associated labels
961
+ - `created` - Task creation time
962
+ - `updated` - Task update time
963
+
964
+ **Operators:**
965
+ - Comparison: `=`, `!=`, `>`, `>=`, `<`, `<=`
966
+ - Pattern matching: `like` (uses `%` wildcard)
967
+ - List matching: `in`, `not in`
968
+
969
+ **Date Math:**
970
+ - `now` - Current time
971
+ - `now+24h` - 24 hours from now
972
+ - `now-7d` - 7 days ago
973
+ - `now/d` - Start of current day
974
+ - Supports: s (seconds), m (minutes), h (hours), d (days), w (weeks), M (months), y (years)
975
+
976
+ **Examples:**
977
+ - `priority = 4`
978
+ - `dueDate < now`
979
+ - `done = false && priority >= 3`
980
+ - `assignees in user1, user2`
981
+ - `dueDate >= now && dueDate < now+7d`
982
+ - `title like "%urgent%"`
983
+
984
+ **Smart Hybrid Filtering:** This MCP server implements an intelligent hybrid filtering approach that combines server-side and client-side filtering for optimal performance and reliability:
985
+ - **Primary**: Attempts server-side filtering first for maximum performance
986
+ - **Fallback**: Falls back to client-side filtering if server-side filtering fails or is unavailable
987
+ - **Transparent**: Same filter syntax works regardless of which method is used
988
+ - **Optimized**: Includes memory protection with pagination limits to prevent unbounded loading
989
+ - **Metadata**: Response includes filtering method used (`serverSideFiltering` or `clientSideFiltering`)
990
+ - **Performance**: Server-side filtering significantly reduces network traffic and processing time
991
+
992
+ ## Response Format
993
+
994
+ All operations in the Vikunja MCP server follow a standardized response format for consistency and predictability:
995
+
996
+ ```typescript
997
+ interface StandardResponse {
998
+ success: boolean;
999
+ operation: string; // The operation performed (e.g., 'create', 'update', 'list')
1000
+ message?: string; // Human-readable description of the result
1001
+ data?: any; // The primary data returned (task, project, label, etc.)
1002
+ metadata?: {
1003
+ timestamp: string; // ISO 8601 timestamp of the operation
1004
+ [key: string]: any; // Additional operation-specific metadata
1005
+ };
1006
+ }
1007
+ ```
1008
+
1009
+ ### Response Examples
1010
+
1011
+ **Success:**
1012
+ ```json
1013
+ {
1014
+ "success": true,
1015
+ "operation": "create",
1016
+ "message": "Task created successfully",
1017
+ "data": { "id": 123, "title": "Complete documentation" },
1018
+ "metadata": { "timestamp": "2025-05-25T12:00:00Z" }
1019
+ }
1020
+ ```
1021
+
1022
+ **Error:**
1023
+ ```json
1024
+ {
1025
+ "success": false,
1026
+ "operation": "update",
1027
+ "message": "Task not found",
1028
+ "error": { "code": "TASK_NOT_FOUND", "details": "No task exists with ID 999" }
1029
+ }
1030
+ ```
1031
+
1032
+ This standardized format ensures:
1033
+ - **Consistency**: All tools return responses in the same structure
1034
+ - **Predictability**: Clients always know what fields to expect
1035
+ - **Debugging**: Metadata provides context for troubleshooting
1036
+ - **Error Handling**: Clear error information with codes and messages
1037
+
1038
+ ## Available Tools
1039
+
1040
+ ### Authentication
1041
+ - `vikunja_auth` - Authentication management
1042
+ - `connect` - Initialize connection with API token
1043
+ - `status` - Check authentication status
1044
+ - `refresh` - Refresh authentication token
1045
+
1046
+ ### Task Management ✅
1047
+ - `vikunja_tasks` - Task operations (fully implemented)
1048
+ - `list` - List tasks with filters
1049
+ - Filter by project or get all tasks
1050
+ - Support for pagination, search, sorting
1051
+ - Filter by completion status
1052
+ - Apply saved filters with `filterId` parameter
1053
+ - `create` - Create a new task
1054
+ - Required: title, projectId
1055
+ - Optional: description, dueDate, priority, labels, assignees
1056
+ - Validates date format (ISO 8601) and IDs
1057
+ - `get` - Get task details by ID
1058
+ - `update` - Update existing task
1059
+ - Supports partial updates (GET + merge before POST — Vikunja replaces the full model)
1060
+ - Can update title, description, dueDate, priority, done status
1061
+ - Can move tasks between projects with `projectId` (verified after update)
1062
+ - Can update labels and assignees (uses efficient diff-based approach)
1063
+ - `delete` - Delete a task by ID
1064
+ - `assign` - Bulk assign users to tasks
1065
+ - `unassign` - Remove users from tasks
1066
+ - `comment` - List or add comments to tasks
1067
+ - `bulk-update` - Update multiple tasks at once
1068
+ - Required: taskIds array, field name, value
1069
+ - Supported fields: done, priority, due_date, project_id, assignees, labels
1070
+ - Validates field types and values
1071
+ - Uses per-task fetch+merge+update (does not call Vikunja's native bulk API, which can wipe omitted fields — see #46)
1072
+ - ⚠️ Performance: O(n) get+update calls (n = number of tasks)
1073
+ - `bulk-delete` - Delete multiple tasks at once
1074
+ - Required: taskIds array
1075
+ - Returns deleted task details for confirmation
1076
+ - Handles partial failures gracefully
1077
+ - ⚠️ Performance: Makes individual delete calls for each task
1078
+ - Recommended: Process in batches of 20 or fewer tasks
1079
+ - `attach` - Not implemented (file handling not available in MCP)
1080
+
1081
+ ### Batch Import ✅
1082
+ - `vikunja_batch_import` - Import multiple tasks from CSV or JSON (fully implemented)
1083
+ - Required: projectId, format ('csv' or 'json'), data
1084
+ - Optional: skipErrors (continue on errors), dryRun (validate only)
1085
+ - **Batch Size Limit**: Maximum 100 tasks per import
1086
+ - **CSV Format**:
1087
+ - Requires header row with field names
1088
+ - Supports quoted values and escaped quotes
1089
+ - Fields: title, description, priority, dueDate, labels, assignees
1090
+ - Labels and assignees as semicolon-separated values (semicolons used to avoid conflicts with CSV commas)
1091
+ - **JSON Format**:
1092
+ - Array of task objects
1093
+ - Same fields as CSV, plus direct support for arrays
1094
+ - **Features**:
1095
+ - Automatic label lookup by name
1096
+ - Automatic user lookup by username
1097
+ - Validation before creation
1098
+ - Detailed error reporting
1099
+ - Dry run mode for testing
1100
+ - Skip errors option for partial imports
1101
+
1102
+ ### Project Management ✅
1103
+ - `vikunja_projects` - Project operations (fully implemented)
1104
+ - `list` - List all projects with filters
1105
+ - Support for pagination and search
1106
+ - Filter by archived status
1107
+ - `get` - Get project details by ID
1108
+ - `create` - Create new project
1109
+ - Required: title
1110
+ - Optional: description, parentProjectId, isArchived, hexColor (format: #RRGGBB)
1111
+ - Validates parent project hierarchy depth (max 10 levels)
1112
+ - `update` - Update existing project
1113
+ - Supports partial updates (fetches current project and merges; omitted fields are preserved)
1114
+ - Can update all project fields including hexColor (format: #RRGGBB)
1115
+ - Omitting `parentProjectId` leaves the current parent unchanged (use `move` to reparent or detach)
1116
+ - Validates parent project hierarchy depth when changing parent
1117
+ - `delete` - Delete a project by ID
1118
+ - `archive` - Archive a project
1119
+ - `unarchive` - Unarchive a project
1120
+ - **Hierarchy Management** (New!)
1121
+ - `get-children` - List direct children of a project
1122
+ - `get-tree` - Get complete project hierarchy as a tree
1123
+ - `get-breadcrumb` - Get path from root to a project
1124
+ - `move` - Move a project to a new parent
1125
+ - Validates against circular references
1126
+ - Enforces maximum depth of 10 levels
1127
+ - **Project Sharing**
1128
+ - `create-share` - Create share link with permissions
1129
+ - `list-shares` - List all shares for a project
1130
+ - `get-share` - Get share details
1131
+ - `delete-share` - Remove a share link
1132
+ - `auth-share` - Authenticate to access a shared project
1133
+
1134
+ ### Label Management ✅
1135
+ - `vikunja_labels` - Label operations (fully implemented)
1136
+ - `list` - List all labels with filters
1137
+ - Support for pagination and search
1138
+ - `get` - Get label details by ID
1139
+ - `create` - Create new label
1140
+ - Required: title
1141
+ - Optional: description, hexColor (format: #RRGGBB)
1142
+ - `update` - Update existing label
1143
+ - Supports partial updates
1144
+ - Can update title, description, hexColor
1145
+ - `delete` - Delete a label by ID
1146
+ - `apply-label` - Apply one or more labels to a task
1147
+ - Required: task id, labels array
1148
+ - Supports bulk label application
1149
+ - `remove-label` - Remove one or more labels from a task
1150
+ - Required: task id, labels array
1151
+ - Supports bulk label removal
1152
+ - `list-labels` - List all labels assigned to a task
1153
+ - Required: task id
1154
+ - Returns detailed label information
1155
+
1156
+ ### Project Templates ✅
1157
+ - `vikunja_templates` - Template operations (fully implemented)
1158
+ - `create` - Create a template from existing project
1159
+ - Required: projectId, name
1160
+ - Optional: description, tags
1161
+ - Captures all project settings and tasks
1162
+ - `list` - List all available templates
1163
+ - Shows template name, tags, and author
1164
+ - `get` - Get template details by ID
1165
+ - `update` - Update template metadata
1166
+ - Can update name, description, tags
1167
+ - `delete` - Delete a template
1168
+ - `instantiate` - Create new project from template
1169
+ - Required: id (template ID), projectName
1170
+ - Optional: parentProjectId, variables
1171
+ - Supports variable substitution:
1172
+ - `{{PROJECT_NAME}}` - The new project name
1173
+ - `{{TODAY}}` - Current date (YYYY-MM-DD)
1174
+ - `{{NOW}}` - Current timestamp
1175
+ - Custom variables via the variables parameter
1176
+ - Creates all tasks with labels from template
1177
+
1178
+ ### Team Management ✅
1179
+ - `vikunja_teams` - Team operations (partially implemented)
1180
+ - `list` - List all teams with filters
1181
+ - Support for pagination and search
1182
+ - `create` - Create new team
1183
+ - Required: name
1184
+ - Optional: description
1185
+ - `delete` - Delete a team by ID (with fallback API support)
1186
+ - `get` - Not yet implemented in node-vikunja
1187
+ - `update` - Not yet implemented in node-vikunja
1188
+ - `members` - Not yet implemented in node-vikunja
1189
+
1190
+ ### User Management ✅
1191
+ - `vikunja_users` - User operations (fully implemented) **[Requires JWT authentication]**
1192
+ - `current` - Get current authenticated user info
1193
+ - `search` - Search for users
1194
+ - Optional: search query, pagination
1195
+ - `settings` - Get current user settings
1196
+ - `update-settings` - Update user settings
1197
+ - Optional: name, language, timezone, weekStart, frontendSettings
1198
+ - **Note:** User operations require JWT authentication. When using API token authentication, these tools will not be available.
1199
+
1200
+ ### Webhook Management ✅
1201
+ - `vikunja_webhooks` - Webhook operations for project automation (fully implemented)
1202
+ - `list-events` - Get all available webhook event types
1203
+ - `list` - List webhooks for a project
1204
+ - Required: projectId
1205
+ - `get` - Get a specific webhook
1206
+ - Required: projectId, webhookId
1207
+ - `create` - Create a new webhook
1208
+ - Required: projectId, targetUrl, events (array)
1209
+ - Optional: secret (for HMAC signing)
1210
+ - **Note**: Events are validated against available event types
1211
+ - `update` - Update webhook events
1212
+ - Required: projectId, webhookId, events (array)
1213
+ - **Note**: Events are validated against available event types
1214
+ - `delete` - Delete a webhook
1215
+ - Required: projectId, webhookId
1216
+
1217
+ **Event Validation**: When creating or updating webhooks, the provided events are automatically validated against the list of available events from the API. Invalid events will result in a clear error message showing which events are invalid and listing all valid options. Valid events are cached for 5 minutes to improve performance.
1218
+
1219
+ ### Filter Management ✅
1220
+ - `vikunja_filters` - Advanced filtering for tasks (fully implemented)
1221
+ - `list` - List saved filters
1222
+ - Optional: projectId (for project-specific filters), global flag
1223
+ - `get` - Get a specific filter by ID
1224
+ - `create` - Create a new saved filter
1225
+ - Required: name, filter (query string)
1226
+ - Optional: description, projectId, isGlobal
1227
+ - `update` - Update an existing filter
1228
+ - Required: id
1229
+ - Optional: name, description, filter, projectId, isGlobal
1230
+ - `delete` - Delete a saved filter
1231
+ - `build` - Build a filter string from conditions
1232
+ - Required: conditions array
1233
+ - Optional: groupOperator (&&, ||)
1234
+ - `validate` - Validate a filter string
1235
+
1236
+ **Note:** Saved filters are currently stored in memory and will be lost when the MCP server restarts. For production use, consider implementing persistent storage.
1237
+
1238
+ ### Data Export ✅
1239
+
1240
+ > **⚠️ WARNING: Memory Usage**
1241
+ > Export operations load entire project hierarchies into memory. For very large projects with thousands of tasks or deeply nested structures, this may consume significant memory. Consider exporting smaller projects individually.
1242
+ - `vikunja_export_project` - Export project data **[Requires JWT authentication]**
1243
+ - **Parameters:**
1244
+ - `projectId` (required) - ID of the project to export
1245
+ - `includeChildren` (optional) - Include child projects recursively (default: false)
1246
+ - **Returns:** Complete project data including tasks, labels, and metadata
1247
+ - **Features:**
1248
+ - Exports all tasks with full details
1249
+ - Includes all labels used in the project
1250
+ - Optionally includes complete child project hierarchy
1251
+ - Circular reference detection for nested projects
1252
+ - Export metadata includes timestamp and version
1253
+ - **Note:** Export operations require JWT authentication. When using API token authentication, this tool will not be available.
1254
+
1255
+ - `vikunja_request_user_export` - Request full user data export
1256
+ - **Parameters:**
1257
+ - `password` (required) - User password for security verification
1258
+ - **Returns:** Confirmation that export has been requested
1259
+ - **Note:** You will receive an email when the export is ready
1260
+
1261
+ - `vikunja_download_user_export` - Download previously requested user data export
1262
+ - **Parameters:**
1263
+ - `password` (required) - User password for security verification
1264
+ - **Returns:** Complete user data export
1265
+ - **Note:** Export must be requested first via `vikunja_request_user_export`
1266
+
1267
+
1268
+
1269
+
1270
+ ## Known Limitations
1271
+
1272
+ 1. **File Attachments**: The `attach` subcommand is not implemented due to MCP protocol limitations
1273
+ 2. **Team Operations**: Limited functionality due to incomplete node-vikunja API support:
1274
+ - Cannot get team by ID
1275
+ - Cannot update team information
1276
+ - Cannot delete teams
1277
+ - Cannot manage team members
1278
+ 3. **Pagination**: Some endpoints may not fully support pagination parameters due to API limitations
1279
+ 4. **Authentication Issues**: Some Vikunja API endpoints have known authentication issues:
1280
+ - **User endpoints**: May fail with token errors even with valid tokens (known Vikunja API limitation)
1281
+ - **Bulk operations**: May have authentication issues with certain Vikunja API versions
1282
+ - **Label operations**: May fail with authentication errors on some server configurations
1283
+ - **Assignee operations**: May fail with authentication errors when creating/updating tasks with assignees
1284
+ - The server provides detailed error messages when these issues occur, suggesting workarounds
1285
+
1286
+ ## Security & Performance Features
1287
+
1288
+ ### Security Enhancements
1289
+ - **Zod Schema Validation**: Enterprise-grade input validation with comprehensive type checking
1290
+ - **DoS Protection**: Input sanitization, length limits, and character allowlisting
1291
+ - **Credential Protection**: Automatic masking of sensitive tokens and URLs in logs and error messages
1292
+ - **Entity Resolution Service**: Robust label and user mapping with defensive error handling for malformed API responses
1293
+ - **Rate Limiting**: Configurable request rate limits and payload size restrictions to prevent DoS attacks
1294
+ - **Memory Protection**: Pagination limits and memory usage monitoring to prevent resource exhaustion
1295
+ - **Error Handling**: Structured error responses that avoid exposing sensitive system information
1296
+
1297
+ ### Performance Optimizations
1298
+ - **Hybrid Filtering**: Smart server-side filtering with client-side fallback for optimal performance
1299
+ - **Connection Pooling**: Efficient session management with automatic client caching
1300
+ - **Request Batching**: Optimized bulk operations with efficient diff-based updates
1301
+ - **Memory Management**: Automatic cleanup and pagination to handle large datasets safely
1302
+ - **Thread-Safe Client Management**: Async-only ClientContext API eliminates race conditions in concurrent scenarios
1303
+ - **Opossum Circuit Breaker**: Production-ready retry logic with automatic failure detection and recovery
1304
+ - **Simplified Storage**: In-memory filter storage with 90% reduced complexity and overhead
1305
+
1306
+ ## Configuration
1307
+
1308
+ ### Environment Variables
1309
+
1310
+ The server supports various configuration options through environment variables:
1311
+
1312
+ #### Basic Configuration
1313
+ ```bash
1314
+ # Vikunja instance URL (required)
1315
+ VIKUNJA_URL=https://your-vikunja-instance.com/api/v1
1316
+
1317
+ # Authentication token (required)
1318
+ VIKUNJA_API_TOKEN=your-api-token
1319
+
1320
+ # Enable debug logging (default: false)
1321
+ DEBUG=true
1322
+
1323
+ # Set log level (error, warn, info, debug)
1324
+ LOG_LEVEL=debug
1325
+ ```
1326
+
1327
+ #### Security & Performance Configuration
1328
+ ```bash
1329
+ # Rate limiting (default: enabled)
1330
+ RATE_LIMIT_ENABLED=true
1331
+ RATE_LIMIT_PER_MINUTE=60 # Requests per minute (default: 60)
1332
+ RATE_LIMIT_PER_HOUR=1000 # Requests per hour (default: 1000)
1333
+
1334
+ # Request size limits (default: 1MB)
1335
+ MAX_REQUEST_SIZE=1048576 # Maximum request payload size in bytes
1336
+ MAX_RESPONSE_SIZE=10485760 # Maximum response size in bytes (default: 10MB)
1337
+
1338
+ # Execution timeout (default: 30 seconds)
1339
+ EXECUTION_TIMEOUT=30000 # Tool execution timeout in milliseconds
1340
+
1341
+ # Memory protection (default: enabled)
1342
+ MEMORY_PROTECTION_ENABLED=true
1343
+ MAX_TASKS_PER_REQUEST=1000 # Maximum tasks to load per request
1344
+
1345
+ # Circuit breaker configuration (opossum)
1346
+ CIRCUIT_BREAKER_ENABLED=true # Enable circuit breaker for API calls
1347
+ CIRCUIT_BREAKER_TIMEOUT=60000 # Circuit breaker timeout in milliseconds (default: 60s)
1348
+ CIRCUIT_BREAKER_ERRORS_THROTTLE=10 # Errors before opening circuit (default: 10)
1349
+ CIRCUIT_BREAKER_RESET_TIMEOUT=30000 # Time to wait before trying half-open state (default: 30s)
1350
+
1351
+ # Filter security (Zod validation)
1352
+ FILTER_MAX_LENGTH=1000 # Maximum filter string length (default: 1000)
1353
+ FILTER_MAX_VALUE_LENGTH=200 # Maximum individual value length (default: 200)
1354
+ ```
1355
+
1356
+ For detailed rate limiting configuration, see [`docs/RATE_LIMITING.md`](docs/RATE_LIMITING.md).
1357
+
1358
+ ## Roadmap
1359
+
1360
+ - [x] ✅ **Security hardening** - Comprehensive vulnerability fixes implemented
1361
+ - [x] ✅ **Performance optimization** - Hybrid filtering and memory protection
1362
+ - [x] ✅ **Error handling** - Centralized error utilities and structured responses
1363
+ - [x] ✅ **Test coverage** - 98.91% function coverage achieved
1364
+ - [x] ✅ **Architecture simplification** - 90% code reduction with enhanced maintainability
1365
+ - [x] ✅ **Production-ready resilience** - Opossum circuit breaker and Zod validation
1366
+ - [ ] Add webhook subscriptions for real-time updates
1367
+ - [ ] Add caching for frequently accessed data
1368
+ - [ ] Add integration tests with real Vikunja instance
1369
+ - [ ] Implement persistent storage for saved filters (optional - in-memory works well)
1370
+
1371
+ ## Contributing
1372
+
1373
+ Please see [CONTRIBUTING.md](CONTRIBUTING.md) for development guidelines and workflow.
1374
+
1375
+ ## License
1376
+
1377
+ MIT