joplin-mcp-server 2.1.0 → 2.2.0

package/dist/index.js

@@ -3,21 +3,20 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import fs, { readFileSync } from "fs";
+import { Either, Left, Match, Option, Right } from "functype";
 import path, { dirname, join, resolve } from "path";
 import { fileURLToPath } from "url";
 import { exec, execFile, spawn } from "child_process";
 import crypto$1 from "crypto";
-import { Either, Left, Match, Option, Right } from "functype";
-import os from "os";
+import { Path, Platform } from "functype-os";
 import { promisify } from "util";
 import axios from "axios";
-import { FastMCP } from "fastmcp";
+import { FastMCP, UserError } from "fastmcp";
 import { z } from "zod";
-
 //#region src/lib/joplin-sidecar.ts
 const execAsync = promisify(exec);
 const execFileAsync = promisify(execFile);
-const isWindows = process.platform === "win32";
+const isWindows = Platform.isWindows();
 const whichCmd = isWindows ? "where" : "which";
 const DEFAULT_API_PORT = 41184;
 const MAX_PORT_ATTEMPTS = 10;
@@ -36,18 +35,64 @@ const fetchWithTimeout = async (url, timeoutMs = 5e3) => {
 		clearTimeout(timer);
 	}
 };
+const CLIPPER_PID_FILE = "clipper-pid.txt";
+const readProfileServerPid = (profileDir) => {
+	try {
+		const raw = fs.readFileSync(join(profileDir, CLIPPER_PID_FILE), "utf-8").trim();
+		const pid = Number.parseInt(raw, 10);
+		return Number.isInteger(pid) && pid > 0 ? Option(pid) : Option.none();
+	} catch {
+		return Option.none();
+	}
+};
+const isProcessAlive = (pid) => {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch {
+		return false;
+	}
+};
+const servesOurProfile = (profileDir) => readProfileServerPid(profileDir).fold(() => false, (pid) => isProcessAlive(pid));
+const SIDECAR_STAMP_FILE = ".mcp-sidecar.json";
+const computeIdentityHash = (config) => crypto$1.createHash("sha256").update(JSON.stringify({
+	version: config.version ?? "unknown",
+	syncTarget: config.syncTarget,
+	syncInterval: config.syncInterval
+})).digest("hex").slice(0, 16);
+const readSidecarStamp = (profileDir) => {
+	try {
+		const stamp = JSON.parse(fs.readFileSync(join(profileDir, SIDECAR_STAMP_FILE), "utf-8"));
+		if (typeof stamp.version !== "string" || typeof stamp.identity !== "string") return Option.none();
+		return Option({
+			version: stamp.version,
+			identity: stamp.identity
+		});
+	} catch {
+		return Option.none();
+	}
+};
+const writeSidecarStamp = (profileDir, stamp) => {
+	try {
+		fs.writeFileSync(join(profileDir, SIDECAR_STAMP_FILE), JSON.stringify(stamp));
+	} catch {}
+};
+const inspectRunningSidecar = (profileDir, identity) => {
+	if (!servesOurProfile(profileDir)) return "not-ours";
+	return readSidecarStamp(profileDir).fold(() => "stale", (stamp) => stamp.identity === identity ? "reusable" : "stale");
+};
 const isConnectionRefused = (err) => {
 	var _e$cause, _e$cause2;
 	const e = err;
-	if ((e === null || e === void 0 || (_e$cause = e.cause) === null || _e$cause === void 0 ? void 0 : _e$cause.code) === "ECONNREFUSED") return true;
-	if (e === null || e === void 0 || (_e$cause2 = e.cause) === null || _e$cause2 === void 0 || (_e$cause2 = _e$cause2.errors) === null || _e$cause2 === void 0 ? void 0 : _e$cause2.some((inner) => (inner === null || inner === void 0 ? void 0 : inner.code) === "ECONNREFUSED")) return true;
+	if (((_e$cause = e.cause) === null || _e$cause === void 0 ? void 0 : _e$cause.code) === "ECONNREFUSED") return true;
+	if (((_e$cause2 = e.cause) === null || _e$cause2 === void 0 || (_e$cause2 = _e$cause2.errors) === null || _e$cause2 === void 0 ? void 0 : _e$cause2.some((inner) => inner.code === "ECONNREFUSED")) === true) return true;
 	return false;
 };
-const probePort = async (port, token) => {
+const probePort = async (port, token, profileDir, identity) => {
 	try {
 		if (await (await fetchWithTimeout(`http://127.0.0.1:${port}/ping`, 3e3)).text() !== "JoplinClipperServer") return "occupied_other";
 		try {
-			if ((await fetchWithTimeout(`http://127.0.0.1:${port}/folders?token=${encodeURIComponent(token)}&limit=1`, 3e3)).ok) return "joplin_ours";
+			if ((await fetchWithTimeout(`http://127.0.0.1:${port}/folders?token=${encodeURIComponent(token)}&limit=1`, 3e3)).ok) return Match(inspectRunningSidecar(profileDir, identity)).case("reusable", () => "joplin_ours").case("stale", () => "joplin_stale").default(() => "joplin_unowned");
 			return "joplin_foreign";
 		} catch {
 			return "joplin_foreign";
@@ -57,10 +102,10 @@ const probePort = async (port, token) => {
 		return "occupied_unresponsive";
 	}
 };
-const resolveAvailablePort = async (startPort, token) => {
-	let desktopDetected = false;
-	for (let port = startPort; port < startPort + MAX_PORT_ATTEMPTS; port++) {
-		const status = await probePort(port, token);
+const resolveAvailablePort = async (startPort, token, profileDir, identity) => {
+	const tryPort = async (port, desktopDetected) => {
+		if (port >= startPort + MAX_PORT_ATTEMPTS) return { outcome: "exhausted" };
+		const status = await probePort(port, token, profileDir, identity);
 		if (status === "free") return {
 			outcome: "free",
 			port,
@@ -71,21 +116,40 @@ const resolveAvailablePort = async (startPort, token) => {
 			port,
 			desktopDetected
 		};
+		if (status === "joplin_stale") return {
+			outcome: "replace_stale",
+			port,
+			desktopDetected
+		};
+		if (status === "joplin_unowned") {
+			process.stderr.write(`[joplin-sidecar] Port ${port}: Joplin server accepts our token but serves a different profile (likely an orphan from a previous run), skipping\n`);
+			return tryPort(port + 1, desktopDetected);
+		}
 		if (status === "joplin_foreign") {
-			desktopDetected = true;
-			process.stderr.write(`[joplin-sidecar] Port ${port}: Joplin Desktop detected (different token), skipping\n`);
-		} else process.stderr.write(`[joplin-sidecar] Port ${port} occupied (${status}), trying next...\n`);
-	}
-	return { outcome: "exhausted" };
+			process.stderr.write(`[joplin-sidecar] Port ${port}: another Joplin instance with a different token (possibly Joplin Desktop), skipping\n`);
+			return tryPort(port + 1, true);
+		}
+		process.stderr.write(`[joplin-sidecar] Port ${port} occupied (${status}), trying next...\n`);
+		return tryPort(port + 1, desktopDetected);
+	};
+	return tryPort(startPort, false);
 };
+const CLI_BIN_NAME = isWindows ? "joplin.cmd" : "joplin";
+const CLI_SEARCH_DEPTH = 5;
+const ancestorDirs = (dir, remaining) => {
+	const parent = dirname(dir);
+	if (remaining <= 0 || parent === dir) return [dir];
+	return [dir, ...ancestorDirs(parent, remaining - 1)];
+};
+const localCliCandidates = () => [...ancestorDirs(dirname(fileURLToPath(import.meta.url)), CLI_SEARCH_DEPTH), process.cwd()].map((root) => join(root, "node_modules", ".bin", CLI_BIN_NAME));
 const findJoplinCli = async () => {
 	const envCli = process.env.JOPLIN_CLI;
 	if (envCli) {
 		if (fs.existsSync(envCli)) return Right(envCli);
 		return Left(sidecarError("CLI_NOT_FOUND", `JOPLIN_CLI path not found: ${envCli}`));
 	}
-	const localBin = join(process.cwd(), "node_modules", ".bin", isWindows ? "joplin.cmd" : "joplin");
-	if (fs.existsSync(localBin)) return Right(localBin);
+	const bundled = localCliCandidates().find((candidate) => fs.existsSync(candidate));
+	if (bundled) return Right(bundled);
 	try {
 		const { stdout } = await execAsync(`${whichCmd} joplin`, {
 			encoding: "utf-8",
@@ -139,20 +203,22 @@ const buildSettingsRecord = (config) => {
 	return settings;
 };
 const runJoplinConfig = async (cli, profileDir, key, value) => {
-	await execFileAsync(cli.endsWith("npx") ? "npx" : cli, cli.endsWith("npx") ? [
+	const cmd = cli.endsWith("npx") ? "npx" : cli;
+	const args = cli.endsWith("npx") ? [
 		"joplin",
-		"config",
 		"--profile",
 		profileDir,
+		"config",
 		key,
 		value
 	] : [
-		"config",
 		"--profile",
 		profileDir,
+		"config",
 		key,
 		value
-	], {
+	];
+	await execFileAsync(cmd, args, {
 		encoding: "utf-8",
 		timeout: 3e4,
 		shell: isWindows
@@ -170,18 +236,17 @@ const configureJoplin = async (cli, config) => {
 };
 const spawnServer = (cli, config) => {
 	try {
-		var _proc$stderr, _proc$stdout;
 		const proc = spawn(cli.endsWith("npx") ? "npx" : cli, cli.endsWith("npx") ? [
 			"joplin",
-			"server",
-			"start",
 			"--profile",
-			config.profileDir
-		] : [
+			config.profileDir,
 			"server",
-			"start",
+			"start"
+		] : [
 			"--profile",
-			config.profileDir
+			config.profileDir,
+			"server",
+			"start"
 		], {
 			stdio: [
 				"ignore",
@@ -191,10 +256,10 @@ const spawnServer = (cli, config) => {
 			detached: false,
 			shell: isWindows
 		});
-		(_proc$stderr = proc.stderr) === null || _proc$stderr === void 0 || _proc$stderr.on("data", (data) => {
+		proc.stderr.on("data", (data) => {
 			process.stderr.write(`[joplin-sidecar] ${data.toString()}`);
 		});
-		(_proc$stdout = proc.stdout) === null || _proc$stdout === void 0 || _proc$stdout.on("data", (data) => {
+		proc.stdout.on("data", (data) => {
 			process.stderr.write(`[joplin-sidecar] ${data.toString()}`);
 		});
 		proc.on("error", (err) => {
@@ -207,13 +272,13 @@ const spawnServer = (cli, config) => {
 };
 const waitForReady = async (port, token, proc, maxRetries = 30, intervalMs = 1e3) => {
 	const deadline = Date.now() + 6e4;
-	let procExitCode = null;
+	const procExitState = { code: null };
 	if (proc) proc.once("exit", (code) => {
-		procExitCode = code;
+		procExitState.code = code;
 	});
-	for (let i = 0; i < maxRetries; i++) {
-		if (Date.now() > deadline) break;
-		if (procExitCode !== null) return Left(sidecarError("SPAWN_FAILED", `Joplin server process exited unexpectedly (code ${procExitCode}). Port ${port} may already be in use by another Joplin instance or process.`));
+	const attempt = async (i) => {
+		if (i >= maxRetries || Date.now() > deadline) return Left(sidecarError("HEALTH_CHECK_FAILED", "Joplin server did not become ready within 60s"));
+		if (procExitState.code !== null) return Left(sidecarError("SPAWN_FAILED", `Joplin server process exited unexpectedly (code ${procExitState.code}). Port ${port} may already be in use by another Joplin instance or process.`));
 		try {
 			if ((await fetchWithTimeout(`http://127.0.0.1:${port}/ping`)).ok) try {
 				const authResponse = await fetchWithTimeout(`http://127.0.0.1:${port}/folders?token=${encodeURIComponent(token)}&limit=1`);
@@ -227,8 +292,9 @@ const waitForReady = async (port, token, proc, maxRetries = 30, intervalMs = 1e3
 			}
 		} catch {}
 		await new Promise((resolve) => setTimeout(resolve, intervalMs));
-	}
-	return Left(sidecarError("HEALTH_CHECK_FAILED", "Joplin server did not become ready within 60s"));
+		return attempt(i + 1);
+	};
+	return attempt(0);
 };
 const CONFIG_CACHE_FILE = ".mcp-configured";
 const computeConfigHash = (config) => {
@@ -263,17 +329,70 @@ var JoplinSidecar = class {
 	childProcess = null;
 	startPromise = null;
 	portResolution = null;
+	cleanupRegistered = false;
 	constructor(config) {
 		this.config = {
-			profileDir: config.profileDir ?? join(os.homedir(), ".config", "joplin-mcp"),
-			apiPort: config.apiPort ?? DEFAULT_API_PORT,
+			profileDir: config.profileDir ?? join(Platform.homeDir(), ".config", "joplin-mcp"),
+			apiPort: config.apiPort ?? 41184,
 			apiToken: config.apiToken,
 			syncTarget: config.syncTarget,
-			syncInterval: config.syncInterval
+			syncInterval: config.syncInterval,
+			version: config.version
 		};
 	}
+	identity() {
+		return computeIdentityHash(this.config);
+	}
+	sidecarAlive() {
+		return servesOurProfile(this.config.profileDir);
+	}
+	async replaceStaleServer(port) {
+		const previous = readSidecarStamp(this.config.profileDir).fold(() => "unstamped", (s) => `v${s.version}`);
+		process.stderr.write(`[joplin-sidecar] Replacing sidecar on port ${port} (${previous} -> v${this.config.version ?? "unknown"} or changed sync config)\n`);
+		this.reapRecordedServer();
+		await this.waitForPortFree(port);
+	}
+	async waitForPortFree(port, maxAttempts = 20) {
+		const attempt = async (i) => {
+			if (i >= maxAttempts) {
+				process.stderr.write(`[joplin-sidecar] Port ${port} still busy after teardown, continuing anyway\n`);
+				return;
+			}
+			try {
+				await fetchWithTimeout(`http://127.0.0.1:${port}/ping`, 1e3);
+			} catch (err) {
+				if (isConnectionRefused(err)) return;
+			}
+			await new Promise((resolve) => setTimeout(resolve, 250));
+			return attempt(i + 1);
+		};
+		return attempt(0);
+	}
+	killChildSync() {
+		if (!this.childProcess) return;
+		try {
+			this.childProcess.kill("SIGTERM");
+		} catch {}
+		this.reapRecordedServer();
+	}
+	reapRecordedServer() {
+		readProfileServerPid(this.config.profileDir).fold(() => void 0, (pid) => {
+			if (pid !== process.pid && isProcessAlive(pid)) try {
+				process.kill(pid, "SIGTERM");
+			} catch {}
+		});
+	}
+	registerCleanup() {
+		if (this.cleanupRegistered) return;
+		this.cleanupRegistered = true;
+		process.once("exit", () => this.killChildSync());
+		process.once("SIGHUP", () => {
+			this.killChildSync();
+			process.exit(0);
+		});
+	}
 	async resolvePort() {
-		const resolution = await resolveAvailablePort(this.config.apiPort, this.config.apiToken);
+		const resolution = await resolveAvailablePort(this.config.apiPort, this.config.apiToken, this.config.profileDir, this.identity());
 		this.portResolution = resolution;
 		if (resolution.outcome === "exhausted") {
 			const lastPort = this.config.apiPort + MAX_PORT_ATTEMPTS - 1;
@@ -288,12 +407,18 @@ var JoplinSidecar = class {
 		return ((_this$portResolution = this.portResolution) === null || _this$portResolution === void 0 ? void 0 : _this$portResolution.outcome) !== "exhausted" && (((_this$portResolution2 = this.portResolution) === null || _this$portResolution2 === void 0 ? void 0 : _this$portResolution2.desktopDetected) ?? false);
 	}
 	async start() {
+		if (this.startPromise && !this.sidecarAlive()) {
+			process.stderr.write("[joplin-sidecar] Sidecar is no longer running, restarting\n");
+			this.startPromise = null;
+			this.childProcess = null;
+			this.portResolution = null;
+		}
 		if (this.startPromise) return this.startPromise;
 		this.startPromise = this.doStart();
 		return this.startPromise;
 	}
 	async doStart() {
-		var _this$portResolution3;
+		var _this$portResolution3, _this$portResolution4;
 		const cliResult = await findJoplinCli();
 		if (Either.isLeft(cliResult)) return Left(cliResult.fold((e) => e, () => null));
 		const cli = cliResult.fold(() => "", (v) => v);
@@ -303,9 +428,10 @@ var JoplinSidecar = class {
 			if (Either.isLeft(portResult)) return Left(portResult.fold((e) => e, () => null));
 		}
 		if (((_this$portResolution3 = this.portResolution) === null || _this$portResolution3 === void 0 ? void 0 : _this$portResolution3.outcome) === "reuse_existing") {
-			process.stderr.write(`[joplin-sidecar] Existing Joplin server with matching token on port ${this.config.apiPort}, reusing\n`);
+			process.stderr.write(`[joplin-sidecar] Existing Joplin server for this profile on port ${this.config.apiPort}, reusing\n`);
 			return Right(this.childProcess ?? null);
 		}
+		if (((_this$portResolution4 = this.portResolution) === null || _this$portResolution4 === void 0 ? void 0 : _this$portResolution4.outcome) === "replace_stale") await this.replaceStaleServer(this.config.apiPort);
 		const configHash = computeConfigHash(this.config);
 		if (isConfigCached(this.config.profileDir, configHash)) process.stderr.write("[joplin-sidecar] Configuration cached, skipping config step\n");
 		else {
@@ -319,10 +445,15 @@ var JoplinSidecar = class {
 			if (Either.isLeft(spawnResult)) return Left(spawnResult.fold((e) => e, () => null));
 			const proc = spawnResult.fold(() => null, (v) => v);
 			this.childProcess = proc;
+			this.registerCleanup();
 			process.stderr.write(`[joplin-sidecar] Server spawned (pid: ${proc.pid})\n`);
 		} else process.stderr.write(`[joplin-sidecar] Server already spawned (pid: ${this.childProcess.pid}), waiting for ready\n`);
 		const readyResult = await waitForReady(this.config.apiPort, this.config.apiToken, this.childProcess);
 		if (Either.isLeft(readyResult)) return Left(readyResult.fold((e) => e, () => null));
+		writeSidecarStamp(this.config.profileDir, {
+			version: this.config.version ?? "unknown",
+			identity: this.identity()
+		});
 		return Right(this.childProcess);
 	}
 	async stop() {
@@ -341,6 +472,7 @@ var JoplinSidecar = class {
 					resolve();
 				});
 			});
+			this.reapRecordedServer();
 			this.childProcess = null;
 			process.stderr.write("[joplin-sidecar] Server stopped\n");
 			return Right(true);
@@ -364,17 +496,9 @@ var JoplinSidecar = class {
 		return "127.0.0.1";
 	}
 };
-
 //#endregion
 //#region src/lib/parse-args.ts
 const expandVars = (p) => p.replace(/\$\{(\w+)\}/g, (_, name) => process.env[name] ?? "").replace(/\$(\w+)/g, (_, name) => process.env[name] ?? "");
-const isWsl = (() => {
-	try {
-		return fs.readFileSync("/proc/version", "utf-8").toLowerCase().includes("microsoft");
-	} catch {
-		return false;
-	}
-})();
 const isNonEmptyDir = (p) => {
 	try {
 		return fs.readdirSync(p).length > 0;
@@ -383,30 +507,21 @@ const isNonEmptyDir = (p) => {
 	}
 };
 const resolveWslPath = (linuxPath, relativeToHome) => {
-	if (!isWsl) return linuxPath;
+	if (!Platform.isWSL()) return linuxPath;
 	if (fs.existsSync(linuxPath) && isNonEmptyDir(linuxPath)) return linuxPath;
-	try {
-		const usersDir = "/mnt/c/Users";
-		const users = fs.readdirSync(usersDir).filter((u) => ![
-			"Public",
-			"Default",
-			"Default User",
-			"All Users"
-		].includes(u));
-		for (const user of users) {
-			const winPath = join(usersDir, user, relativeToHome);
-			if (isNonEmptyDir(winPath)) {
-				process.stderr.write(`[wsl] Path ${linuxPath} empty/missing, using Windows path: ${winPath}\n`);
-				return winPath;
-			}
-		}
-	} catch {}
-	return linuxPath;
+	return Platform.windowsHomeDir().map((winHome) => join(winHome, relativeToHome)).filter(isNonEmptyDir).map((winPath) => {
+		process.stderr.write(`[wsl] Path ${linuxPath} empty/missing, using Windows path: ${winPath}\n`);
+		return winPath;
+	}).orElse(linuxPath);
 };
 const expandPath = (p) => {
 	const expanded = expandVars(p);
-	if (expanded.startsWith("~/") || expanded === "~") return resolveWslPath(expanded.replace("~", os.homedir()), expanded.slice(2));
-	return expanded;
+	const tildeExpanded = Path.expandTilde(expanded);
+	if (expanded === "~" || expanded.startsWith("~/")) {
+		const relativeToHome = expanded === "~" ? "" : expanded.slice(2);
+		return resolveWslPath(tildeExpanded, relativeToHome);
+	}
+	return tildeExpanded;
 };
 const extractArg = (args, flag) => {
 	const index = args.indexOf(flag);
@@ -461,8 +576,6 @@ const buildSyncTarget = (args) => {
 };
 function parseArgs() {
 	const args = process.argv.slice(2);
-	let transport = "stdio";
-	let httpPort = 3e3;
 	const loadEnvFile = (envPath) => {
 		try {
 			if (fs.existsSync(envPath)) {
@@ -489,30 +602,32 @@ function parseArgs() {
 		}
 	};
 	extractArg(args, "--env-file").fold(() => loadEnvFile(".env"), (file) => loadEnvFile(resolve(process.cwd(), file)));
-	extractArg(args, "--token").fold(() => {}, (token) => {
-		process.env.JOPLIN_TOKEN = token;
-	});
-	extractArg(args, "--transport").fold(() => {}, (value) => {
+	const explicitToken = extractArg(args, "--token");
+	const transport = extractArg(args, "--transport").map((value) => {
 		if (value !== "stdio" && value !== "http") {
 			process.stderr.write("Error: --transport must be either 'stdio' or 'http'\n");
 			process.exit(1);
 		}
-		transport = value;
-	});
-	extractArg(args, "--http-port").fold(() => {}, (value) => {
+		return value;
+	}).orElse("stdio");
+	const httpPort = extractArg(args, "--http-port").map((value) => {
 		const parsed = parseInt(value, 10);
 		if (isNaN(parsed) || parsed < 1 || parsed > 65535) {
 			process.stderr.write("Error: --http-port must be a valid port number (1-65535)\n");
 			process.exit(1);
 		}
-		httpPort = parsed;
-	});
-	const profileDir = extractArg(args, "--profile").or(Option(process.env.JOPLIN_PROFILE)).map(expandPath).orElse(`${os.homedir()}/.config/joplin-mcp`);
+		return parsed;
+	}).orElse(3e3);
+	const profileDir = extractArg(args, "--profile").or(Option(process.env.JOPLIN_PROFILE)).map(expandPath).orElse(expandPath("~/.config/joplin-mcp"));
+	const syncTarget = extractArg(args, "--sync-target").or(Option(process.env.JOPLIN_SYNC_TARGET));
+	const syncPath = extractArg(args, "--sync-path").or(Option(process.env.JOPLIN_SYNC_PATH)).map(expandPath);
+	const syncUsername = extractArg(args, "--sync-username").or(Option(process.env.JOPLIN_SYNC_USERNAME));
+	const syncPassword = extractArg(args, "--sync-password").or(Option(process.env.JOPLIN_SYNC_PASSWORD));
 	const syncResult = buildSyncTarget({
-		syncTarget: extractArg(args, "--sync-target").or(Option(process.env.JOPLIN_SYNC_TARGET)),
-		syncPath: extractArg(args, "--sync-path").or(Option(process.env.JOPLIN_SYNC_PATH)).map(expandPath),
-		syncUsername: extractArg(args, "--sync-username").or(Option(process.env.JOPLIN_SYNC_USERNAME)),
-		syncPassword: extractArg(args, "--sync-password").or(Option(process.env.JOPLIN_SYNC_PASSWORD))
+		syncTarget,
+		syncPath,
+		syncUsername,
+		syncPassword
 	});
 	if (Either.isLeft(syncResult)) {
 		const err = syncResult.fold((e) => e, () => "");
@@ -542,7 +657,8 @@ OPTIONS:
   --help, -h                 Show this help message
 
 ENVIRONMENT VARIABLES:
-  JOPLIN_TOKEN               Joplin API token (required)
+  JOPLIN_TOKEN               API token for external mode (JOPLIN_HOST/JOPLIN_PORT).
+                             Ignored in sidecar mode, which manages its own token.
   JOPLIN_HOST                Connect to existing Joplin at this host (skips sidecar)
   JOPLIN_PORT                Connect to existing Joplin on this port (skips sidecar)
   JOPLIN_CLI                 Path to joplin CLI binary (overrides auto-detection)
@@ -597,113 +713,52 @@ Find your Joplin token in: Tools > Options > Web Clipper
 		transport,
 		httpPort,
 		profileDir,
-		syncTarget: resolvedSyncTarget
+		syncTarget: resolvedSyncTarget,
+		explicitToken
 	};
 }
-
 //#endregion
-//#region src/lib/joplin-api-client.ts
-var JoplinAPIClient = class {
-	baseURL;
-	token;
-	constructor({ host = "127.0.0.1", port = 41184, token }) {
-		this.baseURL = `http://${host}:${port}`;
-		this.token = token;
-	}
-	async serviceAvailable() {
-		try {
-			const response = await axios.get(`${this.baseURL}/ping`, { timeout: 5e3 });
-			if (response.status === 200 && response.data === "JoplinClipperServer") return Right(true);
-			return Left(/* @__PURE__ */ new Error("Unexpected response from Joplin ping"));
-		} catch (error) {
-			return Left(error instanceof Error ? error : new Error(String(error)));
-		}
-	}
-	async getAllItems(path, options = {}) {
-		let page = 1;
-		const items = [];
-		try {
-			while (true) {
-				const response = (await this.get(path, this.mergeRequestOptions(options, { query: { page } }))).fold((err) => {
-					throw err;
-				}, (data) => data);
-				if (!response || typeof response !== "object" || !Array.isArray(response.items)) return Left(/* @__PURE__ */ new Error(`Unexpected response format from Joplin API for path: ${path}`));
-				items.push(...response.items);
-				page += 1;
-				if (!response.has_more) break;
-			}
-			return Right(items);
-		} catch (error) {
-			process.stderr.write(`Error in getAllItems for path ${path}: ${error}\n`);
-			return Left(error instanceof Error ? error : new Error(String(error)));
-		}
-	}
-	async get(path, options = {}) {
-		try {
-			const { data } = await axios.get(`${this.baseURL}${path}`, {
-				params: this.requestOptions(options).query,
-				timeout: 3e4
-			});
-			return Right(data);
-		} catch (error) {
-			return Left(error instanceof Error ? error : new Error(String(error)));
-		}
-	}
-	async post(path, body, options = {}) {
-		try {
-			const { data } = await axios.post(`${this.baseURL}${path}`, body, {
-				params: this.requestOptions(options).query,
-				timeout: 3e4
-			});
-			return Right(data);
-		} catch (error) {
-			return Left(error instanceof Error ? error : new Error(String(error)));
-		}
-	}
-	async delete(path, options = {}) {
-		try {
-			const { data } = await axios.delete(`${this.baseURL}${path}`, {
-				params: this.requestOptions(options).query,
-				timeout: 3e4
-			});
-			return Right(data);
-		} catch (error) {
-			return Left(error instanceof Error ? error : new Error(String(error)));
-		}
-	}
-	async put(path, body, options = {}) {
-		try {
-			const { data } = await axios.put(`${this.baseURL}${path}`, body, {
-				params: this.requestOptions(options).query,
-				timeout: 3e4
-			});
-			return Right(data);
-		} catch (error) {
-			return Left(error instanceof Error ? error : new Error(String(error)));
-		}
-	}
-	requestOptions(options = {}) {
-		return this.mergeRequestOptions({ query: { token: this.token } }, options);
-	}
-	mergeRequestOptions(options1, options2) {
-		return {
-			query: {
-				...options1.query || {},
-				...options2.query || {}
-			},
-			...this.except(options1, "query"),
-			...this.except(options2, "query")
-		};
-	}
-	except(obj, key) {
-		const result = { ...obj };
-		delete result[key];
-		return result;
-	}
+//#region src/lib/resolve-token.ts
+const resolveTokenSource = (input) => {
+	if (input.explicitToken.isEmpty === false) return {
+		source: "explicit",
+		ambientIgnored: false
+	};
+	if (input.externalMode) return {
+		source: input.ambientToken.isEmpty === false ? "external-env" : "external-generated",
+		ambientIgnored: false
+	};
+	return {
+		source: "profile",
+		ambientIgnored: input.ambientToken.isEmpty === false
+	};
 };
-
+const externalTokenMissing = (input) => input.externalMode && input.explicitToken.isEmpty && input.ambientToken.isEmpty;
 //#endregion
 //#region src/lib/tools/base-tool.ts
+/**
+* Thrown by tools to signal an operation failure that should surface to the
+* caller (and the LLM agent) as an MCP error response (isError: true), rather
+* than being silently returned as a "successful" text result.
+*/
+var ToolError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "ToolError";
+	}
+};
+/**
+* Extract a Joplin-style error message from an API response body. Joplin can
+* return HTTP 200 with `{ error: "..." }` (or `{ error: ..., code: ... }`)
+* when an operation fails — without this check the tool would treat the
+* malformed payload as a success.
+*/
+const extractJoplinErrorMessage = (data) => {
+	if (data !== null && typeof data === "object" && "error" in data) {
+		const err = data.error;
+		if (typeof err === "string" && err.length > 0) return err;
+	}
+};
 var BaseTool = class {
 	apiClient;
 	constructor(apiClient) {
@@ -711,7 +766,8 @@ var BaseTool = class {
 	}
 	formatError(error, context) {
 		process.stderr.write(`${context} error: ${error}\n`);
-		return `Error ${context.toLowerCase()}: ${error.message || "Unknown error"}`;
+		const message = error instanceof Error ? error.message : "Unknown error";
+		return `Error ${context.toLowerCase()}: ${message}`;
 	}
 	validateId(id, type) {
 		if (!id) return `Please provide a ${type} ID. Example: ${type === "note" ? "read_note" : "read_notebook"} ${type}_id="your-${type}-id"`;
@@ -730,7 +786,6 @@ var BaseTool = class {
 		return new Date(timestamp).toLocaleString();
 	}
 };
-
 //#endregion
 //#region src/lib/tools/create-folder.ts
 var CreateFolder = class extends BaseTool {
@@ -742,14 +797,19 @@ var CreateFolder = class extends BaseTool {
 			const requestBody = { title: options.title.trim() };
 			if (options.parent_id) requestBody.parent_id = options.parent_id;
 			const createdFolder = this.unwrap(await this.apiClient.post("/folders", requestBody));
-			if (!createdFolder || typeof createdFolder !== "object" || !createdFolder.id) return "Error: Unexpected response format from Joplin API when creating folder";
-			let parentInfo = "Top level";
-			if (createdFolder.parent_id) try {
-				const parentNotebook = this.unwrap(await this.apiClient.get(`/folders/${createdFolder.parent_id}`, { query: { fields: "id,title" } }));
-				if (parentNotebook && parentNotebook.title) parentInfo = `Inside "${parentNotebook.title}" (notebook_id: "${createdFolder.parent_id}")`;
-			} catch {
-				parentInfo = `Parent notebook ID: ${createdFolder.parent_id}`;
-			}
+			const joplinError = extractJoplinErrorMessage(createdFolder);
+			if (joplinError !== void 0) throw new ToolError(`Failed to create notebook: ${joplinError}`);
+			if (!createdFolder || typeof createdFolder !== "object" || !createdFolder.id) throw new ToolError(`Failed to create notebook: Joplin API returned an unexpected response (no folder id). Raw response: ${JSON.stringify(createdFolder)}`);
+			const parentInfo = await (async () => {
+				if (!createdFolder.parent_id) return "Top level";
+				try {
+					const parentNotebook = this.unwrap(await this.apiClient.get(`/folders/${createdFolder.parent_id}`, { query: { fields: "id,title" } }));
+					if (parentNotebook === null || parentNotebook === void 0 ? void 0 : parentNotebook.title) return `Inside "${parentNotebook.title}" (notebook_id: "${createdFolder.parent_id}")`;
+					return `Parent notebook ID: ${createdFolder.parent_id}`;
+				} catch {
+					return `Parent notebook ID: ${createdFolder.parent_id}`;
+				}
+			})();
 			const resultLines = [];
 			resultLines.push(`✅ Successfully created notebook!`);
 			resultLines.push("");
@@ -766,19 +826,21 @@ var CreateFolder = class extends BaseTool {
 			resultLines.push(`   - View all notebooks: list_notebooks`);
 			return resultLines.join("\n");
 		} catch (error) {
-			if (error.response) {
-				if (error.response.status === 400) {
-					var _error$response$data;
-					return `Error creating notebook: Invalid request data.\n\nPlease check your input parameters. ${((_error$response$data = error.response.data) === null || _error$response$data === void 0 ? void 0 : _error$response$data.error) || ""}`;
+			if (error instanceof ToolError) throw error;
+			const err = error;
+			process.stderr.write(`creating notebook error: ${error}\n`);
+			if (err.response) {
+				if (err.response.status === 400) {
+					var _err$response$data;
+					throw new ToolError(`Failed to create notebook: Invalid request data. ${((_err$response$data = err.response.data) === null || _err$response$data === void 0 ? void 0 : _err$response$data.error) ?? "Please check your input parameters."}`);
 				}
-				if (error.response.status === 404 && options.parent_id) return `Error: Parent notebook with ID "${options.parent_id}" not found.\n\nUse list_notebooks to see available notebooks and their IDs, or omit parent_id to create a top-level notebook.`;
-				if (error.response.status === 409) return `Error: A notebook with the title "${options.title}" might already exist in this location.\n\nTry a different title or check existing notebooks with list_notebooks.`;
+				if (err.response.status === 404 && options.parent_id !== void 0) throw new ToolError(`Failed to create notebook: Parent notebook with ID "${options.parent_id}" not found. Use list_notebooks to see available notebooks and their IDs, or omit parent_id to create a top-level notebook.`);
+				if (err.response.status === 409) throw new ToolError(`Failed to create notebook: A notebook with the title "${options.title}" might already exist in this location. Try a different title or check existing notebooks with list_notebooks.`);
 			}
-			return this.formatError(error, "creating notebook");
+			throw new ToolError(`Failed to create notebook: ${error instanceof Error ? error.message : "Unknown error"}`);
 		}
 	}
 };
-
 //#endregion
 //#region src/lib/tools/create-note.ts
 var CreateNote = class extends BaseTool {
@@ -795,14 +857,19 @@ var CreateNote = class extends BaseTool {
 			if (options.is_todo !== void 0) requestBody.is_todo = options.is_todo;
 			if (options.image_data_url) requestBody.image_data_url = options.image_data_url;
 			const createdNote = this.unwrap(await this.apiClient.post("/notes", requestBody));
-			if (!createdNote || typeof createdNote !== "object" || !createdNote.id) return "Error: Unexpected response format from Joplin API when creating note";
-			let notebookInfo = "Root level";
-			if (createdNote.parent_id) try {
-				const notebook = this.unwrap(await this.apiClient.get(`/folders/${createdNote.parent_id}`, { query: { fields: "id,title" } }));
-				if (notebook && notebook.title) notebookInfo = `"${notebook.title}" (notebook_id: "${createdNote.parent_id}")`;
-			} catch {
-				notebookInfo = `Notebook ID: ${createdNote.parent_id}`;
-			}
+			const joplinError = extractJoplinErrorMessage(createdNote);
+			if (joplinError !== void 0) throw new ToolError(`Failed to create note: ${joplinError}`);
+			if (!createdNote || typeof createdNote !== "object" || !createdNote.id) throw new ToolError(`Failed to create note: Joplin API returned an unexpected response (no note id). Raw response: ${JSON.stringify(createdNote)}`);
+			const notebookInfo = await (async () => {
+				if (!createdNote.parent_id) return "Root level";
+				try {
+					const notebook = this.unwrap(await this.apiClient.get(`/folders/${createdNote.parent_id}`, { query: { fields: "id,title" } }));
+					if (notebook === null || notebook === void 0 ? void 0 : notebook.title) return `"${notebook.title}" (notebook_id: "${createdNote.parent_id}")`;
+					return `Notebook ID: ${createdNote.parent_id}`;
+				} catch {
+					return `Notebook ID: ${createdNote.parent_id}`;
+				}
+			})();
 			const resultLines = [];
 			resultLines.push(`✅ Successfully created note!`);
 			resultLines.push("");
@@ -820,18 +887,20 @@ var CreateNote = class extends BaseTool {
 			resultLines.push(`   - Search for it: search_notes query="${createdNote.title}"`);
 			return resultLines.join("\n");
 		} catch (error) {
-			if (error.response) {
-				if (error.response.status === 400) {
-					var _error$response$data;
-					return `Error creating note: Invalid request data.\n\nPlease check your input parameters. ${((_error$response$data = error.response.data) === null || _error$response$data === void 0 ? void 0 : _error$response$data.error) || ""}`;
+			if (error instanceof ToolError) throw error;
+			const err = error;
+			process.stderr.write(`creating note error: ${error}\n`);
+			if (err.response) {
+				if (err.response.status === 400) {
+					var _err$response$data;
+					throw new ToolError(`Failed to create note: Invalid request data. ${((_err$response$data = err.response.data) === null || _err$response$data === void 0 ? void 0 : _err$response$data.error) ?? "Please check your input parameters."}`);
 				}
-				if (error.response.status === 404 && options.parent_id) return `Error: Notebook with ID "${options.parent_id}" not found.\n\nUse list_notebooks to see available notebooks and their IDs.`;
+				if (err.response.status === 404 && options.parent_id !== void 0) throw new ToolError(`Failed to create note: Notebook with ID "${options.parent_id}" not found. Use list_notebooks to see available notebooks and their IDs.`);
 			}
-			return this.formatError(error, "creating note");
+			throw new ToolError(`Failed to create note: ${error instanceof Error ? error.message : "Unknown error"}`);
 		}
 	}
 };
-
 //#endregion
 //#region src/lib/tools/delete-folder.ts
 var DeleteFolder = class extends BaseTool {
@@ -842,15 +911,13 @@ var DeleteFolder = class extends BaseTool {
 		if (folderIdError) return folderIdError.replace("notebook ID", "folder ID").replace("notebook_id", "folder_id");
 		if (!options.confirm) return `⚠️  This will permanently delete the notebook/folder!\n\nTo confirm deletion, use:\ndelete_folder {"folder_id": "${options.folder_id}", "confirm": true}\n\n⚠️  This action cannot be undone!`;
 		try {
-			var _notes$items, _subfolders$items;
 			const folderToDelete = this.unwrap(await this.apiClient.get(`/folders/${options.folder_id}`, { query: { fields: "id,title,parent_id" } }));
-			if (!folderToDelete || !folderToDelete.id) return `Folder with ID "${options.folder_id}" not found.\n\nUse list_notebooks to see available folders and their IDs.`;
-			const [notes, subfolders] = await Promise.all([this.apiClient.get(`/folders/${options.folder_id}/notes`, { query: { fields: "id,title" } }).then((result) => result.fold(() => ({ items: [] }), (data) => data)), this.apiClient.get("/folders", { query: { fields: "id,title,parent_id" } }).then((result) => result.fold(() => ({ items: [] }), (response) => {
-				var _response$items;
-				return { items: ((_response$items = response.items) === null || _response$items === void 0 ? void 0 : _response$items.filter((folder) => folder.parent_id === options.folder_id)) || [] };
-			}))]);
-			const noteCount = ((_notes$items = notes.items) === null || _notes$items === void 0 ? void 0 : _notes$items.length) || 0;
-			const subfolderCount = ((_subfolders$items = subfolders.items) === null || _subfolders$items === void 0 ? void 0 : _subfolders$items.length) || 0;
+			const folderLoadError = extractJoplinErrorMessage(folderToDelete);
+			if (folderLoadError !== void 0) throw new ToolError(`Failed to load folder "${options.folder_id}": ${folderLoadError}`);
+			if (!(folderToDelete === null || folderToDelete === void 0 ? void 0 : folderToDelete.id)) throw new ToolError(`Folder with ID "${options.folder_id}" not found. Use list_notebooks to see available folders and their IDs.`);
+			const [notes, subfolders] = await Promise.all([this.apiClient.get(`/folders/${options.folder_id}/notes`, { query: { fields: "id,title" } }).then((result) => result.fold(() => ({ items: [] }), (data) => data)), this.apiClient.get("/folders", { query: { fields: "id,title,parent_id" } }).then((result) => result.fold(() => ({ items: [] }), (response) => ({ items: response.items.filter((folder) => folder.parent_id === options.folder_id) })))]);
+			const noteCount = notes.items.length;
+			const subfolderCount = subfolders.items.length;
 			const totalContent = noteCount + subfolderCount;
 			if (totalContent > 0 && !options.force) {
 				const resultLines = [];
@@ -862,7 +929,7 @@ var DeleteFolder = class extends BaseTool {
 					resultLines.push("");
 					resultLines.push(`📝 Contains ${noteCount} notes:`);
 					notes.items.slice(0, 5).forEach((note) => {
-						resultLines.push(`   - ${note.title || "Untitled"}`);
+						resultLines.push(`   - ${note.title ?? "Untitled"}`);
 					});
 					if (noteCount > 5) resultLines.push(`   ... and ${noteCount - 5} more notes`);
 				}
@@ -870,7 +937,7 @@ var DeleteFolder = class extends BaseTool {
 					resultLines.push("");
 					resultLines.push(`📁 Contains ${subfolderCount} subfolders:`);
 					subfolders.items.slice(0, 5).forEach((folder) => {
-						resultLines.push(`   - ${folder.title}`);
+						resultLines.push(`   - ${folder.title ?? "Untitled"}`);
 					});
 					if (subfolderCount > 5) resultLines.push(`   ... and ${subfolderCount - 5} more folders`);
 				}
@@ -883,14 +950,18 @@ var DeleteFolder = class extends BaseTool {
 				resultLines.push(`⚠️  Force delete will permanently delete ALL ${totalContent} items inside!`);
 				return resultLines.join("\n");
 			}
-			let parentInfo = "Top level";
-			if (folderToDelete.parent_id) try {
-				const parentFolder = this.unwrap(await this.apiClient.get(`/folders/${folderToDelete.parent_id}`, { query: { fields: "title" } }));
-				if (parentFolder === null || parentFolder === void 0 ? void 0 : parentFolder.title) parentInfo = `Inside "${parentFolder.title}" (notebook_id: "${folderToDelete.parent_id}")`;
-			} catch {
-				parentInfo = `Parent ID: ${folderToDelete.parent_id}`;
-			}
-			this.unwrap(await this.apiClient.delete(`/folders/${options.folder_id}`));
+			const parentInfo = await (async () => {
+				if (!folderToDelete.parent_id) return "Top level";
+				try {
+					const parentFolder = this.unwrap(await this.apiClient.get(`/folders/${folderToDelete.parent_id}`, { query: { fields: "title" } }));
+					if (parentFolder === null || parentFolder === void 0 ? void 0 : parentFolder.title) return `Inside "${parentFolder.title}" (notebook_id: "${folderToDelete.parent_id}")`;
+					return `Parent ID: ${folderToDelete.parent_id}`;
+				} catch {
+					return `Parent ID: ${folderToDelete.parent_id}`;
+				}
+			})();
+			const deleteError = extractJoplinErrorMessage(this.unwrap(await this.apiClient.delete(`/folders/${options.folder_id}`)));
+			if (deleteError !== void 0) throw new ToolError(`Failed to delete folder: ${deleteError}`);
 			const resultLines = [];
 			resultLines.push(`🗑️  Successfully deleted notebook!`);
 			resultLines.push("");
@@ -913,16 +984,18 @@ var DeleteFolder = class extends BaseTool {
 			}
 			return resultLines.join("\n");
 		} catch (error) {
-			if (error.response) {
-				if (error.response.status === 404) return `Folder with ID "${options.folder_id}" not found.\n\nUse list_notebooks to see available folders and their IDs.`;
-				if (error.response.status === 403) return `Permission denied: Cannot delete folder with ID "${options.folder_id}".\n\nThis might be a protected system folder.`;
-				if (error.response.status === 409) return `Cannot delete folder: It may contain items that prevent deletion.\n\nTry moving or deleting the contents first, or use force option.`;
+			if (error instanceof ToolError) throw error;
+			const err = error;
+			process.stderr.write(`deleting folder error: ${error}\n`);
+			if (err.response) {
+				if (err.response.status === 404) throw new ToolError(`Failed to delete folder: Folder with ID "${options.folder_id}" not found. Use list_notebooks to see available folders and their IDs.`);
+				if (err.response.status === 403) throw new ToolError(`Failed to delete folder: Permission denied for folder with ID "${options.folder_id}". This might be a protected system folder.`);
+				if (err.response.status === 409) throw new ToolError(`Failed to delete folder: It may contain items that prevent deletion. Try moving or deleting the contents first, or use force option.`);
 			}
-			return this.formatError(error, "deleting folder");
+			throw new ToolError(`Failed to delete folder: ${error instanceof Error ? error.message : "Unknown error"}`);
 		}
 	}
 };
-
 //#endregion
 //#region src/lib/tools/delete-note.ts
 var DeleteNote = class extends BaseTool {
@@ -934,15 +1007,21 @@ var DeleteNote = class extends BaseTool {
 		if (!options.confirm) return `⚠️  This will permanently delete the note!\n\nTo confirm deletion, use:\ndelete_note {"note_id": "${options.note_id}", "confirm": true}\n\n⚠️  This action cannot be undone!`;
 		try {
 			const noteToDelete = this.unwrap(await this.apiClient.get(`/notes/${options.note_id}`, { query: { fields: "id,title,body,parent_id,is_todo,todo_completed,created_time,updated_time" } }));
-			if (!noteToDelete || !noteToDelete.id) return `Note with ID "${options.note_id}" not found.\n\nUse search_notes to find notes and their IDs.`;
-			let notebookInfo = "Root level";
-			if (noteToDelete.parent_id) try {
-				const notebook = this.unwrap(await this.apiClient.get(`/folders/${noteToDelete.parent_id}`, { query: { fields: "title" } }));
-				if (notebook === null || notebook === void 0 ? void 0 : notebook.title) notebookInfo = `"${notebook.title}" (notebook_id: "${noteToDelete.parent_id}")`;
-			} catch {
-				notebookInfo = `Notebook ID: ${noteToDelete.parent_id}`;
-			}
-			this.unwrap(await this.apiClient.delete(`/notes/${options.note_id}`));
+			const noteLoadError = extractJoplinErrorMessage(noteToDelete);
+			if (noteLoadError !== void 0) throw new ToolError(`Failed to load note "${options.note_id}": ${noteLoadError}`);
+			if (!(noteToDelete === null || noteToDelete === void 0 ? void 0 : noteToDelete.id)) throw new ToolError(`Note with ID "${options.note_id}" not found. Use search_notes to find notes and their IDs.`);
+			const notebookInfo = await (async () => {
+				if (!noteToDelete.parent_id) return "Root level";
+				try {
+					const notebook = this.unwrap(await this.apiClient.get(`/folders/${noteToDelete.parent_id}`, { query: { fields: "title" } }));
+					if (notebook === null || notebook === void 0 ? void 0 : notebook.title) return `"${notebook.title}" (notebook_id: "${noteToDelete.parent_id}")`;
+					return `Notebook ID: ${noteToDelete.parent_id}`;
+				} catch {
+					return `Notebook ID: ${noteToDelete.parent_id}`;
+				}
+			})();
+			const deleteError = extractJoplinErrorMessage(this.unwrap(await this.apiClient.delete(`/notes/${options.note_id}`)));
+			if (deleteError !== void 0) throw new ToolError(`Failed to delete note: ${deleteError}`);
 			const resultLines = [];
 			resultLines.push(`🗑️  Successfully deleted note!`);
 			resultLines.push("");
@@ -973,15 +1052,17 @@ var DeleteNote = class extends BaseTool {
 			}
 			return resultLines.join("\n");
 		} catch (error) {
-			if (error.response) {
-				if (error.response.status === 404) return `Note with ID "${options.note_id}" not found.\n\nUse search_notes to find notes and their IDs.`;
-				if (error.response.status === 403) return `Permission denied: Cannot delete note with ID "${options.note_id}".\n\nThis might be a protected system note.`;
+			if (error instanceof ToolError) throw error;
+			const err = error;
+			process.stderr.write(`deleting note error: ${error}\n`);
+			if (err.response) {
+				if (err.response.status === 404) throw new ToolError(`Failed to delete note: Note with ID "${options.note_id}" not found. Use search_notes to find notes and their IDs.`);
+				if (err.response.status === 403) throw new ToolError(`Failed to delete note: Permission denied for note with ID "${options.note_id}". This might be a protected system note.`);
 			}
-			return this.formatError(error, "deleting note");
+			throw new ToolError(`Failed to delete note: ${error instanceof Error ? error.message : "Unknown error"}`);
 		}
 	}
 };
-
 //#endregion
 //#region src/lib/tools/edit-folder.ts
 var EditFolder = class extends BaseTool {
@@ -998,27 +1079,31 @@ var EditFolder = class extends BaseTool {
 		}
 		try {
 			const currentFolder = this.unwrap(await this.apiClient.get(`/folders/${options.folder_id}`, { query: { fields: "id,title,parent_id" } }));
-			if (!currentFolder || !currentFolder.id) return `Folder with ID "${options.folder_id}" not found.\n\nUse list_notebooks to see available folders and their IDs.`;
+			const currentFolderError = extractJoplinErrorMessage(currentFolder);
+			if (currentFolderError !== void 0) throw new ToolError(`Failed to load folder "${options.folder_id}": ${currentFolderError}`);
+			if (!(currentFolder === null || currentFolder === void 0 ? void 0 : currentFolder.id)) throw new ToolError(`Folder with ID "${options.folder_id}" not found. Use list_notebooks to see available folders and their IDs.`);
 			const updateBody = {};
 			if (options.title !== void 0) updateBody.title = options.title.trim();
 			if (options.parent_id !== void 0) updateBody.parent_id = options.parent_id;
 			const updatedFolder = this.unwrap(await this.apiClient.put(`/folders/${options.folder_id}`, updateBody));
-			if (!updatedFolder || typeof updatedFolder !== "object" || !updatedFolder.id) return "Error: Unexpected response format from Joplin API when updating folder";
-			let oldParentInfo = "Top level";
-			let newParentInfo = "Top level";
-			if (currentFolder.parent_id) try {
-				const oldParent = this.unwrap(await this.apiClient.get(`/folders/${currentFolder.parent_id}`, { query: { fields: "title" } }));
-				if (oldParent === null || oldParent === void 0 ? void 0 : oldParent.title) oldParentInfo = `Inside "${oldParent.title}"`;
-			} catch {
-				oldParentInfo = `Parent ID: ${currentFolder.parent_id}`;
-			}
-			if (updatedFolder.parent_id && updatedFolder.parent_id !== currentFolder.parent_id) try {
-				const newParent = this.unwrap(await this.apiClient.get(`/folders/${updatedFolder.parent_id}`, { query: { fields: "title" } }));
-				if (newParent === null || newParent === void 0 ? void 0 : newParent.title) newParentInfo = `Inside "${newParent.title}"`;
-			} catch {
-				newParentInfo = `Parent ID: ${updatedFolder.parent_id}`;
-			}
-			else if (updatedFolder.parent_id) newParentInfo = oldParentInfo;
+			const joplinError = extractJoplinErrorMessage(updatedFolder);
+			if (joplinError !== void 0) throw new ToolError(`Failed to update folder: ${joplinError}`);
+			if (!updatedFolder || typeof updatedFolder !== "object" || !updatedFolder.id) throw new ToolError(`Failed to update folder: Joplin API returned an unexpected response (no folder id). Raw response: ${JSON.stringify(updatedFolder)}`);
+			const fetchParentInfo = async (parentId) => {
+				try {
+					const parent = this.unwrap(await this.apiClient.get(`/folders/${parentId}`, { query: { fields: "title" } }));
+					if (parent === null || parent === void 0 ? void 0 : parent.title) return `Inside "${parent.title}"`;
+					return `Parent ID: ${parentId}`;
+				} catch {
+					return `Parent ID: ${parentId}`;
+				}
+			};
+			const oldParentInfo = currentFolder.parent_id ? await fetchParentInfo(currentFolder.parent_id) : "Top level";
+			const newParentInfo = await (async () => {
+				if (!updatedFolder.parent_id) return "Top level";
+				if (updatedFolder.parent_id === currentFolder.parent_id) return oldParentInfo;
+				return fetchParentInfo(updatedFolder.parent_id);
+			})();
 			const resultLines = [];
 			resultLines.push(`✅ Successfully updated notebook!`);
 			resultLines.push("");
@@ -1039,23 +1124,25 @@ var EditFolder = class extends BaseTool {
 			if (updatedFolder.parent_id) resultLines.push(`   - View parent notebook: read_notebook notebook_id="${updatedFolder.parent_id}"`);
 			return resultLines.join("\n");
 		} catch (error) {
-			if (error.response) {
-				if (error.response.status === 404) {
-					var _error$config;
-					if ((_error$config = error.config) === null || _error$config === void 0 || (_error$config = _error$config.url) === null || _error$config === void 0 ? void 0 : _error$config.includes(`/folders/${options.folder_id}`)) return `Folder with ID "${options.folder_id}" not found.\n\nUse list_notebooks to see available folders and their IDs.`;
-					if (options.parent_id) return `Error: Parent folder with ID "${options.parent_id}" not found.\n\nUse list_notebooks to see available folders and their IDs.`;
+			if (error instanceof ToolError) throw error;
+			const err = error;
+			process.stderr.write(`updating folder error: ${error}\n`);
+			if (err.response) {
+				if (err.response.status === 404) {
+					var _err$config;
+					if (((_err$config = err.config) === null || _err$config === void 0 || (_err$config = _err$config.url) === null || _err$config === void 0 ? void 0 : _err$config.includes(`/folders/${options.folder_id}`)) === true) throw new ToolError(`Failed to update folder: Folder with ID "${options.folder_id}" not found. Use list_notebooks to see available folders and their IDs.`);
+					if (options.parent_id !== void 0) throw new ToolError(`Failed to update folder: Parent folder with ID "${options.parent_id}" not found. Use list_notebooks to see available folders and their IDs.`);
 				}
-				if (error.response.status === 400) {
-					var _error$response$data;
-					return `Error updating folder: Invalid request data.\n\nPlease check your input parameters. ${((_error$response$data = error.response.data) === null || _error$response$data === void 0 ? void 0 : _error$response$data.error) || ""}`;
+				if (err.response.status === 400) {
+					var _err$response$data;
+					throw new ToolError(`Failed to update folder: Invalid request data. ${((_err$response$data = err.response.data) === null || _err$response$data === void 0 ? void 0 : _err$response$data.error) ?? "Please check your input parameters."}`);
 				}
-				if (error.response.status === 409) return `Error: A folder with the title "${options.title}" might already exist in this location.\n\nTry a different title or check existing folders with list_notebooks.`;
+				if (err.response.status === 409) throw new ToolError(`Failed to update folder: A folder with the title "${options.title ?? ""}" might already exist in this location. Try a different title or check existing folders with list_notebooks.`);
 			}
-			return this.formatError(error, "updating folder");
+			throw new ToolError(`Failed to update folder: ${error instanceof Error ? error.message : "Unknown error"}`);
 		}
 	}
 };
-
 //#endregion
 //#region src/lib/tools/edit-note.ts
 var EditNote = class extends BaseTool {
@@ -1078,7 +1165,9 @@ var EditNote = class extends BaseTool {
 		}
 		try {
 			const currentNote = this.unwrap(await this.apiClient.get(`/notes/${options.note_id}`, { query: { fields: "id,title,body,parent_id,is_todo,todo_completed,todo_due,updated_time" } }));
-			if (!currentNote || !currentNote.id) return `Note with ID "${options.note_id}" not found.\n\nUse search_notes to find notes and their IDs.`;
+			const currentNoteError = extractJoplinErrorMessage(currentNote);
+			if (currentNoteError !== void 0) throw new ToolError(`Failed to load note "${options.note_id}": ${currentNoteError}`);
+			if (!(currentNote === null || currentNote === void 0 ? void 0 : currentNote.id)) throw new ToolError(`Note with ID "${options.note_id}" not found. Use search_notes to find notes and their IDs.`);
 			const updateBody = {};
 			if (options.title !== void 0) updateBody.title = options.title;
 			if (options.body !== void 0) updateBody.body = options.body;
@@ -1088,22 +1177,24 @@ var EditNote = class extends BaseTool {
 			if (options.todo_completed !== void 0) updateBody.todo_completed = options.todo_completed;
 			if (options.todo_due !== void 0) updateBody.todo_due = options.todo_due;
 			const updatedNote = this.unwrap(await this.apiClient.put(`/notes/${options.note_id}`, updateBody));
-			if (!updatedNote || typeof updatedNote !== "object" || !updatedNote.id) return "Error: Unexpected response format from Joplin API when updating note";
-			let oldNotebookInfo = "Root level";
-			let newNotebookInfo = "Root level";
-			if (currentNote.parent_id) try {
-				const oldNotebook = this.unwrap(await this.apiClient.get(`/folders/${currentNote.parent_id}`, { query: { fields: "title" } }));
-				if (oldNotebook === null || oldNotebook === void 0 ? void 0 : oldNotebook.title) oldNotebookInfo = `"${oldNotebook.title}"`;
-			} catch {
-				oldNotebookInfo = `Notebook ID: ${currentNote.parent_id}`;
-			}
-			if (updatedNote.parent_id && updatedNote.parent_id !== currentNote.parent_id) try {
-				const newNotebook = this.unwrap(await this.apiClient.get(`/folders/${updatedNote.parent_id}`, { query: { fields: "title" } }));
-				if (newNotebook === null || newNotebook === void 0 ? void 0 : newNotebook.title) newNotebookInfo = `"${newNotebook.title}"`;
-			} catch {
-				newNotebookInfo = `Notebook ID: ${updatedNote.parent_id}`;
-			}
-			else if (updatedNote.parent_id) newNotebookInfo = oldNotebookInfo;
+			const joplinError = extractJoplinErrorMessage(updatedNote);
+			if (joplinError !== void 0) throw new ToolError(`Failed to update note: ${joplinError}`);
+			if (!updatedNote || typeof updatedNote !== "object" || !updatedNote.id) throw new ToolError(`Failed to update note: Joplin API returned an unexpected response (no note id). Raw response: ${JSON.stringify(updatedNote)}`);
+			const fetchNotebookInfo = async (parentId) => {
+				try {
+					const notebook = this.unwrap(await this.apiClient.get(`/folders/${parentId}`, { query: { fields: "title" } }));
+					if (notebook === null || notebook === void 0 ? void 0 : notebook.title) return `"${notebook.title}"`;
+					return `Notebook ID: ${parentId}`;
+				} catch {
+					return `Notebook ID: ${parentId}`;
+				}
+			};
+			const oldNotebookInfo = currentNote.parent_id ? await fetchNotebookInfo(currentNote.parent_id) : "Root level";
+			const newNotebookInfo = await (async () => {
+				if (!updatedNote.parent_id) return "Root level";
+				if (updatedNote.parent_id === currentNote.parent_id) return oldNotebookInfo;
+				return fetchNotebookInfo(updatedNote.parent_id);
+			})();
 			const resultLines = [];
 			resultLines.push(`✅ Successfully updated note!`);
 			resultLines.push("");
@@ -1138,19 +1229,21 @@ var EditNote = class extends BaseTool {
 			if (updatedNote.parent_id) resultLines.push(`   - View notebook: read_notebook notebook_id="${updatedNote.parent_id}"`);
 			return resultLines.join("\n");
 		} catch (error) {
-			if (error.response) {
-				if (error.response.status === 404) return `Note with ID "${options.note_id}" not found.\n\nUse search_notes to find notes and their IDs.`;
-				if (error.response.status === 400) {
-					var _error$response$data;
-					return `Error updating note: Invalid request data.\n\nPlease check your input parameters. ${((_error$response$data = error.response.data) === null || _error$response$data === void 0 ? void 0 : _error$response$data.error) || ""}`;
+			if (error instanceof ToolError) throw error;
+			const err = error;
+			process.stderr.write(`updating note error: ${error}\n`);
+			if (err.response) {
+				if (err.response.status === 404 && options.parent_id !== void 0) throw new ToolError(`Failed to update note: Notebook with ID "${options.parent_id}" not found. Use list_notebooks to see available notebooks and their IDs.`);
+				if (err.response.status === 404) throw new ToolError(`Failed to update note: Note with ID "${options.note_id}" not found. Use search_notes to find notes and their IDs.`);
+				if (err.response.status === 400) {
+					var _err$response$data;
+					throw new ToolError(`Failed to update note: Invalid request data. ${((_err$response$data = err.response.data) === null || _err$response$data === void 0 ? void 0 : _err$response$data.error) ?? "Please check your input parameters."}`);
 				}
-				if (error.response.status === 404 && options.parent_id) return `Error: Notebook with ID "${options.parent_id}" not found.\n\nUse list_notebooks to see available notebooks and their IDs.`;
 			}
-			return this.formatError(error, "updating note");
+			throw new ToolError(`Failed to update note: ${error instanceof Error ? error.message : "Unknown error"}`);
 		}
 	}
 };
-
 //#endregion
 //#region src/lib/tools/list-notebooks.ts
 var ListNotebooks = class extends BaseTool {
@@ -1159,7 +1252,7 @@ var ListNotebooks = class extends BaseTool {
 			const notebooks = this.unwrap(await this.apiClient.getAllItems("/folders", { query: { fields: "id,title,parent_id" } }));
 			const notebooksByParentId = {};
 			notebooks.forEach((notebook) => {
-				const parentId = notebook.parent_id || "";
+				const parentId = notebook.parent_id ?? "";
 				if (!notebooksByParentId[parentId]) notebooksByParentId[parentId] = [];
 				notebooksByParentId[parentId].push(notebook);
 			});
@@ -1168,20 +1261,22 @@ var ListNotebooks = class extends BaseTool {
 				"NOTE: To read a notebook, use the notebook_id with the read_notebook command\n",
 				"Example: read_notebook notebook_id=\"your-notebook-id\"\n\n"
 			];
-			resultLines.push(...this.notebooksLines(notebooksByParentId[""] || [], {
+			resultLines.push(...this.notebooksLines(notebooksByParentId[""] ?? [], {
 				indent: 0,
 				notebooksByParentId
 			}));
 			return resultLines.join("");
 		} catch (error) {
-			return this.formatError(error, "listing notebooks");
+			if (error instanceof ToolError) throw error;
+			process.stderr.write(`listing notebooks error: ${error}\n`);
+			throw new ToolError(`Failed to list notebooks: ${error instanceof Error ? error.message : "Unknown error"}`);
 		}
 	}
 	notebooksLines(notebooks, { indent = 0, notebooksByParentId }) {
 		const result = [];
 		const indentSpaces = " ".repeat(indent);
 		this.sortNotebooks(notebooks).forEach((notebook) => {
-			const id = notebook.id;
+			const { id } = notebook;
 			result.push(`${indentSpaces}Notebook: "${notebook.title}" (notebook_id: "${id}")\n`);
 			const childNotebooks = notebooksByParentId[id];
 			if (childNotebooks) result.push(...this.notebooksLines(childNotebooks, {
@@ -1200,7 +1295,6 @@ var ListNotebooks = class extends BaseTool {
 		});
 	}
 };
-
 //#endregion
 //#region src/lib/tools/read-multi-note.ts
 var ReadMultiNote = class extends BaseTool {
@@ -1213,8 +1307,7 @@ var ReadMultiNote = class extends BaseTool {
 		const errors = [];
 		const successful = [];
 		resultLines.push(`# Reading ${noteIds.length} notes\n`);
-		for (let i = 0; i < noteIds.length; i++) {
-			const noteId = noteIds[i];
+		for (const [i, noteId] of noteIds.entries()) {
 			resultLines.push(`## Note ${i + 1} of ${noteIds.length} (ID: ${noteId})\n`);
 			try {
 				const note = this.unwrap(await this.apiClient.get(`/notes/${noteId}`, { query: { fields: "id,title,body,parent_id,created_time,updated_time,is_todo,todo_completed,todo_due" } }));
@@ -1224,13 +1317,17 @@ var ReadMultiNote = class extends BaseTool {
 					continue;
 				}
 				successful.push(noteId);
-				let notebookInfo = "Unknown notebook";
-				if (note.parent_id) try {
-					const notebook = this.unwrap(await this.apiClient.get(`/folders/${note.parent_id}`, { query: { fields: "id,title" } }));
-					if (notebook && notebook.title) notebookInfo = `"${notebook.title}" (notebook_id: "${note.parent_id}")`;
-				} catch (err) {
-					process.stderr.write(`Error fetching notebook info for note ${noteId}: ${err}\n`);
-				}
+				const notebookInfo = await (async () => {
+					if (!note.parent_id) return "Unknown notebook";
+					try {
+						const notebook = this.unwrap(await this.apiClient.get(`/folders/${note.parent_id}`, { query: { fields: "id,title" } }));
+						if (notebook === null || notebook === void 0 ? void 0 : notebook.title) return `"${notebook.title}" (notebook_id: "${note.parent_id}")`;
+						return "Unknown notebook";
+					} catch (err) {
+						process.stderr.write(`Error fetching notebook info for note ${noteId}: ${err}\n`);
+						return "Unknown notebook";
+					}
+				})();
 				resultLines.push(`### Note: "${note.title}"`);
 				resultLines.push(`Notebook: ${notebookInfo}`);
 				if (note.is_todo) {
@@ -1250,13 +1347,15 @@ var ReadMultiNote = class extends BaseTool {
 				else resultLines.push("(This note has no content)");
 				resultLines.push("\n---\n");
 			} catch (error) {
+				var _err$response;
 				process.stderr.write(`Error reading note ${noteId}: ${error}\n`);
-				if (error.response && error.response.status === 404) {
+				const err = error;
+				if (((_err$response = err.response) === null || _err$response === void 0 ? void 0 : _err$response.status) === 404) {
 					notFound.push(noteId);
 					resultLines.push(`Note with ID "${noteId}" not found.\n`);
 				} else {
 					errors.push(noteId);
-					resultLines.push(`Error reading note: ${error.message || "Unknown error"}\n`);
+					resultLines.push(`Error reading note: ${err.message ?? "Unknown error"}\n`);
 				}
 			}
 		}
@@ -1274,7 +1373,6 @@ var ReadMultiNote = class extends BaseTool {
 		return resultLines.join("\n");
 	}
 };
-
 //#endregion
 //#region src/lib/tools/read-note.ts
 var ReadNote = class extends BaseTool {
@@ -1283,14 +1381,20 @@ var ReadNote = class extends BaseTool {
 		if (validationError) return validationError;
 		try {
 			const note = this.unwrap(await this.apiClient.get(`/notes/${noteId}`, { query: { fields: "id,title,body,parent_id,created_time,updated_time,is_todo,todo_completed,todo_due" } }));
-			if (!note || typeof note !== "object" || !note.id) return `Error: Unexpected response format from Joplin API when fetching note`;
-			let notebookInfo = "Unknown notebook";
-			if (note.parent_id) try {
-				const notebook = this.unwrap(await this.apiClient.get(`/folders/${note.parent_id}`, { query: { fields: "id,title" } }));
-				if (notebook && notebook.title) notebookInfo = `"${notebook.title}" (notebook_id: "${note.parent_id}")`;
-			} catch (err) {
-				process.stderr.write(`Error fetching notebook info: ${err}\n`);
-			}
+			const noteLoadError = extractJoplinErrorMessage(note);
+			if (noteLoadError !== void 0) throw new ToolError(`Failed to read note "${noteId}": ${noteLoadError}`);
+			if (!note || typeof note !== "object" || !note.id) throw new ToolError(`Failed to read note "${noteId}": Joplin API returned an unexpected response (no note id). Raw response: ${JSON.stringify(note)}`);
+			const notebookInfo = await (async () => {
+				if (!note.parent_id) return "Unknown notebook";
+				try {
+					const notebook = this.unwrap(await this.apiClient.get(`/folders/${note.parent_id}`, { query: { fields: "id,title" } }));
+					if (notebook === null || notebook === void 0 ? void 0 : notebook.title) return `"${notebook.title}" (notebook_id: "${note.parent_id}")`;
+					return "Unknown notebook";
+				} catch (err) {
+					process.stderr.write(`Error fetching notebook info: ${err}\n`);
+					return "Unknown notebook";
+				}
+			})();
 			const resultLines = [];
 			resultLines.push(`# Note: "${note.title}"`);
 			resultLines.push(`Note ID: ${note.id}`);
@@ -1316,12 +1420,15 @@ var ReadNote = class extends BaseTool {
 			resultLines.push("- To search for more notes: search_notes query=\"your search term\"");
 			return resultLines.join("\n");
 		} catch (error) {
-			if (error.response && error.response.status === 404) return `Note with ID "${noteId}" not found.\n\nThis might happen if:\n1. The ID is incorrect\n2. You're using a notebook ID instead of a note ID\n3. The note has been deleted\n\nUse search_notes to find notes and their IDs.`;
-			return this.formatError(error, "reading note") + `\n\nMake sure you're using a valid note ID.\nUse search_notes to find notes and their IDs.`;
+			var _err$response;
+			if (error instanceof ToolError) throw error;
+			const err = error;
+			process.stderr.write(`reading note error: ${error}\n`);
+			if (((_err$response = err.response) === null || _err$response === void 0 ? void 0 : _err$response.status) === 404) throw new ToolError(`Note with ID "${noteId}" not found. This might happen if the ID is incorrect, you're using a notebook ID instead of a note ID, or the note has been deleted. Use search_notes to find notes and their IDs.`);
+			throw new ToolError(`Failed to read note "${noteId}": ${error instanceof Error ? error.message : "Unknown error"}. Make sure you're using a valid note ID. Use search_notes to find notes and their IDs.`);
 		}
 	}
 };
-
 //#endregion
 //#region src/lib/tools/read-notebook.ts
 var ReadNotebook = class extends BaseTool {
@@ -1330,9 +1437,13 @@ var ReadNotebook = class extends BaseTool {
 		if (validationError) return validationError;
 		try {
 			const notebook = this.unwrap(await this.apiClient.get(`/folders/${notebookId}`, { query: { fields: "id,title,parent_id" } }));
-			if (!notebook || typeof notebook !== "object" || !notebook.id) return `Error: Unexpected response format from Joplin API when fetching notebook`;
+			const notebookLoadError = extractJoplinErrorMessage(notebook);
+			if (notebookLoadError !== void 0) throw new ToolError(`Failed to read notebook "${notebookId}": ${notebookLoadError}`);
+			if (!notebook || typeof notebook !== "object" || !notebook.id) throw new ToolError(`Failed to read notebook "${notebookId}": Joplin API returned an unexpected response (no notebook id). Raw response: ${JSON.stringify(notebook)}`);
 			const notes = this.unwrap(await this.apiClient.get(`/folders/${notebookId}/notes`, { query: { fields: "id,title,updated_time,is_todo,todo_completed" } }));
-			if (!notes || typeof notes !== "object") return `Error: Unexpected response format from Joplin API when fetching notes`;
+			const notesLoadError = extractJoplinErrorMessage(notes);
+			if (notesLoadError !== void 0) throw new ToolError(`Failed to load notes for notebook "${notebookId}": ${notesLoadError}`);
+			if (!notes || typeof notes !== "object") throw new ToolError(`Failed to load notes for notebook "${notebookId}": Joplin API returned an unexpected response. Raw response: ${JSON.stringify(notes)}`);
 			if (!notes.items || !Array.isArray(notes.items) || notes.items.length === 0) return `Notebook "${notebook.title}" (notebook_id: "${notebook.id}") is empty.\n\nTry another notebook ID or use list_notebooks to see all available notebooks.`;
 			const resultLines = [];
 			resultLines.push(`# Notebook: "${notebook.title}" (notebook_id: "${notebook.id}")`);
@@ -1355,12 +1466,15 @@ var ReadNotebook = class extends BaseTool {
 			});
 			return resultLines.join("\n");
 		} catch (error) {
-			if (error.response && error.response.status === 404) return `Notebook with ID "${notebookId}" not found.\n\nThis might happen if:\n1. The ID is incorrect\n2. You're using a note title instead of a notebook ID\n3. The notebook has been deleted\n\nUse list_notebooks to see all available notebooks with their IDs.`;
-			return this.formatError(error, "reading notebook") + `\n\nMake sure you're using a valid notebook ID, not a note title.\nUse list_notebooks to see all available notebooks with their IDs.`;
+			var _err$response;
+			if (error instanceof ToolError) throw error;
+			const err = error;
+			process.stderr.write(`reading notebook error: ${error}\n`);
+			if (((_err$response = err.response) === null || _err$response === void 0 ? void 0 : _err$response.status) === 404) throw new ToolError(`Notebook with ID "${notebookId}" not found. This might happen if the ID is incorrect, you're using a note title instead of a notebook ID, or the notebook has been deleted. Use list_notebooks to see all available notebooks with their IDs.`);
+			throw new ToolError(`Failed to read notebook "${notebookId}": ${error instanceof Error ? error.message : "Unknown error"}. Make sure you're using a valid notebook ID, not a note title. Use list_notebooks to see all available notebooks with their IDs.`);
 		}
 	}
 };
-
 //#endregion
 //#region src/lib/tools/search-notes.ts
 var SearchNotes = class extends BaseTool {
@@ -1387,8 +1501,8 @@ var SearchNotes = class extends BaseTool {
 				resultLines.push(`read_multinote note_ids=${JSON.stringify(noteIds)}\n`);
 			}
 			searchResults.items.forEach((note) => {
-				const notebookTitle = folderMap[note.parent_id || ""] || "Unknown notebook";
-				const notebookId = note.parent_id || "unknown";
+				const notebookTitle = folderMap[note.parent_id ?? ""] ?? "Unknown notebook";
+				const notebookId = note.parent_id ?? "unknown";
 				const updatedDate = this.formatDate(note.updated_time);
 				resultLines.push(`- Note: "${note.title}" (note_id: "${note.id}")`);
 				resultLines.push(`  Notebook: "${notebookTitle}" (notebook_id: "${notebookId}")`);
@@ -1403,11 +1517,109 @@ var SearchNotes = class extends BaseTool {
 			});
 			return resultLines.join("\n");
 		} catch (error) {
-			return this.formatError(error, "searching notes");
+			if (error instanceof ToolError) throw error;
+			process.stderr.write(`searching notes error: ${error}\n`);
+			throw new ToolError(`Failed to search notes: ${error instanceof Error ? error.message : "Unknown error"}`);
 		}
 	}
 };
-
+//#endregion
+//#region src/lib/joplin-api-client.ts
+var JoplinAPIClient = class {
+	baseURL;
+	token;
+	constructor({ host = "127.0.0.1", port = 41184, token }) {
+		this.baseURL = `http://${host}:${port}`;
+		this.token = token;
+	}
+	async serviceAvailable() {
+		try {
+			const response = await axios.get(`${this.baseURL}/ping`, { timeout: 5e3 });
+			if (response.status === 200 && response.data === "JoplinClipperServer") return Right(true);
+			return Left(/* @__PURE__ */ new Error("Unexpected response from Joplin ping"));
+		} catch (error) {
+			return Left(error instanceof Error ? error : new Error(String(error)));
+		}
+	}
+	async getAllItems(path, options = {}) {
+		const fetchPage = async (page, acc) => {
+			const response = (await this.get(path, this.mergeRequestOptions(options, { query: { page } }))).fold((err) => {
+				throw err;
+			}, (data) => data);
+			if (!Array.isArray(response.items)) throw new Error(`Unexpected response format from Joplin API for path: ${path}`);
+			const combined = [...acc, ...response.items];
+			return response.has_more ? fetchPage(page + 1, combined) : combined;
+		};
+		try {
+			return Right(await fetchPage(1, []));
+		} catch (error) {
+			process.stderr.write(`Error in getAllItems for path ${path}: ${error}\n`);
+			return Left(error instanceof Error ? error : new Error(String(error)));
+		}
+	}
+	async get(path, options = {}) {
+		try {
+			const { data } = await axios.get(`${this.baseURL}${path}`, {
+				params: this.requestOptions(options).query,
+				timeout: 3e4
+			});
+			return Right(data);
+		} catch (error) {
+			return Left(error instanceof Error ? error : new Error(String(error)));
+		}
+	}
+	async post(path, body, options = {}) {
+		try {
+			const { data } = await axios.post(`${this.baseURL}${path}`, body, {
+				params: this.requestOptions(options).query,
+				timeout: 3e4
+			});
+			return Right(data);
+		} catch (error) {
+			return Left(error instanceof Error ? error : new Error(String(error)));
+		}
+	}
+	async delete(path, options = {}) {
+		try {
+			const { data } = await axios.delete(`${this.baseURL}${path}`, {
+				params: this.requestOptions(options).query,
+				timeout: 3e4
+			});
+			return Right(data);
+		} catch (error) {
+			return Left(error instanceof Error ? error : new Error(String(error)));
+		}
+	}
+	async put(path, body, options = {}) {
+		try {
+			const { data } = await axios.put(`${this.baseURL}${path}`, body, {
+				params: this.requestOptions(options).query,
+				timeout: 3e4
+			});
+			return Right(data);
+		} catch (error) {
+			return Left(error instanceof Error ? error : new Error(String(error)));
+		}
+	}
+	requestOptions(options = {}) {
+		return this.mergeRequestOptions({ query: { token: this.token } }, options);
+	}
+	mergeRequestOptions(options1, options2) {
+		return {
+			query: {
+				...options1.query ?? {},
+				...options2.query ?? {}
+			},
+			...this.except(options1, "query"),
+			...this.except(options2, "query")
+		};
+	}
+	except(obj, key) {
+		const result = { ...obj };
+		delete result[key];
+		return result;
+	}
+};
 //#endregion
 //#region src/server-core.ts
 var JoplinServerManager = class {
@@ -1514,7 +1726,7 @@ var JoplinServerManager = class {
 		const desktopWarning = ((_this$config$sidecar = this.config.sidecar) === null || _this$config$sidecar === void 0 ? void 0 : _this$config$sidecar.isDesktopDetected()) ? "\n\nNote: Joplin Desktop is also running. The sidecar and Desktop use separate databases. Notes sync between them only if both are configured with the same sync target." : "";
 		return (await this.apiClient.post("/services/sync", { action: "start" })).fold((error) => {
 			const msg = error.message || String(error);
-			if (msg.includes("404") || msg.includes("No action API") || msg.includes("No such service")) return "Sync is managed automatically by the Joplin server on its configured interval (default: every 5 minutes). On-demand sync is not available via the Joplin Terminal API." + desktopWarning;
+			if (msg.includes("404") || msg.includes("No action API") || msg.includes("No such service")) return `Sync is managed automatically by the Joplin server on its configured interval (default: every 5 minutes). On-demand sync is not available via the Joplin Terminal API.${desktopWarning}`;
 			return `Sync failed: ${msg}${desktopWarning}`;
 		}, () => `Sync triggered successfully.${desktopWarning}`);
 	}
@@ -1522,9 +1734,21 @@ var JoplinServerManager = class {
 function initializeJoplinManager(config) {
 	return new JoplinServerManager(config);
 }
-
 //#endregion
 //#region src/server-fastmcp.ts
+/**
+* Convert a ToolError thrown by a tool into a FastMCP UserError so the error
+* message reaches the agent verbatim with isError: true (instead of being
+* wrapped in FastMCP's generic "Tool 'x' execution failed: ..." envelope).
+*/
+const runWithUserError = async (fn) => {
+	try {
+		return await fn();
+	} catch (e) {
+		if (e instanceof ToolError) throw new UserError(e.message);
+		throw e;
+	}
+};
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const VERSION = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8")).version;
 function createFastMCPServer(options) {
@@ -1554,41 +1778,31 @@ function createFastMCPServer(options) {
 		name: "list_notebooks",
 		description: "Retrieve the complete notebook hierarchy from Joplin",
 		parameters: z.object({}),
-		execute: async () => {
-			return await manager.listNotebooks();
-		}
+		execute: () => runWithUserError(() => manager.listNotebooks())
 	});
 	server.addTool({
 		name: "search_notes",
 		description: "Search for notes in Joplin and return matching notebooks",
 		parameters: z.object({ query: z.string().describe("Search query for notes") }),
-		execute: async (args) => {
-			return await manager.searchNotes(args.query);
-		}
+		execute: (args) => runWithUserError(() => manager.searchNotes(args.query))
 	});
 	server.addTool({
 		name: "read_notebook",
 		description: "Read the contents of a specific notebook",
 		parameters: z.object({ notebook_id: z.string().describe("ID of the notebook to read") }),
-		execute: async (args) => {
-			return await manager.readNotebook(args.notebook_id);
-		}
+		execute: (args) => runWithUserError(() => manager.readNotebook(args.notebook_id))
 	});
 	server.addTool({
 		name: "read_note",
 		description: "Read the full content of a specific note",
 		parameters: z.object({ note_id: z.string().describe("ID of the note to read") }),
-		execute: async (args) => {
-			return await manager.readNote(args.note_id);
-		}
+		execute: (args) => runWithUserError(() => manager.readNote(args.note_id))
 	});
 	server.addTool({
 		name: "read_multinote",
 		description: "Read the full content of multiple notes at once",
 		parameters: z.object({ note_ids: z.array(z.string()).describe("Array of note IDs to read") }),
-		execute: async (args) => {
-			return await manager.readMultiNote(args.note_ids);
-		}
+		execute: (args) => runWithUserError(() => manager.readMultiNote(args.note_ids))
 	});
 	server.addTool({
 		name: "create_note",
@@ -1601,9 +1815,7 @@ function createFastMCPServer(options) {
 			is_todo: z.boolean().optional().describe("Whether this is a todo note"),
 			image_data_url: z.string().optional().describe("Base64 encoded image data URL")
 		}),
-		execute: async (args) => {
-			return await manager.createNote(args);
-		}
+		execute: (args) => runWithUserError(() => manager.createNote(args))
 	});
 	server.addTool({
 		name: "create_folder",
@@ -1612,9 +1824,7 @@ function createFastMCPServer(options) {
 			title: z.string().describe("Notebook title"),
 			parent_id: z.string().optional().describe("ID of parent notebook")
 		}),
-		execute: async (args) => {
-			return await manager.createFolder(args);
-		}
+		execute: (args) => runWithUserError(() => manager.createFolder(args))
 	});
 	server.addTool({
 		name: "edit_note",
@@ -1629,9 +1839,7 @@ function createFastMCPServer(options) {
 			todo_completed: z.boolean().optional().describe("Whether todo is completed"),
 			todo_due: z.number().optional().describe("Todo due date (Unix timestamp)")
 		}),
-		execute: async (args) => {
-			return await manager.editNote(args);
-		}
+		execute: (args) => runWithUserError(() => manager.editNote(args))
 	});
 	server.addTool({
 		name: "edit_folder",
@@ -1641,9 +1849,7 @@ function createFastMCPServer(options) {
 			title: z.string().optional().describe("New folder title"),
 			parent_id: z.string().optional().describe("New parent folder ID")
 		}),
-		execute: async (args) => {
-			return await manager.editFolder(args);
-		}
+		execute: (args) => runWithUserError(() => manager.editFolder(args))
 	});
 	server.addTool({
 		name: "delete_note",
@@ -1652,9 +1858,7 @@ function createFastMCPServer(options) {
 			note_id: z.string().describe("ID of the note to delete"),
 			confirm: z.boolean().optional().describe("Confirmation flag")
 		}),
-		execute: async (args) => {
-			return await manager.deleteNote(args);
-		}
+		execute: (args) => runWithUserError(() => manager.deleteNote(args))
 	});
 	server.addTool({
 		name: "delete_folder",
@@ -1664,17 +1868,13 @@ function createFastMCPServer(options) {
 			confirm: z.boolean().optional().describe("Confirmation flag"),
 			force: z.boolean().optional().describe("Force delete even if folder has contents")
 		}),
-		execute: async (args) => {
-			return await manager.deleteFolder(args);
-		}
+		execute: (args) => runWithUserError(() => manager.deleteFolder(args))
 	});
 	server.addTool({
 		name: "sync",
 		description: "Trigger a Joplin sync to push/pull changes with the configured sync target",
 		parameters: z.object({}),
-		execute: async () => {
-			return await manager.sync();
-		}
+		execute: () => runWithUserError(() => manager.sync())
 	});
 	process.stderr.write("FastMCP server configured with 12 Joplin tools\n");
 	return {
@@ -1685,8 +1885,8 @@ function createFastMCPServer(options) {
 async function startFastMCPServer(options) {
 	const { server } = createFastMCPServer(options);
 	process.stderr.write(`Configured for Joplin at ${options.host}:${options.port}\n`);
-	const port = options.httpPort || 3e3;
-	const endpoint = options.endpoint || "/mcp";
+	const port = options.httpPort ?? 3e3;
+	const endpoint = options.endpoint ?? "/mcp";
 	await server.start({
 		transportType: "httpStream",
 		httpStream: {
@@ -1696,66 +1896,89 @@ async function startFastMCPServer(options) {
 	});
 	process.stderr.write(`FastMCP server running on http://0.0.0.0:${port}${endpoint}\n`);
 }
-
 //#endregion
 //#region src/index.ts
-const { transport, httpPort, profileDir, syncTarget } = parseArgs();
+const { transport, httpPort, profileDir, syncTarget, explicitToken } = parseArgs();
 const isHttpMode = transport === "http";
-const externalHost = process.env.JOPLIN_HOST;
-const externalPort = process.env.JOPLIN_PORT ? parseInt(process.env.JOPLIN_PORT, 10) : void 0;
-const externalMode = !!(externalHost || externalPort);
-if (!process.env.JOPLIN_TOKEN && externalMode) {
-	process.stderr.write("Error: JOPLIN_TOKEN is required in external mode. Use --token <token> or set JOPLIN_TOKEN environment variable.\n");
+const externalHost = process.env.JOPLIN_HOST !== void 0 && process.env.JOPLIN_HOST !== "" ? process.env.JOPLIN_HOST : void 0;
+const externalPort = process.env.JOPLIN_PORT !== void 0 && process.env.JOPLIN_PORT !== "" ? parseInt(process.env.JOPLIN_PORT, 10) : void 0;
+const externalMode = externalHost !== void 0 || externalPort !== void 0;
+const generateToken = () => `mcp-${crypto.randomUUID().replace(/-/g, "").slice(0, 32)}`;
+const explicitTokenValue = explicitToken.orUndefined();
+const ambientToken = process.env.JOPLIN_TOKEN;
+const tokenInput = {
+	externalMode,
+	explicitToken,
+	ambientToken: Option(ambientToken)
+};
+if (externalTokenMissing(tokenInput)) {
+	process.stderr.write("Error: a token is required in external mode. Use --token <token> or set JOPLIN_TOKEN environment variable.\n");
 	process.exit(1);
 }
-const joplinToken = (() => {
-	if (process.env.JOPLIN_TOKEN) return process.env.JOPLIN_TOKEN;
-	if (externalMode) return `mcp-${crypto.randomUUID().replace(/-/g, "").slice(0, 32)}`;
+const readOrCreateProfileToken = () => {
 	const tokenPath = path.join(profileDir, ".mcp-token");
 	try {
 		const saved = fs.readFileSync(tokenPath, "utf-8").trim();
 		if (saved) return saved;
 	} catch {}
-	const token = `mcp-${crypto.randomUUID().replace(/-/g, "").slice(0, 32)}`;
+	const token = generateToken();
 	try {
 		fs.mkdirSync(profileDir, { recursive: true });
 		fs.writeFileSync(tokenPath, token);
 	} catch {}
 	return token;
+};
+const tokenResolution = resolveTokenSource(tokenInput);
+if (tokenResolution.ambientIgnored) process.stderr.write("Note: ignoring JOPLIN_TOKEN in sidecar mode; the sidecar manages its own token in the profile. Pass --token to set one explicitly, or JOPLIN_HOST/JOPLIN_PORT to connect to an external Joplin.\n");
+const joplinToken = (() => {
+	switch (tokenResolution.source) {
+		case "explicit": return explicitTokenValue ?? generateToken();
+		case "external-env": return ambientToken ?? generateToken();
+		case "external-generated": return generateToken();
+		case "profile": return readOrCreateProfileToken();
+	}
 })();
-async function main() {
-	let host;
-	let port;
-	let sidecar;
+async function setupConnection() {
 	if (externalMode) {
-		host = externalHost || "127.0.0.1";
-		port = externalPort || DEFAULT_API_PORT;
+		const host = externalHost ?? "127.0.0.1";
+		const port = externalPort ?? 41184;
 		process.stderr.write(`External mode: connecting to Joplin at ${host}:${port}\n`);
-	} else {
-		sidecar = new JoplinSidecar({
-			profileDir,
-			apiPort: DEFAULT_API_PORT,
-			apiToken: joplinToken,
-			syncTarget: syncTarget.orUndefined()
-		});
-		(await sidecar.resolvePort()).fold((err) => process.stderr.write(`Warning: Port resolution failed: ${err.message}\n`), (p) => process.stderr.write(`Sidecar will use port ${p}\n`));
-		sidecar.start().then((result) => {
-			result.fold((err) => {
-				process.stderr.write(`Warning: Sidecar failed to start: ${err.message}\n`);
-				process.stderr.write("Attempting to connect to existing Joplin instance...\n");
-			}, () => {
-				process.stderr.write("Joplin sidecar started successfully\n");
-			});
-		});
-		host = sidecar.getHost();
-		port = sidecar.getPort();
-		const cleanup = async () => {
-			await sidecar.stop();
-			process.exit(0);
+		return {
+			host,
+			port,
+			sidecar: void 0
 		};
-		process.on("SIGINT", () => void cleanup());
-		process.on("SIGTERM", () => void cleanup());
 	}
+	const sidecar = new JoplinSidecar({
+		profileDir,
+		apiPort: DEFAULT_API_PORT,
+		apiToken: joplinToken,
+		syncTarget: syncTarget.orUndefined(),
+		version: "2.2.0"
+	});
+	(await sidecar.resolvePort()).fold((err) => process.stderr.write(`Warning: Port resolution failed: ${err.message}\n`), (p) => process.stderr.write(`Sidecar will use port ${p}\n`));
+	sidecar.start().then((result) => {
+		result.fold((err) => {
+			process.stderr.write(`Warning: Sidecar failed to start: ${err.message}\n`);
+			process.stderr.write("Attempting to connect to existing Joplin instance...\n");
+		}, () => {
+			process.stderr.write("Joplin sidecar started successfully\n");
+		});
+	});
+	const cleanup = async () => {
+		await sidecar.stop();
+		process.exit(0);
+	};
+	process.on("SIGINT", () => void cleanup());
+	process.on("SIGTERM", () => void cleanup());
+	return {
+		host: sidecar.getHost(),
+		port: sidecar.getPort(),
+		sidecar
+	};
+}
+async function main() {
+	const { host, port, sidecar } = await setupConnection();
 	if (isHttpMode) {
 		process.stderr.write("Starting HTTP transport mode with FastMCP...\n");
 		await startFastMCPServer({
@@ -1783,7 +2006,7 @@ async function startStdioServer(host, port, token, sidecar) {
 	});
 	const server = new Server({
 		name: "joplin-mcp-server",
-		version: "2.1.0"
+		version: "2.2.0"
 	}, { capabilities: {
 		resources: {},
 		tools: {},
@@ -2015,7 +2238,7 @@ async function startStdioServer(host, port, token, sidecar) {
 	});
 	server.setRequestHandler(CallToolRequestSchema, async (request) => {
 		const toolName = request.params.name;
-		const args = request.params.arguments || {};
+		const args = request.params.arguments ?? {};
 		try {
 			switch (toolName) {
 				case "list_notebooks": return {
@@ -2105,10 +2328,11 @@ async function startStdioServer(host, port, token, sidecar) {
 				default: throw new Error(`Unknown tool: ${toolName}`);
 			}
 		} catch (error) {
+			const errorMessage = error instanceof Error ? error.message : String(error);
 			return {
 				content: [{
 					type: "text",
-					text: `Error: ${error instanceof Error ? error.message : String(error)}`
+					text: error instanceof ToolError ? errorMessage : `Error: ${errorMessage}`
 				}],
 				isError: true
 			};
@@ -2132,8 +2356,8 @@ async function startStdioServer(host, port, token, sidecar) {
 				direction: "RESPONSE",
 				message
 			};
-			fs.appendFileSync(logFile, JSON.stringify(logEntry) + "\n");
-			return Object.getPrototypeOf(Object.getPrototypeOf(this)).sendMessage.call(this, message);
+			fs.appendFileSync(logFile, `${JSON.stringify(logEntry)}\n`);
+			await Object.getPrototypeOf(Object.getPrototypeOf(this)).sendMessage.call(this, message);
 		}
 		async handleMessage(message) {
 			this.commandCounter++;
@@ -2143,8 +2367,8 @@ async function startStdioServer(host, port, token, sidecar) {
 				commandNumber: this.commandCounter,
 				message
 			};
-			fs.appendFileSync(logFile, JSON.stringify(logEntry) + "\n");
-			return Object.getPrototypeOf(Object.getPrototypeOf(this)).handleMessage.call(this, message);
+			fs.appendFileSync(logFile, `${JSON.stringify(logEntry)}\n`);
+			await Object.getPrototypeOf(Object.getPrototypeOf(this)).handleMessage.call(this, message);
 		}
 	}
 	const stdioTransport = new LoggingTransport();
@@ -2156,7 +2380,7 @@ async function startStdioServer(host, port, token, sidecar) {
 		process.exit(1);
 	}
 }
-
 //#endregion
-export {  };
+export {};
+
 //# sourceMappingURL=index.js.map