@appsoftwareltd/etherpk-mcp 0.37.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 +96 -63
- package/dist/main.js.map +1 -1
- package/package.json +6 -6
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.
|
|
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
|
|
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
|
|
@@ -8307,7 +8307,11 @@ async function setupSemantic(io) {
|
|
|
8307
8307
|
io.say(`Downloading ${file.name} (${Math.max(1, Math.round(file.bytes / 1e6))} MB) from ${new URL(file.url).host}…`);
|
|
8308
8308
|
await download(io.fetch ?? fetch, file, path);
|
|
8309
8309
|
}
|
|
8310
|
-
io.say(
|
|
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}.`);
|
|
8311
8315
|
return semanticSetupStatus(io.env, files);
|
|
8312
8316
|
}
|
|
8313
8317
|
async function npmInstall(args, cwd, say) {
|
|
@@ -8369,7 +8373,7 @@ var SemanticUnavailable = class extends Error {
|
|
|
8369
8373
|
this.name = "SemanticUnavailable";
|
|
8370
8374
|
}
|
|
8371
8375
|
};
|
|
8372
|
-
var SETUP_HINT = "run `npx @appsoftwareltd/etherpk-mcp semantic setup` on this
|
|
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.";
|
|
8373
8377
|
/** The thread count `serve` uses: the option, else the environment, else the conservative default. */
|
|
8374
8378
|
function semanticThreads(env, requested) {
|
|
8375
8379
|
if (requested !== void 0) return Math.max(1, Math.floor(requested));
|
|
@@ -8383,7 +8387,7 @@ function semanticThreads(env, requested) {
|
|
|
8383
8387
|
*/
|
|
8384
8388
|
async function loadEmbeddingModel(env, options = {}) {
|
|
8385
8389
|
const status = await semanticSetupStatus(env);
|
|
8386
|
-
if (!status.runtime || !status.model) throw new SemanticUnavailable(`Semantic search is not set up on this
|
|
8390
|
+
if (!status.runtime || !status.model) throw new SemanticUnavailable(`Semantic search is not set up on this device: ${SETUP_HINT}`);
|
|
8387
8391
|
const require = createRequire(join(status.runtimeDir, "package.json"));
|
|
8388
8392
|
let ort;
|
|
8389
8393
|
try {
|
|
@@ -13373,11 +13377,11 @@ function offlineSince(connection, now = Date.now()) {
|
|
|
13373
13377
|
/** The note an answer carries while its copy is offline; null while connected and on a folder, which has no connection. */
|
|
13374
13378
|
function offlineNotice(connection, now = Date.now()) {
|
|
13375
13379
|
if (connection?.state !== "offline") return null;
|
|
13376
|
-
return `This
|
|
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.`;
|
|
13377
13381
|
}
|
|
13378
13382
|
/** One line for the host's log. */
|
|
13379
13383
|
function connectionChangeLine(change) {
|
|
13380
|
-
if (change.connection.state === "offline") return "lost the connection to the Sync Server; the tools answer from this
|
|
13384
|
+
if (change.connection.state === "offline") return "lost the connection to the Sync Server; the tools answer from this device's copy.";
|
|
13381
13385
|
return change.offlineForMs === null ? "connected to the Sync Server." : `connected to the Sync Server again, after ${durationWords(change.offlineForMs)} offline.`;
|
|
13382
13386
|
}
|
|
13383
13387
|
// ../client/src/lib/document/publish/selection.ts
|
|
@@ -17398,7 +17402,7 @@ async function setupDiagrams(env, say) {
|
|
|
17398
17402
|
}
|
|
17399
17403
|
const cli = require$2.resolve("playwright-core/cli.js");
|
|
17400
17404
|
const dir = env.PLAYWRIGHT_BROWSERS_PATH?.trim() || browsersDir(env);
|
|
17401
|
-
say(`Installing Chromium into ${dir} (about 170 MB, once per
|
|
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)…`);
|
|
17402
17406
|
await new Promise((resolve, reject) => {
|
|
17403
17407
|
const child = spawn(process.execPath, [
|
|
17404
17408
|
cli,
|
|
@@ -21720,8 +21724,8 @@ async function requireReferencedTask(graph, reference, purpose = "read") {
|
|
|
21720
21724
|
* same words and would fail the same way, so it asks for a retry instead.
|
|
21721
21725
|
*/
|
|
21722
21726
|
function taskNotFoundMessage(connection) {
|
|
21723
|
-
if (connection?.state === "offline") return `No task in this
|
|
21724
|
-
return "No task in the graph has those words now: it was edited or deleted, or the change has not reached this
|
|
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.";
|
|
21725
21729
|
}
|
|
21726
21730
|
/**
|
|
21727
21731
|
* The block's own lines and everything nested under it: in the index's rows, which run in
|
|
@@ -21845,7 +21849,7 @@ async function graphInfo(graph) {
|
|
|
21845
21849
|
complete: status.embedded >= status.total
|
|
21846
21850
|
} : {
|
|
21847
21851
|
state: "not-opened",
|
|
21848
|
-
note: "The first search with mode \"semantic\" loads the model - if it is not set up on this
|
|
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."
|
|
21849
21853
|
},
|
|
21850
21854
|
assets: { available: graph.assets !== void 0 }
|
|
21851
21855
|
};
|
|
@@ -22090,7 +22094,7 @@ async function publish(graph, args, host) {
|
|
|
22090
22094
|
renderer = await openDiagramRenderer(env);
|
|
22091
22095
|
if (!renderer) {
|
|
22092
22096
|
const status = await chromiumStatus(env, cmd);
|
|
22093
|
-
throw new ToolError("chromium_unavailable", `"${publication.name}" has Mermaid diagrams, which a publish draws with a browser, and none is set up on this
|
|
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.`);
|
|
22094
22098
|
}
|
|
22095
22099
|
}
|
|
22096
22100
|
let maps = null;
|
|
@@ -22099,7 +22103,7 @@ async function publish(graph, args, host) {
|
|
|
22099
22103
|
if (!maps) {
|
|
22100
22104
|
await renderer?.dispose();
|
|
22101
22105
|
const status = await chromiumStatus(env, cmd);
|
|
22102
|
-
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
|
|
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.`);
|
|
22103
22107
|
}
|
|
22104
22108
|
}
|
|
22105
22109
|
let drawings = null;
|
|
@@ -22109,7 +22113,7 @@ async function publish(graph, args, host) {
|
|
|
22109
22113
|
await renderer?.dispose();
|
|
22110
22114
|
await maps?.dispose();
|
|
22111
22115
|
const status = await chromiumStatus(env, cmd);
|
|
22112
|
-
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
|
|
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.`);
|
|
22113
22117
|
}
|
|
22114
22118
|
}
|
|
22115
22119
|
try {
|
|
@@ -22871,7 +22875,7 @@ function withOfflineNote(result, connection) {
|
|
|
22871
22875
|
function accessEndedError(graph, cmd) {
|
|
22872
22876
|
const loss = graph.accessLoss();
|
|
22873
22877
|
if (!loss) return null;
|
|
22874
|
-
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
|
|
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.`);
|
|
22875
22879
|
}
|
|
22876
22880
|
var concept = z.string().min(1).describe("A page title, one of its aliases, a journal day as YYYY-MM-DD, or \"today\".");
|
|
22877
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.");
|
|
@@ -22912,17 +22916,17 @@ function createMcpServer(source, info) {
|
|
|
22912
22916
|
version: info.version
|
|
22913
22917
|
}, { instructions: [
|
|
22914
22918
|
`You are connected to the EtherPK knowledge graph "${info.graphName}": daily journal entries and titled pages in plain markdown, linked with [[wikilinks]].`,
|
|
22915
|
-
...backendKind === "synced" ? ["This graph is synced and encrypted: it has no folder on this
|
|
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."] : [],
|
|
22916
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.`,
|
|
22917
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.",
|
|
22918
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.",
|
|
22919
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.",
|
|
22920
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.",
|
|
22921
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.",
|
|
22922
|
-
"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
|
|
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.",
|
|
22923
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.",
|
|
22924
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.",
|
|
22925
|
-
"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
|
|
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.",
|
|
22926
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.",
|
|
22927
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\".",
|
|
22928
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.",
|
|
@@ -22970,7 +22974,7 @@ function createMcpServer(source, info) {
|
|
|
22970
22974
|
}, async (args) => run((graph) => readDocuments(graph, args)));
|
|
22971
22975
|
server.registerTool("search", {
|
|
22972
22976
|
title: "Search",
|
|
22973
|
-
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
|
|
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.`,
|
|
22974
22978
|
inputSchema: {
|
|
22975
22979
|
query: z.string().min(1),
|
|
22976
22980
|
mode: z.enum([
|
|
@@ -23294,7 +23298,7 @@ function createMcpServer(source, info) {
|
|
|
23294
23298
|
}, async (args) => run((graph) => previewTheme(graph, args, host)));
|
|
23295
23299
|
server.registerTool("graph_info", {
|
|
23296
23300
|
title: "Graph info",
|
|
23297
|
-
description: "What you are connected to: the graph's name, whether it is a synced graph (on which server, and whether this
|
|
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.",
|
|
23298
23302
|
inputSchema: {}
|
|
23299
23303
|
}, async () => run(async (graph) => {
|
|
23300
23304
|
const publishing = await publishingInfo(graph, host);
|
|
@@ -30473,11 +30477,13 @@ async function unlockByDeviceApproval(api, io) {
|
|
|
30473
30477
|
const request = await beginDeviceApproval(api);
|
|
30474
30478
|
const where = io.clientUrl ? `open EtherPK at ${io.clientUrl}` : "open EtherPK in a browser";
|
|
30475
30479
|
io.say("");
|
|
30476
|
-
io.say(`To approve this device, ${where}
|
|
30477
|
-
io.say("Encryption Keys are unlocked. A prompt appears on each of them: choose Show the code on the one you approve");
|
|
30478
|
-
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.`);
|
|
30479
30481
|
io.say("");
|
|
30480
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
|
+
}
|
|
30481
30487
|
const abandon = async () => {
|
|
30482
30488
|
await Promise.race([api.cancelDeviceApproval(request.id).catch(() => {}), new Promise((resolve) => setTimeout(resolve, CANCEL_TIMEOUT_MS).unref())]);
|
|
30483
30489
|
throw new ApprovalAbandoned();
|
|
@@ -30519,6 +30525,30 @@ async function unlockByDeviceApproval(api, io) {
|
|
|
30519
30525
|
async function unlockByRecoveryCode(api, code) {
|
|
30520
30526
|
return openVaultWithRecoveryCode(api, code);
|
|
30521
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.";
|
|
30522
30552
|
// ../client/src/lib/storage/fs/directory-adapter.ts
|
|
30523
30553
|
/** All four, in skeleton-creation order. */
|
|
30524
30554
|
var SUBDIRS = [
|
|
@@ -30727,9 +30757,9 @@ var CMD = /[\\/]_npx[\\/]/.test(process.argv[1] ?? "") ? "npx @appsoftwareltd/et
|
|
|
30727
30757
|
var USAGE = `etherpk-mcp - EtherPK Headless Client (an MCP server over one synced graph)
|
|
30728
30758
|
|
|
30729
30759
|
${CMD} login --sync-server <url> [--code <Agent Setup Code>] [--recovery-code]
|
|
30730
|
-
Sign in this
|
|
30760
|
+
Sign in this device as one of your account's devices. Create an Agent Setup Code in EtherPK
|
|
30731
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
|
|
30732
|
-
minutes, and gets this
|
|
30762
|
+
minutes, and gets this device an Agent Token limited to the routes an agent needs. Then
|
|
30733
30763
|
unlock your Encryption Keys by Device Approval: confirm the matching code in EtherPK on
|
|
30734
30764
|
any device where your Encryption Keys are unlocked, then press y. Press r while waiting,
|
|
30735
30765
|
or pass --recovery-code, to type your Recovery Code instead (or ETHERPK_RECOVERY_CODE,
|
|
@@ -30743,7 +30773,7 @@ var USAGE = `etherpk-mcp - EtherPK Headless Client (an MCP server over one synce
|
|
|
30743
30773
|
${CMD} serve --graph <id or name> [--sync-server <url>] [--no-semantic]
|
|
30744
30774
|
Serve one synced graph to an agent over stdio. For Claude Code:
|
|
30745
30775
|
claude mcp add --scope user etherpk -- npx @appsoftwareltd/etherpk-mcp serve --sync-server <url> --graph <id>
|
|
30746
|
-
Once "semantic setup" has run on this
|
|
30776
|
+
Once "semantic setup" has run on this device, serve also keeps a search-by-meaning
|
|
30747
30777
|
store of the graph current (the agent's search tool gains mode: semantic) - pass
|
|
30748
30778
|
--no-semantic to leave it off for this registration.
|
|
30749
30779
|
Any number of agents can serve the same graph at once. The first one starts the graph's
|
|
@@ -30757,7 +30787,7 @@ var USAGE = `etherpk-mcp - EtherPK Headless Client (an MCP server over one synce
|
|
|
30757
30787
|
makes them when it opens a folder) - its index is kept under the cache directory, never
|
|
30758
30788
|
in the folder.
|
|
30759
30789
|
${CMD} running
|
|
30760
|
-
List the graphs served on this
|
|
30790
|
+
List the graphs served on this device: each one's background process, its agents and
|
|
30761
30791
|
its log. A background process stops on its own once no agent has used it for five
|
|
30762
30792
|
minutes (ETHERPK_MCP_HOST_IDLE_SECONDS sets another time).
|
|
30763
30793
|
${CMD} stop [--graph <id or name> [--sync-server <url>] | --folder <path> | --all]
|
|
@@ -30770,7 +30800,7 @@ var USAGE = `etherpk-mcp - EtherPK Headless Client (an MCP server over one synce
|
|
|
30770
30800
|
${CMD} semantic setup
|
|
30771
30801
|
Let the agent search by meaning. Installs a ~300 MB native runtime (onnxruntime-node,
|
|
30772
30802
|
with your npm) and downloads a 23 MB embedding model into the cache directory, once
|
|
30773
|
-
per
|
|
30803
|
+
per device. Nothing leaves this device when the model runs - notes are never sent
|
|
30774
30804
|
to a service to be embedded.
|
|
30775
30805
|
${CMD} semantic status | remove
|
|
30776
30806
|
Whether it is set up here, or delete it (logout --all deletes it too).
|
|
@@ -30796,7 +30826,7 @@ var USAGE = `etherpk-mcp - EtherPK Headless Client (an MCP server over one synce
|
|
|
30796
30826
|
out of public logs.
|
|
30797
30827
|
${CMD} diagrams setup
|
|
30798
30828
|
Let a publish draw Mermaid diagrams, maps and drawings. Downloads a Chromium (about 170 MB) into the
|
|
30799
|
-
cache directory with Playwright's installer, once per
|
|
30829
|
+
cache directory with Playwright's installer, once per device - a publish whose pages hold
|
|
30800
30830
|
diagrams, maps or drawings refuses until this has run. Set ETHERPK_CHROMIUM=<path> to use a browser
|
|
30801
30831
|
already on this machine instead (NixOS needs this).
|
|
30802
30832
|
${CMD} diagrams status
|
|
@@ -30979,7 +31009,8 @@ async function login(args) {
|
|
|
30979
31009
|
}));
|
|
30980
31010
|
};
|
|
30981
31011
|
const vaultKey = await (args["recovery-code"] ? byRecoveryCode() : approveOrFallBack(account, byRecoveryCode)).catch(abandon);
|
|
30982
|
-
|
|
31012
|
+
const exchangedAccessToken = accessTokenKind(token) === "standard";
|
|
31013
|
+
if (exchangedAccessToken) {
|
|
30983
31014
|
const given = token;
|
|
30984
31015
|
token = await exchangeForAgentToken({
|
|
30985
31016
|
syncServer,
|
|
@@ -30988,20 +31019,16 @@ async function login(args) {
|
|
|
30988
31019
|
}).catch(async (error) => {
|
|
30989
31020
|
const reason = describeLoginFailure(error, syncServer);
|
|
30990
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.`);
|
|
30991
|
-
return fail(`Could not swap the access token for an Agent Token (${reason}). Nothing was kept on this
|
|
31022
|
+
return fail(`Could not swap the access token for an Agent Token (${reason}). Nothing was kept on this device: run login again.`);
|
|
30992
31023
|
});
|
|
30993
|
-
console.log("");
|
|
30994
|
-
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.`);
|
|
30995
31024
|
}
|
|
31025
|
+
let replacedEarlierLogin = false;
|
|
30996
31026
|
if (previous) {
|
|
30997
31027
|
const before = await loginCredentials(syncServer, previous, keychain()).catch(() => null);
|
|
30998
|
-
|
|
31028
|
+
replacedEarlierLogin = before !== null && before.pat !== token && await revokeHeldToken({
|
|
30999
31029
|
syncServer,
|
|
31000
31030
|
token: before.pat
|
|
31001
|
-
})
|
|
31002
|
-
console.log("");
|
|
31003
|
-
console.log(`Revoked the token this computer held for ${syncServer} before this login.`);
|
|
31004
|
-
}
|
|
31031
|
+
});
|
|
31005
31032
|
}
|
|
31006
31033
|
const where = await saveLogin({
|
|
31007
31034
|
config,
|
|
@@ -31013,17 +31040,19 @@ async function login(args) {
|
|
|
31013
31040
|
},
|
|
31014
31041
|
keychain: keychain()
|
|
31015
31042
|
});
|
|
31016
|
-
console.log("");
|
|
31017
|
-
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.`);
|
|
31018
31043
|
const others = Object.keys(config.servers).filter((server) => server !== syncServer);
|
|
31019
|
-
if (others.length > 0) {
|
|
31020
|
-
console.log("");
|
|
31021
|
-
console.log(`Also logged in to ${others.join(", ")} - commands now need --sync-server <url> to say which.`);
|
|
31022
|
-
}
|
|
31023
31044
|
const restarted = await stopHosts(process.env, "a new login for its server", ({ status }) => status.target.kind === "synced" && status.target.server === syncServer);
|
|
31024
|
-
|
|
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
|
+
})) {
|
|
31025
31054
|
console.log("");
|
|
31026
|
-
console.log(
|
|
31055
|
+
console.log(paragraph);
|
|
31027
31056
|
}
|
|
31028
31057
|
console.log("");
|
|
31029
31058
|
await listGraphs({
|
|
@@ -31031,6 +31060,11 @@ async function login(args) {
|
|
|
31031
31060
|
pat: token,
|
|
31032
31061
|
vaultKey: toBase64Url(vaultKey)
|
|
31033
31062
|
}, others.length > 0);
|
|
31063
|
+
const setup = agentSetupLine(account.clientUrl);
|
|
31064
|
+
if (setup) {
|
|
31065
|
+
console.log("");
|
|
31066
|
+
console.log(setup);
|
|
31067
|
+
}
|
|
31034
31068
|
}
|
|
31035
31069
|
/**
|
|
31036
31070
|
* Device Approval, with the Recovery Code one keypress away: a user who has no unlocked EtherPK
|
|
@@ -31054,7 +31088,8 @@ async function approveOrFallBack(account, byRecoveryCode) {
|
|
|
31054
31088
|
sleep: (ms) => sleepUnlessAborted(ms, controls.signal),
|
|
31055
31089
|
codesMatch: () => controls.codesMatch,
|
|
31056
31090
|
signal: controls.signal,
|
|
31057
|
-
clientUrl: account.clientUrl
|
|
31091
|
+
clientUrl: account.clientUrl,
|
|
31092
|
+
offersRecoveryCode: interactive
|
|
31058
31093
|
};
|
|
31059
31094
|
const onKey = (chunk) => controls.onKey(chunk.toString("utf8"));
|
|
31060
31095
|
const onInputEnd = () => controls.onInputClosed();
|
|
@@ -31065,11 +31100,8 @@ async function approveOrFallBack(account, byRecoveryCode) {
|
|
|
31065
31100
|
];
|
|
31066
31101
|
const onSignal = (name) => controls.onSignal(name);
|
|
31067
31102
|
for (const name of quitSignals) process.once(name, onSignal);
|
|
31068
|
-
if (interactive)
|
|
31069
|
-
|
|
31070
|
-
console.log("**Press r to type your Recovery Code instead.**");
|
|
31071
|
-
stdin.setRawMode(true);
|
|
31072
|
-
} else stdin.on("end", onInputEnd);
|
|
31103
|
+
if (interactive) stdin.setRawMode(true);
|
|
31104
|
+
else stdin.on("end", onInputEnd);
|
|
31073
31105
|
stdin.resume();
|
|
31074
31106
|
stdin.on("data", onKey);
|
|
31075
31107
|
let abandoned = false;
|
|
@@ -31090,10 +31122,10 @@ async function approveOrFallBack(account, byRecoveryCode) {
|
|
|
31090
31122
|
process.exit(controls.exitCode);
|
|
31091
31123
|
}
|
|
31092
31124
|
if (!abandoned) throw new Error("unreachable");
|
|
31093
|
-
if (controls.mismatched) fail("The codes did not match, so the request was cancelled. Something between this
|
|
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.");
|
|
31094
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.");
|
|
31095
31127
|
console.log("");
|
|
31096
|
-
console.log(
|
|
31128
|
+
console.log(SWITCHING_TO_RECOVERY_CODE);
|
|
31097
31129
|
return byRecoveryCode();
|
|
31098
31130
|
}
|
|
31099
31131
|
/**
|
|
@@ -31142,7 +31174,7 @@ async function openVaultFor(account, login) {
|
|
|
31142
31174
|
try {
|
|
31143
31175
|
return await openAccountVault(account.api, fromBase64Url(login.vaultKey));
|
|
31144
31176
|
} catch (error) {
|
|
31145
|
-
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
|
|
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}`);
|
|
31146
31178
|
throw error;
|
|
31147
31179
|
}
|
|
31148
31180
|
}
|
|
@@ -31171,7 +31203,8 @@ async function semanticCommand(what) {
|
|
|
31171
31203
|
case "setup":
|
|
31172
31204
|
await setupSemantic({
|
|
31173
31205
|
env: process.env,
|
|
31174
|
-
say: (line) => console.log(line)
|
|
31206
|
+
say: (line) => console.log(line),
|
|
31207
|
+
command: CMD
|
|
31175
31208
|
});
|
|
31176
31209
|
return;
|
|
31177
31210
|
case "status": {
|
|
@@ -31265,9 +31298,9 @@ async function publishCommand(args) {
|
|
|
31265
31298
|
return;
|
|
31266
31299
|
case "refused": return fail(reply.message);
|
|
31267
31300
|
case "failed":
|
|
31268
|
-
if ((dryRun || github) && reply.message === "The request was not understood.") return fail(`etherpk-mcp: this graph is served on this
|
|
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.`);
|
|
31269
31302
|
return fail(`etherpk-mcp: ${reply.message}`);
|
|
31270
|
-
case "unsupported": return fail(`etherpk-mcp: this graph is served on this
|
|
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.`);
|
|
31271
31304
|
default: return fail(`etherpk-mcp: the graph's background process gave an answer this version does not know ("${reply.etherpk}").`);
|
|
31272
31305
|
}
|
|
31273
31306
|
}
|
|
@@ -31503,7 +31536,7 @@ async function serve(args) {
|
|
|
31503
31536
|
return unavailable(request, reply.message);
|
|
31504
31537
|
case "unsupported":
|
|
31505
31538
|
socket.destroy();
|
|
31506
|
-
return unavailable(request, `This graph is served on this
|
|
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.`);
|
|
31507
31540
|
default:
|
|
31508
31541
|
socket.destroy();
|
|
31509
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.`);
|
|
@@ -31647,7 +31680,7 @@ async function openSyncedGraph(syncServer, graphId, named) {
|
|
|
31647
31680
|
console.error(`etherpk-mcp: could not tidy the cache of graphs this server no longer lists: ${describeError(error)}`);
|
|
31648
31681
|
return [];
|
|
31649
31682
|
});
|
|
31650
|
-
if (swept.length > 0) console.error(`etherpk-mcp: removed this
|
|
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(", ")}.`);
|
|
31651
31684
|
const listed = graphs.find((graph) => graph.id === graphId);
|
|
31652
31685
|
if (!listed) throw new Error(`No synced graph on ${login.syncServer} is identified by "${graphId}". Run: ${CMD} graphs`);
|
|
31653
31686
|
const label = await graphLabel(listed, vault).catch(() => null);
|
|
@@ -31726,7 +31759,7 @@ async function startSemantic(graph) {
|
|
|
31726
31759
|
start();
|
|
31727
31760
|
return;
|
|
31728
31761
|
}
|
|
31729
|
-
console.error(`etherpk-mcp: semantic search is not set up on this
|
|
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.`);
|
|
31730
31763
|
whenSemanticSetUp(process.env, () => {
|
|
31731
31764
|
console.error("etherpk-mcp: semantic setup found - loading the model and building the store.");
|
|
31732
31765
|
start();
|
|
@@ -31740,7 +31773,7 @@ function describeHostTarget(target) {
|
|
|
31740
31773
|
async function runningCommand() {
|
|
31741
31774
|
const hosts = await runningHosts(process.env);
|
|
31742
31775
|
if (hosts.length === 0) {
|
|
31743
|
-
console.log("No graph is being served on this
|
|
31776
|
+
console.log("No graph is being served on this device.");
|
|
31744
31777
|
return;
|
|
31745
31778
|
}
|
|
31746
31779
|
for (const { cacheDir, status } of hosts) {
|
|
@@ -31774,7 +31807,7 @@ async function stopCommand(args) {
|
|
|
31774
31807
|
};
|
|
31775
31808
|
const stopped = await stopHosts(process.env, "stop was run", which);
|
|
31776
31809
|
if (stopped.length === 0) {
|
|
31777
|
-
console.log(path || wanted ? "That graph is not being served on this
|
|
31810
|
+
console.log(path || wanted ? "That graph is not being served on this device." : "No graph is being served on this device.");
|
|
31778
31811
|
return;
|
|
31779
31812
|
}
|
|
31780
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}).`);
|