@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 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.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
- /** `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
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
- async function readDocument(graph, concept) {
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: capped.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 capped = capText(read.text, READ_TEXT_CAP);
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
- text: capped.text,
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 entry = found.get(id) ?? {
21526
+ const name = displayNameOf(ref);
21527
+ const key = `${id}\n${name}`;
21528
+ const entry = found.get(key) ?? {
21529
+ id,
21475
21530
  ref,
21476
- name: displayNameOf(ref),
21477
- type: mimeTypeForExt(splitNameExt(displayNameOf(ref)).ext),
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(id, entry);
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.entries()].map(([id, entry]) => ({
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 cap = Math.max(0, Math.min(READ_TEXT_CAP, budget));
21526
- const cut = text.length > cap;
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
- text: cut ? text.slice(0, cap) : text,
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: after.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: task.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: "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)));
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", {