Append to Note

Instructions

Implementation Reference

• src/lib/vault.ts:367-378 (handler)

  Core implementation of appendToNote: resolves the vault path safely under lock, reads existing content, adds a newline separator if needed, and atomically writes the combined content back.

  export async function appendToNote(
    vaultPath: string,
    relativePath: string,
    content: string,
  ): Promise<void> {
    const fullPath = await resolveVaultPathSafe(vaultPath, relativePath);
    await withFileLock(fullPath, async () => {
      const existing = await fs.readFile(fullPath, "utf-8");
      const separator = existing.endsWith("\n") ? "" : "\n";
      await atomicWriteFile(fullPath, existing + separator + content);
    });
  }

• src/tools/write.ts:101-134 (registration)

  Registration of the 'append_to_note' MCP tool on the server with input schema (path, content). The handler calls appendToNote from vault.ts.

  // 2. append_to_note
  server.registerTool(
    "append_to_note",
    {
      title: "Append to Note",
      description:
        "Append text to the end of an existing note without altering prior content. By default, inserts a leading newline if the file does not already end in one, so appended content starts on its own line. Use for log entries, running lists, or adding new sections. Fails if the note does not exist — use create_note to make a new note first.",
      annotations: {
        readOnlyHint: false,
        destructiveHint: false,
        idempotentHint: false,
        openWorldHint: false,
      },
      inputSchema: {
        path: z
          .string()
          .min(1)
          .describe("Relative path from vault root to the target note (e.g., 'journal/2026-04-15.md'). Extension optional."),
        content: z
          .string()
          .describe("Markdown text to append to the end of the note. A leading newline is auto-inserted when the file does not already end in one."),
      },
    },
    async ({ path: notePath, content }) => {
      try {
        const resolvedPath = ensureMdExtension(notePath);
        await appendToNote(vaultPath, resolvedPath, content);
        return textResult(`Appended content to '${resolvedPath}'.`);
      } catch (err) {
        log.error("append_to_note failed", { tool: "append_to_note", err: err as Error });
        return errorResult(`Error appending to note: ${sanitizeError(err)}`);
      }
    },
  );

• src/tools/write.ts:114-122 (schema)

  Input schema for append_to_note: path (required string with .md auto-append) and content (required string to append).

  inputSchema: {
    path: z
      .string()
      .min(1)
      .describe("Relative path from vault root to the target note (e.g., 'journal/2026-04-15.md'). Extension optional."),
    content: z
      .string()
      .describe("Markdown text to append to the end of the note. A leading newline is auto-inserted when the file does not already end in one."),
  },

• src/lib/vault.ts:113-120 (helper)

  withFileLock: mutual exclusion helper that ensures serialized file access per path.

  export async function withFileLock<T>(fullPath: string, fn: () => Promise<T>): Promise<T> {
    const key = lockKey(fullPath);
    const prev = fileLocks.get(key) ?? Promise.resolve();
    // Swallow the prior holder's rejection (so the chain continues) but still
    // run `fn` exactly once via `.then()` — the previous form passed `fn` as
    // both fulfillment and rejection handler, which obscured intent.
    const next = prev.catch(() => undefined).then(fn);
    fileLocks.set(key, next);

• src/lib/vault.ts:96-111 (helper)

  atomicWriteFile: writes content to a temp file then atomically renames it, ensuring no partial writes.

  export async function atomicWriteFile(fullPath: string, content: string): Promise<void> {
    const dir = path.dirname(fullPath);
    const base = path.basename(fullPath);
    const tmp = path.join(dir, `.${base}.${process.pid}.${randomBytes(8).toString("hex")}.tmp`);
    try {
      // `wx` on the temp file guards against the astronomically unlikely case
      // of a collision with a leftover tmp from a crashed run.
      await fs.writeFile(tmp, content, { encoding: "utf-8", flag: "wx" });
      await renameWithRetry(tmp, fullPath);
    } catch (err) {
      // Best-effort cleanup: the rename failed (or writeFile did), so the tmp
      // is still on disk. Ignore ENOENT in case writeFile never created it.
      try { await fs.unlink(tmp); } catch { /* ignore */ }
      throw err;
    }
  }