joplin-mcp-server 2.1.1 → 2.2.1

package/dist/bin.d.ts

@@ -1 +1 @@
-export { };
+export {}

package/dist/bin.js

@@ -3,12 +3,12 @@
 process.env.TRANSPORT_TYPE ??= "stdio";
 const args = process.argv.slice(2);
 if (args.includes("--version") || args.includes("-v")) {
-	console.log("2.1.1");
+	console.log("2.2.1");
 	process.exit(0);
 }
 if (args.includes("--help") || args.includes("-h")) {
 	console.log(`
-Joplin MCP Server v2.1.1
+Joplin MCP Server v2.2.1
 
 Usage: joplin-mcp-server [options]
 
@@ -17,7 +17,7 @@ Options:
   -h, --help           Show help
 
 Environment Variables:
-  JOPLIN_TOKEN         Joplin API token (required)
+  JOPLIN_TOKEN         API token for external mode; ignored in sidecar mode
   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)

package/dist/bin.js.map

@@ -1 +1 @@
-{"version":3,"file":"bin.js","names":[],"sources":["../src/bin.ts"],"sourcesContent":["#!/usr/bin/env node\n\n// Version is injected at build time via tsdown.config.ts define\ndeclare const __VERSION__: string\n\n// Force stdio mode for CLI/npx usage (unless explicitly overridden)\nprocess.env.TRANSPORT_TYPE ??= \"stdio\"\n\n// Handle command line arguments BEFORE any other imports\nconst args = process.argv.slice(2)\n\nif (args.includes(\"--version\") || args.includes(\"-v\")) {\n  console.log(__VERSION__)\n  process.exit(0)\n}\n\nif (args.includes(\"--help\") || args.includes(\"-h\")) {\n  console.log(`\nJoplin MCP Server v${__VERSION__}\n\nUsage: joplin-mcp-server [options]\n\nOptions:\n  -v, --version        Show version number\n  -h, --help           Show help\n\nEnvironment Variables:\n  JOPLIN_TOKEN         Joplin API token (required)\n  JOPLIN_HOST          Connect to existing Joplin at this host (skips sidecar)\n  JOPLIN_PORT          Connect to existing Joplin on this port (skips sidecar)\n  JOPLIN_CLI           Path to joplin CLI binary (overrides auto-detection)\n\nFor more information, visit: https://github.com/jordanburke/joplin-mcp-server\n`)\n  process.exit(0)\n}\n\n// Import and start server if not showing version/help\nasync function main() {\n  // Import and run the main function from the FastMCP server\n  await import(\"./index.js\")\n}\n\nvoid main()\n"],"mappings":";;AAMA,QAAQ,IAAI,mBAAmB;AAG/B,MAAM,OAAO,QAAQ,KAAK,MAAM,CAAC;AAEjC,IAAI,KAAK,SAAS,WAAW,KAAK,KAAK,SAAS,IAAI,GAAG;CACrD,QAAQ,IAAA,OAAe;CACvB,QAAQ,KAAK,CAAC;AAChB;AAEA,IAAI,KAAK,SAAS,QAAQ,KAAK,KAAK,SAAS,IAAI,GAAG;CAClD,QAAQ,IAAI;;;;;;;;;;;;;;;;CAgBb;CACC,QAAQ,KAAK,CAAC;AAChB;AAGA,eAAe,OAAO;CAEpB,MAAM,OAAO;AACf;AAEK,KAAK"}
+{"version":3,"file":"bin.js","names":[],"sources":["../src/bin.ts"],"sourcesContent":["#!/usr/bin/env node\n\n// Version is injected at build time via tsdown.config.ts define\ndeclare const __VERSION__: string\n\n// Force stdio mode for CLI/npx usage (unless explicitly overridden)\nprocess.env.TRANSPORT_TYPE ??= \"stdio\"\n\n// Handle command line arguments BEFORE any other imports\nconst args = process.argv.slice(2)\n\nif (args.includes(\"--version\") || args.includes(\"-v\")) {\n  console.log(__VERSION__)\n  process.exit(0)\n}\n\nif (args.includes(\"--help\") || args.includes(\"-h\")) {\n  console.log(`\nJoplin MCP Server v${__VERSION__}\n\nUsage: joplin-mcp-server [options]\n\nOptions:\n  -v, --version        Show version number\n  -h, --help           Show help\n\nEnvironment Variables:\n  JOPLIN_TOKEN         API token for external mode; ignored in sidecar mode\n  JOPLIN_HOST          Connect to existing Joplin at this host (skips sidecar)\n  JOPLIN_PORT          Connect to existing Joplin on this port (skips sidecar)\n  JOPLIN_CLI           Path to joplin CLI binary (overrides auto-detection)\n\nFor more information, visit: https://github.com/jordanburke/joplin-mcp-server\n`)\n  process.exit(0)\n}\n\n// Import and start server if not showing version/help\nasync function main() {\n  // Import and run the main function from the FastMCP server\n  await import(\"./index.js\")\n}\n\nvoid main()\n"],"mappings":";;AAMA,QAAQ,IAAI,mBAAmB;AAG/B,MAAM,OAAO,QAAQ,KAAK,MAAM,CAAC;AAEjC,IAAI,KAAK,SAAS,WAAW,KAAK,KAAK,SAAS,IAAI,GAAG;CACrD,QAAQ,IAAA,OAAe;CACvB,QAAQ,KAAK,CAAC;AAChB;AAEA,IAAI,KAAK,SAAS,QAAQ,KAAK,KAAK,SAAS,IAAI,GAAG;CAClD,QAAQ,IAAI;;;;;;;;;;;;;;;;CAgBb;CACC,QAAQ,KAAK,CAAC;AAChB;AAGA,eAAe,OAAO;CAEpB,MAAM,OAAO;AACf;AAEK,KAAK"}

package/dist/index.d.ts

@@ -1 +1 @@
-export { };
+export {}

package/dist/index.js

@@ -3,11 +3,11 @@ 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 { Path, Platform } from "functype-os";
 import { promisify } from "util";
 import axios from "axios";
@@ -35,6 +35,52 @@ 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;
@@ -42,11 +88,11 @@ const isConnectionRefused = (err) => {
 	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";
@@ -56,10 +102,10 @@ const probePort = async (port, token) => {
 		return "occupied_unresponsive";
 	}
 };
-const resolveAvailablePort = async (startPort, 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);
+		const status = await probePort(port, token, profileDir, identity);
 		if (status === "free") return {
 			outcome: "free",
 			port,
@@ -70,8 +116,17 @@ 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") {
-			process.stderr.write(`[joplin-sidecar] Port ${port}: Joplin Desktop detected (different token), skipping\n`);
+			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`);
@@ -79,14 +134,22 @@ const resolveAvailablePort = async (startPort, token) => {
 	};
 	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",
@@ -140,25 +203,51 @@ 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
 	});
 };
+const runJoplinSync = async (cli, profileDir) => {
+	const cmd = cli.endsWith("npx") ? "npx" : cli;
+	const args = cli.endsWith("npx") ? [
+		"joplin",
+		"--profile",
+		profileDir,
+		"sync"
+	] : [
+		"--profile",
+		profileDir,
+		"sync"
+	];
+	const { stdout } = await execFileAsync(cmd, args, {
+		encoding: "utf-8",
+		timeout: 3e5,
+		shell: isWindows
+	});
+	return stdout;
+};
+const summarizeSyncOutput = (stdout) => {
+	const lines = stdout.split("\n").map((l) => l.trim()).filter((l) => l.length > 0);
+	const completed = lines.filter((l) => l.startsWith("Created") || l.startsWith("Fetched") || l.includes("Completed"));
+	return (completed.length > 0 ? completed[completed.length - 1] : lines[lines.length - 1]) ?? "Sync completed.";
+};
 const configureJoplin = async (cli, config) => {
 	const settings = buildSettingsRecord(config);
 	try {
@@ -173,15 +262,15 @@ const spawnServer = (cli, config) => {
 	try {
 		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",
@@ -264,17 +353,70 @@ var JoplinSidecar = class {
 	childProcess = null;
 	startPromise = null;
 	portResolution = null;
+	cleanupRegistered = false;
 	constructor(config) {
 		this.config = {
 			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;
@@ -289,12 +431,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);
@@ -304,9 +452,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 {
@@ -320,10 +469,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() {
@@ -342,6 +496,7 @@ var JoplinSidecar = class {
 					resolve();
 				});
 			});
+			this.reapRecordedServer();
 			this.childProcess = null;
 			process.stderr.write("[joplin-sidecar] Server stopped\n");
 			return Right(true);
@@ -349,6 +504,45 @@ var JoplinSidecar = class {
 			return Left(error instanceof Error ? error : new Error(String(error)));
 		}
 	}
+	async releaseProfile() {
+		this.startPromise = null;
+		this.portResolution = null;
+		if (this.childProcess) {
+			const proc = this.childProcess;
+			try {
+				proc.kill("SIGTERM");
+				await new Promise((resolve) => {
+					const timeout = setTimeout(() => {
+						proc.kill("SIGKILL");
+						resolve();
+					}, 5e3);
+					proc.on("exit", () => {
+						clearTimeout(timeout);
+						resolve();
+					});
+				});
+			} catch {}
+			this.childProcess = null;
+		}
+		this.reapRecordedServer();
+		await this.waitForPortFree(this.config.apiPort);
+	}
+	async sync() {
+		const cliResult = await findJoplinCli();
+		if (Either.isLeft(cliResult)) return Left(cliResult.fold((e) => e, () => null));
+		const cli = cliResult.fold(() => "", (v) => v);
+		await this.releaseProfile();
+		const syncResult = await (async () => {
+			try {
+				return Right(summarizeSyncOutput(await runJoplinSync(cli, this.config.profileDir)));
+			} catch (e) {
+				return Left(sidecarError("SYNC_FAILED", "joplin sync failed", e));
+			}
+		})();
+		const restart = await this.start();
+		if (Either.isRight(syncResult) && Either.isLeft(restart)) return Left(restart.fold((e) => sidecarError("SYNC_FAILED", `Sync completed but the server failed to restart: ${e.message}`, e), () => null));
+		return syncResult;
+	}
 	async healthCheck() {
 		try {
 			const response = await fetchWithTimeout(`http://127.0.0.1:${this.config.apiPort}/ping`, 5e3);
@@ -386,7 +580,10 @@ const resolveWslPath = (linuxPath, relativeToHome) => {
 const expandPath = (p) => {
 	const expanded = expandVars(p);
 	const tildeExpanded = Path.expandTilde(expanded);
-	if (expanded === "~" || expanded.startsWith("~/")) return resolveWslPath(tildeExpanded, expanded === "~" ? "" : expanded.slice(2));
+	if (expanded === "~" || expanded.startsWith("~/")) {
+		const relativeToHome = expanded === "~" ? "" : expanded.slice(2);
+		return resolveWslPath(tildeExpanded, relativeToHome);
+	}
 	return tildeExpanded;
 };
 const extractArg = (args, flag) => {
@@ -468,9 +665,7 @@ 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;
-	});
+	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");
@@ -487,11 +682,15 @@ function parseArgs() {
 		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, () => "");
@@ -521,7 +720,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)
@@ -576,10 +776,28 @@ Find your Joplin token in: Tools > Options > Web Clipper
 		transport,
 		httpPort,
 		profileDir,
-		syncTarget: resolvedSyncTarget
+		syncTarget: resolvedSyncTarget,
+		explicitToken
 	};
 }
 //#endregion
+//#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
@@ -1569,9 +1787,15 @@ var JoplinServerManager = class {
 		var _this$config$sidecar;
 		await this.ensureConnected();
 		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." : "";
+		if (this.config.sidecar) {
+			const result = await this.config.sidecar.sync();
+			this.connected = false;
+			await this.ensureConnected();
+			return result.fold((error) => `Sync failed: ${error.message}${desktopWarning}`, (summary) => `Sync complete. ${summary}${desktopWarning}`);
+		}
 		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 `On-demand sync is not available on this Joplin instance.${desktopWarning}`;
 			return `Sync failed: ${msg}${desktopWarning}`;
 		}, () => `Sync triggered successfully.${desktopWarning}`);
 	}
@@ -1743,29 +1967,45 @@ async function startFastMCPServer(options) {
 }
 //#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 !== 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;
-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 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 setupConnection() {
 	if (externalMode) {
@@ -1782,7 +2022,8 @@ async function setupConnection() {
 		profileDir,
 		apiPort: DEFAULT_API_PORT,
 		apiToken: joplinToken,
-		syncTarget: syncTarget.orUndefined()
+		syncTarget: syncTarget.orUndefined(),
+		version: "2.2.1"
 	});
 	(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) => {
@@ -1834,7 +2075,7 @@ async function startStdioServer(host, port, token, sidecar) {
 	});
 	const server = new Server({
 		name: "joplin-mcp-server",
-		version: "2.1.1"
+		version: "2.2.1"
 	}, { capabilities: {
 		resources: {},
 		tools: {},