@appsoftwareltd/etherpk-mcp 0.35.0 → 0.36.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 +93 -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.36.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",
|
|
@@ -18380,16 +18380,51 @@ function lastNonBlank(lines) {
|
|
|
18380
18380
|
var READ_TEXT_CAP = 2e5;
|
|
18381
18381
|
/** UTF-16 units across one bulk read before the rest is cut. */
|
|
18382
18382
|
var READ_MANY_TEXT_CAP = 4e5;
|
|
18383
|
-
/**
|
|
18384
|
-
|
|
18385
|
-
|
|
18386
|
-
|
|
18387
|
-
|
|
18388
|
-
|
|
18389
|
-
|
|
18390
|
-
|
|
18383
|
+
/**
|
|
18384
|
+
* The part of `text` from `offset` that fits in `cap` UTF-16 units, so an agent can read a long
|
|
18385
|
+
* document to its end, a window at a time, by passing each `nextOffset` back. A cut window ends
|
|
18386
|
+
* after the last line break inside it, so the next starts on a line of its own; a line longer than
|
|
18387
|
+
* the whole cap is cut at the cap instead. A window never ends between the two halves of a
|
|
18388
|
+
* surrogate pair. An offset past the end, negative or not a whole number is a RangeError.
|
|
18389
|
+
*/
|
|
18390
|
+
function textWindow(text, offset = 0, cap = READ_TEXT_CAP) {
|
|
18391
|
+
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.`);
|
|
18392
|
+
const startLine = lineBreaksBefore(text, offset);
|
|
18393
|
+
if (text.length - offset <= cap) return {
|
|
18394
|
+
text: text.slice(offset),
|
|
18395
|
+
truncated: false,
|
|
18396
|
+
offset,
|
|
18397
|
+
startLine
|
|
18398
|
+
};
|
|
18399
|
+
const end = windowEnd(text, offset, offset + cap);
|
|
18400
|
+
return {
|
|
18401
|
+
text: text.slice(offset, end),
|
|
18402
|
+
truncated: true,
|
|
18403
|
+
offset,
|
|
18404
|
+
startLine,
|
|
18405
|
+
nextOffset: end
|
|
18391
18406
|
};
|
|
18392
18407
|
}
|
|
18408
|
+
/** How many line breaks come before `offset`: the 0-based line it falls on. */
|
|
18409
|
+
function lineBreaksBefore(text, offset) {
|
|
18410
|
+
let count = 0;
|
|
18411
|
+
for (let at = text.indexOf("\n"); at !== -1 && at < offset; at = text.indexOf("\n", at + 1)) count++;
|
|
18412
|
+
return count;
|
|
18413
|
+
}
|
|
18414
|
+
/**
|
|
18415
|
+
* Where a window from `offset` that may reach `limit` ends: after its last line break, or at
|
|
18416
|
+
* `limit` when it holds none, moved off the middle of a surrogate pair (back, or forward past
|
|
18417
|
+
* the pair when going back would leave the window empty).
|
|
18418
|
+
*/
|
|
18419
|
+
function windowEnd(text, offset, limit) {
|
|
18420
|
+
const lastBreak = text.lastIndexOf("\n", limit - 1);
|
|
18421
|
+
if (lastBreak >= offset) return lastBreak + 1;
|
|
18422
|
+
if (!isHighSurrogate(text.charCodeAt(limit - 1))) return limit;
|
|
18423
|
+
return limit - 1 > offset ? limit - 1 : limit + 1;
|
|
18424
|
+
}
|
|
18425
|
+
function isHighSurrogate(unit) {
|
|
18426
|
+
return unit >= 55296 && unit <= 56319;
|
|
18427
|
+
}
|
|
18393
18428
|
/**
|
|
18394
18429
|
* Whether `text` holds encrypted text anywhere: a Protected Document, or any other document with an
|
|
18395
18430
|
* `etherpk-cipher` fence in it. The index flags both as protected (`index-db.ts`), and a reader whose
|
|
@@ -20507,6 +20542,18 @@ var ToolError = class extends Error {
|
|
|
20507
20542
|
this.name = "ToolError";
|
|
20508
20543
|
}
|
|
20509
20544
|
};
|
|
20545
|
+
/**
|
|
20546
|
+
* The window of `text` a read answers, from `offset` up to `cap`, in the shape read results carry.
|
|
20547
|
+
* An offset outside the text is the agent's to correct, so it is refused as an argument.
|
|
20548
|
+
*/
|
|
20549
|
+
function readWindow(text, offset, cap = READ_TEXT_CAP) {
|
|
20550
|
+
try {
|
|
20551
|
+
return textWindow(text, offset ?? 0, cap);
|
|
20552
|
+
} catch (error) {
|
|
20553
|
+
if (error instanceof RangeError) throw new ToolError("invalid_argument", error.message);
|
|
20554
|
+
throw error;
|
|
20555
|
+
}
|
|
20556
|
+
}
|
|
20510
20557
|
/** Keys the frontmatter tools never read or write; each has a tool of its own. */
|
|
20511
20558
|
var OWNED_KEYS = /* @__PURE__ */ new Set([
|
|
20512
20559
|
"title",
|
|
@@ -20692,17 +20739,19 @@ async function listDocuments(graph, args = {}) {
|
|
|
20692
20739
|
hasMore: paged.hasMore
|
|
20693
20740
|
};
|
|
20694
20741
|
}
|
|
20695
|
-
|
|
20742
|
+
/**
|
|
20743
|
+
* One document's body and frontmatter. A body longer than {@link READ_TEXT_CAP} comes a window at
|
|
20744
|
+
* a time: each cut answer gives the `nextOffset` to read on from, so the end is always reachable.
|
|
20745
|
+
*/
|
|
20746
|
+
async function readDocument(graph, concept, options = {}) {
|
|
20696
20747
|
await graph.store.refresh();
|
|
20697
20748
|
const { identity, text } = await requireReadable(graph, concept);
|
|
20698
|
-
const capped = capText(text, READ_TEXT_CAP);
|
|
20699
20749
|
return {
|
|
20700
20750
|
concept: identity.concept,
|
|
20701
20751
|
kind: identity.kind,
|
|
20702
20752
|
aliases: identity.aliases,
|
|
20703
|
-
text
|
|
20704
|
-
frontmatter: agentFrontmatter(graph.store.openRaw(identity.concept).getText())
|
|
20705
|
-
truncated: capped.truncated
|
|
20753
|
+
...readWindow(text, options.offset),
|
|
20754
|
+
frontmatter: agentFrontmatter(graph.store.openRaw(identity.concept).getText())
|
|
20706
20755
|
};
|
|
20707
20756
|
}
|
|
20708
20757
|
function requireVersions(graph) {
|
|
@@ -20727,7 +20776,7 @@ async function listVersions(graph, concept) {
|
|
|
20727
20776
|
};
|
|
20728
20777
|
}
|
|
20729
20778
|
/** One earlier version's text (ADR 0184). */
|
|
20730
|
-
async function readVersion(graph, concept, version) {
|
|
20779
|
+
async function readVersion(graph, concept, version, options = {}) {
|
|
20731
20780
|
await graph.store.refresh();
|
|
20732
20781
|
const versions = requireVersions(graph);
|
|
20733
20782
|
const { identity } = await requireReadable(graph, concept);
|
|
@@ -20740,14 +20789,13 @@ async function readVersion(graph, concept, version) {
|
|
|
20740
20789
|
}
|
|
20741
20790
|
if (!read) throw notFound(concept);
|
|
20742
20791
|
if (holdsEncryptedText(read.text)) throw protectedDocument(concept);
|
|
20743
|
-
const
|
|
20792
|
+
const window = readWindow(read.text, options.offset);
|
|
20744
20793
|
const nameThen = read.identity.kind === "journal" ? read.identity.date ?? identity.concept : read.identity.title ?? identity.concept;
|
|
20745
20794
|
return {
|
|
20746
20795
|
concept: identity.concept,
|
|
20747
20796
|
version,
|
|
20748
20797
|
nameThen,
|
|
20749
|
-
|
|
20750
|
-
truncated: capped.truncated
|
|
20798
|
+
...window
|
|
20751
20799
|
};
|
|
20752
20800
|
}
|
|
20753
20801
|
async function search(graph, args) {
|
|
@@ -21471,14 +21519,17 @@ async function listAssets(graph, args = {}) {
|
|
|
21471
21519
|
for (const [concept, body] of bodies) for (const ref of assetReferencesIn(body)) {
|
|
21472
21520
|
const id = assets.identify(ref);
|
|
21473
21521
|
if (!id) continue;
|
|
21474
|
-
const
|
|
21522
|
+
const name = displayNameOf(ref);
|
|
21523
|
+
const key = `${id}\n${name}`;
|
|
21524
|
+
const entry = found.get(key) ?? {
|
|
21525
|
+
id,
|
|
21475
21526
|
ref,
|
|
21476
|
-
name
|
|
21477
|
-
type: mimeTypeForExt(splitNameExt(
|
|
21527
|
+
name,
|
|
21528
|
+
type: mimeTypeForExt(splitNameExt(name).ext),
|
|
21478
21529
|
documents: /* @__PURE__ */ new Set()
|
|
21479
21530
|
};
|
|
21480
21531
|
entry.documents.add(concept);
|
|
21481
|
-
found.set(
|
|
21532
|
+
found.set(key, entry);
|
|
21482
21533
|
}
|
|
21483
21534
|
let sizes;
|
|
21484
21535
|
try {
|
|
@@ -21486,11 +21537,11 @@ async function listAssets(graph, args = {}) {
|
|
|
21486
21537
|
} catch {
|
|
21487
21538
|
sizes = void 0;
|
|
21488
21539
|
}
|
|
21489
|
-
const list = [...found.
|
|
21540
|
+
const list = [...found.values()].map((entry) => ({
|
|
21490
21541
|
reference: entry.ref,
|
|
21491
21542
|
name: entry.name,
|
|
21492
21543
|
type: entry.type,
|
|
21493
|
-
...sizes?.has(id) ? { bytes: sizes.get(id) } : {},
|
|
21544
|
+
...sizes?.has(entry.id) ? { bytes: sizes.get(entry.id) } : {},
|
|
21494
21545
|
documents: [...entry.documents].sort()
|
|
21495
21546
|
})).sort((a, b) => a.name.localeCompare(b.name));
|
|
21496
21547
|
return {
|
|
@@ -21522,16 +21573,14 @@ async function readDocuments(graph, args) {
|
|
|
21522
21573
|
});
|
|
21523
21574
|
continue;
|
|
21524
21575
|
}
|
|
21525
|
-
const
|
|
21526
|
-
|
|
21527
|
-
budget -= Math.min(text.length, cap);
|
|
21576
|
+
const window = textWindow(text, 0, Math.max(0, Math.min(READ_TEXT_CAP, budget)));
|
|
21577
|
+
budget -= window.text.length;
|
|
21528
21578
|
documents.push({
|
|
21529
21579
|
concept: identity.concept,
|
|
21530
21580
|
kind: identity.kind,
|
|
21531
21581
|
aliases: identity.aliases,
|
|
21532
|
-
|
|
21533
|
-
frontmatter: agentFrontmatter(graph.store.openRaw(identity.concept).getText())
|
|
21534
|
-
truncated: cut
|
|
21582
|
+
...window,
|
|
21583
|
+
frontmatter: agentFrontmatter(graph.store.openRaw(identity.concept).getText())
|
|
21535
21584
|
});
|
|
21536
21585
|
}
|
|
21537
21586
|
return { documents };
|
|
@@ -21590,7 +21639,7 @@ async function setTask(graph, args) {
|
|
|
21590
21639
|
return {
|
|
21591
21640
|
concept: identity.concept,
|
|
21592
21641
|
line,
|
|
21593
|
-
text:
|
|
21642
|
+
text: bulletLabel(next),
|
|
21594
21643
|
status,
|
|
21595
21644
|
priority: after.priority,
|
|
21596
21645
|
due: after.due,
|
|
@@ -21722,7 +21771,7 @@ async function readTask(graph, args) {
|
|
|
21722
21771
|
return {
|
|
21723
21772
|
concept: found.document,
|
|
21724
21773
|
line: found.line,
|
|
21725
|
-
text:
|
|
21774
|
+
text: bulletLabel(line),
|
|
21726
21775
|
status: taskStatus(task.done, task),
|
|
21727
21776
|
priority: task.priority,
|
|
21728
21777
|
due: task.due,
|
|
@@ -22821,6 +22870,7 @@ function accessEndedError(graph, cmd) {
|
|
|
22821
22870
|
return loss.kind === "membership" ? new ToolError("access_removed", `This account no longer has access to the graph: it left, was removed by the owner, or the graph was deleted. Run ${cmd} graphs to see the graphs it can reach.`) : new ToolError("token_revoked", `The Sync Server no longer accepts this computer's access token: it was revoked or has expired, or the account's password was reset. Run ${cmd} login again.`);
|
|
22822
22871
|
}
|
|
22823
22872
|
var concept = z.string().min(1).describe("A page title, one of its aliases, a journal day as YYYY-MM-DD, or \"today\".");
|
|
22873
|
+
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
22874
|
var offset = z.number().int().nonnegative().optional().describe("Skip this many results (paging).");
|
|
22825
22875
|
/** A frontmatter value as JSON carries it; the writer turns it into YAML. */
|
|
22826
22876
|
var frontmatterValue = z.union([
|
|
@@ -22889,9 +22939,12 @@ function createMcpServer(source, info) {
|
|
|
22889
22939
|
}, async (args) => run((graph) => listDocuments(graph, args)));
|
|
22890
22940
|
server.registerTool("read_document", {
|
|
22891
22941
|
title: "Read a document",
|
|
22892
|
-
description:
|
|
22893
|
-
inputSchema: {
|
|
22894
|
-
|
|
22942
|
+
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.`,
|
|
22943
|
+
inputSchema: {
|
|
22944
|
+
concept,
|
|
22945
|
+
offset: readOffset
|
|
22946
|
+
}
|
|
22947
|
+
}, async (args) => run((graph) => readDocument(graph, args.concept, { offset: args.offset })));
|
|
22895
22948
|
server.registerTool("list_versions", {
|
|
22896
22949
|
title: "List a document's versions",
|
|
22897
22950
|
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 +22952,16 @@ function createMcpServer(source, info) {
|
|
|
22899
22952
|
}, async (args) => run((graph) => listVersions(graph, args.concept)));
|
|
22900
22953
|
server.registerTool("read_version", {
|
|
22901
22954
|
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.",
|
|
22955
|
+
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
22956
|
inputSchema: {
|
|
22904
22957
|
concept,
|
|
22905
|
-
version: z.string().uuid().describe("A version id from list_versions.")
|
|
22958
|
+
version: z.string().uuid().describe("A version id from list_versions."),
|
|
22959
|
+
offset: readOffset
|
|
22906
22960
|
}
|
|
22907
|
-
}, async (args) => run((graph) => readVersion(graph, args.concept, args.version)));
|
|
22961
|
+
}, async (args) => run((graph) => readVersion(graph, args.concept, args.version, { offset: args.offset })));
|
|
22908
22962
|
server.registerTool("read_documents", {
|
|
22909
22963
|
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.`,
|
|
22964
|
+
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
22965
|
inputSchema: { concepts: z.array(concept).min(1).max(20) }
|
|
22912
22966
|
}, async (args) => run((graph) => readDocuments(graph, args)));
|
|
22913
22967
|
server.registerTool("search", {
|