@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 CHANGED
@@ -820,7 +820,7 @@ function looksLikeAgentSetupCode(value) {
820
820
  }
821
821
  var package_default = {
822
822
  name: "@appsoftwareltd/etherpk-mcp",
823
- version: "0.35.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
- /** `text` cut at `cap`, and whether it was. */
18384
- function capText(text, cap = READ_TEXT_CAP) {
18385
- return text.length > cap ? {
18386
- text: text.slice(0, cap),
18387
- truncated: true
18388
- } : {
18389
- text,
18390
- truncated: false
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
- async function readDocument(graph, concept) {
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: capped.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 capped = capText(read.text, READ_TEXT_CAP);
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
- text: capped.text,
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 entry = found.get(id) ?? {
21522
+ const name = displayNameOf(ref);
21523
+ const key = `${id}\n${name}`;
21524
+ const entry = found.get(key) ?? {
21525
+ id,
21475
21526
  ref,
21476
- name: displayNameOf(ref),
21477
- type: mimeTypeForExt(splitNameExt(displayNameOf(ref)).ext),
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(id, entry);
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.entries()].map(([id, entry]) => ({
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 cap = Math.max(0, Math.min(READ_TEXT_CAP, budget));
21526
- const cut = text.length > cap;
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
- text: cut ? text.slice(0, cap) : text,
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: after.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: task.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: "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. Long documents are cut and marked truncated: true.",
22893
- inputSchema: { concept }
22894
- }, async (args) => run((graph) => readDocument(graph, args.concept)));
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", {