@fswap/mcp-vikunja 0.1.8 → 0.1.9

package/README.md

@@ -100,8 +100,8 @@ VIKUNJA_API_TOKEN = "tk_..."
 | `get_current_user` | `GET /user` | your own user id, e.g. to assign yourself |
 | `find_users` | `GET /projects/{id}/projectusers` or `GET /users` | user ids for `assigneeIds` |
 | `list_task_comments` | `GET /tasks/{id}/comments` | author, HTML body, reactions |
-| `add_task_comment` | `PUT /tasks/{id}/comments` | plain text is wrapped in `<p>` |
-| `update_task_comment` | `POST /tasks/{id}/comments/{commentId}` | |
+| `add_task_comment` | `PUT /tasks/{id}/comments` | plain text is wrapped in `<p>`; `filePaths` uploads files and shows them in the comment |
+| `update_task_comment` | `POST /tasks/{id}/comments/{commentId}` | `filePaths` without `comment` adds files to the existing text |
 | `set_reaction` | `PUT /{tasks\|comments}/{id}/reactions` | `remove=true` removes your reaction |
 | `add_task_relation` | `PUT /tasks/{id}/relations` | subtask, parenttask, blocking, related, … |
 | `remove_task_relation` | `DELETE /tasks/{id}/relations/{kind}/{otherId}` | |
@@ -114,7 +114,9 @@ VIKUNJA_API_TOKEN = "tk_..."
 | `delete_task_comment` | `DELETE /tasks/{id}/comments/{commentId}` | delete-gated like `delete_task` |
 | `delete_task_attachment` | `DELETE /tasks/{id}/attachments/{attachmentId}` | delete-gated like `delete_task` |
 
-`create_task` and `update_task` cover the rest of the task menu: due/start/end dates, priority, progress (`percentDone`), colour (`hexColor`), favorite (`isFavorite`), repeating interval (`repeatAfterSeconds`, `repeatMode`), reminders (absolute or relative to a date), labels (`labelIds`), assignees (`assigneeIds`) and moving to another project (`projectId`). `labelIds`, `assigneeIds` and `reminders` replace the current values. `get_task` returns all of these plus related tasks, attachments, kanban buckets, subscription and comments.
+`create_task` and `update_task` cover the rest of the task menu: due/start/end dates, priority, progress (`percentDone`), colour (`hexColor`), favorite (`isFavorite`), repeating interval (`repeatAfterSeconds`, `repeatMode`), reminders (absolute or relative to a date), labels (`labelIds`), assignees (`assigneeIds`) and moving to another project (`projectId`). `labelIds`, `assigneeIds` and `reminders` replace the current values. `descriptionFilePaths` uploads local files and shows them at the end of the description. `get_task` returns all of these plus related tasks, attachments, kanban buckets, subscription and comments.
+
+Vikunja has no comment-level attachments. Files shown in a comment or description are task attachments, exactly as when pasting into the web editor: images are embedded as `<img data-src>`, other files are referenced by name.
 
 Every task and project includes a `url` to its page in the Vikunja web UI (taken from `/info` `frontend_url`). Vikunja's zero date (`0001-01-01T00:00:00Z`) is normalised to `null` in every response. API errors are returned to the model as `isError` results rather than crashing the server.
 

package/dist/index.js

@@ -229,8 +229,10 @@ async function frontendUrl(vikunja) {
 */
 function toHtml(text) {
 	if (/<\/?[a-z][\s\S]*>/i.test(text)) return text;
-	const escape = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
-	return text.split(/\n{2,}/).map((para) => `<p>${escape(para).replace(/\n/g, "<br>")}</p>`).join("");
+	return text.split(/\n{2,}/).map((para) => `<p>${escapeHtml(para).replace(/\n/g, "<br>")}</p>`).join("");
+}
+function escapeHtml(s) {
+	return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
 }
 /** Reaction map `{ "👍": [users] }` → `{ "👍": ["alice"] }`, or null when empty. */
 function summarizeReactions(map) {
@@ -305,6 +307,46 @@ function summarizeAttachment(a) {
 		createdBy: summarizeUser(a.created_by)
 	};
 }
+const filePathsField = z.array(z.string().min(1)).min(1).describe("Absolute paths of local files to upload");
+/** Upload local files as task attachments. Throws only when every file failed. */
+async function uploadAttachments(vikunja, taskId, filePaths) {
+	const form = new FormData();
+	for (const p of filePaths) {
+		const abs = path.resolve(p);
+		form.append("files", await fs.openAsBlob(abs), path.basename(abs));
+	}
+	const res = await vikunja.upload(`/tasks/${taskId}/attachments`, form);
+	const uploaded = res?.success ?? [];
+	const errors = (res?.errors ?? []).map((e) => e.message ?? JSON.stringify(e));
+	if (errors.length > 0 && uploaded.length === 0) throw new Error(`Upload failed: ${errors.join("; ")}`);
+	return {
+		uploaded,
+		errors
+	};
+}
+const IMAGE_EXTENSIONS = /\.(png|jpe?g|gif|webp|bmp|avif)$/i;
+/**
+* Show attachments inside a description or comment the way the web editor does:
+* images as `<img data-src>` (the UI fetches them with the viewer's token), other files by name.
+* Vikunja has no comment-level attachments, so these are always task attachments.
+*/
+function attachmentHtml(vikunja, taskId, attachments) {
+	if (attachments.length === 0) return "";
+	return attachments.map((a) => {
+		const name = a.file?.name || `attachment-${a.id}`;
+		if (a.file?.mime?.startsWith("image/") || IMAGE_EXTENSIONS.test(name)) return `<img data-src="${vikunja.baseUrl}/api/v1/tasks/${taskId}/attachments/${a.id}" src="#" id="tiptap-image-${taskId}-${a.id}">`;
+		return `<p>📎 ${escapeHtml(name)} (attachment #${a.id})</p>`;
+	}).join("") + "<p></p>";
+}
+/** Add what was uploaded (and any per-file failures) to a tool result. */
+function withUploadInfo(result, files) {
+	if (!files) return result;
+	return {
+		...result,
+		uploaded: files.uploaded.map(summarizeAttachment),
+		...files.errors.length > 0 ? { uploadErrors: files.errors } : {}
+	};
+}
 const INLINE_IMAGE_TYPES = /* @__PURE__ */ new Set([
 	"image/png",
 	"image/jpeg",
@@ -337,23 +379,15 @@ function registerAttachmentTools(server, vikunja, { allowDelete = false } = {})
 	}));
 	server.registerTool("upload_task_attachment", {
 		title: "Upload task attachment",
-		description: "Attach one or more local files to a task.",
+		description: "Attach one or more local files to a task. To also show them in a comment or the description, use filePaths on add_task_comment / update_task_comment or descriptionFilePaths on create_task / update_task instead.",
 		inputSchema: {
 			taskId: z.number().int().describe("Task id"),
-			filePaths: z.array(z.string().min(1)).min(1).describe("Absolute paths of local files to upload")
+			filePaths: filePathsField
 		}
 	}, guard(async ({ taskId, filePaths }) => {
-		const form = new FormData();
-		for (const p of filePaths) {
-			const abs = path.resolve(p);
-			form.append("files", await fs.openAsBlob(abs), path.basename(abs));
-		}
-		const res = await vikunja.upload(`/tasks/${taskId}/attachments`, form);
-		const uploaded = (res?.success ?? []).map(summarizeAttachment);
-		const errors = (res?.errors ?? []).map((e) => e.message ?? JSON.stringify(e));
-		if (errors.length > 0 && uploaded.length === 0) throw new Error(`Upload failed: ${errors.join("; ")}`);
+		const { uploaded, errors } = await uploadAttachments(vikunja, taskId, filePaths);
 		return ok({
-			uploaded,
+			uploaded: uploaded.map(summarizeAttachment),
 			errors
 		});
 	}));
@@ -419,6 +453,7 @@ function summarizeComment(c) {
 	};
 }
 const commentText = z.string().min(1).describe("Comment body. HTML is sent as-is; plain text is wrapped in <p> (blank line = new paragraph)");
+const commentFiles = filePathsField.describe("Absolute paths of local files to upload as task attachments and show in the comment: images inline, other files by name");
 function registerCommentTools(server, vikunja, { allowDelete = false } = {}) {
 	server.registerTool("list_task_comments", {
 		title: "List task comments",
@@ -432,24 +467,33 @@ function registerCommentTools(server, vikunja, { allowDelete = false } = {}) {
 	}));
 	server.registerTool("add_task_comment", {
 		title: "Add task comment",
-		description: "Post a comment on a task as the current user. Visible to everyone with access to the task.",
+		description: "Post a comment on a task as the current user, optionally with files shown in it. Visible to everyone with access to the task.",
 		inputSchema: {
 			taskId: z.number().int().describe("Task id"),
-			comment: commentText
+			comment: commentText.optional(),
+			filePaths: commentFiles.optional()
 		}
-	}, guard(async ({ taskId, comment }) => {
-		return ok(summarizeComment(await vikunja.put(`/tasks/${taskId}/comments`, { comment: toHtml(comment) })));
+	}, guard(async ({ taskId, comment, filePaths }) => {
+		if (!comment && !filePaths) throw new Error("Pass comment, filePaths, or both.");
+		const files = filePaths ? await uploadAttachments(vikunja, taskId, filePaths) : null;
+		const body = (comment ? toHtml(comment) : "") + (files ? attachmentHtml(vikunja, taskId, files.uploaded) : "");
+		return ok(withUploadInfo(summarizeComment(await vikunja.put(`/tasks/${taskId}/comments`, { comment: body })), files));
 	}));
 	server.registerTool("update_task_comment", {
 		title: "Edit task comment",
-		description: "Replace the text of an existing comment.",
+		description: "Replace the text of an existing comment and/or add files to it. filePaths without comment keeps the current text.",
 		inputSchema: {
 			taskId: z.number().int().describe("Task id"),
 			commentId: z.number().int().describe("Comment id"),
-			comment: commentText
+			comment: commentText.optional(),
+			filePaths: commentFiles.optional()
 		}
-	}, guard(async ({ taskId, commentId, comment }) => {
-		return ok(summarizeComment(await vikunja.post(`/tasks/${taskId}/comments/${commentId}`, { comment: toHtml(comment) })));
+	}, guard(async ({ taskId, commentId, comment, filePaths }) => {
+		if (!comment && !filePaths) throw new Error("Pass comment, filePaths, or both.");
+		const text = comment ? toHtml(comment) : (await vikunja.get(`/tasks/${taskId}/comments/${commentId}`)).comment ?? "";
+		const files = filePaths ? await uploadAttachments(vikunja, taskId, filePaths) : null;
+		const body = text + (files ? attachmentHtml(vikunja, taskId, files.uploaded) : "");
+		return ok(withUploadInfo(summarizeComment(await vikunja.post(`/tasks/${taskId}/comments/${commentId}`, { comment: body })), files));
 	}));
 	server.registerTool("set_reaction", {
 		title: "Add / remove reaction",
@@ -581,7 +625,8 @@ const extraFields = {
 	repeatMode: z.enum(REPEAT_MODES).optional().describe("default = shift dates by repeatAfterSeconds when marked done; monthly = same day next month (ignores repeatAfterSeconds); fromCurrentDate = shift from the moment it is marked done"),
 	reminders: z.array(reminderField).optional().describe("REPLACES all reminders; [] removes them"),
 	labelIds: z.array(z.number().int()).optional().describe("Label ids (list_labels); REPLACES the task's labels"),
-	assigneeIds: z.array(z.number().int()).optional().describe("User ids (find_users / get_current_user); REPLACES the assignees, [] unassigns everyone")
+	assigneeIds: z.array(z.number().int()).optional().describe("User ids (find_users / get_current_user); REPLACES the assignees, [] unassigns everyone"),
+	descriptionFilePaths: filePathsField.optional().describe("Absolute paths of local files to upload as task attachments and show at the end of the description: images inline, other files by name")
 };
 function toApiReminder(r) {
 	if (r.relativeTo) return {
@@ -680,7 +725,7 @@ function registerTaskTools(server, vikunja, { allowDelete = false, defaultProjec
 			priority: priorityField.optional(),
 			...extraFields
 		}
-	}, guard(async ({ projectId, title, description, dueDate, startDate, endDate, priority, labelIds, assigneeIds, ...extra }) => {
+	}, guard(async ({ projectId, title, description, dueDate, startDate, endDate, priority, labelIds, assigneeIds, descriptionFilePaths, ...extra }) => {
 		const body = {
 			...stripUndefined({
 				title,
@@ -695,8 +740,17 @@ function registerTaskTools(server, vikunja, { allowDelete = false, defaultProjec
 		let task = await vikunja.put(`/projects/${projectId}/tasks`, body);
 		if (labelIds && labelIds.length > 0) await setLabels(vikunja, task.id, labelIds);
 		if (assigneeIds && assigneeIds.length > 0) await setAssignees(vikunja, task.id, assigneeIds);
-		if (labelIds?.length || assigneeIds?.length) task = await fetchTask(vikunja, task.id);
-		return ok(fullTask(task, await frontendUrl(vikunja)));
+		let files = null;
+		if (descriptionFilePaths) {
+			files = await uploadAttachments(vikunja, task.id, descriptionFilePaths);
+			const current = await vikunja.get(`/tasks/${task.id}`);
+			await vikunja.post(`/tasks/${task.id}`, {
+				...current,
+				description: (current.description || "") + attachmentHtml(vikunja, task.id, files.uploaded)
+			});
+		}
+		if (labelIds?.length || assigneeIds?.length || files) task = await fetchTask(vikunja, task.id);
+		return ok(withUploadInfo(fullTask(task, await frontendUrl(vikunja)), files));
 	}));
 	server.registerTool("update_task", {
 		title: "Update task",
@@ -713,7 +767,7 @@ function registerTaskTools(server, vikunja, { allowDelete = false, defaultProjec
 			projectId: z.number().int().optional().describe("Move the task to another project"),
 			...extraFields
 		}
-	}, guard(async ({ id, title, description, done, dueDate, startDate, endDate, priority, projectId, labelIds, assigneeIds, ...extra }) => {
+	}, guard(async ({ id, title, description, done, dueDate, startDate, endDate, priority, projectId, labelIds, assigneeIds, descriptionFilePaths, ...extra }) => {
 		const patch = {
 			...stripUndefined({
 				title,
@@ -727,9 +781,14 @@ function registerTaskTools(server, vikunja, { allowDelete = false, defaultProjec
 			}),
 			...extraBody(extra)
 		};
-		if (Object.keys(patch).length === 0 && labelIds === void 0 && assigneeIds === void 0) throw new Error("Nothing to update.");
-		if (Object.keys(patch).length > 0) {
+		if (Object.keys(patch).length === 0 && !descriptionFilePaths && labelIds === void 0 && assigneeIds === void 0) throw new Error("Nothing to update.");
+		let files = null;
+		if (Object.keys(patch).length > 0 || descriptionFilePaths) {
 			const current = await vikunja.get(`/tasks/${id}`);
+			if (descriptionFilePaths) {
+				files = await uploadAttachments(vikunja, id, descriptionFilePaths);
+				patch.description = (description ?? current.description ?? "") + attachmentHtml(vikunja, id, files.uploaded);
+			}
 			await vikunja.post(`/tasks/${id}`, {
 				...current,
 				...patch
@@ -737,7 +796,7 @@ function registerTaskTools(server, vikunja, { allowDelete = false, defaultProjec
 		}
 		if (labelIds !== void 0) await setLabels(vikunja, id, labelIds);
 		if (assigneeIds !== void 0) await setAssignees(vikunja, id, assigneeIds);
-		return ok(fullTask(await fetchTask(vikunja, id), await frontendUrl(vikunja)));
+		return ok(withUploadInfo(fullTask(await fetchTask(vikunja, id), await frontendUrl(vikunja)), files));
 	}));
 	server.registerTool("complete_task", {
 		title: "Complete task",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fswap/mcp-vikunja",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "MCP server for Vikunja — manage tasks, assignees, comments, attachments, relations and kanban from Claude",
   "type": "module",
   "bin": {