@fswap/mcp-vikunja 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gleb Okhrimenko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,126 @@
+# @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.
+
+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).
+2. Run the interactive setup once:
+
+   ```bash
+   npx -y @fswap/mcp-vikunja setup
+   ```
+
+   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.
+
+   **Claude Desktop** (`claude_desktop_config.json`) and **Cursor** (`~/.cursor/mcp.json` or `<project>/.cursor/mcp.json`):
+
+   ```json
+   {
+     "mcpServers": {
+       "vikunja": {
+         "command": "npx",
+         "args": ["-y", "@fswap/mcp-vikunja"]
+       }
+     }
+   }
+   ```
+
+   **Codex** (`~/.codex/config.toml`):
+
+   ```toml
+   [mcp_servers.vikunja]
+   command = "npx"
+   args = ["-y", "@fswap/mcp-vikunja"]
+   ```
+
+   **Claude Code**:
+
+   ```bash
+   claude mcp add vikunja -- npx -y @fswap/mcp-vikunja
+   ```
+
+### Without `setup` (environment variables)
+
+Environment variables take precedence over the config file, so you can skip `setup` entirely (or skip individual values in it and set them here):
+
+```json
+{
+  "mcpServers": {
+    "vikunja": {
+      "command": "npx",
+      "args": ["-y", "@fswap/mcp-vikunja"],
+      "env": {
+        "VIKUNJA_URL": "https://try.vikunja.io",
+        "VIKUNJA_API_TOKEN": "tk_..."
+      }
+    }
+  }
+}
+```
+
+Codex equivalent:
+
+```toml
+[mcp_servers.vikunja]
+command = "npx"
+args = ["-y", "@fswap/mcp-vikunja"]
+[mcp_servers.vikunja.env]
+VIKUNJA_URL = "https://try.vikunja.io"
+VIKUNJA_API_TOKEN = "tk_..."
+```
+
+| Variable | Purpose |
+|---|---|
+| `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_DEFAULT_PROJECT_ID` | Project used by `create_task` when `projectId` is omitted |
+
+## Tools
+
+| Tool | Method + endpoint | Notes |
+|---|---|---|
+| `list_projects` | `GET /projects` | id, title, description, parent |
+| `get_project` | `GET /projects/{id}` | |
+| `create_project` | `PUT /projects` | optional parent project |
+| `list_tasks` | `GET /tasks/all` or `GET /projects/{id}/tasks` | open tasks by default; `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 |
+| `list_labels` | `GET /labels` | label ids for create/update |
+| `create_label` | `PUT /labels` | |
+| `delete_task` | `DELETE /tasks/{id}` | only when delete is allowed (setup answer or `VIKUNJA_ALLOW_DELETE=true`) |
+
+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.
+
+## Development
+
+TypeScript source in `src/`, bundled to `dist/` with [tsdown](https://tsdown.dev). Only `dist/` is published.
+
+```bash
+npm install
+npm run build        # tsdown → dist/index.js
+npm run lint         # eslint (typescript-eslint)
+npm run typecheck    # tsc --noEmit
+npm test             # builds, then spawns the server and checks the tool list
+npm run check        # all of the above (also runs on prepublishOnly)
+VIKUNJA_URL=... VIKUNJA_API_TOKEN=... npm run inspect   # MCP Inspector UI against dist/
+```
+
+Never write to stdout from server code — it is the protocol channel. Use `console.error`.
+
+## Reset
+
+```bash
+npx -y @fswap/mcp-vikunja setup --reset
+```
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,653 @@
+#!/usr/bin/env node
+import { createRequire } from "node:module";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import fs from "node:fs";
+import path from "node:path";
+import envPaths from "env-paths";
+import { z } from "zod";
+import * as p from "@clack/prompts";
+//#region \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __esmMin = (fn, res, err) => () => {
+	if (err) throw err[0];
+	try {
+		return fn && (res = fn(fn = 0)), res;
+	} catch (e) {
+		throw err = [e], e;
+	}
+};
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+//#endregion
+//#region src/config.ts
+function configPath() {
+	return path.join(paths.config, "config.json");
+}
+function truthy(v) {
+	return v != null && /^(1|true|yes|on)$/i.test(v.trim());
+}
+function readConfigFile() {
+	try {
+		return JSON.parse(fs.readFileSync(configPath(), "utf8"));
+	} catch (err) {
+		if (err.code === "ENOENT") return null;
+		console.error(`Warning: could not read ${configPath()}: ${err.message}`);
+		return null;
+	}
+}
+/**
+* Resolve runtime configuration.
+* Precedence: environment variables > config file written by `setup`.
+* Returns null when neither provides url + token.
+*/
+function loadConfig() {
+	const env = process.env;
+	const file = readConfigFile() ?? {};
+	const url = env.VIKUNJA_URL || file.url;
+	const token = env.VIKUNJA_API_TOKEN || file.token;
+	if (!url || !token) return null;
+	const deleteEnv = env.VIKUNJA_ALLOW_DELETE ?? env.ALLOW_DELETE;
+	const allowDelete = deleteEnv != null ? truthy(deleteEnv) : Boolean(file.allowDelete);
+	const envProject = env.VIKUNJA_DEFAULT_PROJECT_ID ? Number(env.VIKUNJA_DEFAULT_PROJECT_ID) : NaN;
+	const defaultProjectId = Number.isFinite(envProject) ? envProject : file.defaultProjectId ?? null;
+	return {
+		url: url.replace(/\/+$/, ""),
+		token,
+		allowDelete,
+		defaultProjectId
+	};
+}
+function saveConfig(config) {
+	const file = configPath();
+	fs.mkdirSync(path.dirname(file), {
+		recursive: true,
+		mode: 448
+	});
+	fs.writeFileSync(file, JSON.stringify(config, null, 2) + "\n", { mode: 384 });
+	fs.chmodSync(file, 384);
+	return file;
+}
+function deleteConfig() {
+	try {
+		fs.unlinkSync(configPath());
+		return true;
+	} catch (err) {
+		if (err.code === "ENOENT") return false;
+		throw err;
+	}
+}
+var pkg, PACKAGE_NAME, VERSION, paths;
+var init_config = __esmMin((() => {
+	pkg = createRequire(import.meta.url)("../package.json");
+	PACKAGE_NAME = pkg.name;
+	VERSION = pkg.version;
+	paths = envPaths("mcp-vikunja", { suffix: "" });
+}));
+//#endregion
+//#region src/client.ts
+function normalizeDate(value) {
+	if (!value) return null;
+	if (value === "0001-01-01T00:00:00Z" || value.startsWith("0001-01-01")) return null;
+	return value;
+}
+function makeClient(baseUrl, token) {
+	const base = baseUrl.replace(/\/+$/, "").replace(/\/api\/v1$/, "");
+	async function request(method, path, body, 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));
+		}
+		let res;
+		try {
+			res = await fetch(url, {
+				method,
+				headers: {
+					Authorization: `Bearer ${token}`,
+					"Content-Type": "application/json",
+					Accept: "application/json"
+				},
+				body: body !== void 0 ? JSON.stringify(body) : void 0
+			});
+		} catch (err) {
+			throw new Error(`${method} ${path} failed: ${err.message}`);
+		}
+		if (!res.ok) {
+			const text = await res.text();
+			let detail = text;
+			try {
+				const json = JSON.parse(text);
+				detail = json.message ? `${json.message}${json.code ? ` (code ${json.code})` : ""}` : text;
+			} catch {}
+			throw new Error(`${method} ${path} → ${res.status}: ${detail}`);
+		}
+		if (res.status === 204) return void 0;
+		const text = await res.text();
+		return text ? JSON.parse(text) : void 0;
+	}
+	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)
+	};
+}
+/** 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((() => {}));
+//#endregion
+//#region src/tools/_shared.ts
+init_config();
+init_client();
+function ok(value) {
+	return { content: [{
+		type: "text",
+		text: typeof value === "string" ? value : JSON.stringify(value, null, 2)
+	}] };
+}
+function fail(err) {
+	return {
+		isError: true,
+		content: [{
+			type: "text",
+			text: `Error: ${err instanceof Error ? err.message : String(err)}`
+		}]
+	};
+}
+/** Wrap a tool handler so API errors become isError results instead of crashes. */
+function guard(fn) {
+	return async (args) => {
+		try {
+			return await fn(args);
+		} catch (err) {
+			return fail(err);
+		}
+	};
+}
+function stripUndefined(obj) {
+	return Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== void 0));
+}
+//#endregion
+//#region src/tools/projects.ts
+function summarizeProject(p) {
+	return {
+		id: p.id,
+		title: p.title,
+		description: p.description || null,
+		identifier: p.identifier || null,
+		parentProjectId: p.parent_project_id || null,
+		archived: Boolean(p.is_archived),
+		favorite: Boolean(p.is_favorite)
+	};
+}
+function registerProjectTools(server, vikunja) {
+	server.registerTool("list_projects", {
+		title: "List projects",
+		description: "List Vikunja projects the user can access. Returns id, title, description, identifier and parent project. Use the id with list_tasks or create_task.",
+		inputSchema: {
+			search: z.string().optional().describe("Filter projects by title"),
+			includeArchived: z.boolean().default(false).describe("Include archived projects"),
+			page: z.number().int().min(1).default(1),
+			perPage: z.number().int().min(1).max(100).default(50)
+		}
+	}, guard(async ({ search, includeArchived, page, perPage }) => {
+		return ok((await vikunja.get("/projects", {
+			s: search,
+			is_archived: includeArchived ? true : void 0,
+			page,
+			per_page: perPage
+		})).map(summarizeProject));
+	}));
+	server.registerTool("get_project", {
+		title: "Get project",
+		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}`)));
+	}));
+	server.registerTool("create_project", {
+		title: "Create project",
+		description: "Create a new Vikunja project. Optionally nest it under a parent project.",
+		inputSchema: {
+			title: z.string().min(1).describe("Project title"),
+			description: z.string().optional().describe("Project description"),
+			parentProjectId: z.number().int().optional().describe("Parent project id for nesting")
+		}
+	}, guard(async ({ title, description, parentProjectId }) => {
+		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)));
+	}));
+}
+//#endregion
+//#region src/tools/tasks.ts
+function summarizeTask(t) {
+	return {
+		id: t.id,
+		title: t.title,
+		done: t.done,
+		dueDate: normalizeDate(t.due_date),
+		priority: t.priority ?? 0,
+		projectId: t.project_id,
+		identifier: t.identifier || null,
+		labels: (t.labels ?? []).map((l) => l.title),
+		updated: t.updated
+	};
+}
+function fullTask(t) {
+	return {
+		...summarizeTask(t),
+		description: t.description || "",
+		doneAt: normalizeDate(t.done_at),
+		startDate: normalizeDate(t.start_date),
+		endDate: normalizeDate(t.end_date),
+		percentDone: t.percent_done ?? 0,
+		repeatAfterSeconds: t.repeat_after || null,
+		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
+		})),
+		created: t.created
+	};
+}
+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");
+/** 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 })) });
+}
+function registerTaskTools(server, vikunja, { allowDelete = false, defaultProjectId = null } = {}) {
+	server.registerTool("list_tasks", {
+		title: "List tasks",
+		description: "List tasks, across all projects or within one project. Returns id, title, done, due date, priority and label names (no descriptions — use get_task). By default only open tasks are returned. For advanced queries pass a raw Vikunja `filter` string such as `done = false && due_date < now+7d` or `labels in 3, 5`.",
+		inputSchema: {
+			projectId: z.number().int().optional().describe("Limit to this project (omit for all projects)"),
+			includeDone: z.boolean().default(false).describe("Include completed tasks"),
+			search: z.string().optional().describe("Full-text search in title/description"),
+			filter: z.string().optional().describe("Raw Vikunja filter expression; overrides includeDone. Fields: done, due_date, priority, labels, assignees, project"),
+			sortBy: z.enum([
+				"due_date",
+				"priority",
+				"id",
+				"title",
+				"done",
+				"created",
+				"updated"
+			]).default("due_date"),
+			orderBy: z.enum(["asc", "desc"]).default("asc"),
+			page: z.number().int().min(1).default(1),
+			perPage: z.number().int().min(1).max(100).default(50)
+		}
+	}, guard(async ({ projectId, includeDone, search, filter, sortBy, orderBy, page, perPage }) => {
+		const effectiveFilter = filter ?? (includeDone ? void 0 : "done = false");
+		const path = projectId != null ? `/projects/${projectId}/tasks` : "/tasks/all";
+		return ok((await vikunja.get(path, {
+			s: search,
+			filter: effectiveFilter,
+			sort_by: sortBy,
+			order_by: orderBy,
+			page,
+			per_page: perPage
+		})).map(summarizeTask));
+	}));
+	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}`)));
+	}));
+	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.` : ""),
+		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)"),
+			dueDate: dateField.optional(),
+			startDate: dateField.optional(),
+			endDate: dateField.optional(),
+			priority: priorityField.optional(),
+			labelIds: z.array(z.number().int()).optional().describe("Label ids to attach")
+		}
+	}, 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
+		});
+		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}`);
+		}
+		return ok(fullTask(task));
+	}));
+	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.",
+		inputSchema: {
+			id: z.number().int().describe("Task id"),
+			title: z.string().min(1).optional(),
+			description: z.string().optional(),
+			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")
+		}
+	}, 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}`);
+		}
+		return ok(fullTask(task));
+	}));
+	server.registerTool("complete_task", {
+		title: "Complete task",
+		description: "Mark a task as done (or 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")
+		}
+	}, guard(async ({ id, done }) => {
+		const current = await vikunja.get(`/tasks/${id}`);
+		return ok(summarizeTask(await vikunja.post(`/tasks/${id}`, {
+			...current,
+			done
+		})));
+	}));
+	server.registerTool("list_labels", {
+		title: "List labels",
+		description: "List labels available to the user, with ids for use in create_task / update_task.",
+		inputSchema: {
+			search: z.string().optional().describe("Filter labels by title"),
+			page: z.number().int().min(1).default(1),
+			perPage: z.number().int().min(1).max(100).default(100)
+		}
+	}, guard(async ({ search, page, perPage }) => {
+		return ok((await vikunja.get("/labels", {
+			s: search,
+			page,
+			per_page: perPage
+		}) ?? []).map((l) => ({
+			id: l.id,
+			title: l.title,
+			color: l.hex_color || null,
+			description: l.description || null
+		})));
+	}));
+	server.registerTool("create_label", {
+		title: "Create label",
+		description: "Create a new label.",
+		inputSchema: {
+			title: z.string().min(1),
+			hexColor: z.string().regex(/^[0-9a-fA-F]{6}$/).optional().describe("Colour as 6 hex digits without '#', e.g. e8e8e8"),
+			description: z.string().optional()
+		}
+	}, guard(async ({ title, hexColor, description }) => {
+		const data = await vikunja.put("/labels", stripUndefined({
+			title,
+			hex_color: hexColor,
+			description
+		}));
+		return ok({
+			id: data.id,
+			title: data.title,
+			color: data.hex_color || null
+		});
+	}));
+	if (allowDelete) server.registerTool("delete_task", {
+		title: "Delete task",
+		description: "Permanently delete a task. Irreversible — only use when the user explicitly asks.",
+		inputSchema: { id: z.number().int().describe("Task id") }
+	}, guard(async ({ id }) => {
+		await vikunja.del(`/tasks/${id}`);
+		return ok({ deleted: id });
+	}));
+}
+//#endregion
+//#region src/snippets.ts
+function jsonSnippet(missing) {
+	const server = {
+		command: "npx",
+		args: ["-y", PACKAGE_NAME]
+	};
+	if (Object.keys(missing).length > 0) server.env = missing;
+	return JSON.stringify({ mcpServers: { [SERVER_KEY]: server } }, null, 2);
+}
+function tomlSnippet(missing) {
+	const lines = [
+		`[mcp_servers.${SERVER_KEY}]`,
+		"command = \"npx\"",
+		`args = ["-y", "${PACKAGE_NAME}"]`
+	];
+	if (Object.keys(missing).length > 0) {
+		lines.push(`[mcp_servers.${SERVER_KEY}.env]`);
+		for (const [k, v] of Object.entries(missing)) lines.push(`${k} = "${v}"`);
+	}
+	return lines.join("\n");
+}
+function claudeCodeSnippet(missing) {
+	const env = Object.entries(missing).map(([k, v]) => `-e ${k}=${v} `).join("");
+	return `claude mcp add ${SERVER_KEY} ${env}-- npx -y ${PACKAGE_NAME}`;
+}
+function clientSnippets(missing = {}) {
+	return [
+		{
+			title: "Claude Desktop — claude_desktop_config.json",
+			body: jsonSnippet(missing)
+		},
+		{
+			title: "Cursor — ~/.cursor/mcp.json (or <project>/.cursor/mcp.json)",
+			body: jsonSnippet(missing)
+		},
+		{
+			title: "Codex — ~/.codex/config.toml",
+			body: tomlSnippet(missing)
+		},
+		{
+			title: "Claude Code",
+			body: claudeCodeSnippet(missing)
+		}
+	];
+}
+var SERVER_KEY, ENV_URL, ENV_TOKEN;
+var init_snippets = __esmMin((() => {
+	SERVER_KEY = "vikunja";
+	ENV_URL = "VIKUNJA_URL";
+	ENV_TOKEN = "VIKUNJA_API_TOKEN";
+}));
+//#endregion
+//#region src/setup.ts
+var setup_exports = /* @__PURE__ */ __exportAll({ runSetup: () => runSetup });
+function abort() {
+	p.cancel("Setup aborted.");
+	process.exit(1);
+}
+function printSnippets(missing) {
+	for (const s of clientSnippets(missing)) p.note(s.body, s.title);
+}
+async function runSetup(args = []) {
+	if (args.includes("--reset")) {
+		const removed = deleteConfig();
+		console.log(removed ? `Removed ${configPath()}` : `Nothing to remove (${configPath()} does not exist)`);
+		return;
+	}
+	const existing = readConfigFile() ?? {};
+	if (args.includes("--print")) {
+		const missing = {};
+		if (!existing.url) missing[ENV_URL] = "https://try.vikunja.io";
+		if (!existing.token) missing[ENV_TOKEN] = "tk_...";
+		printSnippets(missing);
+		return;
+	}
+	p.intro(`${PACKAGE_NAME} setup`);
+	p.log.info("Press Enter to skip any value. Skipped values can be supplied later via the env block of your MCP client config.");
+	const creds = await p.group({
+		url: () => p.text({
+			message: `Vikunja URL (${ENV_URL})`,
+			placeholder: "https://try.vikunja.io  — Enter to skip",
+			initialValue: existing.url ?? "",
+			validate: (v) => !v || /^https?:\/\/\S+$/.test(v) ? void 0 : "Must start with http:// or https://"
+		}),
+		token: () => p.password({
+			message: `API token (${ENV_TOKEN}; Settings → API Tokens in Vikunja) — Enter to skip`,
+			mask: "▪"
+		})
+	}, { onCancel: abort });
+	const url = (creds.url ?? "").trim().replace(/\/+$/, "") || void 0;
+	const token = (creds.token ?? "").trim() || existing.token || void 0;
+	let defaultProjectId = existing.defaultProjectId ?? null;
+	if (url && token) {
+		const s = p.spinner();
+		s.start("Checking connection");
+		try {
+			const me = await currentUser(url, token);
+			s.stop(`ok (logged in as ${me.username})`);
+		} catch (err) {
+			s.stop("failed");
+			p.cancel(`Could not authenticate: ${err.message}`);
+			process.exit(1);
+		}
+		try {
+			const projects = await makeClient(url, token).get("/projects", { per_page: 100 });
+			if (projects.length > 0) {
+				const choice = await p.select({
+					message: "Default project for new tasks (optional)",
+					initialValue: defaultProjectId,
+					options: [{
+						value: null,
+						label: "None — always require projectId"
+					}, ...projects.map((pr) => ({
+						value: pr.id,
+						label: pr.title,
+						hint: `#${pr.id}`
+					}))]
+				});
+				if (typeof choice === "symbol") abort();
+				defaultProjectId = choice;
+			}
+		} catch (err) {
+			p.log.warn(`Could not list projects (${err.message}); skipping default project.`);
+		}
+	} else p.log.warn("Skipping connection check and default-project selection because URL and/or token were not provided.");
+	const allowDelete = await p.confirm({
+		message: "Allow delete tools?",
+		initialValue: Boolean(existing.allowDelete)
+	});
+	if (typeof allowDelete === "symbol") abort();
+	const config = {
+		defaultProjectId,
+		allowDelete
+	};
+	if (url) config.url = url;
+	if (token) config.token = token;
+	const file = saveConfig(config);
+	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.`);
+	printSnippets(missing);
+	p.outro(`Saved to ${file}`);
+}
+var init_setup = __esmMin((() => {
+	init_config();
+	init_client();
+	init_snippets();
+}));
+//#endregion
+//#region src/index.ts
+init_config();
+init_client();
+const [cmd, ...rest] = process.argv.slice(2);
+if (cmd === "setup") {
+	const { runSetup } = await Promise.resolve().then(() => (init_setup(), setup_exports));
+	await runSetup(rest);
+} else if (cmd === "--help" || cmd === "-h" || cmd === "help") printHelp();
+else if (cmd === "--version" || cmd === "-v") console.log(VERSION);
+else await runServer();
+function printHelp() {
+	console.log(`${PACKAGE_NAME} ${VERSION}
+
+Usage:
+  npx ${PACKAGE_NAME}                 start the MCP server (stdio)
+  npx ${PACKAGE_NAME} setup           interactive configuration
+  npx ${PACKAGE_NAME} setup --reset   delete stored configuration
+  npx ${PACKAGE_NAME} setup --print   print MCP client config snippets
+
+Configuration precedence:
+  1. VIKUNJA_URL, VIKUNJA_API_TOKEN, VIKUNJA_ALLOW_DELETE env vars
+  2. ${configPath()}
+`);
+}
+async function runServer() {
+	const config = loadConfig();
+	if (!config) {
+		console.error(`No configuration found. Run: npx ${PACKAGE_NAME} setup`);
+		console.error("(or set VIKUNJA_URL and VIKUNJA_API_TOKEN in the environment)");
+		process.exit(1);
+	}
+	if (process.stdin.isTTY) {
+		console.error(`${PACKAGE_NAME} is an MCP stdio server and expects to be launched by an MCP client.`);
+		console.error(`Run "npx ${PACKAGE_NAME} setup" to configure it, or "npx ${PACKAGE_NAME} --help".`);
+		process.exit(1);
+	}
+	const vikunja = makeClient(config.url, config.token);
+	const server = new McpServer({
+		name: "mcp-vikunja",
+		version: VERSION
+	});
+	registerProjectTools(server, vikunja);
+	registerTaskTools(server, vikunja, {
+		allowDelete: config.allowDelete,
+		defaultProjectId: config.defaultProjectId
+	});
+	const transport = new StdioServerTransport();
+	await server.connect(transport);
+	console.error(`mcp-vikunja ${VERSION} connected (${config.url}, delete tools ${config.allowDelete ? "enabled" : "disabled"})`);
+}
+//#endregion
+export {};

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@fswap/mcp-vikunja",
+  "version": "0.1.0",
+  "description": "MCP server for Vikunja — list, create, update and complete tasks from Claude",
+  "type": "module",
+  "bin": {
+    "mcp-vikunja": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src test",
+    "test": "npm run build && node test/smoke.test.mjs",
+    "check": "npm run lint && npm run typecheck && npm test",
+    "start": "node dist/index.js",
+    "setup": "node dist/index.js setup",
+    "inspect": "npx @modelcontextprotocol/inspector node dist/index.js",
+    "prepublishOnly": "npm run check"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.0.0",
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "env-paths": "^4.0.0",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "eslint": "^10.0.0",
+    "tsdown": "^0.23.0",
+    "typescript": "^5.9.0",
+    "typescript-eslint": "^8.70.0"
+  },
+  "keywords": [
+    "mcp",
+    "vikunja",
+    "tasks",
+    "todo",
+    "claude",
+    "modelcontextprotocol"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sunblob/mcp-vikunja.git"
+  },
+  "homepage": "https://github.com/sunblob/mcp-vikunja#readme",
+  "bugs": {
+    "url": "https://github.com/sunblob/mcp-vikunja/issues"
+  }
+}