@appsoftwareltd/etherpk-mcp 0.1.0 → 0.1.1

package/README.md

@@ -16,18 +16,26 @@ Open the graph in EtherPK, pick **Settings → Agents**, and copy the two comman
 server and graph filled in. They are:
 
 ```sh
-# Once per computer. Prompts for an account-wide Personal Access Token (from your Sync
-# Server's portal, Account → Tokens), then shows a short code to confirm in any unlocked
-# EtherPK tab - the same step as adding a phone.
-npx @appsoftwareltd/etherpk-mcp login --server https://sync.example.com
+# Once per computer. Prompts for an account-wide Personal Access Token (make one at
+# https://server.etherpk.com/account/tokens, also reachable from "Access tokens" in
+# EtherPK's account menu), then shows a short code and the address of your EtherPK:
+# open EtherPK there in a browser where you're signed in with your graphs unlocked -
+# any page will do - and confirm the code. The same step as adding a phone.
+npx @appsoftwareltd/etherpk-mcp login --server https://server.etherpk.com
+
+# Self-hosting your own Sync Server? Give its address instead:
+#   npx @appsoftwareltd/etherpk-mcp login --server https://sync.your-domain.example
+
+# No EtherPK to hand on this computer (a server you reach over SSH, say)? Press r while
+# login is waiting, or use your Recovery Code from the start:
+#   npx @appsoftwareltd/etherpk-mcp login --server https://server.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>
 ```
 
 `npx @appsoftwareltd/etherpk-mcp graphs` lists the graphs the token can reach, by name and id.
-On a computer with no EtherPK tab to hand, `login --recovery-code` takes your Recovery Code
-instead (or `ETHERPK_RECOVERY_CODE` for a scripted setup; `ETHERPK_PAT` likewise).
+For a scripted setup, `ETHERPK_PAT` and `ETHERPK_RECOVERY_CODE` stand in for the prompts.
 
 ## What the agent gets
 
@@ -36,11 +44,18 @@ unique old→new replacement that merges with anyone typing elsewhere on the pag
 `append_document` (a page, or a day's journal entry, created if needed) and `create_page`.
 One running instance serves one graph.
 
-## Stopping it
+## 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.
+- **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
+  asked what moved and only that is fetched, edits made elsewhere arrive as they happen, and a
+  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 token, keys and cached graphs on that computer. The keys live in
-`~/.config/etherpk/mcp.json` and the cached graphs under `~/.cache/etherpk/mcp/`, both readable
-only by your user - the same trust as a browser you have signed in on.
+to forget the keys and delete the cache on that computer.
 
-Full guide: <https://docs.etherpk.com/using-ai-agents-with-your-notes>.
+Full guide, including how the cache stays current and what an agent can and can't do:
+<https://docs.etherpk.com/using-ai-agents-with-your-notes>.

package/dist/main.js

@@ -618,7 +618,8 @@ async function connectAccount(config) {
 			id: me.principal.id,
 			email: me.principal.email,
 			name: me.principal.name
-		}
+		},
+		clientUrl: me.clientUrl ?? null
 	};
 }
 /**
@@ -858,6 +859,7 @@ z.strictObject({
 		image: httpsUrl.nullable()
 	}),
 	authentication: syncAuthenticationSchema,
+	clientUrl: httpsUrl.optional(),
 	entitlement: z.strictObject({
 		plan: z.string().min(1).max(64),
 		status: serviceEntitlementSchema.shape.status,
@@ -1976,37 +1978,50 @@ function serializeClientMessage(message) {
 * still reads on a white surface, and light enough that dark label text works on all of them
 * in both themes. The selection tint is the same colour at 40% alpha (`66`) — the old 20%
 * tint of a primary was already faint; a pastel at 20% disappears on white.
+*
+* The same eight are offered as the ready-made toolbar colours in Graph Settings (ADR 0071):
+* one palette, so a graph's bar and a member's caret speak the same language. The label is
+* for a swatch there; presence itself never shows it (`label`, not `name`: an entry is
+* spread into a {@link PresenceIdentity}, whose `name` is the pseudonym).
 */
 var PRESENCE_PALETTE = [
 	{
+		label: "Sky",
 		color: "#7dd3fc",
 		colorLight: "#7dd3fc66"
 	},
 	{
+		label: "Amber",
 		color: "#fcd34d",
 		colorLight: "#fcd34d66"
 	},
 	{
+		label: "Mint",
 		color: "#6ee7b7",
 		colorLight: "#6ee7b766"
 	},
 	{
+		label: "Salmon",
 		color: "#fca5a5",
 		colorLight: "#fca5a566"
 	},
 	{
+		label: "Lavender",
 		color: "#c4b5fd",
 		colorLight: "#c4b5fd66"
 	},
 	{
+		label: "Pink",
 		color: "#f9a8d4",
 		colorLight: "#f9a8d466"
 	},
 	{
+		label: "Peach",
 		color: "#fdba74",
 		colorLight: "#fdba7466"
 	},
 	{
+		label: "Lime",
 		color: "#bef264",
 		colorLight: "#bef26466"
 	}
@@ -7921,25 +7936,39 @@ async function pollDeviceApproval(api, request) {
 *
 * Pure over an injected clock and output so the flow is testable without a terminal.
 */
+/** The user left the approval wait on purpose (the signal fired); nothing went wrong. */
+var ApprovalAbandoned = class extends Error {
+	constructor() {
+		super("Approval abandoned.");
+		this.name = "ApprovalAbandoned";
+	}
+};
 /** Approval rows expire server-side after ten minutes; poll a little longer and then give up. */
 var APPROVAL_TIMEOUT_MS = 11 * 6e4;
 var APPROVAL_POLL_MS = 2e3;
 async function unlockByDeviceApproval(api, io) {
 	const request = await beginDeviceApproval(api);
+	const where = io.clientUrl ? `open EtherPK at ${io.clientUrl}` : "open EtherPK in a browser";
 	io.say("");
-	io.say(`Approve this device from EtherPK: open any unlocked tab of this account and confirm the code`);
+	io.say(`To approve this device, ${where} (any page - it need not be a note) signed in to this account`);
+	io.say("with its graphs unlocked. A prompt will show a code; confirm it matches this one:");
 	io.say("");
 	io.say(`    ${request.sas}`);
 	io.say("");
 	io.say("Waiting (up to ten minutes)…");
+	const abandon = async () => {
+		await api.cancelDeviceApproval(request.id).catch(() => {});
+		throw new ApprovalAbandoned();
+	};
 	const deadline = Date.now() + APPROVAL_TIMEOUT_MS;
 	while (Date.now() < deadline) {
-		if (io.signal?.aborted) throw new Error("Cancelled.");
+		if (io.signal?.aborted) await abandon();
 		const outcome = await pollDeviceApproval(api, request);
 		if (outcome.state === "unlocked") return outcome.deviceKey;
 		if (outcome.state === "rejected") throw new Error("The approval was rejected in EtherPK.");
 		if (outcome.state === "expired") throw new Error("The approval expired before it was confirmed. Run login again.");
 		await io.sleep(APPROVAL_POLL_MS);
+		if (io.signal?.aborted) await abandon();
 	}
 	throw new Error("The approval was not confirmed in time. Run login again.");
 }
@@ -8320,9 +8349,10 @@ var USAGE = `etherpk-mcp - EtherPK Headless Client (an MCP server over one synce
   etherpk-mcp login --server <url> [--pat <token>] [--recovery-code]
       Sign this machine in as a device of your account. Prompts for a Personal Access
       Token (an account-wide one, from the Sync Server portal at <url>/account/tokens)
-      unless --pat or ETHERPK_PAT is given, then unlocks your keys by Device Approval
-      (confirm a code in any unlocked EtherPK tab) or, with --recovery-code, by typing
-      your Recovery Code (or ETHERPK_RECOVERY_CODE, for a scripted setup).
+      unless --pat or ETHERPK_PAT is given, then unlocks your keys by Device Approval:
+      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).
   etherpk-mcp graphs
       List the synced graphs this account can reach, by name and id.
   etherpk-mcp serve --graph <id or name>
@@ -8393,10 +8423,8 @@ async function login(args) {
 		pat
 	});
 	console.log(`Signed in to ${server} as ${account.principal.email ?? account.principal.name ?? account.principal.id}.`);
-	const vaultKey = args["recovery-code"] ? await unlockByRecoveryCode(account.api, process.env.ETHERPK_RECOVERY_CODE ?? await ask("Recovery Code: ", { secret: true })) : await unlockByDeviceApproval(account.api, {
-		say: (line) => console.log(line),
-		sleep: (ms) => new Promise((r) => setTimeout(r, ms))
-	});
+	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, {
 		server,
 		pat,
@@ -8409,6 +8437,53 @@ async function login(args) {
 		vaultKey: toBase64Url(vaultKey)
 	});
 }
+/**
+* Device Approval, with the Recovery Code one keypress away: a user who has no unlocked EtherPK
+* to hand should not have to Ctrl-C and re-read the help to find `--recovery-code`. On a
+* terminal, `r` during the wait abandons the approval (cancelled server-side) and asks for the
+* code instead; without a terminal the wait runs to its outcome.
+*/
+async function approveOrFallBack(account, byRecoveryCode) {
+	const abort = new AbortController();
+	const io = {
+		say: (line) => console.log(line),
+		sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
+		signal: abort.signal,
+		clientUrl: account.clientUrl
+	};
+	const stdin = process.stdin;
+	const interactive = stdin.isTTY === true;
+	const onKey = (chunk) => {
+		const key = chunk.toString("utf8");
+		if (key === "r" || key === "R") abort.abort();
+		if (key === "") {
+			console.log("");
+			process.exit(130);
+		}
+	};
+	if (interactive) {
+		console.log("(Press r to type your Recovery Code instead.)");
+		stdin.setRawMode(true);
+		stdin.resume();
+		stdin.on("data", onKey);
+	}
+	let abandoned = false;
+	try {
+		return await unlockByDeviceApproval(account.api, io);
+	} catch (error) {
+		if (!(error instanceof ApprovalAbandoned)) throw error;
+		abandoned = true;
+	} finally {
+		if (interactive) {
+			stdin.off("data", onKey);
+			stdin.setRawMode(false);
+			stdin.pause();
+		}
+	}
+	if (!abandoned) throw new Error("unreachable");
+	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: etherpk-mcp login");
 	const account = await connectAccount(config);