@appsoftwareltd/etherpk-mcp 0.1.0 → 0.1.2

package/README.md

@@ -16,18 +16,30 @@ 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.
+
+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
+drop the `npx @appsoftwareltd/` prefix; the program's own hints follow whichever way you ran it.
 
 ## What the agent gets
 
@@ -36,11 +48,43 @@ 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.
+
+## Building and publishing
+
+From the EtherPK monorepo (`apps/mcp`; the bundle compiles the Client's own sync, crypto and
+index code in through a `$lib` alias, so it builds from the repo, not from this folder alone):
+
+```sh
+pnpm install                      # once, at the repo root
+pnpm --filter @appsoftwareltd/etherpk-mcp check   # type-check
+pnpm --filter @appsoftwareltd/etherpk-mcp test    # unit tests (loopback relay, no server)
+pnpm --filter @appsoftwareltd/etherpk-mcp build   # dist/main.js; run it with node dist/main.js
+```
+
+To release: bump `version` in `package.json` (the CLI reads its version from there), then from
+`apps/mcp` in a real terminal (both the login and the publish need a browser or one-time code,
+which needs a TTY):
+
+```sh
+npm whoami || npm login                        # only if not already signed in (or the token has expired); needs publish rights on @appsoftwareltd
+pnpm publish --access public --no-git-checks   # prepack runs the build; pnpm rewrites workspace:* deps
+npx -y @appsoftwareltd/etherpk-mcp@<version> --version   # verify, once the registry lists it (a few minutes)
+```
+
+The end-to-end specs in `tests-server/agents/` build and drive this bundle against a real Sync
+Server; the technical notes are in the repo under `docs/docs/technical/Headless Client.md`.
 
-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

@@ -15,6 +15,61 @@ import { parser } from "@lezer/markdown";
 import { parse, stringify } from "yaml";
 import { deserialize, serialize } from "node:v8";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+var package_default = {
+	name: "@appsoftwareltd/etherpk-mcp",
+	version: "0.1.2",
+	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",
+	"private": false,
+	bin: { "etherpk-mcp": "./bin/etherpk-mcp.js" },
+	files: ["bin", "dist"],
+	scripts: {
+		"build": "vite build",
+		"check": "tsc -p tsconfig.json --noEmit",
+		"test": "vitest run",
+		"test:watch": "vitest",
+		"prepack": "pnpm build"
+	},
+	dependencies: {
+		"@lezer/markdown": "^1.6.4",
+		"@modelcontextprotocol/sdk": "^1.30.0",
+		"@noble/curves": "^2.2.0",
+		"@noble/hashes": "^2.2.0",
+		"@sqlite.org/sqlite-wasm": "3.53.0-build1",
+		"fake-indexeddb": "^6.2.5",
+		"lib0": "^0.2.117",
+		"y-protocols": "^1.0.7",
+		"yaml": "^2.9.0",
+		"yjs": "^13.6.31",
+		"zod": "^4.3.6"
+	},
+	devDependencies: {
+		"@appsoftwareltd/etherpk-shared": "workspace:*",
+		"@codemirror/view": "^6.43.0",
+		"@types/node": "^25.6.0",
+		"typescript": "^6.0.2",
+		"vite": "^8.0.8",
+		"vitest": "^4.1.4"
+	},
+	publishConfig: { "access": "public" },
+	homepage: "https://docs.etherpk.com/using-ai-agents-with-your-notes",
+	repository: {
+		"type": "git",
+		"url": "https://github.com/appsoftwareltd/etherpk",
+		"directory": "apps/mcp"
+	},
+	keywords: [
+		"etherpk",
+		"mcp",
+		"model-context-protocol",
+		"knowledge-graph",
+		"notes",
+		"agent"
+	],
+	engines: { "node": ">=22" }
+};
+//#endregion
 //#region ../client/src/lib/crypto/bytes.ts
 /**
 * Byte-array and encoding primitives for the crypto core. No cryptography here.
@@ -618,7 +673,8 @@ async function connectAccount(config) {
 			id: me.principal.id,
 			email: me.principal.email,
 			name: me.principal.name
-		}
+		},
+		clientUrl: me.clientUrl ?? null
 	};
 }
 /**
@@ -858,6 +914,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 +2033,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 +7991,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.");
 }
@@ -8314,21 +8398,29 @@ function createMcpServer(graph, info) {
 * `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.
 */
-var VERSION = "0.1.0";
+var VERSION = package_default.version;
+/**
+* How the user invokes this program, so every hint is one they can paste. Through npx - the way
+* the Agents tab, the README and the docs all say - the bin is never on their PATH, and an npx
+* run executes out of npm's `_npx` cache; a global install (`npm install -g`) runs from
+* anywhere else and does have `etherpk-mcp` on the PATH, so it gets the short spelling.
+*/
+var CMD = /[\\/]_npx[\\/]/.test(process.argv[1] ?? "") ? "npx @appsoftwareltd/etherpk-mcp" : "etherpk-mcp";
 var USAGE = `etherpk-mcp - EtherPK Headless Client (an MCP server over one synced graph)
 
-  etherpk-mcp login --server <url> [--pat <token>] [--recovery-code]
+  ${CMD} 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).
-  etherpk-mcp graphs
+      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).
+  ${CMD} graphs
       List the synced graphs this account can reach, by name and id.
-  etherpk-mcp serve --graph <id or name>
+  ${CMD} serve --graph <id or name>
       Serve one graph to an agent over stdio. For Claude Code:
         claude mcp add etherpk -- npx @appsoftwareltd/etherpk-mcp serve --graph <id>
-  etherpk-mcp logout
+  ${CMD} logout
       Forget the token, keys and cached graphs on this machine.
 
 The config file is ${defaultConfigPath()} (override with ETHERPK_MCP_CONFIG); cached graphs live
@@ -8379,7 +8471,7 @@ async function ask(question, { secret = false } = {}) {
 }
 async function requireConfig(path) {
 	const config = await readConfig(path);
-	if (!config) fail(`Not logged in on this machine. Run: etherpk-mcp login --server <url>`);
+	if (!config) fail(`Not logged in on this machine. Run: ${CMD} login --server <url>`);
 	return config;
 }
 async function login(args) {
@@ -8393,10 +8485,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,8 +8499,55 @@ 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");
+	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 graphs = await account.api.listGraphs();
@@ -8432,13 +8569,14 @@ async function listGraphs(config) {
 		console.log(`  ${record.id}  ${label}  [${record.role}]`);
 	}
 	console.log("");
-	console.log("Serve one to an agent with:  etherpk-mcp serve --graph <id>");
+	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>`);
 }
 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: etherpk-mcp login");
+	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 graphs = await account.api.listGraphs();
@@ -8460,7 +8598,7 @@ async function serve(args) {
 			break;
 		}
 	}
-	if (!graphId) fail(`No synced graph is named or identified by "${wanted}". Run: etherpk-mcp graphs`);
+	if (!graphId) fail(`No synced graph 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({