@fswap/mcp-vikunja 0.1.4 → 0.1.7

package/README.md

@@ -1,12 +1,12 @@
 # @fswap/mcp-vikunja
 
-An [MCP](https://modelcontextprotocol.io) server for [Vikunja](https://vikunja.io) that lets Claude Desktop, Claude Code, Cursor and other MCP clients list, create, update and complete your tasks.
+An [MCP](https://modelcontextprotocol.io) server for [Vikunja](https://vikunja.io) that lets Claude Desktop, Claude Code, Cursor and other MCP clients manage your tasks: create, update, complete, assign, comment, attach files, relate, move on kanban boards and everything else in the task menu.
 
 Runs locally over stdio. No install step — clients launch it with `npx`.
 
 ## Quick start
 
-1. Create an API token in Vikunja under **Settings → API Tokens** (scope it to projects, tasks and labels).
+1. Create an API token in Vikunja under **Settings → API Tokens** (scope it to projects, tasks, labels, task comments, attachments, assignees, relations, subscriptions, reactions and users — tools whose scope is missing return a 401).
 2. Run the interactive setup once:
 
    ```bash
@@ -78,7 +78,7 @@ VIKUNJA_API_TOKEN = "tk_..."
 |---|---|
 | `VIKUNJA_URL` | Vikunja base URL (with or without `/api/v1`) |
 | `VIKUNJA_API_TOKEN` | API token or login JWT |
-| `VIKUNJA_ALLOW_DELETE` | `true` to expose `delete_task` |
+| `VIKUNJA_ALLOW_DELETE` | `true` to expose `delete_task`, `delete_task_comment` and `delete_task_attachment` |
 | `VIKUNJA_DEFAULT_PROJECT_ID` | Project used by `create_task` when `projectId` is omitted |
 
 ## Tools
@@ -89,13 +89,32 @@ VIKUNJA_API_TOKEN = "tk_..."
 | `get_project` | `GET /projects/{id}` | |
 | `create_project` | `PUT /projects` | optional parent project |
 | `list_tasks` | `GET /tasks` or `GET /projects/{id}/tasks` | open tasks by default; `assignedToMe`, `filter`, `sortBy`, pagination |
-| `get_task` | `GET /tasks/{id}` | full task incl. description, labels, assignees |
-| `create_task` | `PUT /projects/{id}/tasks` | title, description, dates, priority, labels |
-| `update_task` | `POST /tasks/{id}` | merges your changes onto the current task; `labelIds` replaces labels |
-| `complete_task` | `POST /tasks/{id}` with `done: true` | `done=false` reopens |
+| `get_task` | `GET /tasks/{id}` + `GET /tasks/{id}/comments` | everything on the task page, including comments (`includeComments=false` skips them) |
+| `create_task` | `PUT /projects/{id}/tasks` | all task fields, see below |
+| `update_task` | `POST /tasks/{id}` (+ labels/assignees bulk) | merges your changes onto the current task |
+| `complete_task` | `POST /tasks/{id}` with `done: true` | `done=false` marks undone |
+| `duplicate_task` | `PUT /tasks/{id}/duplicate` | copies labels, assignees, attachments, reminders |
+| `set_subscription` | `PUT` / `DELETE /subscriptions/{task\|project}/{id}` | subscribe / unsubscribe |
 | `list_labels` | `GET /labels` | label ids for create/update |
 | `create_label` | `PUT /labels` | |
+| `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}` | |
+| `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}` | |
+| `list_task_attachments` | `GET /tasks/{id}/attachments` | |
+| `upload_task_attachment` | `PUT /tasks/{id}/attachments` (multipart) | local file paths |
+| `download_task_attachment` | `GET /tasks/{id}/attachments/{attachmentId}` | saves to disk; small images/text returned inline |
+| `list_kanban_buckets` | `GET /projects/{id}/views` + `/views/{view}/buckets` | kanban columns |
+| `move_task_to_bucket` | `POST /projects/{id}/views/{view}/buckets/{bucket}/tasks` | |
 | `delete_task` | `DELETE /tasks/{id}` | only when delete is allowed (setup answer or `VIKUNJA_ALLOW_DELETE=true`) |
+| `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.
 
 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

@@ -6,6 +6,7 @@ import fs from "node:fs";
 import path from "node:path";
 import envPaths from "env-paths";
 import { z } from "zod";
+import os from "node:os";
 import * as p from "@clack/prompts";
 //#region \0rolldown/runtime.js
 var __defProp = Object.defineProperty;
@@ -100,7 +101,7 @@ function normalizeDate(value) {
 }
 function makeClient(baseUrl, token) {
 	const base = baseUrl.replace(/\/+$/, "").replace(/\/api\/v1$/, "");
-	async function request(method, path, body, query) {
+	async function send(method, path, init, query) {
 		const url = new URL(`${base}/api/v1${path}`);
 		if (query) {
 			for (const [k, v] of Object.entries(query)) if (v !== void 0 && v !== "") url.searchParams.set(k, String(v));
@@ -108,13 +109,12 @@ function makeClient(baseUrl, token) {
 		let res;
 		try {
 			res = await fetch(url, {
+				...init,
 				method,
 				headers: {
 					Authorization: `Bearer ${token}`,
-					"Content-Type": "application/json",
-					Accept: "application/json"
-				},
-				body: body !== void 0 ? JSON.stringify(body) : void 0
+					...init.headers
+				}
 			});
 		} catch (err) {
 			throw new Error(`${method} ${path} failed: ${err.message}`);
@@ -128,24 +128,50 @@ function makeClient(baseUrl, token) {
 			} catch {}
 			throw new Error(`${method} ${path} → ${res.status}: ${detail}`);
 		}
+		return res;
+	}
+	async function parseJson(res) {
 		if (res.status === 204) return void 0;
 		const text = await res.text();
 		return text ? JSON.parse(text) : void 0;
 	}
+	async function request(method, path, body, query) {
+		return parseJson(await send(method, path, {
+			headers: {
+				"Content-Type": "application/json",
+				Accept: "application/json"
+			},
+			body: body !== void 0 ? JSON.stringify(body) : void 0
+		}, query));
+	}
 	return {
 		baseUrl: base,
 		request,
 		get: (path, query) => request("GET", path, void 0, query),
 		put: (path, body) => request("PUT", path, body),
 		post: (path, body) => request("POST", path, body),
-		del: (path) => request("DELETE", path)
+		del: (path) => request("DELETE", path),
+		upload: async (path, form) => parseJson(await send("PUT", path, {
+			headers: { Accept: "application/json" },
+			body: form
+		})),
+		download: async (path) => {
+			const res = await send("GET", path, {});
+			return {
+				data: Buffer.from(await res.arrayBuffer()),
+				contentType: res.headers.get("content-type")
+			};
+		}
 	};
 }
 /** Cheap authenticated call used by `setup` to validate URL + token. */
 async function currentUser(baseUrl, token) {
 	return makeClient(baseUrl, token).get("/user");
 }
-var init_client = __esmMin((() => {}));
+var ZERO_DATE;
+var init_client = __esmMin((() => {
+	ZERO_DATE = "0001-01-01T00:00:00Z";
+}));
 //#endregion
 //#region src/tools/_shared.ts
 init_config();
@@ -178,6 +204,39 @@ function guard(fn) {
 function stripUndefined(obj) {
 	return Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== void 0));
 }
+function summarizeUser(u) {
+	if (!u) return null;
+	return {
+		id: u.id,
+		username: u.username,
+		name: u.name || null
+	};
+}
+let frontendBase = null;
+/** Resolve the web UI base URL once (Vikunja's API host may differ from its frontend host). */
+async function frontendUrl(vikunja) {
+	if (frontendBase) return frontendBase;
+	try {
+		frontendBase = ((await vikunja.get("/info")).frontend_url || vikunja.baseUrl).replace(/\/+$/, "");
+	} catch {
+		frontendBase = vikunja.baseUrl;
+	}
+	return frontendBase;
+}
+/**
+* Vikunja stores descriptions and comments as HTML. Pass HTML through untouched;
+* wrap plain text in paragraphs so line breaks survive.
+*/
+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("");
+}
+/** Reaction map `{ "👍": [users] }` → `{ "👍": ["alice"] }`, or null when empty. */
+function summarizeReactions(map) {
+	if (!map || Object.keys(map).length === 0) return null;
+	return Object.fromEntries(Object.entries(map).map(([value, users]) => [value, users.map((u) => u.username)]));
+}
 //#endregion
 //#region src/tools/projects.ts
 function summarizeProject(p, base) {
@@ -192,16 +251,6 @@ function summarizeProject(p, base) {
 		favorite: Boolean(p.is_favorite)
 	};
 }
-let frontendBase$1 = null;
-async function frontendUrl$1(vikunja) {
-	if (frontendBase$1) return frontendBase$1;
-	try {
-		frontendBase$1 = ((await vikunja.get("/info")).frontend_url || vikunja.baseUrl).replace(/\/+$/, "");
-	} catch {
-		frontendBase$1 = vikunja.baseUrl;
-	}
-	return frontendBase$1;
-}
 function registerProjectTools(server, vikunja) {
 	server.registerTool("list_projects", {
 		title: "List projects",
@@ -219,7 +268,7 @@ function registerProjectTools(server, vikunja) {
 			page,
 			per_page: perPage
 		});
-		const base = await frontendUrl$1(vikunja);
+		const base = await frontendUrl(vikunja);
 		return ok(data.map((p) => summarizeProject(p, base)));
 	}));
 	server.registerTool("get_project", {
@@ -227,7 +276,7 @@ function registerProjectTools(server, vikunja) {
 		description: "Get one Vikunja project by id.",
 		inputSchema: { id: z.number().int().describe("Project id") }
 	}, guard(async ({ id }) => {
-		return ok(summarizeProject(await vikunja.get(`/projects/${id}`), await frontendUrl$1(vikunja)));
+		return ok(summarizeProject(await vikunja.get(`/projects/${id}`), await frontendUrl(vikunja)));
 	}));
 	server.registerTool("create_project", {
 		title: "Create project",
@@ -241,22 +290,207 @@ function registerProjectTools(server, vikunja) {
 		const body = { title };
 		if (description !== void 0) body.description = description;
 		if (parentProjectId !== void 0) body.parent_project_id = parentProjectId;
-		return ok(summarizeProject(await vikunja.put("/projects", body), await frontendUrl$1(vikunja)));
+		return ok(summarizeProject(await vikunja.put("/projects", body), await frontendUrl(vikunja)));
 	}));
 }
 //#endregion
-//#region src/tools/tasks.ts
-let frontendBase = null;
-/** Resolve the web UI base URL once (Vikunja's API host may differ from its frontend host). */
-async function frontendUrl(vikunja) {
-	if (frontendBase) return frontendBase;
-	try {
-		frontendBase = ((await vikunja.get("/info")).frontend_url || vikunja.baseUrl).replace(/\/+$/, "");
-	} catch {
-		frontendBase = vikunja.baseUrl;
-	}
-	return frontendBase;
+//#region src/tools/attachments.ts
+function summarizeAttachment(a) {
+	return {
+		id: a.id,
+		name: a.file?.name ?? null,
+		mime: a.file?.mime || null,
+		size: a.file?.size ?? null,
+		created: a.created,
+		createdBy: summarizeUser(a.created_by)
+	};
+}
+const INLINE_IMAGE_TYPES = /* @__PURE__ */ new Set([
+	"image/png",
+	"image/jpeg",
+	"image/gif",
+	"image/webp"
+]);
+const MAX_INLINE_IMAGE_BYTES = 1e6;
+const MAX_INLINE_TEXT_BYTES = 2e5;
+function isTextual(mime) {
+	return /^text\/|json|xml|yaml|csv|markdown|javascript/.test(mime);
+}
+function safeFileName(name, fallback) {
+	const base = path.basename((name || "").replace(/[\\/]/g, "_"));
+	return base && base !== "." && base !== ".." ? base : fallback;
+}
+function registerAttachmentTools(server, vikunja, { allowDelete = false } = {}) {
+	server.registerTool("list_task_attachments", {
+		title: "List task attachments",
+		description: "List files attached to a task (id, name, mime type, size, uploader).",
+		inputSchema: {
+			taskId: z.number().int().describe("Task id"),
+			page: z.number().int().min(1).default(1),
+			perPage: z.number().int().min(1).max(100).default(50)
+		}
+	}, guard(async ({ taskId, page, perPage }) => {
+		return ok((await vikunja.get(`/tasks/${taskId}/attachments`, {
+			page,
+			per_page: perPage
+		}) ?? []).map(summarizeAttachment));
+	}));
+	server.registerTool("upload_task_attachment", {
+		title: "Upload task attachment",
+		description: "Attach one or more local files to a task.",
+		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")
+		}
+	}, 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("; ")}`);
+		return ok({
+			uploaded,
+			errors
+		});
+	}));
+	server.registerTool("download_task_attachment", {
+		title: "Download task attachment",
+		description: "Save a task attachment to a local file. Small images and text files are also returned inline so you can read them.",
+		inputSchema: {
+			taskId: z.number().int().describe("Task id"),
+			attachmentId: z.number().int().describe("Attachment id (from get_task or list_task_attachments)"),
+			outputPath: z.string().optional().describe("Where to save the file; defaults to <tmp>/mcp-vikunja/task-<taskId>/<file name>")
+		}
+	}, guard(async ({ taskId, attachmentId, outputPath }) => {
+		const attachment = ((await vikunja.get(`/tasks/${taskId}`)).attachments ?? []).find((a) => a.id === attachmentId);
+		if (!attachment) throw new Error(`Attachment ${attachmentId} not found on task ${taskId}.`);
+		const { data, contentType } = await vikunja.download(`/tasks/${taskId}/attachments/${attachmentId}`);
+		const name = safeFileName(attachment.file?.name, `attachment-${attachmentId}`);
+		const target = path.resolve(outputPath ?? path.join(os.tmpdir(), "mcp-vikunja", `task-${taskId}`, name));
+		fs.mkdirSync(path.dirname(target), { recursive: true });
+		fs.writeFileSync(target, data);
+		const mime = (attachment.file?.mime || contentType || "application/octet-stream").split(";")[0].trim();
+		const content = [{
+			type: "text",
+			text: JSON.stringify({
+				savedTo: target,
+				name,
+				mime,
+				size: data.length
+			}, null, 2)
+		}];
+		if (INLINE_IMAGE_TYPES.has(mime) && data.length <= MAX_INLINE_IMAGE_BYTES) content.push({
+			type: "image",
+			data: data.toString("base64"),
+			mimeType: mime
+		});
+		else if (isTextual(mime) && data.length <= MAX_INLINE_TEXT_BYTES) content.push({
+			type: "text",
+			text: data.toString("utf8")
+		});
+		return { content };
+	}));
+	if (allowDelete) server.registerTool("delete_task_attachment", {
+		title: "Delete task attachment",
+		description: "Permanently delete an attachment. Irreversible — only use when the user explicitly asks.",
+		inputSchema: {
+			taskId: z.number().int().describe("Task id"),
+			attachmentId: z.number().int().describe("Attachment id")
+		}
+	}, guard(async ({ taskId, attachmentId }) => {
+		await vikunja.del(`/tasks/${taskId}/attachments/${attachmentId}`);
+		return ok({ deleted: attachmentId });
+	}));
+}
+//#endregion
+//#region src/tools/comments.ts
+function summarizeComment(c) {
+	return {
+		id: c.id,
+		author: summarizeUser(c.author),
+		comment: c.comment,
+		reactions: summarizeReactions(c.reactions),
+		created: c.created,
+		edited: c.updated && c.updated !== c.created ? c.updated : null
+	};
+}
+const commentText = z.string().min(1).describe("Comment body. HTML is sent as-is; plain text is wrapped in <p> (blank line = new paragraph)");
+function registerCommentTools(server, vikunja, { allowDelete = false } = {}) {
+	server.registerTool("list_task_comments", {
+		title: "List task comments",
+		description: "List all comments on a task with author, HTML body, reactions and timestamps.",
+		inputSchema: {
+			taskId: z.number().int().describe("Task id"),
+			order: z.enum(["asc", "desc"]).default("asc").describe("asc = oldest first")
+		}
+	}, guard(async ({ taskId, order }) => {
+		return ok((await vikunja.get(`/tasks/${taskId}/comments`, { order_by: order }) ?? []).map(summarizeComment));
+	}));
+	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.",
+		inputSchema: {
+			taskId: z.number().int().describe("Task id"),
+			comment: commentText
+		}
+	}, guard(async ({ taskId, comment }) => {
+		return ok(summarizeComment(await vikunja.put(`/tasks/${taskId}/comments`, { comment: toHtml(comment) })));
+	}));
+	server.registerTool("update_task_comment", {
+		title: "Edit task comment",
+		description: "Replace the text of an existing comment.",
+		inputSchema: {
+			taskId: z.number().int().describe("Task id"),
+			commentId: z.number().int().describe("Comment id"),
+			comment: commentText
+		}
+	}, guard(async ({ taskId, commentId, comment }) => {
+		return ok(summarizeComment(await vikunja.post(`/tasks/${taskId}/comments/${commentId}`, { comment: toHtml(comment) })));
+	}));
+	server.registerTool("set_reaction", {
+		title: "Add / remove reaction",
+		description: "Add an emoji reaction (or remove yours with remove=true) on a task or a task comment.",
+		inputSchema: {
+			entity: z.enum(["task", "comment"]).default("task"),
+			id: z.number().int().describe("Task id, or comment id when entity=comment"),
+			reaction: z.string().min(1).max(20).describe("Emoji or short text, e.g. 👍"),
+			remove: z.boolean().default(false)
+		}
+	}, guard(async ({ entity, id, reaction, remove }) => {
+		const kind = entity === "task" ? "tasks" : "comments";
+		if (remove) await vikunja.post(`/${kind}/${id}/reactions/delete`, { value: reaction });
+		else await vikunja.put(`/${kind}/${id}/reactions`, { value: reaction });
+		return ok({
+			entity,
+			id,
+			reaction,
+			active: !remove
+		});
+	}));
+	if (allowDelete) server.registerTool("delete_task_comment", {
+		title: "Delete task comment",
+		description: "Permanently delete a comment. Irreversible — only use when the user explicitly asks.",
+		inputSchema: {
+			taskId: z.number().int().describe("Task id"),
+			commentId: z.number().int().describe("Comment id")
+		}
+	}, guard(async ({ taskId, commentId }) => {
+		await vikunja.del(`/tasks/${taskId}/comments/${commentId}`);
+		return ok({ deleted: commentId });
+	}));
 }
+//#endregion
+//#region src/tools/tasks.ts
+/** Index = Vikunja's numeric repeat_mode. */
+const REPEAT_MODES = [
+	"default",
+	"monthly",
+	"fromCurrentDate"
+];
 function summarizeTask(t, base) {
 	return {
 		id: t.id,
@@ -280,26 +514,100 @@ function fullTask(t, base) {
 		startDate: normalizeDate(t.start_date),
 		endDate: normalizeDate(t.end_date),
 		percentDone: t.percent_done ?? 0,
-		repeatAfterSeconds: t.repeat_after || null,
+		color: t.hex_color || null,
+		favorite: Boolean(t.is_favorite),
+		repeat: t.repeat_after || t.repeat_mode ? {
+			afterSeconds: t.repeat_after || 0,
+			mode: REPEAT_MODES[t.repeat_mode ?? 0] ?? "default"
+		} : null,
+		reminders: (t.reminders ?? []).map((r) => r.relative_to ? {
+			relativeTo: r.relative_to,
+			relativePeriodSeconds: r.relative_period ?? 0,
+			reminder: normalizeDate(r.reminder)
+		} : { reminder: normalizeDate(r.reminder) }),
 		labels: (t.labels ?? []).map((l) => ({
 			id: l.id,
 			title: l.title,
 			color: l.hex_color || null
 		})),
-		assignees: (t.assignees ?? []).map((u) => ({
-			id: u.id,
-			username: u.username,
-			name: u.name || null
-		})),
+		assignees: (t.assignees ?? []).map((u) => summarizeUser(u)),
+		subscription: t.subscription ? {
+			entity: t.subscription.entity,
+			entityId: t.subscription.entity_id
+		} : null,
+		relatedTasks: Object.fromEntries(Object.entries(t.related_tasks ?? {}).map(([kind, tasks]) => [kind, (tasks ?? []).map((r) => ({
+			id: r.id,
+			title: r.title,
+			done: r.done,
+			projectId: r.project_id,
+			url: `${base}/tasks/${r.id}`
+		}))])),
+		attachments: (t.attachments ?? []).map(summarizeAttachment),
+		coverImageAttachmentId: t.cover_image_attachment_id || null,
+		kanbanBuckets: t.buckets ? t.buckets.map((b) => ({
+			id: b.id,
+			title: b.title,
+			viewId: b.project_view_id
+		})) : void 0,
+		createdBy: summarizeUser(t.created_by),
 		created: t.created
 	};
 }
+/** Fetch one task including its kanban buckets; falls back for Vikunja versions without `expand`. */
+async function fetchTask(vikunja, id) {
+	try {
+		return await vikunja.get(`/tasks/${id}`, { expand: "buckets" });
+	} catch {
+		return vikunja.get(`/tasks/${id}`);
+	}
+}
 const dateField = z.string().datetime({ offset: true }).describe("RFC 3339 timestamp, e.g. 2026-09-15T17:00:00Z");
 const priorityField = z.number().int().min(0).max(5).describe("0 = unset, 1 = low, 2 = medium, 3 = high, 4 = urgent, 5 = DO NOW");
+const reminderField = z.object({
+	reminder: dateField.optional().describe("Absolute reminder time"),
+	relativeTo: z.enum([
+		"due_date",
+		"start_date",
+		"end_date"
+	]).optional().describe("Date the reminder is relative to"),
+	relativePeriodSeconds: z.number().int().optional().describe("Offset from relativeTo in seconds; negative = before (e.g. -3600 = one hour before)")
+}).refine((r) => r.reminder !== void 0 || r.relativeTo !== void 0, "Give either reminder or relativeTo");
+/** Fields shared by create_task and update_task beyond the basic ones. */
+const extraFields = {
+	percentDone: z.number().min(0).max(1).optional().describe("Progress as a fraction 0–1 (the UI uses 10% steps)"),
+	hexColor: z.string().regex(/^#?([0-9a-fA-F]{6})?$/).optional().describe("Task colour as 6 hex digits, e.g. 1973ff; empty string removes the colour"),
+	isFavorite: z.boolean().optional().describe("Add to (true) or remove from (false) the current user's favorites"),
+	repeatAfterSeconds: z.number().int().min(0).optional().describe("Repeat interval in seconds (3600 hourly, 86400 daily, 604800 weekly); 0 stops repeating"),
+	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")
+};
+function toApiReminder(r) {
+	if (r.relativeTo) return {
+		relative_to: r.relativeTo,
+		relative_period: r.relativePeriodSeconds ?? 0
+	};
+	return { reminder: r.reminder };
+}
+function extraBody(a) {
+	return stripUndefined({
+		percent_done: a.percentDone,
+		hex_color: a.hexColor?.replace(/^#/, ""),
+		is_favorite: a.isFavorite,
+		repeat_after: a.repeatAfterSeconds,
+		repeat_mode: a.repeatMode === void 0 ? void 0 : REPEAT_MODES.indexOf(a.repeatMode),
+		reminders: a.reminders?.map(toApiReminder)
+	});
+}
 /** Replace the task's labels with exactly `labelIds` (Vikunja has no single-call "set labels"). */
 async function setLabels(vikunja, taskId, labelIds) {
 	await vikunja.post(`/tasks/${taskId}/labels/bulk`, { labels: labelIds.map((id) => ({ id })) });
 }
+/** Replace the task's assignees; users missing from the list are unassigned. */
+async function setAssignees(vikunja, taskId, userIds) {
+	await vikunja.post(`/tasks/${taskId}/assignees/bulk`, { assignees: userIds.map((id) => ({ id })) });
+}
 function registerTaskTools(server, vikunja, { allowDelete = false, defaultProjectId = null } = {}) {
 	server.registerTool("list_tasks", {
 		title: "List tasks",
@@ -346,84 +654,94 @@ function registerTaskTools(server, vikunja, { allowDelete = false, defaultProjec
 	}));
 	server.registerTool("get_task", {
 		title: "Get task",
-		description: "Get a single task with full details: description, dates, priority, labels and assignees.",
-		inputSchema: { id: z.number().int().describe("Task id") }
-	}, guard(async ({ id }) => {
-		return ok(fullTask(await vikunja.get(`/tasks/${id}`), await frontendUrl(vikunja)));
+		description: "Get a single task with full details: description, dates, priority, progress, colour, favorite, repeat, reminders, labels, assignees, subscription, related tasks, attachments, kanban buckets and (by default) comments.",
+		inputSchema: {
+			id: z.number().int().describe("Task id"),
+			includeComments: z.boolean().default(true).describe("Also return the task's comments (oldest first)")
+		}
+	}, guard(async ({ id, includeComments }) => {
+		const [task, comments] = await Promise.all([fetchTask(vikunja, id), includeComments ? vikunja.get(`/tasks/${id}/comments`) : Promise.resolve(void 0)]);
+		const result = fullTask(task, await frontendUrl(vikunja));
+		return ok(comments === void 0 ? result : {
+			...result,
+			comments: (comments ?? []).map(summarizeComment)
+		});
 	}));
 	server.registerTool("create_task", {
 		title: "Create task",
-		description: "Create a task in a project. Use list_projects to find the projectId and list_labels for label ids." + (defaultProjectId != null ? ` If projectId is omitted, project ${defaultProjectId} is used.` : ""),
+		description: "Create a task in a project. Use list_projects for the projectId, list_labels for label ids and find_users for assignee ids. Descriptions are HTML." + (defaultProjectId != null ? ` If projectId is omitted, project ${defaultProjectId} is used.` : ""),
 		inputSchema: {
 			projectId: defaultProjectId != null ? z.number().int().default(defaultProjectId).describe("Project id") : z.number().int().describe("Project id"),
 			title: z.string().min(1).describe("Task title"),
-			description: z.string().optional().describe("Task description (markdown/HTML accepted by Vikunja)"),
+			description: z.string().optional().describe("Task description (HTML)"),
 			dueDate: dateField.optional(),
 			startDate: dateField.optional(),
 			endDate: dateField.optional(),
 			priority: priorityField.optional(),
-			labelIds: z.array(z.number().int()).optional().describe("Label ids to attach")
+			...extraFields
 		}
-	}, guard(async ({ projectId, title, description, dueDate, startDate, endDate, priority, labelIds }) => {
-		const body = stripUndefined({
-			title,
-			description,
-			due_date: dueDate,
-			start_date: startDate,
-			end_date: endDate,
-			priority
-		});
+	}, guard(async ({ projectId, title, description, dueDate, startDate, endDate, priority, labelIds, assigneeIds, ...extra }) => {
+		const body = {
+			...stripUndefined({
+				title,
+				description,
+				due_date: dueDate,
+				start_date: startDate,
+				end_date: endDate,
+				priority
+			}),
+			...extraBody(extra)
+		};
 		let task = await vikunja.put(`/projects/${projectId}/tasks`, body);
-		if (labelIds && labelIds.length > 0) {
-			await setLabels(vikunja, task.id, labelIds);
-			task = await vikunja.get(`/tasks/${task.id}`);
-		}
+		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)));
 	}));
 	server.registerTool("update_task", {
 		title: "Update task",
-		description: "Update fields of an existing task. Only the fields you pass are changed. To clear a date pass null. labelIds, when given, REPLACES the task's labels. Use complete_task to just mark a task done.",
+		description: "Update fields of an existing task. Only the fields you pass are changed. To clear a date pass null. labelIds, assigneeIds and reminders REPLACE the current values. projectId moves the task to another project. Use complete_task to just mark a task done.",
 		inputSchema: {
 			id: z.number().int().describe("Task id"),
 			title: z.string().min(1).optional(),
-			description: z.string().optional(),
+			description: z.string().optional().describe("Task description (HTML)"),
 			done: z.boolean().optional(),
 			dueDate: dateField.nullable().optional(),
 			startDate: dateField.nullable().optional(),
 			endDate: dateField.nullable().optional(),
 			priority: priorityField.optional(),
-			percentDone: z.number().min(0).max(1).optional().describe("Progress as a fraction 0–1"),
 			projectId: z.number().int().optional().describe("Move the task to another project"),
-			labelIds: z.array(z.number().int()).optional().describe("Replace labels with these ids")
+			...extraFields
 		}
-	}, guard(async ({ id, title, description, done, dueDate, startDate, endDate, priority, percentDone, projectId, labelIds }) => {
-		const current = await vikunja.get(`/tasks/${id}`);
-		const patch = stripUndefined({
-			title,
-			description,
-			done,
-			due_date: dueDate === null ? "0001-01-01T00:00:00Z" : dueDate,
-			start_date: startDate === null ? "0001-01-01T00:00:00Z" : startDate,
-			end_date: endDate === null ? "0001-01-01T00:00:00Z" : endDate,
-			priority,
-			percent_done: percentDone,
-			project_id: projectId
-		});
-		if (Object.keys(patch).length === 0 && labelIds === void 0) throw new Error("Nothing to update.");
-		let task = current;
-		if (Object.keys(patch).length > 0) task = await vikunja.post(`/tasks/${id}`, {
-			...current,
-			...patch
-		});
-		if (labelIds !== void 0) {
-			await setLabels(vikunja, id, labelIds);
-			task = await vikunja.get(`/tasks/${id}`);
+	}, guard(async ({ id, title, description, done, dueDate, startDate, endDate, priority, projectId, labelIds, assigneeIds, ...extra }) => {
+		const patch = {
+			...stripUndefined({
+				title,
+				description,
+				done,
+				due_date: dueDate === null ? ZERO_DATE : dueDate,
+				start_date: startDate === null ? ZERO_DATE : startDate,
+				end_date: endDate === null ? ZERO_DATE : endDate,
+				priority,
+				project_id: projectId
+			}),
+			...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) {
+			const current = await vikunja.get(`/tasks/${id}`);
+			await vikunja.post(`/tasks/${id}`, {
+				...current,
+				...patch
+			});
 		}
-		return ok(fullTask(task, await frontendUrl(vikunja)));
+		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)));
 	}));
 	server.registerTool("complete_task", {
 		title: "Complete task",
-		description: "Mark a task as done (or reopen it with done=false).",
+		description: "Mark a task as done (or undone / reopen it with done=false).",
 		inputSchema: {
 			id: z.number().int().describe("Task id"),
 			done: z.boolean().default(true).describe("false to reopen a completed task")
@@ -435,6 +753,45 @@ function registerTaskTools(server, vikunja, { allowDelete = false, defaultProjec
 			done
 		}), await frontendUrl(vikunja)));
 	}));
+	server.registerTool("duplicate_task", {
+		title: "Duplicate task",
+		description: "Copy a task with labels, assignees, attachments and reminders into the same project. The copy gets a \"copiedfrom\" relation to the original.",
+		inputSchema: { id: z.number().int().describe("Task id to duplicate") }
+	}, guard(async ({ id }) => {
+		const res = await vikunja.put(`/tasks/${id}/duplicate`);
+		if (!res?.duplicated_task) throw new Error("Vikunja did not return the duplicated task.");
+		return ok(fullTask(res.duplicated_task, await frontendUrl(vikunja)));
+	}));
+	server.registerTool("set_subscription", {
+		title: "Subscribe / unsubscribe",
+		description: "Subscribe the current user to notifications for a task or project, or unsubscribe (subscribed=false). A task subscription may be inherited from its project; then unsubscribe from the project instead.",
+		inputSchema: {
+			entity: z.enum(["task", "project"]).default("task"),
+			id: z.number().int().describe("Task or project id"),
+			subscribed: z.boolean().default(true).describe("false to unsubscribe")
+		}
+	}, guard(async ({ entity, id, subscribed }) => {
+		if (entity === "task") {
+			const task = await vikunja.get(`/tasks/${id}`);
+			const sub = task.subscription;
+			if (Boolean(sub) === subscribed) return ok({
+				entity,
+				id,
+				subscribed,
+				changed: false,
+				via: sub ? String(sub.entity) : null
+			});
+			if (sub && String(sub.entity) !== "task") throw new Error(`Task ${id} inherits its subscription from project ${task.project_id}; unsubscribe with entity="project", id=${task.project_id}.`);
+		}
+		if (subscribed) await vikunja.put(`/subscriptions/${entity}/${id}`);
+		else await vikunja.del(`/subscriptions/${entity}/${id}`);
+		return ok({
+			entity,
+			id,
+			subscribed,
+			changed: true
+		});
+	}));
 	server.registerTool("list_labels", {
 		title: "List labels",
 		description: "List labels available to the user, with ids for use in create_task / update_task.",
@@ -485,6 +842,137 @@ function registerTaskTools(server, vikunja, { allowDelete = false, defaultProjec
 	}));
 }
 //#endregion
+//#region src/tools/relations.ts
+const relationInput = {
+	taskId: z.number().int().describe("The base task"),
+	kind: z.enum([
+		"subtask",
+		"parenttask",
+		"related",
+		"duplicateof",
+		"duplicates",
+		"blocking",
+		"blocked",
+		"precedes",
+		"follows",
+		"copiedfrom",
+		"copiedto"
+	]).describe("What otherTaskId is to taskId: subtask = other is a subtask of taskId, parenttask = other is its parent, blocking = taskId blocks other, blocked = taskId is blocked by other, precedes / follows, related, duplicateof / duplicates, copiedfrom / copiedto. Vikunja creates the inverse relation automatically."),
+	otherTaskId: z.number().int().describe("The related task")
+};
+function registerRelationTools(server, vikunja) {
+	server.registerTool("add_task_relation", {
+		title: "Add task relation",
+		description: "Relate two tasks (subtask, parent, blocking, related, …). See get_task relatedTasks for current ones.",
+		inputSchema: relationInput
+	}, guard(async ({ taskId, kind, otherTaskId }) => {
+		await vikunja.put(`/tasks/${taskId}/relations`, {
+			task_id: taskId,
+			other_task_id: otherTaskId,
+			relation_kind: kind
+		});
+		return ok({
+			taskId,
+			kind,
+			otherTaskId,
+			related: true
+		});
+	}));
+	server.registerTool("remove_task_relation", {
+		title: "Remove task relation",
+		description: "Remove a relation between two tasks (the inverse relation is removed too).",
+		inputSchema: relationInput
+	}, guard(async ({ taskId, kind, otherTaskId }) => {
+		await vikunja.del(`/tasks/${taskId}/relations/${kind}/${otherTaskId}`);
+		return ok({
+			taskId,
+			kind,
+			otherTaskId,
+			related: false
+		});
+	}));
+}
+//#endregion
+//#region src/tools/kanban.ts
+async function kanbanViews(vikunja, projectId) {
+	return (await vikunja.get(`/projects/${projectId}/views`) ?? []).filter((v) => v.view_kind === "kanban" || v.view_kind === 3);
+}
+async function viewBuckets(vikunja, projectId, viewId) {
+	return await vikunja.get(`/projects/${projectId}/views/${viewId}/buckets`) ?? [];
+}
+function registerKanbanTools(server, vikunja) {
+	server.registerTool("list_kanban_buckets", {
+		title: "List kanban buckets",
+		description: "List a project's kanban views and their buckets (columns), with ids for move_task_to_bucket.",
+		inputSchema: { projectId: z.number().int().describe("Project id") }
+	}, guard(async ({ projectId }) => {
+		const views = await kanbanViews(vikunja, projectId);
+		return ok(await Promise.all(views.map(async (v) => ({
+			viewId: v.id,
+			title: v.title,
+			defaultBucketId: v.default_bucket_id || null,
+			doneBucketId: v.done_bucket_id || null,
+			buckets: (await viewBuckets(vikunja, projectId, v.id)).map((b) => ({
+				id: b.id,
+				title: b.title,
+				limit: b.limit || null
+			}))
+		}))));
+	}));
+	server.registerTool("move_task_to_bucket", {
+		title: "Move task to kanban bucket",
+		description: "Move a task into a kanban bucket (column) of its project. Moving into the view's done bucket marks the task done. To move a task to another project use update_task with projectId.",
+		inputSchema: {
+			taskId: z.number().int().describe("Task id"),
+			bucketId: z.number().int().describe("Target bucket id (list_kanban_buckets)"),
+			viewId: z.number().int().optional().describe("Kanban view id; looked up from the bucket when omitted")
+		}
+	}, guard(async ({ taskId, bucketId, viewId }) => {
+		const projectId = (await vikunja.get(`/tasks/${taskId}`)).project_id;
+		let view = viewId;
+		if (view == null) {
+			for (const v of await kanbanViews(vikunja, projectId)) if ((await viewBuckets(vikunja, projectId, v.id)).some((b) => b.id === bucketId)) {
+				view = v.id;
+				break;
+			}
+			if (view == null) throw new Error(`Bucket ${bucketId} is not in any kanban view of project ${projectId}; see list_kanban_buckets.`);
+		}
+		await vikunja.post(`/projects/${projectId}/views/${view}/buckets/${bucketId}/tasks`, {
+			task_id: taskId,
+			bucket_id: bucketId,
+			project_view_id: view
+		});
+		return ok({
+			taskId,
+			projectId,
+			viewId: view,
+			bucketId,
+			moved: true
+		});
+	}));
+}
+//#endregion
+//#region src/tools/users.ts
+function registerUserTools(server, vikunja) {
+	server.registerTool("get_current_user", {
+		title: "Get current user",
+		description: "Return the authenticated user's id, username and name (e.g. to assign a task to yourself).",
+		inputSchema: {}
+	}, guard(async () => ok(summarizeUser(await vikunja.get("/user")))));
+	server.registerTool("find_users", {
+		title: "Find users",
+		description: "Find user ids for assigning tasks. With projectId, lists users who have access to that project (only they can be assigned); search narrows by username or name.",
+		inputSchema: {
+			search: z.string().optional().describe("Username, name or full email"),
+			projectId: z.number().int().optional().describe("Only users with access to this project")
+		}
+	}, guard(async ({ search, projectId }) => {
+		if (projectId == null && !search) throw new Error("Pass search, projectId, or both.");
+		const path = projectId != null ? `/projects/${projectId}/projectusers` : "/users";
+		return ok((await vikunja.get(path, { s: search }) ?? []).map((u) => summarizeUser(u)));
+	}));
+}
+//#endregion
 //#region src/snippets.ts
 function jsonSnippet(missing) {
 	const server = {
@@ -543,8 +1031,13 @@ function abort() {
 	p.cancel("Setup aborted.");
 	process.exit(1);
 }
+/** Plain stdout, no box drawing, so the snippets can be selected and copied (or piped to a file). */
 function printSnippets(missing) {
-	for (const s of clientSnippets(missing)) p.note(s.body, s.title);
+	for (const s of clientSnippets(missing)) {
+		console.log(`\n# ${s.title}\n`);
+		console.log(s.body);
+	}
+	console.log();
 }
 async function runSetup(args = []) {
 	if (args.includes("--reset")) {
@@ -626,8 +1119,9 @@ async function runSetup(args = []) {
 	if (!url) missing[ENV_URL] = "https://try.vikunja.io";
 	if (!token) missing[ENV_TOKEN] = "tk_...";
 	if (Object.keys(missing).length > 0) p.log.warn(`Still needed: ${Object.keys(missing).join(", ")}. Add them to the env block below, or run setup again.`);
-	printSnippets(missing);
 	p.outro(`Saved to ${file}`);
+	console.log("Add one of these to your MCP client (plain text, safe to copy). Re-print any time with: setup --print");
+	printSnippets(missing);
 }
 var init_setup = __esmMin((() => {
 	init_config();
@@ -681,6 +1175,11 @@ async function runServer() {
 		allowDelete: config.allowDelete,
 		defaultProjectId: config.defaultProjectId
 	});
+	registerCommentTools(server, vikunja, { allowDelete: config.allowDelete });
+	registerAttachmentTools(server, vikunja, { allowDelete: config.allowDelete });
+	registerRelationTools(server, vikunja);
+	registerKanbanTools(server, vikunja);
+	registerUserTools(server, vikunja);
 	const transport = new StdioServerTransport();
 	await server.connect(transport);
 	console.error(`mcp-vikunja ${VERSION} connected (${config.url}, delete tools ${config.allowDelete ? "enabled" : "disabled"})`);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fswap/mcp-vikunja",
-  "version": "0.1.4",
-  "description": "MCP server for Vikunja — list, create, update and complete tasks from Claude",
+  "version": "0.1.7",
+  "description": "MCP server for Vikunja — manage tasks, assignees, comments, attachments, relations and kanban from Claude",
   "type": "module",
   "bin": {
     "mcp-vikunja": "dist/index.js"