obsidian_read_note

Instructions

Implementation Reference

• src/tools.ts:120-153 (registration)

  Registration of the obsidian_read_note tool with its schema and handler in the registerObsidianTools function.

  tool(
    "obsidian_read_note",
    "Read a note as raw content, full structured content, a document map, or one section.",
    {
      vault: vaultArg,
      path: pathArg,
      format: z.enum(["content", "full", "document-map", "section"]).optional().default("full"),
      sectionType: z.enum(["heading", "block", "frontmatter"]).optional(),
      section: z.string().optional(),
      includeLinks: z.boolean().optional().default(true),
    },
    async (args) => {
      const read = await vaults.readText(args.path, args.vault);
      if (args.format === "content") return { path: read.path, content: read.text };
      if (args.format === "document-map") return documentMap(read.path, read.text);
      if (args.format === "section") {
        if (!args.sectionType || !args.section) throw new Error("sectionType and section are required for format=section");
        const selector = selectorFrom(args.sectionType, args.section);
        const range = findSectionRange(read.text, selector);
        if (!range) return { path: read.path, found: false };
        return { path: read.path, found: true, content: read.text.slice(range.start, range.end) };
      }
      const parsed = parseFrontmatter(read.text);
      return {
        path: read.path,
        content: read.text,
        frontmatter: parsed.data,
        tags: extractAllTags(read.text),
        stat: { size: read.stat.size, mtime: read.stat.mtime.toISOString(), ctime: read.stat.ctime.toISOString() },
        links: args.includeLinks ? { wiki: extractWikiLinks(read.text), markdown: extractMarkdownLinks(read.text) } : undefined,
      };
    },
    { readOnlyHint: true },
  );

• src/tools.ts:131-151 (handler)

  Handler function for the obsidian_read_note tool. Reads a note from the vault and returns content, full structured data, a document map, or a section based on the format parameter. Uses vaults.readText (from src/vault.ts line 89) to read the file, parseFrontmatter (from src/frontmatter.ts line 12) to parse YAML frontmatter, and helper functions like documentMap and selectorFrom for formatting.

  async (args) => {
    const read = await vaults.readText(args.path, args.vault);
    if (args.format === "content") return { path: read.path, content: read.text };
    if (args.format === "document-map") return documentMap(read.path, read.text);
    if (args.format === "section") {
      if (!args.sectionType || !args.section) throw new Error("sectionType and section are required for format=section");
      const selector = selectorFrom(args.sectionType, args.section);
      const range = findSectionRange(read.text, selector);
      if (!range) return { path: read.path, found: false };
      return { path: read.path, found: true, content: read.text.slice(range.start, range.end) };
    }
    const parsed = parseFrontmatter(read.text);
    return {
      path: read.path,
      content: read.text,
      frontmatter: parsed.data,
      tags: extractAllTags(read.text),
      stat: { size: read.stat.size, mtime: read.stat.mtime.toISOString(), ctime: read.stat.ctime.toISOString() },
      links: args.includeLinks ? { wiki: extractWikiLinks(read.text), markdown: extractMarkdownLinks(read.text) } : undefined,
    };
  },

• src/tools.ts:123-130 (schema)

  Zod schema for the obsidian_read_note tool defining input parameters: vault (optional), path (required), format (optional enum with default 'full'), sectionType (optional enum), section (optional string), includeLinks (optional boolean default true).

  {
    vault: vaultArg,
    path: pathArg,
    format: z.enum(["content", "full", "document-map", "section"]).optional().default("full"),
    sectionType: z.enum(["heading", "block", "frontmatter"]).optional(),
    section: z.string().optional(),
    includeLinks: z.boolean().optional().default(true),
  },

• src/tools.ts:1348-1358 (helper)

  Helper function used by obsidian_read_note when format='document-map'. Returns a structural map of the note including frontmatter keys, tags, headings, block references, and links.

  function documentMap(notePath: string, markdown: string): unknown {
    const parsed = parseFrontmatter(markdown);
    return {
      path: notePath,
      frontmatterKeys: Object.keys(parsed.data),
      tags: extractAllTags(markdown),
      headings: extractHeadings(markdown),
      blocks: extractBlockRefs(markdown),
      links: { wiki: extractWikiLinks(markdown), markdown: extractMarkdownLinks(markdown) },
    };
  }

• src/tools.ts:1360-1364 (helper)

  Helper function used by obsidian_read_note when format='section'. Converts section type and value into a SectionSelector object for findSectionRange.

  function selectorFrom(type: "heading" | "block" | "frontmatter", value: string): SectionSelector {
    if (type === "heading") return { type, heading: value };
    if (type === "block") return { type, block: value.replace(/^\^/, "") };
    return { type, key: value };
  }