@fswap/mcp-outline 0.1.2 → 0.1.5

package/README.md

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

package/dist/index.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fswap/mcp-outline",
-  "version": "0.1.2",
+  "version": "0.1.5",
   "description": "MCP server for Outline (getoutline.com) — search, read, create and update wiki documents from Claude",
   "type": "module",
   "bin": {
@@ -17,7 +17,7 @@
     "dev": "tsdown --watch",
     "typecheck": "tsc --noEmit",
     "lint": "eslint src test",
-    "test": "npm run build && node test/smoke.test.mjs",
+    "test": "npm run build && node test/smoke.test.mjs && node --test test/install.test.mjs",
     "check": "npm run lint && npm run typecheck && npm test",
     "start": "node dist/index.js",
     "setup": "node dist/index.js setup",