@appsoftwareltd/etherpk-mcp 0.1.1 → 0.1.2

package/README.md

@@ -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-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, 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.
@@ -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 --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,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) {
@@ -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({