List Sections

Instructions

Implementation Reference

• src/tools/sections.ts:159-174 (handler)

  The async handler function for the 'list_sections' tool. It reads the note content via readNote, parses headings using parseHeadings, and returns a formatted tree of heading paths with indentation reflecting depth.

  async ({ path: notePath }) => {
    try {
      const { readNote } = await import("../lib/vault.js");
      const content = await readNote(vaultPath, notePath);
      const headings = parseHeadings(content);
      if (headings.length === 0) return textResult(`No headings in ${notePath}`);
      const lines = [`${headings.length} heading(s) in ${notePath}:`, ""];
      for (const h of headings) {
        lines.push(`${"  ".repeat(h.level - 1)}${"#".repeat(h.level)} ${h.text}`);
      }
      return textResult(lines.join("\n"));
    } catch (err) {
      log.error("list_sections failed", { tool: "list_sections", err: err as Error });
      return errorResult(`Error listing sections: ${sanitizeError(err)}`);
    }
  },

• src/tools/sections.ts:146-158 (schema)

  The input schema definition for 'list_sections'. It defines a single required string parameter 'path' (vault-relative path to the note). Annotations declare it as read-only and idempotent.

  {
    title: "List Sections",
    description:
      "List all headings in a note as a tree of paths (with depth). Useful for discovering valid `section` arguments before calling get_note, update_section, or insert_at_section.",
    annotations: {
      readOnlyHint: true,
      idempotentHint: true,
      openWorldHint: false,
    },
    inputSchema: {
      path: z.string().min(1).describe("Vault-relative path to the note."),
    },
  },

• src/tools/sections.ts:144-175 (registration)

  Registration of the 'list_sections' tool via server.registerTool with the name 'list_sections', schema, and handler within registerSectionTools.

  server.registerTool(
    "list_sections",
    {
      title: "List Sections",
      description:
        "List all headings in a note as a tree of paths (with depth). Useful for discovering valid `section` arguments before calling get_note, update_section, or insert_at_section.",
      annotations: {
        readOnlyHint: true,
        idempotentHint: true,
        openWorldHint: false,
      },
      inputSchema: {
        path: z.string().min(1).describe("Vault-relative path to the note."),
      },
    },
    async ({ path: notePath }) => {
      try {
        const { readNote } = await import("../lib/vault.js");
        const content = await readNote(vaultPath, notePath);
        const headings = parseHeadings(content);
        if (headings.length === 0) return textResult(`No headings in ${notePath}`);
        const lines = [`${headings.length} heading(s) in ${notePath}:`, ""];
        for (const h of headings) {
          lines.push(`${"  ".repeat(h.level - 1)}${"#".repeat(h.level)} ${h.text}`);
        }
        return textResult(lines.join("\n"));
      } catch (err) {
        log.error("list_sections failed", { tool: "list_sections", err: err as Error });
        return errorResult(`Error listing sections: ${sanitizeError(err)}`);
      }
    },
  );

• src/lib/sections.ts:106-134 (handler)

  The parseHeadings helper function that parses all ATX headings from markdown content, skipping fenced code blocks and frontmatter. Returns an array of Heading objects with level, text, and byte offsets.

  export function parseHeadings(content: string): Heading[] {
    const out: Heading[] = [];
    const start = bodyOffset(content);
    const fence = newFenceState();
    let cursor = start;
    // Walk line-by-line preserving byte offsets.
    while (cursor < content.length) {
      const nl = content.indexOf("\n", cursor);
      const lineEnd = nl === -1 ? content.length : nl;
      const line = content.slice(cursor, lineEnd);
      const lineEndExclusive = nl === -1 ? content.length : nl + 1;
  
      const isFenceLine = updateFence(fence, line);
      if (!isFenceLine && !fence.insideFence) {
        const m = line.match(ATX_HEADING_RE);
        if (m) {
          out.push({
            level: m[1].length,
            text: m[2].trim(),
            lineStart: cursor,
            lineEnd: lineEndExclusive,
          });
        }
      }
      cursor = lineEndExclusive;
      if (nl === -1) break;
    }
    return out;
  }

• src/lib/vault.ts:340-353 (helper)

  The readNote helper function that reads a note's content from disk given a vault path and relative path, used by the list_sections handler to load the file.

  export async function readNote(
    vaultPath: string,
    relativePath: string,
  ): Promise<string> {
    const fullPath = await resolveVaultPathSafe(vaultPath, relativePath);
    try {
      return await fs.readFile(fullPath, "utf-8");
    } catch (err) {
      if ((err as NodeJS.ErrnoException).code === "ENOENT") {
        throw new Error(`Note not found: ${relativePath}`);
      }
      throw err;
    }
  }