@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 +100 -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
|
|
@@ -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(
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
21720
|
-
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.";
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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}
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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(
|
|
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
|
-
|
|
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
|
|
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(
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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}).`);
|