@openparachute/vault 0.2.4 → 0.3.0

package/src/context.test.ts

@@ -0,0 +1,136 @@
+import { describe, test, expect } from "bun:test";
+import type { Note, Store } from "../core/src/types.ts";
+import { appendContextPart, fetchContextEntries } from "./context.ts";
+
+function mkNote(overrides: Partial<Note>): Note {
+  return {
+    id: overrides.id ?? "n1",
+    content: "",
+    createdAt: "2026-04-20T00:00:00Z",
+    updatedAt: "2026-04-20T00:00:00Z",
+    tags: [],
+    metadata: {},
+    ...overrides,
+  };
+}
+
+function mkStore(byTag: Record<string, Note[]>): Store {
+  return {
+    queryNotes: async ({ tags, excludeTags }) => {
+      const tag = tags?.[0];
+      if (!tag) return [];
+      const pool = byTag[tag] ?? [];
+      if (!excludeTags?.length) return pool;
+      const excluded = new Set(excludeTags);
+      return pool.filter((n) => !(n.tags ?? []).some((t) => excluded.has(t)));
+    },
+  } as unknown as Store;
+}
+
+describe("fetchContextEntries", () => {
+  test("returns whitelisted metadata keyed on path basename", async () => {
+    const store = mkStore({
+      person: [
+        mkNote({
+          id: "p1",
+          path: "People/Aaron.md",
+          tags: ["person"],
+          metadata: { summary: "founder", aliases: ["A"], secret: "don't leak" },
+        }),
+      ],
+    });
+
+    const payload = await fetchContextEntries(store, [
+      { tag: "person", include_metadata: ["summary", "aliases"] },
+    ]);
+
+    expect(payload.entries.length).toBe(1);
+    expect(payload.entries[0].name).toBe("Aaron");
+    expect(payload.entries[0].summary).toBe("founder");
+    expect(payload.entries[0].aliases).toEqual(["A"]);
+    // Non-whitelisted metadata never surfaces.
+    expect(payload.entries[0].secret).toBeUndefined();
+  });
+
+  test("honors exclude_tag", async () => {
+    const store = mkStore({
+      project: [
+        mkNote({ id: "pj1", path: "Projects/Active.md", tags: ["project"] }),
+        mkNote({ id: "pj2", path: "Projects/Old.md", tags: ["project", "archived"] }),
+      ],
+    });
+
+    const payload = await fetchContextEntries(store, [
+      { tag: "project", exclude_tag: "archived", include_metadata: [] },
+    ]);
+
+    expect(payload.entries.map((e) => e.name)).toEqual(["Active"]);
+  });
+
+  test("dedups notes across predicates by note id (first-match wins)", async () => {
+    const overlap = mkNote({ id: "x1", path: "People/X.md", tags: ["person", "project"] });
+    const store = mkStore({ person: [overlap], project: [overlap] });
+
+    const payload = await fetchContextEntries(store, [
+      { tag: "person", include_metadata: [] },
+      { tag: "project", include_metadata: [] },
+    ]);
+
+    expect(payload.entries.length).toBe(1);
+    expect(payload.entries[0].name).toBe("X");
+  });
+
+  test("falls back to note.id when path is absent", async () => {
+    const store = mkStore({
+      person: [mkNote({ id: "no-path-note", path: undefined, tags: ["person"] })],
+    });
+
+    const payload = await fetchContextEntries(store, [{ tag: "person" }]);
+
+    expect(payload.entries[0].name).toBe("no-path-note");
+  });
+
+  test("skips predicates with empty tag (defensive — not throw)", async () => {
+    const store = mkStore({ person: [mkNote({ id: "p1", path: "x" })] });
+    const payload = await fetchContextEntries(store, [
+      { tag: "" },
+      { tag: "person" },
+    ]);
+    expect(payload.entries.length).toBe(1);
+  });
+
+  test("logs and continues on queryNotes throw; does not abort the whole fetch", async () => {
+    const errors: unknown[] = [];
+    const logger = { error: (...args: unknown[]) => errors.push(args) };
+    const store: Store = {
+      queryNotes: async ({ tags }) => {
+        if (tags?.[0] === "broken") throw new Error("boom");
+        return [mkNote({ id: "ok", path: "Ok.md", tags: ["ok"] })];
+      },
+    } as unknown as Store;
+
+    const payload = await fetchContextEntries(
+      store,
+      [{ tag: "broken" }, { tag: "ok" }],
+      logger,
+    );
+
+    expect(errors.length).toBe(1);
+    expect(payload.entries.map((e) => e.name)).toEqual(["Ok"]);
+  });
+});
+
+describe("appendContextPart", () => {
+  test("appends a JSON blob when entries exist", () => {
+    const form = new FormData();
+    appendContextPart(form, { entries: [{ name: "x" }] });
+    const part = form.get("context");
+    expect(part).toBeInstanceOf(Blob);
+  });
+
+  test("no-ops on zero-entries payload", () => {
+    const form = new FormData();
+    appendContextPart(form, { entries: [] });
+    expect(form.get("context")).toBeNull();
+  });
+});

package/src/context.ts

@@ -0,0 +1,115 @@
+/**
+ * Shared "vault-provided context" helpers for outbound webhook/worker calls.
+ *
+ * Triggers (`include_context`) and the transcription worker (`transcription.context`
+ * in vault.yaml) both send vault context to an external caller so the caller
+ * does not need to reach back into vault to fetch person/project/etc. notes
+ * on its own. The shape is caller-agnostic — the receiver just gets a JSON
+ * blob of `{ entries: [...] }` — so this module doesn't know anything about
+ * scribe specifically.
+ *
+ * ## Predicate shape
+ *
+ *   include_context:
+ *     - tag: person
+ *       exclude_tag: archived
+ *       include_metadata: [summary, aliases]
+ *
+ * Each predicate is a query (scoped by `tag`, optionally excluding `exclude_tag`)
+ * plus a whitelist of metadata fields to surface on the resulting entries.
+ * Fields not in `include_metadata` are dropped. `name` is always included and
+ * is the note's path basename (or id, if no path).
+ *
+ * ## Output
+ *
+ *   {"entries": [{"name": "Aaron", "aliases": ["A"], "summary": "..."}, ...]}
+ */
+
+import type { Store } from "../core/src/types.ts";
+
+export interface ContextPredicate {
+  /** Tag the note must carry. Required — a predicate with no tag is a no-op. */
+  tag: string;
+  /** If set, notes with this tag are excluded. */
+  exclude_tag?: string;
+  /** Metadata keys to pass through on each entry. Unknown keys are ignored. */
+  include_metadata?: string[];
+}
+
+export interface ContextEntry {
+  /** Note path basename, or note id if no path. */
+  name: string;
+  /** Whitelisted metadata fields from the predicate. */
+  [key: string]: unknown;
+}
+
+export interface ContextPayload {
+  entries: ContextEntry[];
+}
+
+/**
+ * Query the vault for notes matching each predicate, project to the whitelisted
+ * metadata fields, and return a combined payload. Predicates are run in order;
+ * duplicate notes (same id across predicates) are included once by first match.
+ *
+ * Errors on a single predicate are logged and skipped — a malformed predicate
+ * should not take down a whole trigger or worker cycle.
+ */
+export async function fetchContextEntries(
+  store: Store,
+  predicates: ContextPredicate[],
+  logger: { error: (...args: unknown[]) => void } = console,
+): Promise<ContextPayload> {
+  const seen = new Set<string>();
+  const entries: ContextEntry[] = [];
+
+  for (const pred of predicates) {
+    if (!pred.tag) continue;
+    let notes;
+    try {
+      notes = await store.queryNotes({
+        tags: [pred.tag],
+        excludeTags: pred.exclude_tag ? [pred.exclude_tag] : undefined,
+      });
+    } catch (err) {
+      logger.error(`[context] query failed for tag="${pred.tag}":`, err);
+      continue;
+    }
+
+    for (const note of notes) {
+      if (seen.has(note.id)) continue;
+      seen.add(note.id);
+
+      const entry: ContextEntry = { name: nameForNote(note.path, note.id) };
+      const meta = (note.metadata as Record<string, unknown> | undefined) ?? {};
+      for (const key of pred.include_metadata ?? []) {
+        if (key in meta) entry[key] = meta[key];
+      }
+      entries.push(entry);
+    }
+  }
+
+  return { entries };
+}
+
+function nameForNote(path: string | undefined, id: string): string {
+  if (!path) return id;
+  const base = path.split("/").pop() ?? path;
+  // Drop extension if present — same rule a UI would apply for display.
+  const dot = base.lastIndexOf(".");
+  return dot > 0 ? base.slice(0, dot) : base;
+}
+
+/**
+ * Append a `context` multipart part to the given FormData. Does nothing if
+ * the payload has no entries (avoids a zero-entries part that the receiver
+ * would have to special-case).
+ */
+export function appendContextPart(form: FormData, payload: ContextPayload): void {
+  if (!payload.entries.length) return;
+  form.append(
+    "context",
+    new Blob([JSON.stringify(payload)], { type: "application/json" }),
+    "context.json",
+  );
+}

package/src/daemon.ts

@@ -5,25 +5,26 @@
  * Rationale: both platforms historically hardcoded the absolute path to
  * `src/server.ts` into their respective service/wrapper files at init
  * time. When the repo moved, the service kept respawning bun on a missing
- * file and crash-looped silently into `~/.parachute/vault.err`.
+ * file and crash-looped silently into `~/.parachute/vault/vault.err`.
  *
- * The fix: a small bash wrapper (`~/.parachute/start.sh`) and a pointer
- * file (`~/.parachute/server-path`) that the wrapper reads at every boot.
- * Moving the repo now only requires re-running `parachute vault init` —
- * no plist/unit re-registration needed. Callers can override the path for
- * a single boot via `PARACHUTE_VAULT_SERVER_PATH` in `~/.parachute/.env`.
+ * The fix: a small bash wrapper (`~/.parachute/vault/start.sh`) and a
+ * pointer file (`~/.parachute/vault/server-path`) that the wrapper reads
+ * at every boot. Moving the repo now only requires re-running
+ * `parachute-vault init` — no plist/unit re-registration needed. Callers
+ * can override the path for a single boot via `PARACHUTE_VAULT_SERVER_PATH`
+ * in `~/.parachute/vault/.env`.
  */
 
 import { homedir } from "os";
 import { join, resolve, dirname } from "path";
 import { writeFile, unlink } from "fs/promises";
 import { existsSync, readFileSync } from "fs";
-import { CONFIG_DIR, ENV_PATH } from "./config.ts";
+import { VAULT_HOME, ENV_PATH } from "./config.ts";
 
 /** Start-up script sourced by launchd and systemd alike. */
-export const WRAPPER_PATH = join(CONFIG_DIR, "start.sh");
+export const WRAPPER_PATH = join(VAULT_HOME, "start.sh");
 /** Pointer file. Contents: absolute path to `server.ts`, one line. */
-export const SERVER_PATH_FILE = join(CONFIG_DIR, "server-path");
+export const SERVER_PATH_FILE = join(VAULT_HOME, "server-path");
 
 /**
  * Build the start.sh contents. Pure string builder — easy to assert on.
@@ -31,7 +32,7 @@ export const SERVER_PATH_FILE = join(CONFIG_DIR, "server-path");
  * The generated script:
  *   1. Sources the user's login shell profiles to pick up PATH (needed
  *      when the daemon shells out to tools like ffmpeg, parakeet-mlx).
- *   2. Sources ~/.parachute/.env.
+ *   2. Sources ~/.parachute/vault/.env.
  *   3. Resolves the server path: env override first, then pointer file.
  *   4. Fails loudly with an actionable message if the path is missing or
  *      the target file doesn't exist — instead of silently respawning
@@ -46,10 +47,10 @@ export function generateWrapper(opts: {
   const envPath = opts.envPath ?? ENV_PATH;
   const pointer = opts.serverPathFile ?? SERVER_PATH_FILE;
   return `#!/bin/bash
-# Auto-generated by \`parachute vault init\`. Do not edit by hand — edits
+# Auto-generated by \`parachute-vault init\`. Do not edit by hand — edits
 # are clobbered on the next init. To override the server path for a
-# single boot, set PARACHUTE_VAULT_SERVER_PATH in ~/.parachute/.env.
-# To point at a different repo permanently, re-run \`parachute vault init\`
+# single boot, set PARACHUTE_VAULT_SERVER_PATH in ~/.parachute/vault/.env.
+# To point at a different repo permanently, re-run \`parachute-vault init\`
 # from that repo.
 
 set -u
@@ -61,7 +62,7 @@ set -u
 # empty because of the 2>/dev/null below — launchd would respawn silently
 # until it gave up. Keep the stderr redirect so expected "command not found"
 # noise from incomplete setups doesn't fill vault.err; to debug silent
-# wrapper failures, run \`bash -x ~/.parachute/start.sh\` by hand.
+# wrapper failures, run \`bash -x ~/.parachute/vault/start.sh\` by hand.
 set +u
 [ -f "$HOME/.zprofile" ] && source "$HOME/.zprofile" 2>/dev/null
 [ -f "$HOME/.zshrc" ] && source "$HOME/.zshrc" 2>/dev/null
@@ -81,13 +82,13 @@ fi
 
 if [ -z "$SERVER_PATH" ]; then
   echo "parachute-vault: server path not configured (no ${pointer} and PARACHUTE_VAULT_SERVER_PATH is unset)." >&2
-  echo "parachute-vault: run \\\`parachute vault init\\\` to configure it." >&2
+  echo "parachute-vault: run \\\`parachute-vault init\\\` to configure it." >&2
   exit 1
 fi
 
 if [ ! -f "$SERVER_PATH" ]; then
   echo "parachute-vault: server.ts not found at $SERVER_PATH" >&2
-  echo "parachute-vault: the repo may have moved. Run \\\`parachute vault init\\\` from the current repo location." >&2
+  echo "parachute-vault: the repo may have moved. Run \\\`parachute-vault init\\\` from the current repo location." >&2
   exit 1
 fi
 

package/src/doctor.test.ts

@@ -1,5 +1,5 @@
 /**
- * Integration tests for `parachute vault doctor` and `parachute vault url`.
+ * Integration tests for `parachute-vault doctor` and `parachute-vault url`.
  *
  * We spawn the CLI as a subprocess with `PARACHUTE_HOME` pointed at a
  * fresh tempdir — so each test exercises the real code path (config +
@@ -74,7 +74,7 @@ describe("vault doctor", () => {
     expect(res.exitCode).toBe(1);
     expect(res.stdout).toMatch(/server-path pointer/);
     expect(res.stdout).toMatch(/missing/);
-    expect(res.stdout).toMatch(/parachute vault init/);
+    expect(res.stdout).toMatch(/parachute-vault init/);
   });
 
   test("fails when the pointer targets a non-existent file (moved repo)", () => {
@@ -172,7 +172,7 @@ describe("vault doctor — extended checks", () => {
     // Use a non-default port to prove we're actually reading config.yaml,
     // not just matching against DEFAULT_PORT.
     writeFileSync(join(dir, "config.yaml"), "port: 4321\n");
-    writeClaudeJson(dir, "http://127.0.0.1:4321/vaults/default/mcp");
+    writeClaudeJson(dir, "http://127.0.0.1:4321/vault/default/mcp");
     const res = runCli(["doctor"], dir, { HOME: dir });
     expect(res.stdout).toMatch(/✓ MCP entry in ~\/\.claude\.json/);
     expect(res.stdout).toMatch(/✓ MCP URL port matches vault\s+\(port 4321\)/);
@@ -184,7 +184,7 @@ describe("vault doctor — extended checks", () => {
 
   test("warns when MCP URL port does not match the vault's configured port", () => {
     writeFileSync(join(dir, "config.yaml"), "port: 4321\n");
-    writeClaudeJson(dir, "http://127.0.0.1:9999/vaults/default/mcp");
+    writeClaudeJson(dir, "http://127.0.0.1:9999/vault/default/mcp");
     const res = runCli(["doctor"], dir, { HOME: dir });
     expect(res.stdout).toMatch(/✓ MCP entry in ~\/\.claude\.json/);
     expect(res.stdout).toMatch(/! MCP URL port matches vault/);
@@ -304,9 +304,11 @@ describe("vault uninstall", () => {
   });
 
   test("answering 'no' at the prompt does not touch daemon/filesystem", async () => {
-    // Set up a fake install: wrapper + pointer in the temp PARACHUTE_HOME.
-    const wrapper = join(dir, "start.sh");
-    const pointer = join(dir, "server-path");
+    // Set up a fake install: wrapper + pointer in the vault/ subdir of the
+    // temp PARACHUTE_HOME (the post-0.3 layout).
+    mkdirSync(join(dir, "vault"), { recursive: true });
+    const wrapper = join(dir, "vault", "start.sh");
+    const pointer = join(dir, "vault", "server-path");
     writeFileSync(wrapper, "#!/bin/bash\n");
     writeFileSync(pointer, "/tmp/fake.ts\n");
 

package/src/launchd.test.ts

@@ -40,7 +40,7 @@ describe("generateWrapper", () => {
     expect(wrapper).toContain('if [ -z "$SERVER_PATH" ]; then');
     expect(wrapper).toContain("exit 1");
     // Actionable message — user needs to know what to run.
-    expect(wrapper).toMatch(/parachute vault init/);
+    expect(wrapper).toMatch(/parachute-vault init/);
   });
 
   test("fails loudly when pointer target no longer exists (moved repo)", () => {

package/src/launchd.ts

@@ -1,16 +1,16 @@
 /**
  * macOS launchd agent management for the vault daemon.
  *
- * The plist runs `~/.parachute/start.sh` (the shared wrapper from
+ * The plist runs `~/.parachute/vault/start.sh` (the shared wrapper from
  * daemon.ts). The wrapper reads the pointer file at every boot, so
- * moving the repo only requires re-running `parachute vault init`.
+ * moving the repo only requires re-running `parachute-vault init`.
  */
 
 import { homedir } from "os";
 import { join } from "path";
 import { writeFile, unlink } from "fs/promises";
 import { $ } from "bun";
-import { CONFIG_DIR, LOG_PATH, ERR_PATH } from "./config.ts";
+import { VAULT_HOME, LOG_PATH, ERR_PATH } from "./config.ts";
 import { WRAPPER_PATH, writeDaemonWrapper } from "./daemon.ts";
 
 const LABEL = "computer.parachute.vault";
@@ -37,7 +37,7 @@ export function generatePlist(): string {
   <key>StandardErrorPath</key>
   <string>${ERR_PATH}</string>
   <key>WorkingDirectory</key>
-  <string>${CONFIG_DIR}</string>
+  <string>${VAULT_HOME}</string>
 </dict>
 </plist>`;
 }
@@ -45,7 +45,7 @@ export function generatePlist(): string {
 /**
  * Install or re-install the launchd agent. Idempotent: if the agent is
  * already loaded, it's unloaded first so the new wrapper + pointer take
- * effect. This is what makes `parachute vault init` safe to re-run after
+ * effect. This is what makes `parachute-vault init` safe to re-run after
  * a folder move — the incident that motivated this PR.
  */
 export async function installAgent(): Promise<{ serverPath: string }> {
@@ -86,7 +86,7 @@ export async function uninstallAgent(): Promise<void> {
   // Linux uninstall path. Callers that want a fully-clean teardown must
   // also call `removeDaemonWrapper()` — the CLI's `uninstall` command in
   // PR 3 wires that up. Leaving them here programmatically would strand
-  // orphaned files in `~/.parachute/`.
+  // orphaned files in `~/.parachute/vault/`.
 }
 
 export async function isAgentLoaded(): Promise<boolean> {

package/src/mcp-http.ts

@@ -10,12 +10,9 @@
  * root cause of vault#56. The `initialize` method still works if a
  * client sends it (the Server class handles it natively).
  *
- * Two modes:
- *   /mcp              — unified, all vaults via `vault` param + list-vaults
- *   /vaults/{name}/mcp — scoped to one vault, no vault param
- *
- * Vault description is sent as the MCP server instruction.
- * Read-only keys see fewer tools.
+ * Every MCP session is scoped to one vault via `/vault/{name}/mcp`.
+ * The vault's description is sent as the MCP server instruction, and
+ * read-only keys see a filtered tool list.
  */
 
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
@@ -23,22 +20,45 @@ import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/
 import {
   ListToolsRequestSchema,
   CallToolRequestSchema,
+  ErrorCode,
+  McpError,
 } from "@modelcontextprotocol/sdk/types.js";
-import { generateUnifiedMcpTools, generateScopedMcpTools, getServerInstruction } from "./mcp-tools.ts";
-import { isToolAllowed } from "./auth.ts";
+import { generateScopedMcpTools, getServerInstruction } from "./mcp-tools.ts";
+import { requireScope } from "./auth.ts";
 import type { AuthResult } from "./auth.ts";
 import type { McpToolDef } from "../core/src/mcp.ts";
+import { SCOPE_READ, SCOPE_WRITE } from "./scopes.ts";
+
+/**
+ * Required scope for each MCP tool. Tools that mutate note/tag state require
+ * `vault:write`; pure query tools need `vault:read`. `vault-info` is listed as
+ * read because read-only callers can fetch stats — the description-update
+ * branch inside vault-info performs its own secondary `vault:write` check
+ * (see `overrideVaultInfo` in mcp-tools.ts). Do not assume the outer gate
+ * alone protects the inner branch.
+ */
+const TOOL_REQUIRED_SCOPE: Record<string, string> = {
+  "query-notes": SCOPE_READ,
+  "list-tags": SCOPE_READ,
+  "find-path": SCOPE_READ,
+  "vault-info": SCOPE_READ,
+  "create-note": SCOPE_WRITE,
+  "update-note": SCOPE_WRITE,
+  "delete-note": SCOPE_WRITE,
+  "update-tag": SCOPE_WRITE,
+  "delete-tag": SCOPE_WRITE,
+};
 
-/** Handle unified MCP at /mcp (all vaults). */
-export async function handleUnifiedMcp(req: Request, auth: AuthResult): Promise<Response> {
-  const instruction = getServerInstruction();
-  return handleMcp(req, () => generateUnifiedMcpTools(), "parachute-vault", auth, instruction);
+function requiredScopeForTool(toolName: string): string {
+  // Default-deny: unknown tools require write. Keeps accidental reads of
+  // a not-yet-mapped mutation tool from slipping past.
+  return TOOL_REQUIRED_SCOPE[toolName] ?? SCOPE_WRITE;
 }
 
-/** Handle scoped MCP at /vaults/{name}/mcp (single vault). */
+/** Handle scoped MCP at /vault/{name}/mcp (single vault). */
 export async function handleScopedMcp(req: Request, vaultName: string, auth: AuthResult): Promise<Response> {
   const instruction = getServerInstruction(vaultName);
-  return handleMcp(req, () => generateScopedMcpTools(vaultName), `parachute-vault/${vaultName}`, auth, instruction);
+  return handleMcp(req, () => generateScopedMcpTools(vaultName, auth), `parachute-vault/${vaultName}`, auth, instruction);
 }
 
 async function handleMcp(
@@ -48,7 +68,6 @@ async function handleMcp(
   auth: AuthResult,
   instruction: string,
 ): Promise<Response> {
-  const { permission } = auth;
   const transport = new WebStandardStreamableHTTPServerTransport({
     sessionIdGenerator: undefined,
     enableJsonResponse: true,
@@ -64,10 +83,13 @@ async function handleMcp(
 
   const mcpTools = getTools();
 
-  // For read-only keys, only list readable tools
-  const visibleTools = permission === "read"
-    ? mcpTools.filter((t) => isToolAllowed(t.name, "read"))
-    : mcpTools;
+  // Filter the advertised tool list to what the caller's scopes actually
+  // permit. Callers without `vault:write` don't see mutation tools at all —
+  // matches the prior behavior of the read/full permission model but is now
+  // driven by scope inheritance.
+  const visibleTools = mcpTools.filter((t) =>
+    requireScope(auth, requiredScopeForTool(t.name)),
+  );
 
   server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: visibleTools.map((t) => ({
@@ -80,9 +102,13 @@ async function handleMcp(
   server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;
 
-    if (!isToolAllowed(name, permission)) {
+    const neededScope = requiredScopeForTool(name);
+    if (!requireScope(auth, neededScope)) {
       return {
-        content: [{ type: "text" as const, text: `Forbidden: insufficient permissions to call ${name}` }],
+        content: [{
+          type: "text" as const,
+          text: `Forbidden: tool '${name}' requires the '${neededScope}' scope. Granted scopes: ${auth.scopes.join(" ") || "(none)"}.`,
+        }],
         isError: true,
       };
     }
@@ -100,7 +126,35 @@ async function handleMcp(
         content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
       };
     } catch (err) {
+      // Domain errors from the core tools (conflict, missing precondition) get
+      // surfaced as JSON-RPC errors with a structured `data` field so an
+      // agent can key off `data.error_type` and the concurrency tokens.
+      // Everything else falls through to an in-band tool error with
+      // `isError: true` — legible but unstructured.
       const message = err instanceof Error ? err.message : "Unknown error";
+      const e = err as {
+        code?: string;
+        note_id?: string;
+        note_path?: string | null;
+        current_updated_at?: string | null;
+        expected_updated_at?: string;
+      };
+      if (e?.code === "CONFLICT") {
+        throw new McpError(ErrorCode.InvalidRequest, message, {
+          error_type: "conflict",
+          current_updated_at: e.current_updated_at ?? null,
+          your_updated_at: e.expected_updated_at,
+          path: e.note_path ?? null,
+          note_id: e.note_id,
+        });
+      }
+      if (e?.code === "PRECONDITION_REQUIRED") {
+        throw new McpError(ErrorCode.InvalidParams, message, {
+          error_type: "precondition_required",
+          note_id: e.note_id,
+          path: e.note_path ?? null,
+        });
+      }
       return {
         content: [{ type: "text" as const, text: `Error: ${message}` }],
         isError: true,