@appsoftwareltd/etherpk-mcp 0.36.0 → 0.38.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/main.js CHANGED
@@ -820,7 +820,7 @@ function looksLikeAgentSetupCode(value) {
820
820
  }
821
821
  var package_default = {
822
822
  name: "@appsoftwareltd/etherpk-mcp",
823
- version: "0.36.0",
823
+ version: "0.38.0",
824
824
  license: "Elastic-2.0",
825
825
  description: "EtherPK Headless Client: an MCP server over a synced knowledge graph, run beside the agent on the user's own machine.",
826
826
  type: "module",
@@ -3217,7 +3217,7 @@ async function upgradeToAgentToken(opts) {
3217
3217
  },
3218
3218
  keychain: inKeychain(stored) ? keychain : null
3219
3219
  });
3220
- say(`etherpk-mcp: replaced the access token for ${current.syncServer} with an agent token for this computer, kept in ${where}. An agent token can do only what an agent needs, and the old token has been revoked.`);
3220
+ say(`etherpk-mcp: replaced the access token for ${current.syncServer} with an agent token for this device, kept in ${where}. An agent token can do only what an agent needs, and the old token has been revoked.`);
3221
3221
  return {
3222
3222
  ...current,
3223
3223
  pat: agentToken
@@ -7194,6 +7194,10 @@ function priorityClause(priorities) {
7194
7194
  /** The tasks due in `window` of `today`, or null for any. */
7195
7195
  function dueClause(window, today) {
7196
7196
  if (window === "any") return null;
7197
+ if (window === "none") return {
7198
+ sql: "t.due IS NULL",
7199
+ params: []
7200
+ };
7197
7201
  if (window === "overdue") return {
7198
7202
  sql: "(t.due IS NOT NULL AND t.due < ?)",
7199
7203
  params: [today]
@@ -8303,7 +8307,11 @@ async function setupSemantic(io) {
8303
8307
  io.say(`Downloading ${file.name} (${Math.max(1, Math.round(file.bytes / 1e6))} MB) from ${new URL(file.url).host}…`);
8304
8308
  await download(io.fetch ?? fetch, file, path);
8305
8309
  }
8306
- io.say(`Semantic search is set up. Model: ${MODEL.id} (${MODEL.dims} dimensions) in ${status.modelDir}.`);
8310
+ io.say("Semantic search is set up.");
8311
+ io.say("");
8312
+ io.say(`Next, serve embeds the passages of each graph it serves, in the background. This can take a few minutes on a large graph. A serve that is already running starts within half a minute, otherwise the next serve starts it. Until it finishes, a semantic search answers from the passages embedded so far and marks its results incomplete. To see progress, run: ${io.command ?? "etherpk-mcp"} semantic status`);
8313
+ io.say("");
8314
+ io.say(`Model: ${MODEL.id} (${MODEL.dims} dimensions), in ${status.modelDir}.`);
8307
8315
  return semanticSetupStatus(io.env, files);
8308
8316
  }
8309
8317
  async function npmInstall(args, cwd, say) {
@@ -8365,7 +8373,7 @@ var SemanticUnavailable = class extends Error {
8365
8373
  this.name = "SemanticUnavailable";
8366
8374
  }
8367
8375
  };
8368
- var SETUP_HINT = "run `npx @appsoftwareltd/etherpk-mcp semantic setup` on this computer once (it installs a ~300 MB runtime and a 23 MB model into the cache directory) - the next semantic search will use it, no restart needed.";
8376
+ var SETUP_HINT = "run `npx @appsoftwareltd/etherpk-mcp semantic setup` on this device once (it installs a ~300 MB runtime and a 23 MB model into the cache directory) - the next semantic search will use it, no restart needed.";
8369
8377
  /** The thread count `serve` uses: the option, else the environment, else the conservative default. */
8370
8378
  function semanticThreads(env, requested) {
8371
8379
  if (requested !== void 0) return Math.max(1, Math.floor(requested));
@@ -8379,7 +8387,7 @@ function semanticThreads(env, requested) {
8379
8387
  */
8380
8388
  async function loadEmbeddingModel(env, options = {}) {
8381
8389
  const status = await semanticSetupStatus(env);
8382
- if (!status.runtime || !status.model) throw new SemanticUnavailable(`Semantic search is not set up on this computer: ${SETUP_HINT}`);
8390
+ if (!status.runtime || !status.model) throw new SemanticUnavailable(`Semantic search is not set up on this device: ${SETUP_HINT}`);
8383
8391
  const require = createRequire(join(status.runtimeDir, "package.json"));
8384
8392
  let ort;
8385
8393
  try {
@@ -13369,11 +13377,11 @@ function offlineSince(connection, now = Date.now()) {
13369
13377
  /** The note an answer carries while its copy is offline; null while connected and on a folder, which has no connection. */
13370
13378
  function offlineNotice(connection, now = Date.now()) {
13371
13379
  if (connection?.state !== "offline") return null;
13372
- return `This computer's copy of the graph has been ${offlineSince(connection, now)}. This answer comes from that copy: it can lack edits made elsewhere since then, and a page or task it does not find may only be newer than the copy. Tell the user before relying on it. The copy catches up when the connection returns.`;
13380
+ return `This device's copy of the graph has been ${offlineSince(connection, now)}. This answer comes from that copy: it can lack edits made elsewhere since then, and a page or task it does not find may only be newer than the copy. Tell the user before relying on it. The copy catches up when the connection returns.`;
13373
13381
  }
13374
13382
  /** One line for the host's log. */
13375
13383
  function connectionChangeLine(change) {
13376
- if (change.connection.state === "offline") return "lost the connection to the Sync Server; the tools answer from this computer's copy.";
13384
+ if (change.connection.state === "offline") return "lost the connection to the Sync Server; the tools answer from this device's copy.";
13377
13385
  return change.offlineForMs === null ? "connected to the Sync Server." : `connected to the Sync Server again, after ${durationWords(change.offlineForMs)} offline.`;
13378
13386
  }
13379
13387
  // ../client/src/lib/document/publish/selection.ts
@@ -17394,7 +17402,7 @@ async function setupDiagrams(env, say) {
17394
17402
  }
17395
17403
  const cli = require$2.resolve("playwright-core/cli.js");
17396
17404
  const dir = env.PLAYWRIGHT_BROWSERS_PATH?.trim() || browsersDir(env);
17397
- say(`Installing Chromium into ${dir} (about 170 MB, once per computer - a diagram is rendered by a browser, and this is the one etherpk-mcp drives)…`);
17405
+ say(`Installing Chromium into ${dir} (about 170 MB, once per device - a diagram is rendered by a browser, and this is the one etherpk-mcp drives)…`);
17398
17406
  await new Promise((resolve, reject) => {
17399
17407
  const child = spawn(process.execPath, [
17400
17408
  cli,
@@ -21716,8 +21724,8 @@ async function requireReferencedTask(graph, reference, purpose = "read") {
21716
21724
  * same words and would fail the same way, so it asks for a retry instead.
21717
21725
  */
21718
21726
  function taskNotFoundMessage(connection) {
21719
- if (connection?.state === "offline") return `No task in this computer's copy of the graph has those words, but the copy has been ${offlineSince(connection)}, so the task may be newer than the copy. Tell the user, and try again once graph_info says the copy is connected.`;
21720
- return "No task in the graph has those words now: it was edited or deleted, or the change has not reached this computer yet. Ask the user for a fresh agent instruction.";
21727
+ if (connection?.state === "offline") return `No task in this device's copy of the graph has those words, but the copy has been ${offlineSince(connection)}, so the task may be newer than the copy. Tell the user, and try again once graph_info says the copy is connected.`;
21728
+ return "No task in the graph has those words now: it was edited or deleted, or the change has not reached this device yet. Ask the user for a fresh agent instruction.";
21721
21729
  }
21722
21730
  /**
21723
21731
  * The block's own lines and everything nested under it: in the index's rows, which run in
@@ -21841,7 +21849,7 @@ async function graphInfo(graph) {
21841
21849
  complete: status.embedded >= status.total
21842
21850
  } : {
21843
21851
  state: "not-opened",
21844
- note: "The first search with mode \"semantic\" loads the model - if it is not set up on this computer, that search says so and names the command."
21852
+ note: "The first search with mode \"semantic\" loads the model - if it is not set up on this device, that search says so and names the command."
21845
21853
  },
21846
21854
  assets: { available: graph.assets !== void 0 }
21847
21855
  };
@@ -22086,7 +22094,7 @@ async function publish(graph, args, host) {
22086
22094
  renderer = await openDiagramRenderer(env);
22087
22095
  if (!renderer) {
22088
22096
  const status = await chromiumStatus(env, cmd);
22089
- throw new ToolError("chromium_unavailable", `"${publication.name}" has Mermaid diagrams, which a publish draws with a browser, and none is set up on this computer. Ask the user to run: ${status.setupCommand} (or set ETHERPK_CHROMIUM to a Chromium on this machine). Nothing was published.`);
22097
+ throw new ToolError("chromium_unavailable", `"${publication.name}" has Mermaid diagrams, which a publish draws with a browser, and none is set up on this device. Ask the user to run: ${status.setupCommand} (or set ETHERPK_CHROMIUM to a Chromium on this machine). Nothing was published.`);
22090
22098
  }
22091
22099
  }
22092
22100
  let maps = null;
@@ -22095,7 +22103,7 @@ async function publish(graph, args, host) {
22095
22103
  if (!maps) {
22096
22104
  await renderer?.dispose();
22097
22105
  const status = await chromiumStatus(env, cmd);
22098
- throw new ToolError("chromium_unavailable", `"${publication.name}" has maps, which a publish draws as pictures with a browser, and none is set up on this computer. Ask the user to run: ${status.setupCommand} (or set ETHERPK_CHROMIUM to a Chromium on this machine). Nothing was published.`);
22106
+ throw new ToolError("chromium_unavailable", `"${publication.name}" has maps, which a publish draws as pictures with a browser, and none is set up on this device. Ask the user to run: ${status.setupCommand} (or set ETHERPK_CHROMIUM to a Chromium on this machine). Nothing was published.`);
22099
22107
  }
22100
22108
  }
22101
22109
  let drawings = null;
@@ -22105,7 +22113,7 @@ async function publish(graph, args, host) {
22105
22113
  await renderer?.dispose();
22106
22114
  await maps?.dispose();
22107
22115
  const status = await chromiumStatus(env, cmd);
22108
- throw new ToolError("chromium_unavailable", `"${publication.name}" has drawings, which a publish draws as pictures with a browser, and none is set up on this computer. Ask the user to run: ${status.setupCommand} (or set ETHERPK_CHROMIUM to a Chromium on this machine). Nothing was published.`);
22116
+ throw new ToolError("chromium_unavailable", `"${publication.name}" has drawings, which a publish draws as pictures with a browser, and none is set up on this device. Ask the user to run: ${status.setupCommand} (or set ETHERPK_CHROMIUM to a Chromium on this machine). Nothing was published.`);
22109
22117
  }
22110
22118
  }
22111
22119
  try {
@@ -22867,7 +22875,7 @@ function withOfflineNote(result, connection) {
22867
22875
  function accessEndedError(graph, cmd) {
22868
22876
  const loss = graph.accessLoss();
22869
22877
  if (!loss) return null;
22870
- return loss.kind === "membership" ? new ToolError("access_removed", `This account no longer has access to the graph: it left, was removed by the owner, or the graph was deleted. Run ${cmd} graphs to see the graphs it can reach.`) : new ToolError("token_revoked", `The Sync Server no longer accepts this computer's access token: it was revoked or has expired, or the account's password was reset. Run ${cmd} login again.`);
22878
+ return loss.kind === "membership" ? new ToolError("access_removed", `This account no longer has access to the graph: it left, was removed by the owner, or the graph was deleted. Run ${cmd} graphs to see the graphs it can reach.`) : new ToolError("token_revoked", `The Sync Server no longer accepts this device's access token: it was revoked or has expired, or the account's password was reset. Run ${cmd} login again.`);
22871
22879
  }
22872
22880
  var concept = z.string().min(1).describe("A page title, one of its aliases, a journal day as YYYY-MM-DD, or \"today\".");
22873
22881
  var readOffset = z.number().int().min(0).optional().describe("Where to start reading: the nextOffset a cut answer gave. 0 (the start) by default.");
@@ -22908,17 +22916,17 @@ function createMcpServer(source, info) {
22908
22916
  version: info.version
22909
22917
  }, { instructions: [
22910
22918
  `You are connected to the EtherPK knowledge graph "${info.graphName}": daily journal entries and titled pages in plain markdown, linked with [[wikilinks]].`,
22911
- ...backendKind === "synced" ? ["This graph is synced and encrypted: it has no folder on this computer, so reach it only through these tools.", "The tools answer from this computer's copy of the graph. While that copy is offline from the Sync Server, every answer ends with a note saying since when and graph_info reports connection.state \"offline\". Edits made elsewhere since then are missing, so a page or task that is not found may only be newer than the copy: tell the user that, rather than saying it is gone."] : [],
22919
+ ...backendKind === "synced" ? ["This graph is synced and encrypted: it has no folder on this device, so reach it only through these tools.", "The tools answer from this device's copy of the graph. While that copy is offline from the Sync Server, every answer ends with a note saying since when and graph_info reports connection.state \"offline\". Edits made elsewhere since then are missing, so a page or task that is not found may only be newer than the copy: tell the user that, rather than saying it is gone."] : [],
22912
22920
  `This process holds the EtherPK sign-in and Encryption Keys it needs. Never read, print, copy or search ${info.credentialsDir ?? "~/.config/etherpk"}, or any keychain entry named etherpk-mcp: they are credentials that open the whole account, not notes.`,
22913
22921
  "Concept names are case-insensitive. Protected documents are not shown here: no list, search, backlink, task or graph answer names one, and a read of one answers not_found. graph_info says how many there are. A write onto a protected document's name is refused with protected_document - tell the user to make that change in EtherPK.",
22914
22922
  "Bullets are \"- \" with two-space nesting. Tasks are \"- [ ]\" / \"- [x]\" with task tags (#P1 #P2 #P3, #W #D #C, #D-YYYY-MM-DD due, #S-YYYY-MM-DD scheduled) right after the checkbox. A free tag such as #bug or #needs-review (letters, digits and single hyphens) is the user's own label and can go anywhere in a task's text; write task tags first.",
22915
22923
  "read_document returns a document's body as text and its frontmatter block as data (the \"frontmatter\" object) - the block is never in the text, so line numbers from search, backlinks and tasks match the text. Set frontmatter keys with set_frontmatter (public, publications, date, author, description and any other key) - a document's title and aliases and a publication page's definition are not frontmatter here and have tools of their own.",
22916
22924
  "Edit with edit_document (an exact, unique old→new replacement) or append_document - read first, then edit, and never paste a whole page back.",
22917
22925
  "To rename a page or concept use plan_rename then rename, never a frontmatter edit: rename carries scoped concepts (\"[[Old]] Notes\") along and by default rewrites every [[Old]] link in the graph to the new name (strategy \"rewrite\") - strategy \"alias\" keeps the old name resolving instead. A rename onto a name that is taken merges two documents and needs confirm_merge: true. References inside protected documents cannot be seen or rewritten, and a protected page under the old name moves with it without being named.",
22918
- "search has two kinds of matching: mode \"text\" (default) matches words and quoted phrases, and mode \"semantic\" finds passages about what a question or description means even when no words match. Use semantic for questions and descriptions, text for names, identifiers and exact phrases. \"hybrid\" returns both groups. When you answer from a search result, cite the document and where in it (its breadcrumb or lines). Semantic mode needs a one-time \"semantic setup\" on this computer - if it is not set up, search says so and names the command.",
22926
+ "search has two kinds of matching: mode \"text\" (default) matches words and quoted phrases, and mode \"semantic\" finds passages about what a question or description means even when no words match. Use semantic for questions and descriptions, text for names, identifiers and exact phrases. \"hybrid\" returns both groups. When you answer from a search result, cite the document and where in it (its breadcrumb or lines). Semantic mode needs a one-time \"semantic setup\" on this device - if it is not set up, search says so and names the command.",
22919
22927
  "graph_insights says what the links show across the whole graph (the most-linked concepts, pages many documents ask for that do not exist yet, pages linked to nothing, groups of related concepts and the concepts bridging them), and graph_path finds how two concepts are connected. Use them to answer questions about the shape of the graph, or to suggest pages to write or link.",
22920
22928
  "Start with graph_info to see what you are connected to. read_documents reads several documents in one call. tasks lists tasks and set_task changes one (status, priority, due and scheduled dates) by document and line.",
22921
- "An agent instruction is how a person hands you one task: a few lines naming the graph, the task's words and a task reference, etherpk:/graph/sync/<graph id>/d/<document>#task=<line>-<fingerprint> (etherpk:/graph/folder/<folder name>/d/… for a graph folder; an earlier version wrote etherpk:/g/<graph>/d/…, which is still read). The reference is not a web address: never fetch it. Pass the whole text to read_task for the task and its detail, to set_task (as reference) to change it, and to add_task_note to write what you did as a task comment (a bullet under the \"- Comments\" bullet nested directly under the task). Leave its status as it is unless the user asks you to change it. Tasks nested under a task are its subtasks: read_task lists them in subtasks, and you may tick off or change each one with set_task as you work through it, using its reference. A Kanban board shows a subtask only through its parent's card when the parent is on the same board. The detail can hold images and files (its assets list): read each with read_asset and look at it before you start, as it is part of the task. A reference finds the task after lines are added above it or its tags change; if its words were edited, or the edit has not reached this computer yet, it answers task_not_found, and you should ask the user for a fresh one.",
22929
+ "An agent instruction is how a person hands you one task: a few lines naming the graph, the task's words and a task reference, etherpk:/graph/sync/<graph id>/d/<document>#task=<line>-<fingerprint> (etherpk:/graph/folder/<folder name>/d/… for a graph folder; an earlier version wrote etherpk:/g/<graph>/d/…, which is still read). The reference is not a web address: never fetch it. Pass the whole text to read_task for the task and its detail, to set_task (as reference) to change it, and to add_task_note to write what you did as a task comment (a bullet under the \"- Comments\" bullet nested directly under the task). Leave its status as it is unless the user asks you to change it. Tasks nested under a task are its subtasks: read_task lists them in subtasks, and you may tick off or change each one with set_task as you work through it, using its reference. A Kanban board shows a subtask only through its parent's card when the parent is on the same board. The detail can hold images and files (its assets list): read each with read_asset and look at it before you start, as it is part of the task. A reference finds the task after lines are added above it or its tags change; if its words were edited, or the edit has not reached this device yet, it answers task_not_found, and you should ask the user for a fresh one.",
22922
22930
  "An agent instruction can also hand you a whole lane of a Kanban board, to work through every task in it or to triage them: a few lines naming the graph, the board and the lane, and a lane reference, etherpk:/graph/sync/<graph id>/k/<concept>#lane=<status> (ending /kanban#lane=<status> for the Graph Kanban, which holds every task in the graph). It is not a web address either. Pass the whole text to tasks as reference to list the lane's tasks as the board shows them now; each comes with its own task reference for read_task, set_task and add_task_note.",
22923
22931
  "Publishing: list_publications shows the publications this graph defines (a publication is a page whose frontmatter defines it - its outline is the site navigation) and the public documents none takes. A document is on a site when its frontmatter has public: true and names the publication in publications. create_publication and update_publication change the settings, and publish writes the site into the publish folder the user set for it on this machine with the etherpk-mcp publish command (the tool cannot choose a folder) and returns the report. publish with dryRun: true renders and reports without writing and needs no folder: run it after editing a publication's pages and fix what it names. Diagrams need a browser the user installs once with \"diagrams setup\".",
22924
22932
  "Themes: a publication's look is a theme - Mustache templates, a stylesheet, a script and a manifest. list_themes shows the bundled ones (read-only) and the graph's own. read_theme writes a theme's files to a folder on this machine to read and edit. customise_publication_theme copies a publication's bundled theme into the graph and points the publication at the copy (create_theme copies any theme). write_theme_file, delete_theme_file and import_theme_folder change a graph theme. preview_theme renders a theme to a folder (with screenshots when a browser is set up) to check before publish. For a snippet such as an analytics script, an include slot (update_publication includes, e.g. head) filled by a page may be lighter than a theme copy.",
@@ -22966,7 +22974,7 @@ function createMcpServer(source, info) {
22966
22974
  }, async (args) => run((graph) => readDocuments(graph, args)));
22967
22975
  server.registerTool("search", {
22968
22976
  title: "Search",
22969
- description: `Search every unprotected document. mode "text" (default): words match by prefix, "quoted phrases" match exactly. Documents come most-matches-first with the matching lines. In text mode a term key:value is a property filter on the documents' frontmatter when some document has that key, and keys and values ignore case (key:"two words", -key:value excludes, key:* means the key is set, key:va* matches the start of a value, publication.id:docs reaches a nested key, title: and aliases: match the document's names). Filters alone list every matching document with the values they matched and no hits. mode "semantic": the passages closest in MEANING to the query, best first, each with its text, a similarity 0..1 and where it is (concept, breadcrumb of headings and parent bullets, start and end line) - finds a note that says "self-assessment is due 31 January" for "tax deadline". Line numbers are 0-based in every mode. Passage text is the note's own words with bullet markers and [[ ]] stripped: quote and cite it, but anchor edit_document on text from read_document. Use semantic for questions and descriptions, text for names, identifiers and exact phrases. mode "hybrid" returns both as separate groups. Semantic results carry complete: false while this computer is still embedding the graph (rerun later for more). If semantic mode answers error semantic_unavailable, it is not set up on this computer: tell the user the command in the message. At most 50 documents per call.`,
22977
+ description: `Search every unprotected document. mode "text" (default): words match by prefix, "quoted phrases" match exactly. Documents come most-matches-first with the matching lines. In text mode a term key:value is a property filter on the documents' frontmatter when some document has that key, and keys and values ignore case (key:"two words", -key:value excludes, key:* means the key is set, key:va* matches the start of a value, publication.id:docs reaches a nested key, title: and aliases: match the document's names). Filters alone list every matching document with the values they matched and no hits. mode "semantic": the passages closest in MEANING to the query, best first, each with its text, a similarity 0..1 and where it is (concept, breadcrumb of headings and parent bullets, start and end line) - finds a note that says "self-assessment is due 31 January" for "tax deadline". Line numbers are 0-based in every mode. Passage text is the note's own words with bullet markers and [[ ]] stripped: quote and cite it, but anchor edit_document on text from read_document. Use semantic for questions and descriptions, text for names, identifiers and exact phrases. mode "hybrid" returns both as separate groups. Semantic results carry complete: false while this device is still embedding the graph (rerun later for more). If semantic mode answers error semantic_unavailable, it is not set up on this device: tell the user the command in the message. At most 50 documents per call.`,
22970
22978
  inputSchema: {
22971
22979
  query: z.string().min(1),
22972
22980
  mode: z.enum([
@@ -23290,7 +23298,7 @@ function createMcpServer(source, info) {
23290
23298
  }, async (args) => run((graph) => previewTheme(graph, args, host)));
23291
23299
  server.registerTool("graph_info", {
23292
23300
  title: "Graph info",
23293
- description: "What you are connected to: the graph's name, whether it is a synced graph (on which server, and whether this computer's copy is connected to it now: connection.state and since) or a folder, how many pages and journal entries it has and how many of them are protected (protected documents are counted here and shown nowhere else), the state of semantic search, whether assets are available, the publications with the publish folder set for each on this machine, and whether Mermaid diagrams can be drawn here.",
23301
+ description: "What you are connected to: the graph's name, whether it is a synced graph (on which server, and whether this device's copy is connected to it now: connection.state and since) or a folder, how many pages and journal entries it has and how many of them are protected (protected documents are counted here and shown nowhere else), the state of semantic search, whether assets are available, the publications with the publish folder set for each on this machine, and whether Mermaid diagrams can be drawn here.",
23294
23302
  inputSchema: {}
23295
23303
  }, async () => run(async (graph) => {
23296
23304
  const publishing = await publishingInfo(graph, host);
@@ -30469,11 +30477,13 @@ async function unlockByDeviceApproval(api, io) {
30469
30477
  const request = await beginDeviceApproval(api);
30470
30478
  const where = io.clientUrl ? `open EtherPK at ${io.clientUrl}` : "open EtherPK in a browser";
30471
30479
  io.say("");
30472
- io.say(`To approve this device, ${where} (any page - it need not be a note) on any device where this account's`);
30473
- io.say("Encryption Keys are unlocked. A prompt appears on each of them: choose Show the code on the one you approve");
30474
- io.say("from, and this terminal then shows the same code.");
30480
+ io.say(`To approve this device, ${where} on any other device where your Encryption Keys are unlocked. Any page will do. Each of those devices shows a prompt: choose Show the code on one of them, and this terminal shows the same code.`);
30475
30481
  io.say("");
30476
30482
  io.say("Waiting (up to ten minutes)…");
30483
+ if (io.offersRecoveryCode) {
30484
+ io.say("");
30485
+ io.say("Press r to type your Recovery Code instead.");
30486
+ }
30477
30487
  const abandon = async () => {
30478
30488
  await Promise.race([api.cancelDeviceApproval(request.id).catch(() => {}), new Promise((resolve) => setTimeout(resolve, CANCEL_TIMEOUT_MS).unref())]);
30479
30489
  throw new ApprovalAbandoned();
@@ -30515,6 +30525,30 @@ async function unlockByDeviceApproval(api, io) {
30515
30525
  async function unlockByRecoveryCode(api, code) {
30516
30526
  return openVaultWithRecoveryCode(api, code);
30517
30527
  }
30528
+ // src/login-summary.ts
30529
+ function loginSummary(outcome) {
30530
+ const { syncServer, configPath, keptIn } = outcome;
30531
+ const paragraphs = [`Logged in. This device can now serve your synced graphs on ${syncServer} to agents.`];
30532
+ if (outcome.exchangedAccessToken) paragraphs.push(`The access token you gave has been revoked. This device now holds an Agent Token, limited to the routes an agent needs. If you used that access token anywhere else, create a new one at ${syncServer}/account/tokens.`);
30533
+ if (outcome.replacedEarlierLogin) paragraphs.push(`Replaced this device's earlier login to ${syncServer}. Its old token no longer works.`);
30534
+ paragraphs.push(keptIn === configPath ? `Encryption Keys unlocked and kept in ${configPath} (owner-only). Anyone who can read your files on this device can read this account, as with a signed-in browser. Never let an agent read, print or search that file.` : `Encryption Keys unlocked and kept in ${keptIn}. ${configPath} names only the server. A program you run can still ask ${keptIn} for them, so run only agents you trust with this account.`);
30535
+ if (outcome.otherServers.length > 0) paragraphs.push(`Also logged in to ${outcome.otherServers.join(", ")}, so commands need --sync-server <url> to say which server they mean.`);
30536
+ if (outcome.stoppedHosts > 0) {
30537
+ const graphs = outcome.stoppedHosts === 1 ? "one graph" : `${outcome.stoppedHosts} graphs`;
30538
+ paragraphs.push(`Stopped the background process of ${graphs} served with the previous login. Agents start a new one with this login on their next call.`);
30539
+ }
30540
+ return paragraphs;
30541
+ }
30542
+ /**
30543
+ * The last line of `login`: where the Client explains the rest of agent setup. Built from the
30544
+ * Client the Sync Server declares, since both can be self-hosted; null when it declares none.
30545
+ */
30546
+ function agentSetupLine(clientUrl) {
30547
+ if (!clientUrl) return null;
30548
+ return `Full instructions for setting up agents: ${new URL("/graphs?tab=agents", clientUrl).href}`;
30549
+ }
30550
+ /** Printed when the person presses r during Device Approval: their choice, not a failure. */
30551
+ var SWITCHING_TO_RECOVERY_CODE = "Unlocking with your Recovery Code instead.";
30518
30552
  // ../client/src/lib/storage/fs/directory-adapter.ts
30519
30553
  /** All four, in skeleton-creation order. */
30520
30554
  var SUBDIRS = [
@@ -30723,9 +30757,9 @@ var CMD = /[\\/]_npx[\\/]/.test(process.argv[1] ?? "") ? "npx @appsoftwareltd/et
30723
30757
  var USAGE = `etherpk-mcp - EtherPK Headless Client (an MCP server over one synced graph)
30724
30758
 
30725
30759
  ${CMD} login --sync-server <url> [--code <Agent Setup Code>] [--recovery-code]
30726
- Sign in this computer as a device of your account. Create an Agent Setup Code in EtherPK
30760
+ Sign in this device as one of your account's devices. Create an Agent Setup Code in EtherPK
30727
30761
  (the Graphs page's Agents tab, or a synced graph's Settings > Agents, or <url>/account/tokens) and pass it with --code: it works once, within 10
30728
- minutes, and gets this computer an Agent Token limited to the routes an agent needs. Then
30762
+ minutes, and gets this device an Agent Token limited to the routes an agent needs. Then
30729
30763
  unlock your Encryption Keys by Device Approval: confirm the matching code in EtherPK on
30730
30764
  any device where your Encryption Keys are unlocked, then press y. Press r while waiting,
30731
30765
  or pass --recovery-code, to type your Recovery Code instead (or ETHERPK_RECOVERY_CODE,
@@ -30739,7 +30773,7 @@ var USAGE = `etherpk-mcp - EtherPK Headless Client (an MCP server over one synce
30739
30773
  ${CMD} serve --graph <id or name> [--sync-server <url>] [--no-semantic]
30740
30774
  Serve one synced graph to an agent over stdio. For Claude Code:
30741
30775
  claude mcp add --scope user etherpk -- npx @appsoftwareltd/etherpk-mcp serve --sync-server <url> --graph <id>
30742
- Once "semantic setup" has run on this computer, serve also keeps a search-by-meaning
30776
+ Once "semantic setup" has run on this device, serve also keeps a search-by-meaning
30743
30777
  store of the graph current (the agent's search tool gains mode: semantic) - pass
30744
30778
  --no-semantic to leave it off for this registration.
30745
30779
  Any number of agents can serve the same graph at once. The first one starts the graph's
@@ -30753,7 +30787,7 @@ var USAGE = `etherpk-mcp - EtherPK Headless Client (an MCP server over one synce
30753
30787
  makes them when it opens a folder) - its index is kept under the cache directory, never
30754
30788
  in the folder.
30755
30789
  ${CMD} running
30756
- List the graphs served on this computer: each one's background process, its agents and
30790
+ List the graphs served on this device: each one's background process, its agents and
30757
30791
  its log. A background process stops on its own once no agent has used it for five
30758
30792
  minutes (ETHERPK_MCP_HOST_IDLE_SECONDS sets another time).
30759
30793
  ${CMD} stop [--graph <id or name> [--sync-server <url>] | --folder <path> | --all]
@@ -30766,7 +30800,7 @@ var USAGE = `etherpk-mcp - EtherPK Headless Client (an MCP server over one synce
30766
30800
  ${CMD} semantic setup
30767
30801
  Let the agent search by meaning. Installs a ~300 MB native runtime (onnxruntime-node,
30768
30802
  with your npm) and downloads a 23 MB embedding model into the cache directory, once
30769
- per computer. Nothing leaves this computer when the model runs - notes are never sent
30803
+ per device. Nothing leaves this device when the model runs - notes are never sent
30770
30804
  to a service to be embedded.
30771
30805
  ${CMD} semantic status | remove
30772
30806
  Whether it is set up here, or delete it (logout --all deletes it too).
@@ -30792,7 +30826,7 @@ var USAGE = `etherpk-mcp - EtherPK Headless Client (an MCP server over one synce
30792
30826
  out of public logs.
30793
30827
  ${CMD} diagrams setup
30794
30828
  Let a publish draw Mermaid diagrams, maps and drawings. Downloads a Chromium (about 170 MB) into the
30795
- cache directory with Playwright's installer, once per computer - a publish whose pages hold
30829
+ cache directory with Playwright's installer, once per device - a publish whose pages hold
30796
30830
  diagrams, maps or drawings refuses until this has run. Set ETHERPK_CHROMIUM=<path> to use a browser
30797
30831
  already on this machine instead (NixOS needs this).
30798
30832
  ${CMD} diagrams status
@@ -30975,7 +31009,8 @@ async function login(args) {
30975
31009
  }));
30976
31010
  };
30977
31011
  const vaultKey = await (args["recovery-code"] ? byRecoveryCode() : approveOrFallBack(account, byRecoveryCode)).catch(abandon);
30978
- if (accessTokenKind(token) === "standard") {
31012
+ const exchangedAccessToken = accessTokenKind(token) === "standard";
31013
+ if (exchangedAccessToken) {
30979
31014
  const given = token;
30980
31015
  token = await exchangeForAgentToken({
30981
31016
  syncServer,
@@ -30984,20 +31019,16 @@ async function login(args) {
30984
31019
  }).catch(async (error) => {
30985
31020
  const reason = describeLoginFailure(error, syncServer);
30986
31021
  if (!await tokenStillWorks(syncServer, given)) return fail(`Could not swap the access token for an Agent Token (${reason}), and the access token you gave no longer works. Run login again with an Agent Setup Code.`);
30987
- return fail(`Could not swap the access token for an Agent Token (${reason}). Nothing was kept on this computer: run login again.`);
31022
+ return fail(`Could not swap the access token for an Agent Token (${reason}). Nothing was kept on this device: run login again.`);
30988
31023
  });
30989
- console.log("");
30990
- console.log(`The access token you gave has been revoked. This computer now holds an Agent Token, limited to the routes an agent needs. If you used that access token anywhere else, create a new one at ${syncServer}/account/tokens.`);
30991
31024
  }
31025
+ let replacedEarlierLogin = false;
30992
31026
  if (previous) {
30993
31027
  const before = await loginCredentials(syncServer, previous, keychain()).catch(() => null);
30994
- if (before && before.pat !== token && await revokeHeldToken({
31028
+ replacedEarlierLogin = before !== null && before.pat !== token && await revokeHeldToken({
30995
31029
  syncServer,
30996
31030
  token: before.pat
30997
- })) {
30998
- console.log("");
30999
- console.log(`Revoked the token this computer held for ${syncServer} before this login.`);
31000
- }
31031
+ });
31001
31032
  }
31002
31033
  const where = await saveLogin({
31003
31034
  config,
@@ -31009,17 +31040,19 @@ async function login(args) {
31009
31040
  },
31010
31041
  keychain: keychain()
31011
31042
  });
31012
- console.log("");
31013
- console.log(where === path ? `Encryption Keys unlocked and kept in ${path} (owner-only). Anyone who can read your files on this machine can read this account, as with a signed-in browser. Never let an agent read, print or search that file.` : `Encryption Keys unlocked and kept in ${where}; ${path} names only the server. A program you run can still ask ${where} for them, so run only agents you trust with this account.`);
31014
31043
  const others = Object.keys(config.servers).filter((server) => server !== syncServer);
31015
- if (others.length > 0) {
31016
- console.log("");
31017
- console.log(`Also logged in to ${others.join(", ")} - commands now need --sync-server <url> to say which.`);
31018
- }
31019
31044
  const restarted = await stopHosts(process.env, "a new login for its server", ({ status }) => status.target.kind === "synced" && status.target.server === syncServer);
31020
- if (restarted.length > 0) {
31045
+ for (const paragraph of loginSummary({
31046
+ syncServer,
31047
+ configPath: path,
31048
+ keptIn: where,
31049
+ exchangedAccessToken,
31050
+ replacedEarlierLogin,
31051
+ otherServers: others,
31052
+ stoppedHosts: restarted.length
31053
+ })) {
31021
31054
  console.log("");
31022
- console.log(`Stopped the background process of ${restarted.length === 1 ? "one graph" : `${restarted.length} graphs`} served with the previous login. Agents start a new one with this login on their next call.`);
31055
+ console.log(paragraph);
31023
31056
  }
31024
31057
  console.log("");
31025
31058
  await listGraphs({
@@ -31027,6 +31060,11 @@ async function login(args) {
31027
31060
  pat: token,
31028
31061
  vaultKey: toBase64Url(vaultKey)
31029
31062
  }, others.length > 0);
31063
+ const setup = agentSetupLine(account.clientUrl);
31064
+ if (setup) {
31065
+ console.log("");
31066
+ console.log(setup);
31067
+ }
31030
31068
  }
31031
31069
  /**
31032
31070
  * Device Approval, with the Recovery Code one keypress away: a user who has no unlocked EtherPK
@@ -31050,7 +31088,8 @@ async function approveOrFallBack(account, byRecoveryCode) {
31050
31088
  sleep: (ms) => sleepUnlessAborted(ms, controls.signal),
31051
31089
  codesMatch: () => controls.codesMatch,
31052
31090
  signal: controls.signal,
31053
- clientUrl: account.clientUrl
31091
+ clientUrl: account.clientUrl,
31092
+ offersRecoveryCode: interactive
31054
31093
  };
31055
31094
  const onKey = (chunk) => controls.onKey(chunk.toString("utf8"));
31056
31095
  const onInputEnd = () => controls.onInputClosed();
@@ -31061,11 +31100,8 @@ async function approveOrFallBack(account, byRecoveryCode) {
31061
31100
  ];
31062
31101
  const onSignal = (name) => controls.onSignal(name);
31063
31102
  for (const name of quitSignals) process.once(name, onSignal);
31064
- if (interactive) {
31065
- console.log("");
31066
- console.log("**Press r to type your Recovery Code instead.**");
31067
- stdin.setRawMode(true);
31068
- } else stdin.on("end", onInputEnd);
31103
+ if (interactive) stdin.setRawMode(true);
31104
+ else stdin.on("end", onInputEnd);
31069
31105
  stdin.resume();
31070
31106
  stdin.on("data", onKey);
31071
31107
  let abandoned = false;
@@ -31086,10 +31122,10 @@ async function approveOrFallBack(account, byRecoveryCode) {
31086
31122
  process.exit(controls.exitCode);
31087
31123
  }
31088
31124
  if (!abandoned) throw new Error("unreachable");
31089
- if (controls.mismatched) fail("The codes did not match, so the request was cancelled. Something between this computer and your other device may have interfered. Run login again, or pass --recovery-code.");
31125
+ if (controls.mismatched) fail("The codes did not match, so the request was cancelled. Something between this device and your other device may have interfered. Run login again, or pass --recovery-code.");
31090
31126
  if (controls.inputClosed) fail("Device approval needs someone to confirm the code it shows. Run login in a terminal and press y when the codes match, or pass --recovery-code, or set ETHERPK_RECOVERY_CODE.");
31091
31127
  console.log("");
31092
- console.log("Approval cancelled - unlocking with your Recovery Code instead.");
31128
+ console.log(SWITCHING_TO_RECOVERY_CODE);
31093
31129
  return byRecoveryCode();
31094
31130
  }
31095
31131
  /**
@@ -31138,7 +31174,7 @@ async function openVaultFor(account, login) {
31138
31174
  try {
31139
31175
  return await openAccountVault(account.api, fromBase64Url(login.vaultKey));
31140
31176
  } catch (error) {
31141
- if (error instanceof EnvelopeError) throw new Error(`Your Encryption Keys on ${login.syncServer} were replaced or reset on another device, so the key saved on this computer no longer opens them. Run: ${CMD} login --sync-server ${login.syncServer}`);
31177
+ if (error instanceof EnvelopeError) throw new Error(`Your Encryption Keys on ${login.syncServer} were replaced or reset on another device, so the key saved on this device no longer opens them. Run: ${CMD} login --sync-server ${login.syncServer}`);
31142
31178
  throw error;
31143
31179
  }
31144
31180
  }
@@ -31167,7 +31203,8 @@ async function semanticCommand(what) {
31167
31203
  case "setup":
31168
31204
  await setupSemantic({
31169
31205
  env: process.env,
31170
- say: (line) => console.log(line)
31206
+ say: (line) => console.log(line),
31207
+ command: CMD
31171
31208
  });
31172
31209
  return;
31173
31210
  case "status": {
@@ -31261,9 +31298,9 @@ async function publishCommand(args) {
31261
31298
  return;
31262
31299
  case "refused": return fail(reply.message);
31263
31300
  case "failed":
31264
- if ((dryRun || github) && reply.message === "The request was not understood.") return fail(`etherpk-mcp: this graph is served on this computer by an older etherpk-mcp, which cannot ${dryRun ? "run a dry run" : "publish to a repository"}. Run: ${CMD} stop, then try again.`);
31301
+ if ((dryRun || github) && reply.message === "The request was not understood.") return fail(`etherpk-mcp: this graph is served on this device by an older etherpk-mcp, which cannot ${dryRun ? "run a dry run" : "publish to a repository"}. Run: ${CMD} stop, then try again.`);
31265
31302
  return fail(`etherpk-mcp: ${reply.message}`);
31266
- case "unsupported": return fail(`etherpk-mcp: this graph is served on this computer by etherpk-mcp ${reply.version}, which cannot run a publish for this version (${VERSION}). Run: ${CMD} stop, then publish again.`);
31303
+ case "unsupported": return fail(`etherpk-mcp: this graph is served on this device by etherpk-mcp ${reply.version}, which cannot run a publish for this version (${VERSION}). Run: ${CMD} stop, then publish again.`);
31267
31304
  default: return fail(`etherpk-mcp: the graph's background process gave an answer this version does not know ("${reply.etherpk}").`);
31268
31305
  }
31269
31306
  }
@@ -31499,7 +31536,7 @@ async function serve(args) {
31499
31536
  return unavailable(request, reply.message);
31500
31537
  case "unsupported":
31501
31538
  socket.destroy();
31502
- return unavailable(request, `This graph is served on this computer by etherpk-mcp ${reply.version}, which cannot share it with this version (${VERSION}). Run: ${CMD} stop, then restart your agents.`);
31539
+ return unavailable(request, `This graph is served on this device by etherpk-mcp ${reply.version}, which cannot share it with this version (${VERSION}). Run: ${CMD} stop, then restart your agents.`);
31503
31540
  default:
31504
31541
  socket.destroy();
31505
31542
  return unavailable(request, `The graph's background process gave an answer this version does not know ("${reply.etherpk}"). Run: ${CMD} stop, then restart your agents.`);
@@ -31643,7 +31680,7 @@ async function openSyncedGraph(syncServer, graphId, named) {
31643
31680
  console.error(`etherpk-mcp: could not tidy the cache of graphs this server no longer lists: ${describeError(error)}`);
31644
31681
  return [];
31645
31682
  });
31646
- if (swept.length > 0) console.error(`etherpk-mcp: removed this computer's copy of ${swept.length === 1 ? "a graph" : `${swept.length} graphs`} ${account.serverBaseUrl} no longer lists for you: ${swept.join(", ")}.`);
31683
+ if (swept.length > 0) console.error(`etherpk-mcp: removed this device's copy of ${swept.length === 1 ? "a graph" : `${swept.length} graphs`} ${account.serverBaseUrl} no longer lists for you: ${swept.join(", ")}.`);
31647
31684
  const listed = graphs.find((graph) => graph.id === graphId);
31648
31685
  if (!listed) throw new Error(`No synced graph on ${login.syncServer} is identified by "${graphId}". Run: ${CMD} graphs`);
31649
31686
  const label = await graphLabel(listed, vault).catch(() => null);
@@ -31722,7 +31759,7 @@ async function startSemantic(graph) {
31722
31759
  start();
31723
31760
  return;
31724
31761
  }
31725
- console.error(`etherpk-mcp: semantic search is not set up on this computer (run: ${CMD} semantic setup - this process will notice within half a minute, no restart needed). Search answers by text only until then.`);
31762
+ console.error(`etherpk-mcp: semantic search is not set up on this device (run: ${CMD} semantic setup - this process will notice within half a minute, no restart needed). Search answers by text only until then.`);
31726
31763
  whenSemanticSetUp(process.env, () => {
31727
31764
  console.error("etherpk-mcp: semantic setup found - loading the model and building the store.");
31728
31765
  start();
@@ -31736,7 +31773,7 @@ function describeHostTarget(target) {
31736
31773
  async function runningCommand() {
31737
31774
  const hosts = await runningHosts(process.env);
31738
31775
  if (hosts.length === 0) {
31739
- console.log("No graph is being served on this computer.");
31776
+ console.log("No graph is being served on this device.");
31740
31777
  return;
31741
31778
  }
31742
31779
  for (const { cacheDir, status } of hosts) {
@@ -31770,7 +31807,7 @@ async function stopCommand(args) {
31770
31807
  };
31771
31808
  const stopped = await stopHosts(process.env, "stop was run", which);
31772
31809
  if (stopped.length === 0) {
31773
- console.log(path || wanted ? "That graph is not being served on this computer." : "No graph is being served on this computer.");
31810
+ console.log(path || wanted ? "That graph is not being served on this device." : "No graph is being served on this device.");
31774
31811
  return;
31775
31812
  }
31776
31813
  for (const host of stopped) console.log(`${host.stopped ? "Stopped" : "Could not stop"} the background process of "${host.status.graph.name}" (${describeHostTarget(host.status.target)}, process ${host.status.pid}).`);