@appsoftwareltd/etherpk-mcp 0.35.0 → 0.37.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 +97 -39
- 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.37.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",
|
|
@@ -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]
|
|
@@ -18380,16 +18384,51 @@ function lastNonBlank(lines) {
|
|
|
18380
18384
|
var READ_TEXT_CAP = 2e5;
|
|
18381
18385
|
/** UTF-16 units across one bulk read before the rest is cut. */
|
|
18382
18386
|
var READ_MANY_TEXT_CAP = 4e5;
|
|
18383
|
-
/**
|
|
18384
|
-
|
|
18385
|
-
|
|
18386
|
-
|
|
18387
|
-
|
|
18388
|
-
|
|
18389
|
-
|
|
18390
|
-
|
|
18387
|
+
/**
|
|
18388
|
+
* The part of `text` from `offset` that fits in `cap` UTF-16 units, so an agent can read a long
|
|
18389
|
+
* document to its end, a window at a time, by passing each `nextOffset` back. A cut window ends
|
|
18390
|
+
* after the last line break inside it, so the next starts on a line of its own; a line longer than
|
|
18391
|
+
* the whole cap is cut at the cap instead. A window never ends between the two halves of a
|
|
18392
|
+
* surrogate pair. An offset past the end, negative or not a whole number is a RangeError.
|
|
18393
|
+
*/
|
|
18394
|
+
function textWindow(text, offset = 0, cap = READ_TEXT_CAP) {
|
|
18395
|
+
if (!Number.isInteger(offset) || offset < 0 || offset > text.length) throw new RangeError(`offset must be a whole number from 0 to ${text.length}, the text's length.`);
|
|
18396
|
+
const startLine = lineBreaksBefore(text, offset);
|
|
18397
|
+
if (text.length - offset <= cap) return {
|
|
18398
|
+
text: text.slice(offset),
|
|
18399
|
+
truncated: false,
|
|
18400
|
+
offset,
|
|
18401
|
+
startLine
|
|
18402
|
+
};
|
|
18403
|
+
const end = windowEnd(text, offset, offset + cap);
|
|
18404
|
+
return {
|
|
18405
|
+
text: text.slice(offset, end),
|
|
18406
|
+
truncated: true,
|
|
18407
|
+
offset,
|
|
18408
|
+
startLine,
|
|
18409
|
+
nextOffset: end
|
|
18391
18410
|
};
|
|
18392
18411
|
}
|
|
18412
|
+
/** How many line breaks come before `offset`: the 0-based line it falls on. */
|
|
18413
|
+
function lineBreaksBefore(text, offset) {
|
|
18414
|
+
let count = 0;
|
|
18415
|
+
for (let at = text.indexOf("\n"); at !== -1 && at < offset; at = text.indexOf("\n", at + 1)) count++;
|
|
18416
|
+
return count;
|
|
18417
|
+
}
|
|
18418
|
+
/**
|
|
18419
|
+
* Where a window from `offset` that may reach `limit` ends: after its last line break, or at
|
|
18420
|
+
* `limit` when it holds none, moved off the middle of a surrogate pair (back, or forward past
|
|
18421
|
+
* the pair when going back would leave the window empty).
|
|
18422
|
+
*/
|
|
18423
|
+
function windowEnd(text, offset, limit) {
|
|
18424
|
+
const lastBreak = text.lastIndexOf("\n", limit - 1);
|
|
18425
|
+
if (lastBreak >= offset) return lastBreak + 1;
|
|
18426
|
+
if (!isHighSurrogate(text.charCodeAt(limit - 1))) return limit;
|
|
18427
|
+
return limit - 1 > offset ? limit - 1 : limit + 1;
|
|
18428
|
+
}
|
|
18429
|
+
function isHighSurrogate(unit) {
|
|
18430
|
+
return unit >= 55296 && unit <= 56319;
|
|
18431
|
+
}
|
|
18393
18432
|
/**
|
|
18394
18433
|
* Whether `text` holds encrypted text anywhere: a Protected Document, or any other document with an
|
|
18395
18434
|
* `etherpk-cipher` fence in it. The index flags both as protected (`index-db.ts`), and a reader whose
|
|
@@ -20507,6 +20546,18 @@ var ToolError = class extends Error {
|
|
|
20507
20546
|
this.name = "ToolError";
|
|
20508
20547
|
}
|
|
20509
20548
|
};
|
|
20549
|
+
/**
|
|
20550
|
+
* The window of `text` a read answers, from `offset` up to `cap`, in the shape read results carry.
|
|
20551
|
+
* An offset outside the text is the agent's to correct, so it is refused as an argument.
|
|
20552
|
+
*/
|
|
20553
|
+
function readWindow(text, offset, cap = READ_TEXT_CAP) {
|
|
20554
|
+
try {
|
|
20555
|
+
return textWindow(text, offset ?? 0, cap);
|
|
20556
|
+
} catch (error) {
|
|
20557
|
+
if (error instanceof RangeError) throw new ToolError("invalid_argument", error.message);
|
|
20558
|
+
throw error;
|
|
20559
|
+
}
|
|
20560
|
+
}
|
|
20510
20561
|
/** Keys the frontmatter tools never read or write; each has a tool of its own. */
|
|
20511
20562
|
var OWNED_KEYS = /* @__PURE__ */ new Set([
|
|
20512
20563
|
"title",
|
|
@@ -20692,17 +20743,19 @@ async function listDocuments(graph, args = {}) {
|
|
|
20692
20743
|
hasMore: paged.hasMore
|
|
20693
20744
|
};
|
|
20694
20745
|
}
|
|
20695
|
-
|
|
20746
|
+
/**
|
|
20747
|
+
* One document's body and frontmatter. A body longer than {@link READ_TEXT_CAP} comes a window at
|
|
20748
|
+
* a time: each cut answer gives the `nextOffset` to read on from, so the end is always reachable.
|
|
20749
|
+
*/
|
|
20750
|
+
async function readDocument(graph, concept, options = {}) {
|
|
20696
20751
|
await graph.store.refresh();
|
|
20697
20752
|
const { identity, text } = await requireReadable(graph, concept);
|
|
20698
|
-
const capped = capText(text, READ_TEXT_CAP);
|
|
20699
20753
|
return {
|
|
20700
20754
|
concept: identity.concept,
|
|
20701
20755
|
kind: identity.kind,
|
|
20702
20756
|
aliases: identity.aliases,
|
|
20703
|
-
text
|
|
20704
|
-
frontmatter: agentFrontmatter(graph.store.openRaw(identity.concept).getText())
|
|
20705
|
-
truncated: capped.truncated
|
|
20757
|
+
...readWindow(text, options.offset),
|
|
20758
|
+
frontmatter: agentFrontmatter(graph.store.openRaw(identity.concept).getText())
|
|
20706
20759
|
};
|
|
20707
20760
|
}
|
|
20708
20761
|
function requireVersions(graph) {
|
|
@@ -20727,7 +20780,7 @@ async function listVersions(graph, concept) {
|
|
|
20727
20780
|
};
|
|
20728
20781
|
}
|
|
20729
20782
|
/** One earlier version's text (ADR 0184). */
|
|
20730
|
-
async function readVersion(graph, concept, version) {
|
|
20783
|
+
async function readVersion(graph, concept, version, options = {}) {
|
|
20731
20784
|
await graph.store.refresh();
|
|
20732
20785
|
const versions = requireVersions(graph);
|
|
20733
20786
|
const { identity } = await requireReadable(graph, concept);
|
|
@@ -20740,14 +20793,13 @@ async function readVersion(graph, concept, version) {
|
|
|
20740
20793
|
}
|
|
20741
20794
|
if (!read) throw notFound(concept);
|
|
20742
20795
|
if (holdsEncryptedText(read.text)) throw protectedDocument(concept);
|
|
20743
|
-
const
|
|
20796
|
+
const window = readWindow(read.text, options.offset);
|
|
20744
20797
|
const nameThen = read.identity.kind === "journal" ? read.identity.date ?? identity.concept : read.identity.title ?? identity.concept;
|
|
20745
20798
|
return {
|
|
20746
20799
|
concept: identity.concept,
|
|
20747
20800
|
version,
|
|
20748
20801
|
nameThen,
|
|
20749
|
-
|
|
20750
|
-
truncated: capped.truncated
|
|
20802
|
+
...window
|
|
20751
20803
|
};
|
|
20752
20804
|
}
|
|
20753
20805
|
async function search(graph, args) {
|
|
@@ -21471,14 +21523,17 @@ async function listAssets(graph, args = {}) {
|
|
|
21471
21523
|
for (const [concept, body] of bodies) for (const ref of assetReferencesIn(body)) {
|
|
21472
21524
|
const id = assets.identify(ref);
|
|
21473
21525
|
if (!id) continue;
|
|
21474
|
-
const
|
|
21526
|
+
const name = displayNameOf(ref);
|
|
21527
|
+
const key = `${id}\n${name}`;
|
|
21528
|
+
const entry = found.get(key) ?? {
|
|
21529
|
+
id,
|
|
21475
21530
|
ref,
|
|
21476
|
-
name
|
|
21477
|
-
type: mimeTypeForExt(splitNameExt(
|
|
21531
|
+
name,
|
|
21532
|
+
type: mimeTypeForExt(splitNameExt(name).ext),
|
|
21478
21533
|
documents: /* @__PURE__ */ new Set()
|
|
21479
21534
|
};
|
|
21480
21535
|
entry.documents.add(concept);
|
|
21481
|
-
found.set(
|
|
21536
|
+
found.set(key, entry);
|
|
21482
21537
|
}
|
|
21483
21538
|
let sizes;
|
|
21484
21539
|
try {
|
|
@@ -21486,11 +21541,11 @@ async function listAssets(graph, args = {}) {
|
|
|
21486
21541
|
} catch {
|
|
21487
21542
|
sizes = void 0;
|
|
21488
21543
|
}
|
|
21489
|
-
const list = [...found.
|
|
21544
|
+
const list = [...found.values()].map((entry) => ({
|
|
21490
21545
|
reference: entry.ref,
|
|
21491
21546
|
name: entry.name,
|
|
21492
21547
|
type: entry.type,
|
|
21493
|
-
...sizes?.has(id) ? { bytes: sizes.get(id) } : {},
|
|
21548
|
+
...sizes?.has(entry.id) ? { bytes: sizes.get(entry.id) } : {},
|
|
21494
21549
|
documents: [...entry.documents].sort()
|
|
21495
21550
|
})).sort((a, b) => a.name.localeCompare(b.name));
|
|
21496
21551
|
return {
|
|
@@ -21522,16 +21577,14 @@ async function readDocuments(graph, args) {
|
|
|
21522
21577
|
});
|
|
21523
21578
|
continue;
|
|
21524
21579
|
}
|
|
21525
|
-
const
|
|
21526
|
-
|
|
21527
|
-
budget -= Math.min(text.length, cap);
|
|
21580
|
+
const window = textWindow(text, 0, Math.max(0, Math.min(READ_TEXT_CAP, budget)));
|
|
21581
|
+
budget -= window.text.length;
|
|
21528
21582
|
documents.push({
|
|
21529
21583
|
concept: identity.concept,
|
|
21530
21584
|
kind: identity.kind,
|
|
21531
21585
|
aliases: identity.aliases,
|
|
21532
|
-
|
|
21533
|
-
frontmatter: agentFrontmatter(graph.store.openRaw(identity.concept).getText())
|
|
21534
|
-
truncated: cut
|
|
21586
|
+
...window,
|
|
21587
|
+
frontmatter: agentFrontmatter(graph.store.openRaw(identity.concept).getText())
|
|
21535
21588
|
});
|
|
21536
21589
|
}
|
|
21537
21590
|
return { documents };
|
|
@@ -21590,7 +21643,7 @@ async function setTask(graph, args) {
|
|
|
21590
21643
|
return {
|
|
21591
21644
|
concept: identity.concept,
|
|
21592
21645
|
line,
|
|
21593
|
-
text:
|
|
21646
|
+
text: bulletLabel(next),
|
|
21594
21647
|
status,
|
|
21595
21648
|
priority: after.priority,
|
|
21596
21649
|
due: after.due,
|
|
@@ -21722,7 +21775,7 @@ async function readTask(graph, args) {
|
|
|
21722
21775
|
return {
|
|
21723
21776
|
concept: found.document,
|
|
21724
21777
|
line: found.line,
|
|
21725
|
-
text:
|
|
21778
|
+
text: bulletLabel(line),
|
|
21726
21779
|
status: taskStatus(task.done, task),
|
|
21727
21780
|
priority: task.priority,
|
|
21728
21781
|
due: task.due,
|
|
@@ -22821,6 +22874,7 @@ function accessEndedError(graph, cmd) {
|
|
|
22821
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 computer's access token: it was revoked or has expired, or the account's password was reset. Run ${cmd} login again.`);
|
|
22822
22875
|
}
|
|
22823
22876
|
var concept = z.string().min(1).describe("A page title, one of its aliases, a journal day as YYYY-MM-DD, or \"today\".");
|
|
22877
|
+
var readOffset = z.number().int().min(0).optional().describe("Where to start reading: the nextOffset a cut answer gave. 0 (the start) by default.");
|
|
22824
22878
|
var offset = z.number().int().nonnegative().optional().describe("Skip this many results (paging).");
|
|
22825
22879
|
/** A frontmatter value as JSON carries it; the writer turns it into YAML. */
|
|
22826
22880
|
var frontmatterValue = z.union([
|
|
@@ -22889,9 +22943,12 @@ function createMcpServer(source, info) {
|
|
|
22889
22943
|
}, async (args) => run((graph) => listDocuments(graph, args)));
|
|
22890
22944
|
server.registerTool("read_document", {
|
|
22891
22945
|
title: "Read a document",
|
|
22892
|
-
description:
|
|
22893
|
-
inputSchema: {
|
|
22894
|
-
|
|
22946
|
+
description: `One document: its body as "text" (the markdown after any frontmatter block) and its frontmatter as the "frontmatter" object, minus title and aliases (its identity) and any publication definition. A protected document answers not_found, as a name nothing has. A body longer than ${READ_TEXT_CAP.toLocaleString("en-GB")} characters comes in parts: an answer cut short says truncated: true and gives nextOffset - read again with offset set to it for the next part, until truncated is false. startLine is the line the text starts on, so line numbers from search and tasks still apply.`,
|
|
22947
|
+
inputSchema: {
|
|
22948
|
+
concept,
|
|
22949
|
+
offset: readOffset
|
|
22950
|
+
}
|
|
22951
|
+
}, async (args) => run((graph) => readDocument(graph, args.concept, { offset: args.offset })));
|
|
22895
22952
|
server.registerTool("list_versions", {
|
|
22896
22953
|
title: "List a document's versions",
|
|
22897
22954
|
description: "A synced document's earlier versions, newest first, each with when it was made and what made it (\"Edited\", \"Before a rename\", \"Before an agent's edit\"), and how many days the graph keeps them. Your first edit to a document in a session is preceded by a version of it. You cannot restore a version: tell the person, who restores it from the document's Version history in EtherPK.",
|
|
@@ -22899,15 +22956,16 @@ function createMcpServer(source, info) {
|
|
|
22899
22956
|
}, async (args) => run((graph) => listVersions(graph, args.concept)));
|
|
22900
22957
|
server.registerTool("read_version", {
|
|
22901
22958
|
title: "Read a document version",
|
|
22902
|
-
description: "The whole text a synced document held at one earlier version (list_versions names them), frontmatter included, and the name it had then. Read-only: a person restores a version in EtherPK.",
|
|
22959
|
+
description: "The whole text a synced document held at one earlier version (list_versions names them), frontmatter included, and the name it had then. A long text comes in parts, as read_document gives them: truncated: true with nextOffset to pass as offset. Read-only: a person restores a version in EtherPK.",
|
|
22903
22960
|
inputSchema: {
|
|
22904
22961
|
concept,
|
|
22905
|
-
version: z.string().uuid().describe("A version id from list_versions.")
|
|
22962
|
+
version: z.string().uuid().describe("A version id from list_versions."),
|
|
22963
|
+
offset: readOffset
|
|
22906
22964
|
}
|
|
22907
|
-
}, async (args) => run((graph) => readVersion(graph, args.concept, args.version)));
|
|
22965
|
+
}, async (args) => run((graph) => readVersion(graph, args.concept, args.version, { offset: args.offset })));
|
|
22908
22966
|
server.registerTool("read_documents", {
|
|
22909
22967
|
title: "Read several documents",
|
|
22910
|
-
description: `Up to 20 documents in one call, each as read_document returns it. A protected or unknown document is reported in its place as not_found rather than failing the call. Long texts are cut and marked truncated.`,
|
|
22968
|
+
description: `Up to 20 documents in one call, each as read_document returns it. A protected or unknown document is reported in its place as not_found rather than failing the call. Long texts are cut and marked truncated, with the nextOffset to read the rest from with read_document.`,
|
|
22911
22969
|
inputSchema: { concepts: z.array(concept).min(1).max(20) }
|
|
22912
22970
|
}, async (args) => run((graph) => readDocuments(graph, args)));
|
|
22913
22971
|
server.registerTool("search", {
|