get_vault_guide

Instructions

Implementation Reference

• src/mcp_server/tools.py:271-286 (handler)

  Core handler that reads CLAUDE.md from the vault and combines it with a static Obsidian primer markdown file to produce the vault guide.

  @_tracked("get_vault_guide", [])
  async def get_vault_guide_impl() -> str:
      """Return the Obsidian primer plus any vault-specific conventions from CLAUDE.md."""
      uid = current_user_id.get()
      try:
          note = read_file("CLAUDE.md", user_id=uid)
          vault_section = (
              "# Vault-Specific Conventions\n"
              "\n"
              f"{note['content']}"
          )
      except FileNotFoundError:
          vault_section = _NO_CLAUDE_MD_MESSAGE
      except ValueError as e:
          vault_section = f"# Vault-Specific Conventions\n\n{e}"
      return f"{_VAULT_GUIDE_PRIMER}\n\n---\n\n{vault_section}"

• src/mcp_server/tools.py:23-25 (schema)

  Loads the static Obsidian syntax primer from a markdown file at module load time.

  _VAULT_GUIDE_PRIMER = (Path(__file__).parent / "vault_guide_primer.md").read_text(
      encoding="utf-8"
  )

• src/mcp_server/tools.py:27-43 (schema)

  Fallback message shown when CLAUDE.md does not exist in the vault.

  _NO_CLAUDE_MD_MESSAGE = (
      "# Vault-Specific Conventions\n"
      "\n"
      "No `CLAUDE.md` found at the vault root. To teach the agent about your\n"
      "folder structure, file-naming conventions, tag taxonomy, required\n"
      "frontmatter fields, or task-management syntax, create a `CLAUDE.md`\n"
      "file at the root of your vault. The agent will pick it up automatically\n"
      "on the next call.\n"
      "\n"
      "Suggested sections:\n"
      "\n"
      "- **Folder structure** — what lives where, and where new notes belong.\n"
      "- **Naming conventions** — how filenames are formatted.\n"
      "- **Frontmatter** — required and conventional YAML fields.\n"
      "- **Tag taxonomy** — top-level tags and their meaning.\n"
      "- **Task syntax** — any GTD/Dataview/checklist conventions in use.\n"
  )

• src/mcp_server/server.py:229-241 (registration)

  MCP tool registration (with @mcp.tool() decorator) that exposes `get_vault_guide` as a tool and delegates to the implementation.

  @mcp.tool()
  async def get_vault_guide() -> str:
      """Returns a two-part guide for working with this Obsidian vault:
  
      1. **Obsidian primer** — generic syntax (wikilinks, embeds, block refs,
         heading refs, tags, frontmatter, callouts, comments, highlights,
         math, mermaid, footnotes, tasks, plugin literals).
      2. **Vault-specific conventions** — folder structure, naming rules,
         frontmatter requirements, and tag taxonomy as configured by the
         vault owner in `CLAUDE.md`. If `CLAUDE.md` is absent, the response
         includes instructions for creating one.
      """
      return await get_vault_guide_impl()

• src/mcp_server/server.py:5-20 (helper)

  Import of get_vault_guide_impl from tools.py into server.py for registration.

  from src.mcp_server.tools import (
      create_note_impl,
      delete_note_impl,
      edit_note_impl,
      find_orphans_impl,
      find_related_impl,
      get_backlinks_impl,
      get_links_impl,
      get_neighborhood_impl,
      get_recent_impl,
      get_tags_impl,
      get_vault_guide_impl,
      list_notes_impl,
      move_note_impl,
      read_note_impl,
      search_notes_impl,