seekstone 0.20.3 → 0.21.0

package/README.md

@@ -104,7 +104,7 @@ Other MCP clients (Windsurf, Cline, …) take the Option 3 JSON block in their o
 
 ## Tools
 
-21 tools: 11 read, 10 write.
+22 tools: 12 read, 10 write.
 
 ### Read
 
@@ -114,6 +114,7 @@ Other MCP clients (Windsurf, Cline, …) take the Option 3 JSON block in their o
 | `query_notes` | Structured metadata query. Filter by frontmatter key/value predicates (`eq`, `ne`, `contains`, `exists`, `missing`, `gt`/`gte`/`lt`/`lte`), tag, folder, modified time, and size; sort and select the fields you need. Returns compact rows, not note content. |
 | `context_pack` | Answer-ready context for a natural-language question in one call, hard-capped at a byte budget (default 2 KB): ranked excerpts, linked neighbor notes with one-line summaries, and follow-up source paths — replaces a search → read → get_backlinks round-trip loop. Scopable by `folder`/`tag` and takes the same `mode` as `search`. |
 | `read_note` | Read the full content of a note by vault-relative path. Supports returning a single section, block, or line range. |
+| `read_notes` | Read up to 20 notes (or sections, blocks, line ranges) in one call under a total byte budget (default 16 KB). Over budget, each note is cut to a fair share and marked `truncated`; one bad path returns its own error without failing the batch. |
 | `list_notes` | List notes, optionally filtered by folder prefix or tag. |
 | `list_tags` | List all tags in the vault sorted by usage count (or alphabetically). |
 | `outline_note` | Return a note's heading and block structure without its full content. |

package/dist/index.js

@@ -2694,19 +2694,77 @@ async function readNote(ctx2, input) {
   };
 }
 
+// src/tools/read_notes.ts
+import { z as z18 } from "zod";
+var DEFAULT_BUDGET_BYTES = 16384;
+var ReadNotesInput = z18.object({
+  items: z18.array(ReadNoteInput).min(1).max(20).describe(
+    "Notes to read, 1\u201320, each with the same options as read_note (path plus at most one of section, block, or lines)."
+  ),
+  budgetBytes: z18.number().int().min(256).max(65536).default(DEFAULT_BUDGET_BYTES).describe(
+    "Cap on the total note text returned across all items (UTF-8 bytes). When exceeded, each item is truncated to a fair share."
+  )
+});
+async function readNotes(ctx2, input) {
+  const budget = input.budgetBytes;
+  const results = await Promise.all(
+    input.items.map((item) => readNote(ctx2, item).catch((err) => toItemError(item.path, err)))
+  );
+  const entries = results.filter((r) => !("error" in r)).map((r) => ({ r, size: r.bytesReturned, alloc: 0 }));
+  allocate(entries, budget);
+  const cut = new Map(
+    entries.map((e) => [e.r, truncateItem(e.r, e.alloc)])
+  );
+  const notes2 = results.map((r) => cut.get(r) ?? r);
+  const bytesUsed = [...cut.values()].reduce((sum, r) => sum + r.bytesReturned, 0);
+  return { notes: notes2, budgetBytes: budget, bytesUsed };
+}
+function toItemError(path2, err) {
+  const { message, code } = err;
+  if (message.startsWith("{")) return { path: path2, ...JSON.parse(message) };
+  if (message.startsWith("Path outside vault")) return { path: path2, error: "outside_vault" };
+  if (code === "ENOENT") return { path: path2, error: "not_found" };
+  return { path: path2, error: "read_failed", message };
+}
+function allocate(entries, budget) {
+  let pending = entries.filter((e) => e.size > 0);
+  let remaining = budget;
+  for (const e of entries) e.alloc = e.size;
+  if (entries.reduce((sum, e) => sum + e.size, 0) <= budget) return;
+  while (pending.length > 0) {
+    const share = Math.floor(remaining / pending.length);
+    const fits = pending.filter((e) => e.size <= share);
+    if (fits.length === 0) {
+      const extra = remaining - share * pending.length;
+      for (const [k, e] of pending.entries()) e.alloc = share + (k < extra ? 1 : 0);
+      return;
+    }
+    for (const e of fits) remaining -= e.size;
+    pending = pending.filter((e) => e.size > share);
+  }
+}
+function truncateItem(r, maxBytes) {
+  if (r.bytesReturned <= maxBytes) return r;
+  const buf = Buffer.from(r.content, "utf8");
+  let end = maxBytes;
+  while (end > 0 && (buf.readUInt8(end) & 192) === 128) end--;
+  const content = buf.toString("utf8", 0, end);
+  return { ...r, content, bytesReturned: end, truncated: true };
+}
+
 // src/tools/rename_heading.ts
 import { readFile as readFile11 } from "fs/promises";
 import { join as join5 } from "path";
-import { z as z18 } from "zod";
-var RenameHeadingInput = z18.object({
-  path: z18.string().describe("Vault-relative path of the note containing the heading."),
-  oldHeading: z18.string().min(1).describe(
+import { z as z19 } from "zod";
+var RenameHeadingInput = z19.object({
+  path: z19.string().describe("Vault-relative path of the note containing the heading."),
+  oldHeading: z19.string().min(1).describe(
     "Current heading text, without # markers. Matched case-insensitively; if the note has duplicate headings the first one wins, mirroring Obsidian link resolution."
   ),
-  newHeading: z18.string().min(1).refine((s) => !/[\n[\]|#]/.test(s), {
+  newHeading: z19.string().min(1).refine((s) => !/[\n[\]|#]/.test(s), {
     message: 'newHeading must not contain newlines, "[", "]", "|", or "#" \u2014 those break [[note#heading]] link syntax.'
   }).describe("New heading text, without # markers."),
-  prevHash: z18.string().optional().describe(
+  prevHash: z19.string().optional().describe(
     "Optional compare-and-swap guard: the contentHash from a prior read of this note. Fails with hash_conflict if the note changed since."
   )
 });
@@ -2829,17 +2887,17 @@ async function renameHeading(ctx2, rawInput) {
 
 // src/tools/replace_in_note.ts
 import { readFile as readFile12 } from "fs/promises";
-import { z as z19 } from "zod";
-var ReplaceInNoteInput = z19.object({
-  path: z19.string().describe("Vault-relative path to the note."),
-  find: z19.string().min(1).max(1e3).describe("Text or pattern to find (max 1000 chars; bounds regex-mode pattern size)."),
-  replace: z19.string().describe("Replacement text. Supports $1, $2, \u2026 backreferences in regex mode."),
-  regex: z19.boolean().default(false).describe("Treat find as a regular expression."),
-  caseSensitive: z19.boolean().default(false).describe("Case-sensitive matching."),
-  wholeWord: z19.boolean().default(false).describe("Match whole words only (\\b word-boundary)."),
-  limit: z19.number().int().min(1).optional().describe("Maximum number of replacements. Omit to replace all."),
-  dryRun: z19.boolean().default(false).describe("If true, report matches without writing anything."),
-  prevHash: z19.string().optional().describe(
+import { z as z20 } from "zod";
+var ReplaceInNoteInput = z20.object({
+  path: z20.string().describe("Vault-relative path to the note."),
+  find: z20.string().min(1).max(1e3).describe("Text or pattern to find (max 1000 chars; bounds regex-mode pattern size)."),
+  replace: z20.string().describe("Replacement text. Supports $1, $2, \u2026 backreferences in regex mode."),
+  regex: z20.boolean().default(false).describe("Treat find as a regular expression."),
+  caseSensitive: z20.boolean().default(false).describe("Case-sensitive matching."),
+  wholeWord: z20.boolean().default(false).describe("Match whole words only (\\b word-boundary)."),
+  limit: z20.number().int().min(1).optional().describe("Maximum number of replacements. Omit to replace all."),
+  dryRun: z20.boolean().default(false).describe("If true, report matches without writing anything."),
+  prevHash: z20.string().optional().describe(
     "Optional compare-and-swap guard: the contentHash from a prior read. Fails with hash_conflict if the note changed since."
   )
 });
@@ -2924,12 +2982,12 @@ async function replaceInNote(ctx2, input) {
 // src/tools/undo_write.ts
 import { mkdir as mkdir6, readFile as readFile13, rm as rm3 } from "fs/promises";
 import { dirname as dirname4 } from "path";
-import { z as z20 } from "zod";
-var UndoWriteInput = z20.object({
-  seq: z20.number().int().min(1).optional().describe(
+import { z as z21 } from "zod";
+var UndoWriteInput = z21.object({
+  seq: z21.number().int().min(1).optional().describe(
     "Journal entry to revert (from list_writes). Defaults to the most recent undoable write."
   ),
-  force: z20.boolean().default(false).describe(
+  force: z21.boolean().default(false).describe(
     "Restore even if a file changed after the journaled write. The clobbered state is journaled first, so nothing is lost. Defaults to false \u2014 conflicts are refused."
   )
 });
@@ -3086,6 +3144,7 @@ function safeMeta(args) {
   }
   if (typeof a.query === "string") out.queryLen = a.query.length;
   if (Array.isArray(a.where)) out.whereCount = a.where.length;
+  if (Array.isArray(a.items)) out.itemsCount = a.items.length;
   return out;
 }
 function resultBytes(r) {
@@ -3235,6 +3294,11 @@ async function run(ctx2, name, args) {
       const result = await readNote(ctx2, input);
       return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     }
+    case "read_notes": {
+      const input = ReadNotesInput.parse(args);
+      const result = await readNotes(ctx2, input);
+      return { content: [{ type: "text", text: JSON.stringify(result) }] };
+    }
     case "list_notes": {
       const input = ListNotesInput.parse(args);
       const entries = listNotes(ctx2, input);
@@ -5121,6 +5185,59 @@ var ALL_TOOLS = [
       required: ["path"]
     }
   },
+  {
+    name: "read_notes",
+    annotations: READ_ONLY_ANNOTATIONS,
+    description: "Read up to 20 notes (or spans of them) in one call instead of repeated read_note calls, e.g. the top hits from search, query_notes, list_notes, or get_backlinks. Each item takes the same options as read_note and returns the same fields, in request order. budgetBytes (default 16384) caps the total note text: when the notes exceed it, each is cut to a fair share, marked truncated: true, and keeps noteBytes, so read the rest with read_note. A failing item (missing path, unknown section) returns its own error without failing the batch. contentHash is always the whole file's hash, usable as prevHash.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        items: {
+          type: "array",
+          description: "Notes to read, 1\u201320. Same options as read_note.",
+          items: {
+            type: "object",
+            properties: {
+              path: {
+                type: "string",
+                description: 'Vault-relative path, e.g. "Daily Notes/2026-05-29.md".'
+              },
+              section: {
+                type: "string",
+                description: "Return only this heading section (heading text, # prefix optional)."
+              },
+              block: {
+                type: "string",
+                description: "Return only the line anchored by this block id (^ prefix optional)."
+              },
+              lines: {
+                type: "object",
+                description: "Return only this line range (1-indexed, inclusive).",
+                properties: {
+                  from: { type: "number", description: "First line (1-indexed)." },
+                  to: {
+                    type: "number",
+                    description: "Last line (1-indexed, inclusive). Defaults to EOF."
+                  }
+                },
+                required: ["from"]
+              },
+              includeFrontmatter: {
+                type: "boolean",
+                description: "Prepend frontmatter to section/block span results. Default false for spans."
+              }
+            },
+            required: ["path"]
+          }
+        },
+        budgetBytes: {
+          type: "number",
+          description: "Cap on total note text returned across all items, in UTF-8 bytes (256\u201365536, default 16384)."
+        }
+      },
+      required: ["items"]
+    }
+  },
   {
     name: "list_notes",
     annotations: READ_ONLY_ANNOTATIONS,
@@ -5628,7 +5745,7 @@ function startWatcher(ctx2, log2, opts) {
 }
 
 // src/index.ts
-var VERSION = true ? "0.20.3" : "0.0.0-dev";
+var VERSION = true ? "0.21.0" : "0.0.0-dev";
 var intent = parseCliIntent(process.argv.slice(2));
 if (intent === "version") {
   process.stdout.write(`${VERSION}