@appsoftwareltd/etherpk-mcp 0.19.1 → 0.19.3

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/README.md CHANGED
@@ -27,7 +27,7 @@ links to the server's **Access tokens** page, which makes the code.
27
27
  npx @appsoftwareltd/etherpk-mcp login --sync-server https://sync.etherpk.com --code <Agent Setup Code>
28
28
 
29
29
  # Register the graph with your agent (Claude Code shown, the Agents tab has the others).
30
- claude mcp add etherpk -- npx @appsoftwareltd/etherpk-mcp serve --sync-server https://sync.etherpk.com --graph <graph id>
30
+ claude mcp add --scope user etherpk -- npx @appsoftwareltd/etherpk-mcp serve --sync-server https://sync.etherpk.com --graph <graph id>
31
31
  ```
32
32
 
33
33
  ### A local graph folder
@@ -35,7 +35,7 @@ claude mcp add etherpk -- npx @appsoftwareltd/etherpk-mcp serve --sync-server ht
35
35
  No sign-in and no Sync Server:
36
36
 
37
37
  ```sh
38
- claude mcp add etherpk -- npx @appsoftwareltd/etherpk-mcp serve --folder /path/to/your/notes
38
+ claude mcp add --scope user etherpk -- npx @appsoftwareltd/etherpk-mcp serve --folder /path/to/your/notes
39
39
  ```
40
40
 
41
41
  The folder must already be an EtherPK graph, with `pages/` and `journals/` folders in it. EtherPK
@@ -62,7 +62,7 @@ onto its name is refused.
62
62
  | --- | --- | --- |
63
63
  | Find and read | `graph_info`, `list_documents`, `read_document`, `read_documents`, `search`, `backlinks`, `tasks`, `graph_insights`, `graph_path` | `list_documents` can narrow to a range of journal days. `graph_insights` lists the most-linked concepts, clusters and bridges, and `graph_path` finds how two concepts connect. |
64
64
  | Edit | `edit_document`, `append_document`, `create_page`, `set_task`, `set_frontmatter`, `set_aliases` | `edit_document` replaces one exact, unique piece of text, and on a synced graph it merges with edits made elsewhere. `append_document` creates the day's journal entry when there is none. |
65
- | Tasks handed over | `read_task`, `add_task_note`, `set_task` | Paste the agent a task reference copied in EtherPK. The reference still finds the task after lines are added above it, and refuses once the task's words change. |
65
+ | Tasks handed over | `read_task`, `add_task_note`, `set_task` | Paste the agent the text **Copy agent instruction** copies in EtherPK. Its reference still finds the task after lines are added above it, and refuses once the task's words change. |
66
66
  | Rename | `plan_rename`, `rename` | Links to the old name are rewritten. Renaming onto a name in use merges two documents and needs confirming. |
67
67
  | Images and files | `upload_asset`, `read_asset`, `list_assets` | `upload_asset` returns the markdown to paste into a document. It refuses hidden files and folders (`.ssh`, `.env`), the Headless Client's own config and cache, and files over 100 MiB. |
68
68
  | Publishing | `list_publications`, `create_publication`, `update_publication`, `publish` | `publish` writes to the folder set with the `publish` command. The agent can't choose one, and it never publishes to a GitHub repository, which only the `publish` command commits to. |
package/dist/main.js CHANGED
@@ -714,7 +714,7 @@ function looksLikeAgentSetupCode(value) {
714
714
  }
715
715
  var package_default = {
716
716
  name: "@appsoftwareltd/etherpk-mcp",
717
- version: "0.19.1",
717
+ version: "0.19.3",
718
718
  license: "Elastic-2.0",
719
719
  description: "EtherPK Headless Client: an MCP server over a synced knowledge graph, run beside the agent on the user's own machine.",
720
720
  type: "module",
@@ -7129,6 +7129,14 @@ function tasksMatchingCount(db, query) {
7129
7129
  if (predicate === null) return 0;
7130
7130
  return db.all(`SELECT COUNT(*) AS n FROM tasks t JOIN pages p ON p.id = t.page_id WHERE ${predicate.where}`, predicate.params)[0]?.n ?? 0;
7131
7131
  }
7132
+ /**
7133
+ * Every task in the live generation, in no order. A separate read from {@link tasksMatching},
7134
+ * which sorts every task for each page and loads what surrounds it: finding a Task Reference
7135
+ * elsewhere in a graph compares every task's words and uses none of that.
7136
+ */
7137
+ function taskLabels(db) {
7138
+ return db.all("SELECT p.concept AS document, t.line AS line, t.text AS label FROM tasks t JOIN pages p ON p.id = t.page_id WHERE p.generation = ?", [activeIndexGeneration(db)]);
7139
+ }
7132
7140
  /** `YYYY-MM-DD` shifted by whole days, so the caller never leaves string space. */
7133
7141
  function addDays(day, days) {
7134
7142
  const [year, month, date] = day.split("-").map(Number);
@@ -18801,29 +18809,6 @@ async function resolveTaskReference(reference, sources) {
18801
18809
  code: "task_not_found"
18802
18810
  };
18803
18811
  }
18804
- /** How many tasks `everyIndexedTask` asks the index for at a time. */
18805
- var INDEX_PAGE = 500;
18806
- /** Every task the index knows, in pages, as {@link TaskReferenceSources.allTasks} wants them. */
18807
- async function everyIndexedTask(index, today) {
18808
- const query = {
18809
- concept: null,
18810
- statuses: TASK_STATUSES,
18811
- priorities: TASK_PRIORITY_FILTERS,
18812
- due: "any",
18813
- groupBy: "document",
18814
- today
18815
- };
18816
- const out = [];
18817
- for (let offset = 0;; offset += INDEX_PAGE) {
18818
- const page = await index.tasks(query, offset, INDEX_PAGE);
18819
- for (const hit of page.hits) out.push({
18820
- document: hit.concept,
18821
- line: hit.line,
18822
- label: hit.text
18823
- });
18824
- if (!page.hasMore) return out;
18825
- }
18826
- }
18827
18812
  /** The lines of `lines` that hold a task with this fingerprint, never one inside a code fence. */
18828
18813
  async function taskLinesWith(lines, fingerprint) {
18829
18814
  const inFence = /* @__PURE__ */ new Set();
@@ -19951,7 +19936,7 @@ async function graphPath(graph, args) {
19951
19936
  function taskSelection(graph, args) {
19952
19937
  if (args.reference !== void 0) {
19953
19938
  const lane = parseLaneReference(args.reference);
19954
- if (!lane) throw new ToolError("invalid_argument", "reference is not a lane reference. Pass the text Copy lane reference wrote, or its etherpk:/g/…#lane= address; for one task, use read_task.");
19939
+ if (!lane) throw new ToolError("invalid_argument", "reference is not a lane reference. Pass the text Copy agent instruction wrote, or its etherpk:/g/…#lane= address; for one task, use read_task.");
19955
19940
  if (args.concept !== void 0 || args.statuses !== void 0) throw new ToolError("invalid_argument", "A lane reference names the concept and status itself: pass reference without concept or statuses.");
19956
19941
  if (graph.backend.kind === "synced" && lane.graphId !== graph.graphId) throw new ToolError("other_graph", `That lane reference is for another graph. This server serves "${graph.name}" (${graph.graphId}); ask the user to connect the graph the reference is from.`);
19957
19942
  return {
@@ -20635,7 +20620,7 @@ function referenceSources(graph) {
20635
20620
  const identity = resolveIdentity(graph, document);
20636
20621
  return identity ? visibleText(graph, identity, hidden) : null;
20637
20622
  },
20638
- allTasks: async () => (await everyIndexedTask(graph.index, todayISO())).filter((task) => !hidden.has(conceptKey(task.document)))
20623
+ allTasks: async () => (await graph.index.taskLabels()).filter((task) => !hidden.has(conceptKey(task.document)))
20639
20624
  };
20640
20625
  }
20641
20626
  /** The Task Reference to the task at `line` of `concept`, whose label is `label`. */
@@ -20655,7 +20640,7 @@ async function referenceFor(graph, concept, line, label) {
20655
20640
  */
20656
20641
  async function requireReferencedTask(graph, reference, purpose = "read") {
20657
20642
  const parsed = parseTaskReference(reference);
20658
- if (!parsed) throw new ToolError("invalid_argument", "That is not a task reference: one is etherpk:/g/<graph>/d/<document>#task=<line>-<fingerprint>, as Copy task reference in EtherPK writes it.");
20643
+ if (!parsed) throw new ToolError("invalid_argument", "That is not a task reference: one is etherpk:/g/<graph>/d/<document>#task=<line>-<fingerprint>, as Copy agent instruction in EtherPK writes it.");
20659
20644
  await graph.store.refresh();
20660
20645
  const found = await resolveTaskReference(parsed, referenceSources(graph));
20661
20646
  if (found.ok) return found;
@@ -20663,7 +20648,7 @@ async function requireReferencedTask(graph, reference, purpose = "read") {
20663
20648
  if (found.code === "task_ambiguous") throw new ToolError("task_ambiguous", `More than one task has those words (${found.candidates.map((candidate) => `"${candidate.document}" line ${candidate.line}`).join(", ")}), so none was chosen. Ask the user which one, or name it by concept and line.`);
20664
20649
  const named = resolveIdentity(graph, parsed.document);
20665
20650
  if (purpose === "write" && named && await visibleText(graph, named) === null) throw protectedDocument(parsed.document);
20666
- throw new ToolError("task_not_found", "No task in the graph has those words now: it was edited or deleted. Ask the user for a fresh reference.");
20651
+ throw new ToolError("task_not_found", "No task in the graph has those words now: it was edited or deleted. Ask the user for a fresh agent instruction.");
20667
20652
  }
20668
20653
  /**
20669
20654
  * The block's own lines and everything nested under it: in the index's rows, which run in
@@ -20750,7 +20735,7 @@ async function addTaskNote(graph, args) {
20750
20735
  if (typeof args.text !== "string" || args.text.trim() === "") throw new ToolError("invalid_argument", "text must not be empty.");
20751
20736
  const found = await requireReferencedTask(graph, args.reference, "write");
20752
20737
  const change = commentChange(found.body, found.line, asCommentBullet(asWritten(args.text.trim())));
20753
- if (!change) throw new ToolError("task_not_found", "The task moved while the note was being written. Ask the user for a fresh reference.");
20738
+ if (!change) throw new ToolError("task_not_found", "The task moved while the note was being written. Ask the user for a fresh agent instruction.");
20754
20739
  graph.store.open(found.document).applyChange({
20755
20740
  from: change.from,
20756
20741
  to: change.to,
@@ -21835,8 +21820,8 @@ function createMcpServer(source, info) {
21835
21820
  "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 computer - if it is not set up, search says so and names the command.",
21836
21821
  "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.",
21837
21822
  "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.",
21838
- "A task reference is how a person hands you one task: a few lines naming the graph, the task's words and a reference, etherpk:/g/<graph>/d/<document>#task=<line>-<fingerprint> (an earlier version wrote a web address ending in the same #task=). 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 it answers task_not_found, and you should ask the user for a fresh one.",
21839
- "A lane reference is how a person hands 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 reference, etherpk:/g/<graph>/k/<concept>#lane=<status> (etherpk:/g/<graph>/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.",
21823
+ "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:/g/<graph>/d/<document>#task=<line>-<fingerprint> (an earlier version wrote a web address ending in the same #task=). 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 it answers task_not_found, and you should ask the user for a fresh one.",
21824
+ "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:/g/<graph>/k/<concept>#lane=<status> (etherpk:/g/<graph>/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.",
21840
21825
  "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\".",
21841
21826
  "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.",
21842
21827
  "Images and files are assets: upload_asset adds a file from this machine and returns the markdown to paste into a document. read_asset writes an asset to a local file you can open, and list_assets shows the assets documents reference. An asset is available only where a document you can read references it (or you uploaded it this session). read_asset, read_theme and preview_theme write under the graph's downloads directory and return the path - name a folder relative to it, never elsewhere.",
@@ -21909,7 +21894,7 @@ function createMcpServer(source, info) {
21909
21894
  title: "Tasks",
21910
21895
  description: `Tasks ("- [ ]" bullets) across the graph with their tags, and freeTags: the person's own #words anywhere in a task's text (#bug), which carry no status. Defaults to every unfinished task. A concept filter matches tasks written on that page or on a page named for it ("[[Concept]] Notes"), linking it, or nested under a block or heading that links it. A task nested under another lists its parentTask (its text and line), and subtasks counts the tasks nested under each one (done of total; cancelled counts as done, archived is left out). board: true lists what a Kanban board shows: a task whose parent task is also on the board is left out, as you reach it through its parent with read_task. A lane reference (a Kanban lane the user copied) in reference lists that lane's tasks as the board shows them: it sets the concept and status, so pass it without concept or statuses; errors invalid_argument (not a lane reference) and other_graph (the lane is in another graph). At most 200 per call.`,
21911
21896
  inputSchema: {
21912
- reference: z.string().min(1).optional().describe("A lane reference as the user gave it: the whole text, or the etherpk: reference alone. In place of concept and statuses."),
21897
+ reference: z.string().min(1).optional().describe("The agent instruction for a lane as the user gave it: the whole text, or its etherpk: lane reference alone. In place of concept and statuses."),
21913
21898
  concept: concept.optional(),
21914
21899
  statuses: z.array(z.enum([
21915
21900
  "open",
@@ -21940,13 +21925,13 @@ function createMcpServer(source, info) {
21940
21925
  server.registerTool("read_task", {
21941
21926
  title: "Read a task",
21942
21927
  description: "The task a task reference names: its text, status, priority, due and scheduled days, its free tags, its document and current 0-based line, its breadcrumb (the headings and bullets above it), its detail (its continuation lines and everything nested under it), foundBy (at_line, moved or other_document), its current reference, assets: the images and files the task and its detail show, to read with read_asset, comments: the task comments, each the text of one bullet under the \"Comments\" bullet nested directly under the task (they are in its detail too), and subtasks: every task nested under it at any depth, each with its text, status, line, depth and a reference for set_task, read_task and add_task_note. Errors: task_not_found (its words were edited or it was deleted), task_ambiguous (two tasks have its words; the message names them), other_graph (the reference is from another graph).",
21943
- inputSchema: { reference: z.string().min(1).describe("The task reference as the user gave it: the whole text, or the etherpk: reference alone.") }
21928
+ inputSchema: { reference: z.string().min(1).describe("The agent instruction as the user gave it: the whole text, or its etherpk: reference alone.") }
21944
21929
  }, async (args) => run((graph) => readTask(graph, args)));
21945
21930
  server.registerTool("add_task_note", {
21946
21931
  title: "Add a comment to a task",
21947
21932
  description: "Add a task comment to the task a task reference names: a bullet under the task's \"Comments\" bullet, after the comments already there. A \"- Comments\" bullet is started as the task's last child when it has none. A line of text becomes one bullet, and bullets are nested as written. Use it to record what you did about the task. To write a comment by hand instead, add a bullet under \"- Comments\" nested directly under the task. Refuses as read_task does when the reference finds no single task.",
21948
21933
  inputSchema: {
21949
- reference: z.string().min(1).describe("The task reference as the user gave it."),
21934
+ reference: z.string().min(1).describe("The agent instruction as the user gave it, or its etherpk: reference."),
21950
21935
  text: z.string().min(1).describe("Markdown: a line, or \"- \" bullets.")
21951
21936
  }
21952
21937
  }, async (args) => run((graph) => addTaskNote(graph, args)));
@@ -23151,19 +23136,8 @@ function createIndexCore(host) {
23151
23136
  id: request.id,
23152
23137
  documents: db ? documentsMatchingProperties(db, request.filters) : []
23153
23138
  }];
23154
- case "tasks": {
23155
- const page = db ? tasksMatching(db, request.query, request.offset, request.limit) : {
23156
- hits: [],
23157
- hasMore: false
23158
- };
23159
- return [{
23160
- type: "tasks",
23161
- id: request.id,
23162
- hits: page.hits,
23163
- hasMore: page.hasMore,
23164
- total: db ? tasksMatchingCount(db, request.query) : 0
23165
- }];
23166
- }
23139
+ case "tasks":
23140
+ case "task-labels": return [taskResponse(db, request)];
23167
23141
  case "asset-usage": {
23168
23142
  const usage = db ? assetUsage(db, request.needles) : {
23169
23143
  references: 0,
@@ -23295,6 +23269,25 @@ function createIndexCore(host) {
23295
23269
  * request failed" from "this request failed and the whole index is now empty — re-derive".
23296
23270
  */
23297
23271
  var INDEX_DISCARDED_PREFIX = "index-discarded:";
23272
+ /** The answer to a request for tasks: nothing with no database open. */
23273
+ function taskResponse(db, request) {
23274
+ if (request.type === "task-labels") return {
23275
+ type: "task-labels",
23276
+ id: request.id,
23277
+ tasks: db ? taskLabels(db) : []
23278
+ };
23279
+ const page = db ? tasksMatching(db, request.query, request.offset, request.limit) : {
23280
+ hits: [],
23281
+ hasMore: false
23282
+ };
23283
+ return {
23284
+ type: "tasks",
23285
+ id: request.id,
23286
+ hits: page.hits,
23287
+ hasMore: page.hasMore,
23288
+ total: db ? tasksMatchingCount(db, request.query) : 0
23289
+ };
23290
+ }
23298
23291
  /**
23299
23292
  * Whether an error is SQLite saying the file itself is damaged, as opposed to a bad query or
23300
23293
  * a busy lock. sqlite-wasm throws `SQLite3Error` with a `resultCode`; the message form is
@@ -24075,6 +24068,12 @@ function createRemoteGraphIndex(source, transport, options) {
24075
24068
  total: response.total
24076
24069
  };
24077
24070
  },
24071
+ async taskLabels() {
24072
+ return (await request((id) => ({
24073
+ type: "task-labels",
24074
+ id
24075
+ }))).tasks;
24076
+ },
24078
24077
  semantic: {
24079
24078
  async status(model) {
24080
24079
  return (await request((id) => ({
@@ -28771,7 +28770,7 @@ var USAGE = `etherpk-mcp - EtherPK Headless Client (an MCP server over one synce
28771
28770
  List the synced graphs each logged-in account can reach, by name and id.
28772
28771
  ${CMD} serve --graph <id or name> [--sync-server <url>] [--no-semantic]
28773
28772
  Serve one synced graph to an agent over stdio. For Claude Code:
28774
- claude mcp add etherpk -- npx @appsoftwareltd/etherpk-mcp serve --sync-server <url> --graph <id>
28773
+ claude mcp add --scope user etherpk -- npx @appsoftwareltd/etherpk-mcp serve --sync-server <url> --graph <id>
28775
28774
  Once "semantic setup" has run on this computer, serve also keeps a search-by-meaning
28776
28775
  store of the graph current (the agent's search tool gains mode: semantic) - pass
28777
28776
  --no-semantic to leave it off for this registration.
@@ -29176,7 +29175,7 @@ async function listGraphs(login, several) {
29176
29175
  for (const record of graphs) console.log(` ${record.id} ${describeGraphLabel(await resolveGraphLabel(record, vault, readMeta))} [${record.role}]`);
29177
29176
  console.log("");
29178
29177
  console.log(`Serve one to an agent with: ${CMD} serve${serverFlag} --graph <id>`);
29179
- console.log(`For Claude Code: claude mcp add etherpk -- ${CMD} serve${serverFlag} --graph <id>`);
29178
+ console.log(`For Claude Code: claude mcp add --scope user etherpk -- ${CMD} serve${serverFlag} --graph <id>`);
29180
29179
  }
29181
29180
  async function semanticCommand(what) {
29182
29181
  switch (what) {