@appsoftwareltd/etherpk-mcp 0.1.1 → 0.2.0

package/README.md

@@ -17,18 +17,18 @@ server and graph filled in. They are:
 
 ```sh
 # 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
+# https://sync.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
+npx @appsoftwareltd/etherpk-mcp login --sync-server https://sync.etherpk.com
 
 # Self-hosting your own Sync Server? Give its address instead:
-#   npx @appsoftwareltd/etherpk-mcp login --server https://sync.your-domain.example
+#   npx @appsoftwareltd/etherpk-mcp login --sync-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
+#   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>
@@ -37,6 +37,10 @@ claude mcp add etherpk -- npx @appsoftwareltd/etherpk-mcp serve --graph <graph i
 `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.
 
+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
 
 `list_documents`, `read_document`, `search`, `backlinks`, `tasks`, `edit_document` (an exact,
@@ -57,5 +61,30 @@ One running instance serves one graph.
 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.
 
+## 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-sync/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, 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.2.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",
+	"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.
@@ -598,13 +653,13 @@ function createSyncTokenSource(mint, opts) {
 */
 function createHeadlessAccount(config) {
 	const api = createSyncApi({
-		baseUrl: config.server,
+		baseUrl: config.syncServer,
 		token: config.pat
 	});
 	return {
 		api,
-		serverBaseUrl: config.server,
-		relayUrl: relayUrlFrom(config.server),
+		serverBaseUrl: config.syncServer,
+		relayUrl: relayUrlFrom(config.syncServer),
 		tokenFor: (graphId) => createSyncTokenSource(() => api.mintSyncToken(graphId))
 	};
 }
@@ -674,9 +729,9 @@ function parseConfig(raw) {
 	}
 	if (typeof parsed !== "object" || parsed === null) return null;
 	const rec = parsed;
-	if (typeof rec.server !== "string" || typeof rec.pat !== "string") return null;
+	if (typeof rec.syncServer !== "string" || typeof rec.pat !== "string") return null;
 	const out = {
-		server: rec.server.replace(/\/$/, ""),
+		syncServer: rec.syncServer.replace(/\/$/, ""),
 		pat: rec.pat
 	};
 	if (typeof rec.vaultKey === "string" && rec.vaultKey !== "") out.vaultKey = rec.vaultKey;
@@ -8335,7 +8390,7 @@ function createMcpServer(graph, info) {
 /**
 * `etherpk-mcp`: the [[Headless Client]]'s command line (ADR 0072).
 *
-*   etherpk-mcp login  --server <url> [--pat <token>] [--recovery-code]
+*   etherpk-mcp login  --sync-server <url> [--pat <token>] [--recovery-code]
 *   etherpk-mcp graphs
 *   etherpk-mcp serve  --graph <id or name>
 *   etherpk-mcp logout
@@ -8343,22 +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 --sync-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:
       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
+  ${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
@@ -8409,30 +8471,30 @@ 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 --sync-server <url>`);
 	return config;
 }
 async function login(args) {
 	const path = defaultConfigPath();
-	const server = (args.server ?? (await readConfig(path))?.server ?? await ask("Sync Server URL: ")).replace(/\/$/, "");
-	if (!/^https?:\/\//.test(server)) fail("The server must be an http(s) URL.");
-	const pat = args.pat ?? process.env.ETHERPK_PAT ?? await ask(`Personal Access Token (account-wide, from ${server}/account/tokens): `, { secret: true });
+	const syncServer = (args["sync-server"] ?? (await readConfig(path))?.syncServer ?? await ask("Sync Server URL: ")).replace(/\/$/, "");
+	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.");
 	const account = await connectAccount({
-		server,
+		syncServer,
 		pat
 	});
-	console.log(`Signed in to ${server} as ${account.principal.email ?? account.principal.name ?? account.principal.id}.`);
+	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, {
-		server,
+		syncServer,
 		pat,
 		vaultKey: toBase64Url(vaultKey)
 	});
 	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.`);
 	await listGraphs({
-		server,
+		syncServer,
 		pat,
 		vaultKey: toBase64Url(vaultKey)
 	});
@@ -8485,7 +8547,7 @@ async function approveOrFallBack(account, byRecoveryCode) {
 	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();
@@ -8507,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();
@@ -8535,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({
@@ -8579,7 +8642,7 @@ async function main() {
 		args: process.argv.slice(2),
 		allowPositionals: true,
 		options: {
-			server: { type: "string" },
+			"sync-server": { type: "string" },
 			pat: { type: "string" },
 			"recovery-code": { type: "boolean" },
 			graph: { type: "string" },