@appsoftwareltd/etherpk-mcp 0.2.0 → 0.3.0

package/README.md

@@ -31,11 +31,30 @@ npx @appsoftwareltd/etherpk-mcp login --sync-server https://sync.etherpk.com
 #   npx @appsoftwareltd/etherpk-mcp login --sync-server https://sync.etherpk.com --recovery-code
 
 # Tell the agent about the graph (Claude Code shown; the Agents tab has the others).
-claude mcp add etherpk -- npx @appsoftwareltd/etherpk-mcp serve --graph <graph id>
+claude mcp add etherpk -- npx @appsoftwareltd/etherpk-mcp serve --sync-server https://sync.etherpk.com --graph <graph id>
 ```
 
-`npx @appsoftwareltd/etherpk-mcp graphs` lists the graphs the token can reach, by name and id.
-For a scripted setup, `ETHERPK_PAT` and `ETHERPK_RECOVERY_CODE` stand in for the prompts.
+`npx @appsoftwareltd/etherpk-mcp graphs` lists the graphs each signed-in account can reach, by
+name and id. For a scripted setup, `ETHERPK_PAT` and `ETHERPK_RECOVERY_CODE` stand in for the
+prompts.
+
+## More than one Sync Server
+
+One computer can be signed in to several Sync Servers at once - your own self-hosted one beside
+the managed service, say. Run `login` once per server; every login lives in the one config file.
+`--sync-server <url>` then says which server a command means:
+
+```sh
+npx @appsoftwareltd/etherpk-mcp login  --sync-server https://sync.your-domain.example
+npx @appsoftwareltd/etherpk-mcp graphs                                   # every server, in turn
+npx @appsoftwareltd/etherpk-mcp serve  --sync-server https://sync.your-domain.example --graph <graph id>
+npx @appsoftwareltd/etherpk-mcp logout --sync-server https://sync.your-domain.example
+```
+
+While only one server is signed in, `--sync-server` can be left off `graphs`, `serve` and
+`logout`. With two or more, `serve` and `logout` refuse to guess and ask for it. The commands
+the Agents tab shows always include it, so they stay right whatever else the computer is signed
+in to. `logout --all` forgets every server at once.
 
 Every command runs through `npx`, which fetches the package but never puts `etherpk-mcp` on your
 PATH. If you'd rather type the short form, `npm install -g @appsoftwareltd/etherpk-mcp` once and
@@ -50,8 +69,8 @@ One running instance serves one graph.
 
 ## What it keeps on your computer
 
-- **Keys**: `~/.config/etherpk/mcp.json`, readable only by your user - the same trust as a browser
-  you've signed in on.
+- **Keys**: `~/.config/etherpk/mcp.json`, one entry per Sync Server, readable only by your user -
+  the same trust as a browser you've signed in on.
 - **A cache of each graph you serve**: `~/.cache/etherpk/mcp/`, so a restart catches up on what
   changed instead of downloading everything again. It holds your notes readably, like a signed-in
   browser's own storage does. It is never the source of truth: on every start the Sync Server is
@@ -59,7 +78,7 @@ One running instance serves one graph.
   newer version of this program discards a cache it no longer understands and rebuilds it.
 
 Revoke the token at the portal to cut the agent off, and `npx @appsoftwareltd/etherpk-mcp logout`
-to forget the keys and delete the cache on that computer.
+to forget that server's keys and delete its cache on that computer (`--all` for every server).
 
 ## Building and publishing
 

package/dist/main.js

@@ -17,7 +17,7 @@ import { deserialize, serialize } from "node:v8";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 var package_default = {
 	name: "@appsoftwareltd/etherpk-mcp",
-	version: "0.2.0",
+	version: "0.3.0",
 	license: "Elastic-2.0",
 	description: "EtherPK Headless Client: an MCP server over a synced knowledge graph, run beside the agent on the user's own machine.",
 	type: "module",
@@ -705,12 +705,16 @@ function resolveGraphById(graphs, vault, graphId) {
 //#endregion
 //#region src/config.ts
 /**
-* What `login` leaves behind and `serve` reads: the Sync Server origin, the account-wide
-* [[Personal Access Token]], and the vault key that opens the account's keys on this machine.
+* What `login` leaves behind and `serve` reads: for each Sync Server this machine is signed in
+* to, keyed by origin, the account-wide [[Personal Access Token]] and the vault key that opens
+* the account's keys here. One file holds every login (ADR 0075), so a dev instance beside a
+* production one, or a self-hosted server beside the managed service, need no second file and
+* no environment variable to keep them apart; a command names its server with `--sync-server`
+* and may leave it out while only one is signed in.
 *
 * The file is the same trust class as the browser's `localStorage` cache of the same key
 * (DESIGN.md → Key storage between sessions): whoever can read this user's files can read the
-* account. It is written `0600` in the user's config directory, never anywhere a project
+* accounts. It is written `0600` in the user's config directory, never anywhere a project
 * checkout could pick it up, and `ETHERPK_MCP_CONFIG` overrides the path for tests and for a
 * box that keeps its secrets elsewhere. An OS keychain would be the next step (ADR 0072).
 */
@@ -719,7 +723,18 @@ function defaultConfigPath(env = process.env) {
 	if (override) return override;
 	return join(env.XDG_CONFIG_HOME?.trim() || join(homedir(), ".config"), "etherpk", "mcp.json");
 }
-/** Tolerant of a hand-edited file: keeps the fields it knows, refuses the rest. */
+function emptyConfig() {
+	return { servers: {} };
+}
+/** The origin form every key and `--sync-server` value is reduced to before comparison. */
+function normaliseSyncServer(value) {
+	return value.trim().replace(/\/+$/, "");
+}
+/**
+* Tolerant of a hand-edited file: keeps the entries it knows, refuses the rest. A file in the
+* single-login shape written before 0.3.0 reads as null, so its commands say "not logged in"
+* and one `login` rewrites it; the token in it was never lost, only its shape.
+*/
 function parseConfig(raw) {
 	let parsed;
 	try {
@@ -727,14 +742,20 @@ function parseConfig(raw) {
 	} catch {
 		return null;
 	}
-	if (typeof parsed !== "object" || parsed === null) return null;
-	const rec = parsed;
-	if (typeof rec.syncServer !== "string" || typeof rec.pat !== "string") return null;
-	const out = {
-		syncServer: rec.syncServer.replace(/\/$/, ""),
-		pat: rec.pat
-	};
-	if (typeof rec.vaultKey === "string" && rec.vaultKey !== "") out.vaultKey = rec.vaultKey;
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return null;
+	const servers = parsed.servers;
+	if (typeof servers !== "object" || servers === null || Array.isArray(servers)) return null;
+	const out = emptyConfig();
+	for (const [key, entry] of Object.entries(servers)) {
+		if (typeof entry !== "object" || entry === null) return null;
+		const login = entry;
+		if (typeof login.pat !== "string" || login.pat === "") return null;
+		const syncServer = normaliseSyncServer(key);
+		if (!/^https?:\/\//.test(syncServer)) return null;
+		const kept = { pat: login.pat };
+		if (typeof login.vaultKey === "string" && login.vaultKey !== "") kept.vaultKey = login.vaultKey;
+		out.servers[syncServer] = kept;
+	}
 	return out;
 }
 function serialiseConfig(config) {
@@ -744,7 +765,7 @@ async function readConfig(path) {
 	try {
 		return parseConfig(await readFile(path, "utf8"));
 	} catch (error) {
-		if (error.code === "ENOENT") return null;
+		if (error.code === "ENOENT") return emptyConfig();
 		throw error;
 	}
 }
@@ -757,6 +778,54 @@ async function writeConfig(path, config) {
 	await writeFile(path, serialiseConfig(config), { mode: 384 });
 	await chmod(path, 384);
 }
+/** The logins as a list, in file order, each carrying its server. */
+function listLogins(config) {
+	return Object.entries(config.servers).map(([syncServer, login]) => ({
+		syncServer,
+		...login
+	}));
+}
+/**
+* Which login a command means. Named, it must exist; unnamed, it is the only one there is.
+* With two or more logins and no name the command refuses rather than guess: the graphs of
+* one server are not the graphs of another, and a guess would serve the wrong one silently.
+*/
+function selectServer(config, wanted) {
+	const known = Object.keys(config.servers);
+	if (wanted !== void 0 && wanted.trim() !== "") {
+		const syncServer = normaliseSyncServer(wanted);
+		const login = config.servers[syncServer];
+		return login ? {
+			ok: true,
+			credentials: {
+				syncServer,
+				...login
+			}
+		} : {
+			ok: false,
+			reason: "unknown",
+			syncServer,
+			known
+		};
+	}
+	if (known.length === 0) return {
+		ok: false,
+		reason: "none"
+	};
+	if (known.length > 1) return {
+		ok: false,
+		reason: "ambiguous",
+		known
+	};
+	const syncServer = known[0];
+	return {
+		ok: true,
+		credentials: {
+			syncServer,
+			...config.servers[syncServer]
+		}
+	};
+}
 //#endregion
 //#region ../client/src/lib/diagnostics/performance.ts
 function assertSafeName(name) {
@@ -7853,13 +7922,20 @@ function nodeIndexHost(dir) {
 		}
 	};
 }
-/** Remove every persisted graph under the cache root (logout). */
+/** Remove every persisted graph under the cache root (logout of the last server). */
 async function removeCacheRoot(env) {
 	await rm(cacheRoot(env), {
 		recursive: true,
 		force: true
 	});
 }
+/** Remove one server's persisted graphs (logout of that server while others stay). */
+async function removeServerCache(env, serverBaseUrl) {
+	await rm(dirname(graphCacheDir(env, serverBaseUrl, "x")), {
+		recursive: true,
+		force: true
+	});
+}
 //#endregion
 //#region src/headless-graph.ts
 /** Open the graph, scan its registry and build the index; resolves once tools can answer. */
@@ -8391,9 +8467,12 @@ function createMcpServer(graph, info) {
 * `etherpk-mcp`: the [[Headless Client]]'s command line (ADR 0072).
 *
 *   etherpk-mcp login  --sync-server <url> [--pat <token>] [--recovery-code]
-*   etherpk-mcp graphs
-*   etherpk-mcp serve  --graph <id or name>
-*   etherpk-mcp logout
+*   etherpk-mcp graphs [--sync-server <url>]
+*   etherpk-mcp serve  --graph <id or name> [--sync-server <url>]
+*   etherpk-mcp logout [--sync-server <url> | --all]
+*
+* One config file holds a login per Sync Server (ADR 0075). `--sync-server` names the one a
+* command means and may be left out while only one is signed in.
 *
 * `serve` speaks MCP over stdio, so everything for the human goes to stderr; stdout belongs
 * to the agent. `login` and `graphs` are interactive and print to stdout.
@@ -8415,16 +8494,19 @@ var USAGE = `etherpk-mcp - EtherPK Headless Client (an MCP server over one synce
       open EtherPK in a browser signed in to the account with its graphs unlocked and
       confirm the code shown. Press r while waiting, or pass --recovery-code, to type
       your Recovery Code instead (or ETHERPK_RECOVERY_CODE, for a scripted setup).
-  ${CMD} graphs
-      List the synced graphs this account can reach, by name and id.
-  ${CMD} serve --graph <id or name>
+  ${CMD} graphs [--sync-server <url>]
+      List the synced graphs each signed-in account can reach, by name and id.
+  ${CMD} serve --graph <id or name> [--sync-server <url>]
       Serve one graph to an agent over stdio. For Claude Code:
-        claude mcp add etherpk -- npx @appsoftwareltd/etherpk-mcp serve --graph <id>
-  ${CMD} logout
-      Forget the token, keys and cached graphs on this machine.
+        claude mcp add etherpk -- npx @appsoftwareltd/etherpk-mcp serve --sync-server <url> --graph <id>
+  ${CMD} logout [--sync-server <url> | --all]
+      Forget that server's token, keys and cached graphs on this machine.
 
-The config file is ${defaultConfigPath()} (override with ETHERPK_MCP_CONFIG); cached graphs live
-under ~/.cache/etherpk/mcp (override with ETHERPK_MCP_CACHE_DIR).
+This machine can be signed in to several Sync Servers at once (a self-hosted one beside the
+managed service, say); --sync-server says which one a command means, and can be left out
+while only one is signed in. The config file is ${defaultConfigPath()} (override with
+ETHERPK_MCP_CONFIG); cached graphs live under ~/.cache/etherpk/mcp (override with
+ETHERPK_MCP_CACHE_DIR).
 Docs: https://docs.etherpk.com/using-ai-agents-with-your-notes
 `;
 function fail(message) {
@@ -8469,14 +8551,26 @@ async function ask(question, { secret = false } = {}) {
 		stdin.on("data", onData);
 	});
 }
-async function requireConfig(path) {
+async function loadConfig(path) {
 	const config = await readConfig(path);
-	if (!config) fail(`Not logged in on this machine. Run: ${CMD} login --sync-server <url>`);
+	if (!config) fail(`${path} is not a config file this version understands. Run: ${CMD} login --sync-server <url> (it will be rewritten; nothing else is affected).`);
 	return config;
 }
+/** The login a command means, or the reason there is none - in words the user can act on. */
+function requireServer(config, wanted) {
+	const selection = selectServer(config, wanted);
+	if (selection.ok) return selection.credentials;
+	switch (selection.reason) {
+		case "none": return fail(`Not logged in on this machine. Run: ${CMD} login --sync-server <url>`);
+		case "unknown": return fail(`Not logged in to ${selection.syncServer}. Signed in to: ${selection.known.join(", ") || "(none)"}. Run: ${CMD} login --sync-server ${selection.syncServer}`);
+		case "ambiguous": return fail(`Signed in to more than one Sync Server here: ${selection.known.join(", ")}. Say which with --sync-server <url>.`);
+	}
+}
 async function login(args) {
 	const path = defaultConfigPath();
-	const syncServer = (args["sync-server"] ?? (await readConfig(path))?.syncServer ?? await ask("Sync Server URL: ")).replace(/\/$/, "");
+	const config = await readConfig(path) ?? emptyConfig();
+	const known = Object.keys(config.servers);
+	const syncServer = normaliseSyncServer(args["sync-server"] ?? (known.length === 1 ? known[0] : await ask("Sync Server URL: ")));
 	if (!/^https?:\/\//.test(syncServer)) fail("The Sync Server must be an http(s) URL.");
 	const pat = args.pat ?? process.env.ETHERPK_PAT ?? await ask(`Personal Access Token (account-wide, from ${syncServer}/account/tokens): `, { secret: true });
 	if (!pat) fail("A Personal Access Token is required.");
@@ -8487,17 +8581,19 @@ async function login(args) {
 	console.log(`Signed in to ${syncServer} as ${account.principal.email ?? account.principal.name ?? account.principal.id}.`);
 	const byRecoveryCode = async () => unlockByRecoveryCode(account.api, process.env.ETHERPK_RECOVERY_CODE ?? await ask("Recovery Code: ", { secret: true }));
 	const vaultKey = args["recovery-code"] ? await byRecoveryCode() : await approveOrFallBack(account, byRecoveryCode);
-	await writeConfig(path, {
-		syncServer,
+	config.servers[syncServer] = {
 		pat,
 		vaultKey: toBase64Url(vaultKey)
-	});
+	};
+	await writeConfig(path, config);
 	console.log(`Keys unlocked and cached in ${path} (owner-only). Anyone who can read your files on this machine can read this account, as with a signed-in browser.`);
+	const others = Object.keys(config.servers).filter((server) => server !== syncServer);
+	if (others.length > 0) console.log(`Also signed in to ${others.join(", ")}; commands now need --sync-server <url> to say which.`);
 	await listGraphs({
 		syncServer,
 		pat,
 		vaultKey: toBase64Url(vaultKey)
-	});
+	}, others.length > 0);
 }
 /**
 * Device Approval, with the Recovery Code one keypress away: a user who has no unlocked EtherPK
@@ -8546,16 +8642,28 @@ async function approveOrFallBack(account, byRecoveryCode) {
 	console.log("Approval cancelled; unlocking with your Recovery Code instead.");
 	return byRecoveryCode();
 }
-async function listGraphs(config) {
-	if (!config.vaultKey) fail(`Keys are not unlocked on this machine. Run: ${CMD} login`);
-	const account = await connectAccount(config);
-	const vault = await openAccountVault(account.api, fromBase64Url(config.vaultKey));
+/**
+* `graphs` with a server named lists that server; unnamed, it lists every signed-in server in
+* turn, because "what can the agent reach from here" is the question and it has one answer
+* per login.
+*/
+async function graphsCommand(args) {
+	const config = await loadConfig(defaultConfigPath());
+	const logins = args["sync-server"] ? [requireServer(config, args["sync-server"])] : listLogins(config);
+	if (logins.length === 0) fail(`Not logged in on this machine. Run: ${CMD} login --sync-server <url>`);
+	for (const login of logins) await listGraphs(login, logins.length > 1);
+}
+async function listGraphs(login, several) {
+	if (!login.vaultKey) fail(`Keys are not unlocked on this machine for ${login.syncServer}. Run: ${CMD} login --sync-server ${login.syncServer}`);
+	const account = await connectAccount(login);
+	const vault = await openAccountVault(account.api, fromBase64Url(login.vaultKey));
 	const graphs = await account.api.listGraphs();
+	const serverFlag = several ? ` --sync-server ${login.syncServer}` : "";
 	if (graphs.length === 0) {
-		console.log("No synced graphs are reachable with this token.");
+		console.log(`No synced graphs are reachable with the token for ${login.syncServer}.`);
 		return;
 	}
-	console.log("Synced graphs:");
+	console.log(several ? `Synced graphs on ${login.syncServer}:` : "Synced graphs:");
 	for (const record of graphs) {
 		const keyring = vault.keyrings.find((entry) => entry.graphId === record.id);
 		const name = keyring ? await readGraphName({
@@ -8569,16 +8677,16 @@ async function listGraphs(config) {
 		console.log(`  ${record.id}  ${label}  [${record.role}]`);
 	}
 	console.log("");
-	console.log(`Serve one to an agent with:  ${CMD} serve --graph <id>`);
-	console.log(`For Claude Code:             claude mcp add etherpk -- ${CMD} serve --graph <id>`);
+	console.log(`Serve one to an agent with:  ${CMD} serve${serverFlag} --graph <id>`);
+	console.log(`For Claude Code:             claude mcp add etherpk -- ${CMD} serve${serverFlag} --graph <id>`);
 }
 async function serve(args) {
 	const wanted = args.graph?.trim();
 	if (!wanted) fail("serve needs --graph <id or name>.");
-	const config = await requireConfig(defaultConfigPath());
-	if (!config.vaultKey) fail(`Keys are not unlocked on this machine. Run: ${CMD} login`);
-	const account = await connectAccount(config);
-	const vault = await openAccountVault(account.api, fromBase64Url(config.vaultKey));
+	const login = requireServer(await loadConfig(defaultConfigPath()), args["sync-server"]);
+	if (!login.vaultKey) fail(`Keys are not unlocked on this machine for ${login.syncServer}. Run: ${CMD} login --sync-server ${login.syncServer}`);
+	const account = await connectAccount(login);
+	const vault = await openAccountVault(account.api, fromBase64Url(login.vaultKey));
 	const graphs = await account.api.listGraphs();
 	let graphId = graphs.find((graph) => graph.id === wanted)?.id;
 	let graphName = null;
@@ -8598,7 +8706,7 @@ async function serve(args) {
 			break;
 		}
 	}
-	if (!graphId) fail(`No synced graph is named or identified by "${wanted}". Run: ${CMD} graphs`);
+	if (!graphId) fail(`No synced graph on ${login.syncServer} is named or identified by "${wanted}". Run: ${CMD} graphs`);
 	const { record, keyring } = resolveGraphById(graphs, vault, graphId);
 	console.error(`etherpk-mcp: opening graph ${graphId} on ${account.serverBaseUrl}…`);
 	const graph = await openHeadlessGraph({
@@ -8629,13 +8737,27 @@ async function serve(args) {
 	await server.connect(transport);
 	console.error(`etherpk-mcp: serving "${graphName}" over stdio as "Agent on ${hostname()}".`);
 }
-async function logout() {
+async function logout(args) {
 	const path = defaultConfigPath();
-	await unlink(path).catch((error) => {
-		if (error.code !== "ENOENT") throw error;
-	});
-	await removeCacheRoot(process.env);
-	console.log(`Forgot the token and keys in ${path} and the cached graphs. Revoke the Personal Access Token in the Sync Server portal too if this machine is not yours to keep.`);
+	const config = await readConfig(path);
+	if (args.all || !config) {
+		await unlink(path).catch((error) => {
+			if (error.code !== "ENOENT") throw error;
+		});
+		await removeCacheRoot(process.env);
+		console.log(`Forgot every token and key in ${path} and the cached graphs. Revoke the Personal Access Tokens in each Sync Server portal too if this machine is not yours to keep.`);
+		return;
+	}
+	const login = requireServer(config, args["sync-server"]);
+	delete config.servers[login.syncServer];
+	await removeServerCache(process.env, login.syncServer);
+	if (Object.keys(config.servers).length === 0) {
+		await unlink(path).catch((error) => {
+			if (error.code !== "ENOENT") throw error;
+		});
+		await removeCacheRoot(process.env);
+	} else await writeConfig(path, config);
+	console.log(`Forgot the token, keys and cached graphs for ${login.syncServer}. Revoke the Personal Access Token in its portal too if this machine is not yours to keep.`);
 }
 async function main() {
 	const { values, positionals } = parseArgs({
@@ -8646,6 +8768,7 @@ async function main() {
 			pat: { type: "string" },
 			"recovery-code": { type: "boolean" },
 			graph: { type: "string" },
+			all: { type: "boolean" },
 			help: {
 				type: "boolean",
 				short: "h"
@@ -8667,9 +8790,9 @@ async function main() {
 	}
 	switch (command) {
 		case "login": return login(values);
-		case "graphs": return listGraphs(await requireConfig(defaultConfigPath()));
+		case "graphs": return graphsCommand(values);
 		case "serve": return serve(values);
-		case "logout": return logout();
+		case "logout": return logout(values);
 		default: fail(`Unknown command "${command}".\n\n${USAGE}`);
 	}
 }