@fswap/mcp-vikunja 0.1.8 → 0.1.10

package/README.md

@@ -15,7 +15,9 @@ Runs locally over stdio. No install step — clients launch it with `npx`.
 
    It asks for your Vikunja URL and token, verifies them against `/api/v1/user`, lets you pick a default project, and stores the answers in your OS config directory (mode `0600`).
 
-3. Add the server to your client. Every value asked in `setup` can be skipped with Enter; anything you skip goes into the `env` block shown below instead. `setup --print` shows these snippets again at any time.
+3. Add the server to your client. At the end, `setup` offers to do this for you in Claude Code, Claude Desktop, Cursor and Codex: clients it finds are pre-selected (except Claude Code when Claude Desktop is installed, because the desktop app's Code tab already loads `claude_desktop_config.json`), an existing `vikunja` entry is only replaced after you confirm, and any config file it changes gets a one-time `.bak` copy.
+
+   To add it by hand instead, use the snippets below. Every value asked in `setup` can be skipped with Enter; anything you skip goes into the `env` block instead. `setup --print` shows these snippets again at any time.
 
    **Claude Desktop** (`claude_desktop_config.json`) and **Cursor** (`~/.cursor/mcp.json` or `<project>/.cursor/mcp.json`):
 
@@ -100,8 +102,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 +116,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

@@ -8,6 +8,7 @@ import envPaths from "env-paths";
 import { z } from "zod";
 import os from "node:os";
 import * as p from "@clack/prompts";
+import { spawnSync } from "node:child_process";
 //#region \0rolldown/runtime.js
 var __defProp = Object.defineProperty;
 var __esmMin = (fn, res, err) => () => {
@@ -229,8 +230,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 +308,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 +380,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 +454,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 +468,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 +626,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 +726,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 +741,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 +768,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 +782,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 +797,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",
@@ -974,13 +1034,17 @@ function registerUserTools(server, vikunja) {
 }
 //#endregion
 //#region src/snippets.ts
-function jsonSnippet(missing) {
+/** The `mcpServers.<key>` value used by JSON-configured clients. */
+function serverEntry(missing) {
 	const server = {
 		command: "npx",
-		args: ["-y", `${PACKAGE_NAME}@latest`]
+		args: SERVER_ARGS
 	};
 	if (Object.keys(missing).length > 0) server.env = missing;
-	return JSON.stringify({ mcpServers: { [SERVER_KEY]: server } }, null, 2);
+	return server;
+}
+function jsonSnippet(missing) {
+	return JSON.stringify({ mcpServers: { [SERVER_KEY]: serverEntry(missing) } }, null, 2);
 }
 function tomlSnippet(missing) {
 	const lines = [
@@ -1018,11 +1082,199 @@ function clientSnippets(missing = {}) {
 		}
 	];
 }
-var SERVER_KEY, ENV_URL, ENV_TOKEN;
+var SERVER_KEY, ENV_URL, ENV_TOKEN, SERVER_ARGS;
 var init_snippets = __esmMin((() => {
 	SERVER_KEY = "vikunja";
 	ENV_URL = "VIKUNJA_URL";
 	ENV_TOKEN = "VIKUNJA_API_TOKEN";
+	SERVER_ARGS = ["-y", `${PACKAGE_NAME}@latest`];
+}));
+//#endregion
+//#region src/install.ts
+function onPath(cmd) {
+	const exts = process.platform === "win32" ? (process.env.PATHEXT ?? ".EXE;.CMD;.BAT").split(";") : [""];
+	return (process.env.PATH ?? "").split(path.delimiter).filter(Boolean).some((dir) => exts.some((ext) => fs.existsSync(path.join(dir, cmd + ext))));
+}
+function runCommand(cmd, args) {
+	const r = spawnSync(cmd, args, {
+		encoding: "utf8",
+		shell: process.platform === "win32"
+	});
+	return {
+		ok: r.status === 0,
+		output: `${r.stdout ?? ""}${r.stderr ?? ""}${r.error?.message ?? ""}`.trim()
+	};
+}
+function claudeDesktopConfig(env) {
+	if (env.platform === "darwin") return path.join(env.home, "Library", "Application Support", "Claude", "claude_desktop_config.json");
+	if (env.platform === "win32") return path.join(env.appData ?? path.join(env.home, "AppData", "Roaming"), "Claude", "claude_desktop_config.json");
+	return path.join(env.home, ".config", "Claude", "claude_desktop_config.json");
+}
+function detectClients(env = hostEnv) {
+	const dirExists = (file) => fs.existsSync(path.dirname(file));
+	return [
+		{
+			id: "claude-code",
+			label: "Claude Code",
+			detected: env.which("claude"),
+			location: CLAUDE_CODE_LOCATION,
+			hint: "terminal / IDE"
+		},
+		{
+			id: "claude-desktop",
+			label: "Claude Desktop",
+			detected: dirExists(claudeDesktopConfig(env)),
+			location: claudeDesktopConfig(env),
+			hint: "chat + Code tab"
+		},
+		{
+			id: "cursor",
+			label: "Cursor",
+			detected: dirExists(cursorConfig(env)),
+			location: cursorConfig(env)
+		},
+		{
+			id: "codex",
+			label: "Codex",
+			detected: dirExists(codexConfig(env)) || env.which("codex"),
+			location: codexConfig(env)
+		}
+	];
+}
+/**
+* Detected clients to pre-select. Claude Code is left out when Claude Desktop is present: the desktop
+* app's Code tab also loads claude_desktop_config.json, so selecting both would register the server twice there.
+*/
+function defaultSelection(clients) {
+	const desktopFound = clients.some((c) => c.id === "claude-desktop" && c.detected);
+	return clients.filter((c) => c.detected && !(desktopFound && c.id === "claude-code")).map((c) => c.id);
+}
+function readIfExists(file) {
+	try {
+		return fs.readFileSync(file, "utf8");
+	} catch (err) {
+		if (err.code === "ENOENT") return null;
+		throw err;
+	}
+}
+/** Writes `content`, keeping a copy of the original the first time an existing file is changed. */
+function writeWithBackup(file, original, content) {
+	if (original !== null && !fs.existsSync(`${file}.bak`)) fs.writeFileSync(`${file}.bak`, original);
+	fs.mkdirSync(path.dirname(file), { recursive: true });
+	fs.writeFileSync(file, content);
+}
+function parseJsonConfig(file, text) {
+	if (text === null || text.trim() === "") return {};
+	try {
+		const parsed = JSON.parse(text);
+		if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) return parsed;
+	} catch {}
+	throw new Error(`Could not parse ${file}; left it unchanged`);
+}
+function jsonHasEntry(file) {
+	return Boolean(parseJsonConfig(file, readIfExists(file)).mcpServers?.[SERVER_KEY]);
+}
+function jsonInstall(file, missing) {
+	const original = readIfExists(file);
+	const config = parseJsonConfig(file, original);
+	const replaced = Boolean(config.mcpServers?.[SERVER_KEY]);
+	config.mcpServers = {
+		...config.mcpServers,
+		[SERVER_KEY]: serverEntry(missing)
+	};
+	writeWithBackup(file, original, JSON.stringify(config, null, 2) + "\n");
+	return {
+		status: replaced ? "replaced" : "added",
+		location: file
+	};
+}
+function tomlHasEntry(text) {
+	return text !== null && text.split("\n").some((line) => ownHeader.test(line));
+}
+function tomlWithoutEntry(text) {
+	let inOwnSection = false;
+	return text.split("\n").filter((line) => {
+		if (anyHeader.test(line)) inOwnSection = ownHeader.test(line);
+		return !inOwnSection;
+	}).join("\n");
+}
+function codexInstall(file, missing) {
+	const original = readIfExists(file);
+	const rest = original === null ? "" : tomlWithoutEntry(original).trimEnd();
+	writeWithBackup(file, original, (rest ? `${rest}\n\n` : "") + tomlSnippet(missing) + "\n");
+	return {
+		status: tomlHasEntry(original) ? "replaced" : "added",
+		location: file
+	};
+}
+function claude(env, args) {
+	const r = env.run("claude", args);
+	if (!r.ok) throw new Error(`claude ${args.join(" ")} failed${r.output ? `: ${r.output}` : ""}`);
+}
+function claudeCodeInstall(env, missing) {
+	const replaced = hasEntry("claude-code", env);
+	if (replaced) claude(env, [
+		"mcp",
+		"remove",
+		SERVER_KEY,
+		"-s",
+		"user"
+	]);
+	const envArgs = Object.entries(missing).flatMap(([k, v]) => ["-e", `${k}=${v}`]);
+	claude(env, [
+		"mcp",
+		"add",
+		SERVER_KEY,
+		"-s",
+		"user",
+		...envArgs,
+		"--",
+		"npx",
+		...SERVER_ARGS
+	]);
+	return {
+		status: replaced ? "replaced" : "added",
+		location: CLAUDE_CODE_LOCATION
+	};
+}
+/** Whether the client already has a server registered under SERVER_KEY. Throws if its config is unreadable. */
+function hasEntry(id, env = hostEnv) {
+	switch (id) {
+		case "claude-code": return env.run("claude", [
+			"mcp",
+			"get",
+			SERVER_KEY
+		]).ok;
+		case "claude-desktop": return jsonHasEntry(claudeDesktopConfig(env));
+		case "cursor": return jsonHasEntry(cursorConfig(env));
+		case "codex": return tomlHasEntry(readIfExists(codexConfig(env)));
+	}
+}
+/** Adds (or overwrites) this server in the client's config. Throws with a readable message on failure. */
+function installClient(id, missing, env = hostEnv) {
+	switch (id) {
+		case "claude-code": return claudeCodeInstall(env, missing);
+		case "claude-desktop": return jsonInstall(claudeDesktopConfig(env), missing);
+		case "cursor": return jsonInstall(cursorConfig(env), missing);
+		case "codex": return codexInstall(codexConfig(env), missing);
+	}
+}
+var hostEnv, cursorConfig, codexConfig, CLAUDE_CODE_LOCATION, escapeRe, ownHeader, anyHeader;
+var init_install = __esmMin((() => {
+	init_snippets();
+	hostEnv = {
+		home: os.homedir(),
+		platform: process.platform,
+		appData: process.env.APPDATA,
+		which: onPath,
+		run: runCommand
+	};
+	cursorConfig = (env) => path.join(env.home, ".cursor", "mcp.json");
+	codexConfig = (env) => path.join(env.home, ".codex", "config.toml");
+	CLAUDE_CODE_LOCATION = "user scope via claude mcp";
+	escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+	ownHeader = new RegExp(`^\\s*\\[\\s*mcp_servers\\.("?)${escapeRe(SERVER_KEY)}\\1\\s*(\\]|\\.)`);
+	anyHeader = /^\s*\[/;
 }));
 //#endregion
 //#region src/setup.ts
@@ -1118,15 +1370,60 @@ async function runSetup(args = []) {
 	const missing = {};
 	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.`);
+	const updated = await addToClients(missing);
+	if (Object.keys(missing).length > 0) {
+		const where = updated ? "env block of the client config updated above" : "env block below";
+		p.log.warn(`Still needed: ${Object.keys(missing).join(", ")}. Replace the placeholders in the ${where}, or run setup again.`);
+	}
 	p.outro(`Saved to ${file}`);
+	if (updated) {
+		console.log("Re-print MCP client config snippets any time with: setup --print");
+		return;
+	}
 	console.log("Add one of these to your MCP client (plain text, safe to copy). Re-print any time with: setup --print");
 	printSnippets(missing);
 }
+/** Offers to register the server in MCP clients. Returns true when at least one client was updated. */
+async function addToClients(missing) {
+	const clients = detectClients();
+	const selected = await p.multiselect({
+		message: "Add to MCP clients? (Space to toggle, Enter to confirm, none to skip)",
+		options: clients.map((c) => ({
+			value: c.id,
+			label: c.label,
+			hint: [c.hint, c.detected ? "detected" : "not found"].filter(Boolean).join(" — ")
+		})),
+		initialValues: defaultSelection(clients),
+		required: false
+	});
+	if (typeof selected === "symbol") abort();
+	let updated = false;
+	for (const client of clients.filter((c) => selected.includes(c.id))) try {
+		if (hasEntry(client.id)) {
+			const replace = await p.confirm({
+				message: `${client.label} already has a "${SERVER_KEY}" server. Replace it?`,
+				initialValue: false
+			});
+			if (typeof replace === "symbol") abort();
+			if (!replace) {
+				p.log.info(`${client.label}: skipped, existing entry kept`);
+				continue;
+			}
+		}
+		const result = installClient(client.id, missing);
+		const restart = client.id === "claude-desktop" ? " — restart Claude Desktop to load it" : "";
+		p.log.success(`${client.label}: ${result.status} (${result.location})${restart}`);
+		updated = true;
+	} catch (err) {
+		p.log.error(`${client.label}: failed — ${err.message}`);
+	}
+	return updated;
+}
 var init_setup = __esmMin((() => {
 	init_config();
 	init_client();
 	init_snippets();
+	init_install();
 }));
 //#endregion
 //#region src/index.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fswap/mcp-vikunja",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "description": "MCP server for Vikunja — manage tasks, assignees, comments, attachments, relations and kanban from Claude",
   "type": "module",
   "bin": {
@@ -17,7 +17,7 @@
     "dev": "tsdown --watch",
     "typecheck": "tsc --noEmit",
     "lint": "eslint src test",
-    "test": "npm run build && node test/smoke.test.mjs",
+    "test": "npm run build && node test/smoke.test.mjs && node --test test/install.test.mjs",
     "check": "npm run lint && npm run typecheck && npm test",
     "start": "node dist/index.js",
     "setup": "node dist/index.js setup",