mcp-obsidian-cli 1.0.0 → 1.1.0

package/README.md

@@ -69,6 +69,23 @@ The generic `obsidian` tool means the MCP server never falls behind the CLI —
 | `OBSIDIAN_VAULT` | _(none)_ | Target vault by name |
 | `OBSIDIAN_CLI_PATH` | `obsidian` | Path to CLI binary |
 | `OBSIDIAN_TIMEOUT_MS` | `15000` | Command timeout |
+| `XDG_CONFIG_HOME` | `~/.config` | Base path for config file |
+
+## Config file
+
+The server can read settings from a YAML config file:
+
+- Default: `~/.config/mcp-obsidian-cli/config.yaml`
+- With `XDG_CONFIG_HOME`: `$XDG_CONFIG_HOME/mcp-obsidian-cli/config.yaml`
+
+Config file format:
+```yaml
+vault: "my-vault"
+cliPath: "obsidian"
+timeoutMs: 15000
+```
+
+Config precedence: env vars > config file > hardcoded defaults
 
 ## Compared to alternatives
 

package/package.json

@@ -1,12 +1,16 @@
 {
   "name": "mcp-obsidian-cli",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "type": "module",
   "description": "MCP server wrapping the Obsidian CLI — full native API access over Model Context Protocol",
   "main": "server.js",
   "bin": {
     "mcp-obsidian-cli": "server.js"
   },
+  "files": [
+    "server.js",
+    "prompts/"
+  ],
   "scripts": {
     "start": "node server.js",
     "test": "node --test test/run.test.js"

package/prompts/obsidian-bases.md

@@ -0,0 +1,380 @@
+# Obsidian Bases Reference
+
+Bases are database-like views of vault notes, defined as `.base` YAML files. They let you query, filter, and display notes as tables, card galleries, lists, or maps — without writing custom code.
+
+## Overview
+
+- **File format:** `.base` files containing valid YAML
+- **How they work:** Obsidian reads all vault notes, applies your filters, computes any formulas, and renders results in the configured views
+- **When to use:** Tracking tasks, reading lists, project dashboards, meeting logs, any situation where you want a live view across multiple notes
+
+## YAML Schema
+
+```yaml
+# Global filters apply to ALL views
+filters:
+  and: []
+  or: []
+  not: []
+
+# Computed properties available across all views
+formulas:
+  formula_name: 'expression'
+
+# Display name overrides for properties
+properties:
+  property_name:
+    displayName: "Display Name"
+  formula.formula_name:
+    displayName: "Formula Display Name"
+  file.ext:
+    displayName: "Extension"
+
+# Custom summary formulas
+summaries:
+  custom_name: 'values.mean().round(3)'
+
+# One or more views
+views:
+  - type: table | cards | list | map
+    name: "View Name"
+    limit: 10
+    groupBy:
+      property: property_name
+      direction: ASC | DESC
+    filters:
+      and: []
+    order:
+      - file.name
+      - property_name
+      - formula.formula_name
+    summaries:
+      property_name: Average
+```
+
+## Filters
+
+Filters narrow which notes appear. Apply globally (to all views) or per-view.
+
+### Filter Structure
+
+```yaml
+# Single filter expression
+filters: 'status == "done"'
+
+# AND - all conditions must be true
+filters:
+  and:
+    - 'status == "done"'
+    - 'priority > 3'
+
+# OR - any condition can be true
+filters:
+  or:
+    - 'file.hasTag("book")'
+    - 'file.hasTag("article")'
+
+# NOT - exclude matching items
+filters:
+  not:
+    - 'file.hasTag("archived")'
+
+# Nested filters
+filters:
+  or:
+    - file.hasTag("tag")
+    - and:
+        - file.hasTag("book")
+        - file.hasLink("Textbook")
+    - not:
+        - file.hasTag("book")
+        - file.inFolder("Required Reading")
+```
+
+### Filter Operators
+
+| Operator | Description |
+|----------|-------------|
+| `==` | equals |
+| `!=` | not equal |
+| `>` | greater than |
+| `<` | less than |
+| `>=` | greater than or equal |
+| `<=` | less than or equal |
+| `&&` | logical and |
+| `\|\|` | logical or |
+| `!` | logical not |
+
+Useful filter functions: `file.hasTag("tag")`, `file.inFolder("path/")`, `file.hasLink("Note Name")`.
+
+## Properties
+
+### Three Property Types
+
+1. **Note properties** — from note frontmatter: `status`, `priority`, `due`
+2. **File properties** — computed file metadata: `file.name`, `file.path`, `file.mtime`, etc.
+3. **Formula properties** — your computed values: `formula.days_until_due`
+
+### File Properties Reference
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `file.name` | String | File name with extension |
+| `file.basename` | String | File name without extension |
+| `file.path` | String | Full path from vault root |
+| `file.folder` | String | Parent folder path |
+| `file.ext` | String | File extension |
+| `file.size` | Number | File size in bytes |
+| `file.ctime` | Date | Created time |
+| `file.mtime` | Date | Modified time |
+| `file.tags` | List | All tags in file |
+| `file.links` | List | Internal links in file |
+| `file.backlinks` | List | Files linking to this file |
+
+## Formula Syntax
+
+Formulas compute values from properties. Define them in the `formulas` section, reference them as `formula.name` in views.
+
+```yaml
+formulas:
+  # Simple arithmetic
+  total: "price * quantity"
+
+  # Conditional logic
+  status_icon: 'if(done, "Done", "Pending")'
+
+  # String formatting
+  formatted_price: 'if(price, price.toFixed(2) + " USD", "")'
+
+  # Date formatting
+  created_label: 'file.ctime.format("YYYY-MM-DD")'
+
+  # Days since creation
+  days_old: '(now() - file.ctime).days'
+
+  # Days until due date (with null guard)
+  days_until_due: 'if(due_date, (date(due_date) - today()).days, "")'
+```
+
+### Key Functions
+
+| Function | Description |
+|----------|-------------|
+| `date(string)` | Parse string to date (`YYYY-MM-DD`) |
+| `now()` | Current date and time |
+| `today()` | Current date (time = 00:00:00) |
+| `if(condition, trueVal, falseVal?)` | Conditional expression |
+| `duration(string)` | Parse duration string |
+| `file(path)` | Get file object |
+| `link(path, display?)` | Create a link |
+
+### Duration Type
+
+Subtracting two dates returns a **Duration** — not a number. Access a numeric field before applying math:
+
+```yaml
+# CORRECT
+"(now() - file.ctime).days"               # Returns days as number
+"(date(due) - today()).days.round(0)"      # Rounded days
+
+# WRONG — Duration doesn't support direct round()
+# "(date(due) - today()).round(0)"
+```
+
+### Date Arithmetic
+
+```yaml
+"now() + \"1 day\""      # Tomorrow
+"today() + \"7d\""       # A week from today
+"now() - file.ctime"     # Returns Duration type
+```
+
+## View Types
+
+### Table View
+
+Displays notes as rows with sortable columns.
+
+```yaml
+views:
+  - type: table
+    name: "Task List"
+    order:
+      - file.name
+      - status
+      - due_date
+    summaries:
+      priority: Average
+```
+
+### Cards View
+
+Displays notes as a visual card gallery.
+
+```yaml
+views:
+  - type: cards
+    name: "Gallery"
+    order:
+      - file.name
+      - cover_image
+      - description
+```
+
+### List View
+
+Displays a minimal list of notes.
+
+```yaml
+views:
+  - type: list
+    name: "Quick List"
+    order:
+      - file.name
+      - status
+```
+
+### Map View
+
+Requires latitude/longitude properties and the Maps community plugin.
+
+```yaml
+views:
+  - type: map
+    name: "Locations"
+```
+
+## Summaries
+
+Summarize numeric or date columns in table footers.
+
+| Summary | Input | Description |
+|---------|-------|-------------|
+| `Average` | Number | Mean value |
+| `Sum` | Number | Total |
+| `Min` | Number | Smallest value |
+| `Max` | Number | Largest value |
+| `Range` | Number | Max minus Min |
+| `Median` | Number | Median value |
+| `Stddev` | Number | Standard deviation |
+| `Earliest` | Date | Earliest date |
+| `Latest` | Date | Latest date |
+| `Checked` | Boolean | Count of true |
+| `Unchecked` | Boolean | Count of false |
+| `Empty` | Any | Count of empty |
+| `Filled` | Any | Count of non-empty |
+| `Unique` | Any | Count of distinct values |
+
+## Complete Examples
+
+### Task Tracker
+
+```yaml
+filters:
+  and:
+    - file.hasTag("task")
+
+formulas:
+  days_until_due: 'if(due, (date(due) - today()).days, "")'
+  is_overdue: 'if(due, date(due) < today() && status != "done", false)'
+  priority_label: 'if(priority == 1, "High", if(priority == 2, "Medium", "Low"))'
+
+properties:
+  formula.days_until_due:
+    displayName: "Days Until Due"
+  formula.priority_label:
+    displayName: Priority
+
+views:
+  - type: table
+    name: "Active Tasks"
+    filters:
+      and:
+        - 'status != "done"'
+    order:
+      - file.name
+      - status
+      - formula.priority_label
+      - due
+      - formula.days_until_due
+    groupBy:
+      property: status
+      direction: ASC
+```
+
+### Reading List
+
+```yaml
+filters:
+  or:
+    - file.hasTag("book")
+    - file.hasTag("article")
+
+formulas:
+  status_icon: 'if(status == "reading", "Reading", if(status == "done", "Done", "To Read"))'
+  year_read: 'if(finished_date, date(finished_date).year, "")'
+
+views:
+  - type: cards
+    name: "Library"
+    order:
+      - cover
+      - file.name
+      - author
+      - formula.status_icon
+    filters:
+      not:
+        - 'status == "dropped"'
+```
+
+### Daily Notes Index
+
+```yaml
+filters:
+  and:
+    - file.inFolder("Daily Notes")
+
+formulas:
+  word_estimate: '(file.size / 5).round(0)'
+  day_of_week: 'date(file.basename).format("dddd")'
+
+properties:
+  formula.day_of_week:
+    displayName: "Day"
+  formula.word_estimate:
+    displayName: "~Words"
+
+views:
+  - type: table
+    name: "Recent Notes"
+    limit: 30
+    order:
+      - file.name
+      - formula.day_of_week
+      - formula.word_estimate
+      - file.mtime
+```
+
+## YAML Quoting Rules
+
+- Use single quotes for formulas containing double quotes: `'if(done, "Yes", "No")'`
+- Use double quotes for simple string values: `"My View Name"`
+- Strings containing `:`, `{`, `}`, `[`, `]`, `#` must be quoted
+
+## Embedding Bases in Notes
+
+```markdown
+![[MyBase.base]]
+
+![[MyBase.base#View Name]]
+```
+
+## Using This Knowledge with MCP Tools
+
+When working with Bases through this MCP server:
+
+- Create a new base: `obsidian_create({ name: "Tasks", path: "bases/Tasks.base", content: "<yaml content>" })`
+- Read an existing base definition: `obsidian_read({ path: "bases/Tasks.base" })`
+- List all base files: `obsidian_files({ ext: "base" })`
+- Set a property on a note that a base queries: `obsidian_property_set({ name: "status", value: "done", file: "My Task Note" })`
+- Search for notes that match base criteria: `obsidian_search({ query: "tag:#task" })`

package/prompts/obsidian-canvas.md

@@ -0,0 +1,312 @@
+# JSON Canvas Reference
+
+Canvas files (`.canvas`) are JSON files that define visual layouts of notes, text, links, and groups on an infinite canvas. Use them for brainstorming, relationship mapping, project planning, and content organization.
+
+## File Structure
+
+A canvas file contains two top-level arrays following the JSON Canvas Spec 1.0:
+
+```json
+{
+  "nodes": [],
+  "edges": []
+}
+```
+
+- `nodes` — array of node objects placed on the canvas
+- `edges` — array of connections between nodes
+
+Both arrays are optional (empty canvas is valid).
+
+## Common Workflows
+
+### Create a New Canvas
+
+1. Create a `.canvas` file with base structure `{"nodes": [], "edges": []}`
+2. Generate unique 16-character hex IDs for each node (e.g., `"6f0ad84f44ce9c17"`)
+3. Add nodes with required fields: `id`, `type`, `x`, `y`, `width`, `height`
+4. Add edges referencing valid node IDs via `fromNode` and `toNode`
+5. Validate: ensure all `fromNode`/`toNode` values reference existing node IDs
+
+### Add a Node to an Existing Canvas
+
+1. Read and parse the existing `.canvas` file
+2. Generate a unique ID that does not collide with existing IDs
+3. Choose `x`, `y` position that avoids overlapping existing nodes (50-100px spacing)
+4. Append the new node to the `nodes` array
+5. Optionally add edges connecting it to existing nodes
+
+### Connect Two Nodes
+
+1. Identify source and target node IDs
+2. Generate a unique edge ID
+3. Set `fromNode` and `toNode`; optionally set `fromSide`/`toSide` for anchor points
+4. Optionally add a `label`
+5. Append to the `edges` array
+
+## Node Types
+
+All nodes share these required attributes:
+
+| Attribute | Required | Type | Description |
+|-----------|----------|------|-------------|
+| `id` | Yes | string | Unique 16-char hex identifier |
+| `type` | Yes | string | `text`, `file`, `link`, or `group` |
+| `x` | Yes | integer | X position in pixels (left edge) |
+| `y` | Yes | integer | Y position in pixels (top edge) |
+| `width` | Yes | integer | Width in pixels |
+| `height` | Yes | integer | Height in pixels |
+| `color` | No | string | Preset `"1"`-`"6"` or hex `"#RRGGBB"` |
+
+### Text Nodes
+
+Display rich text with Markdown content.
+
+| Attribute | Required | Description |
+|-----------|----------|-------------|
+| `text` | Yes | Markdown string |
+
+```json
+{
+  "id": "6f0ad84f44ce9c17",
+  "type": "text",
+  "x": 0,
+  "y": 0,
+  "width": 400,
+  "height": 200,
+  "text": "# Hello World\n\nThis is **Markdown** content."
+}
+```
+
+Use `\n` for line breaks in JSON strings. Do NOT use literal `\\n`.
+
+### File Nodes
+
+Display a vault note or attachment inline.
+
+| Attribute | Required | Description |
+|-----------|----------|-------------|
+| `file` | Yes | Path to file from vault root |
+| `subpath` | No | Link to heading or block (starts with `#`) |
+
+```json
+{
+  "id": "a1b2c3d4e5f67890",
+  "type": "file",
+  "x": 500,
+  "y": 0,
+  "width": 400,
+  "height": 300,
+  "file": "Projects/Alpha.md"
+}
+```
+
+### Link Nodes
+
+Display an external URL as a web preview.
+
+| Attribute | Required | Description |
+|-----------|----------|-------------|
+| `url` | Yes | External URL |
+
+```json
+{
+  "id": "c3d4e5f678901234",
+  "type": "link",
+  "x": 1000,
+  "y": 0,
+  "width": 400,
+  "height": 200,
+  "url": "https://obsidian.md"
+}
+```
+
+### Group Nodes
+
+Visual containers for organizing other nodes. Position child nodes inside the group's bounds.
+
+| Attribute | Required | Description |
+|-----------|----------|-------------|
+| `label` | No | Text label for the group |
+| `background` | No | Path to background image |
+| `backgroundStyle` | No | `cover`, `ratio`, or `repeat` |
+
+```json
+{
+  "id": "d4e5f6789012345a",
+  "type": "group",
+  "x": -50,
+  "y": -50,
+  "width": 1000,
+  "height": 600,
+  "label": "Project Overview",
+  "color": "4"
+}
+```
+
+Groups do not automatically contain nodes — nodes are "inside" a group visually based on position overlap.
+
+## Edges
+
+Edges connect nodes via their IDs.
+
+| Attribute | Required | Default | Description |
+|-----------|----------|---------|-------------|
+| `id` | Yes | - | Unique identifier |
+| `fromNode` | Yes | - | Source node ID |
+| `toNode` | Yes | - | Target node ID |
+| `fromSide` | No | - | `top`, `right`, `bottom`, or `left` |
+| `toSide` | No | - | `top`, `right`, `bottom`, or `left` |
+| `fromEnd` | No | `none` | `none` or `arrow` |
+| `toEnd` | No | `arrow` | `none` or `arrow` |
+| `color` | No | - | Line color (preset or hex) |
+| `label` | No | - | Text label on the edge |
+
+```json
+{
+  "id": "0123456789abcdef",
+  "fromNode": "6f0ad84f44ce9c17",
+  "fromSide": "right",
+  "toNode": "a1b2c3d4e5f67890",
+  "toSide": "left",
+  "toEnd": "arrow",
+  "label": "leads to"
+}
+```
+
+## Color Presets
+
+| Preset | Color |
+|--------|-------|
+| `"1"` | Red |
+| `"2"` | Orange |
+| `"3"` | Yellow |
+| `"4"` | Green |
+| `"5"` | Cyan |
+| `"6"` | Purple |
+
+Also accepts hex strings: `"#FF0000"`. Exact shades depend on the Obsidian theme.
+
+## ID Generation
+
+Use 16-character lowercase hexadecimal strings (64-bit random value):
+
+```
+"6f0ad84f44ce9c17"
+"a3b2c1d0e9f8a7b6"
+```
+
+IDs must be unique across all nodes and edges in the file.
+
+## Layout Guidelines
+
+- Coordinates can be negative — the canvas is infinite
+- `x` increases rightward, `y` increases downward
+- `x`, `y` mark the top-left corner of the node
+- Space nodes 50-100px apart; leave 20-50px padding inside groups
+- Align to grid (multiples of 10 or 20) for cleaner layouts
+- Array order determines z-index: first node = bottom layer, last = top layer
+
+| Node Type | Suggested Width | Suggested Height |
+|-----------|-----------------|------------------|
+| Small text | 200-300 | 80-150 |
+| Medium text | 300-450 | 150-300 |
+| Large text | 400-600 | 300-500 |
+| File preview | 300-500 | 200-400 |
+| Link preview | 250-400 | 100-200 |
+
+## Validation Checklist
+
+Before writing a canvas file, verify:
+
+1. All `id` values are unique across nodes and edges
+2. Every `fromNode` and `toNode` references an existing node ID
+3. Required fields are present for each node type:
+   - text nodes: `text`
+   - file nodes: `file`
+   - link nodes: `url`
+4. `type` is one of: `text`, `file`, `link`, `group`
+5. `fromSide`/`toSide` are one of: `top`, `right`, `bottom`, `left`
+6. `fromEnd`/`toEnd` are one of: `none`, `arrow`
+7. Color presets are `"1"` through `"6"` or valid hex `"#RRGGBB"`
+8. JSON is valid and parseable (especially: `\n` not `\\n` in text)
+
+## Complete Example
+
+A minimal project overview canvas with a group, two notes, a text summary, and a connecting edge:
+
+```json
+{
+  "nodes": [
+    {
+      "id": "d4e5f6789012345a",
+      "type": "group",
+      "x": -60,
+      "y": -60,
+      "width": 1100,
+      "height": 500,
+      "label": "Project Alpha",
+      "color": "4"
+    },
+    {
+      "id": "6f0ad84f44ce9c17",
+      "type": "text",
+      "x": 0,
+      "y": 0,
+      "width": 350,
+      "height": 150,
+      "text": "## Goal\n\nDeliver MVP by end of quarter.\n\n- Backend API\n- Frontend UI\n- Documentation"
+    },
+    {
+      "id": "a1b2c3d4e5f67890",
+      "type": "file",
+      "x": 450,
+      "y": 0,
+      "width": 400,
+      "height": 300,
+      "file": "Projects/Alpha/Requirements.md"
+    },
+    {
+      "id": "b2c3d4e5f6789012",
+      "type": "link",
+      "x": 450,
+      "y": 320,
+      "width": 400,
+      "height": 120,
+      "url": "https://github.com/example/project-alpha"
+    }
+  ],
+  "edges": [
+    {
+      "id": "0123456789abcdef",
+      "fromNode": "6f0ad84f44ce9c17",
+      "fromSide": "right",
+      "toNode": "a1b2c3d4e5f67890",
+      "toSide": "left",
+      "toEnd": "arrow",
+      "label": "defines"
+    }
+  ]
+}
+```
+
+## Using This Knowledge with MCP Tools
+
+When working with canvas files through this MCP server:
+
+- Create a new canvas:
+  ```
+  obsidian_create({
+    name: "Project Map",
+    path: "canvas/Project Map.canvas",
+    content: "{\"nodes\": [], \"edges\": []}"
+  })
+  ```
+- Read an existing canvas (parse the JSON to see its structure):
+  `obsidian_read({ path: "canvas/Project Map.canvas" })`
+- List all canvas files in the vault:
+  `obsidian_files({ ext: "canvas" })`
+- Update a canvas (read, modify JSON, write back):
+  `obsidian_create({ path: "canvas/Project Map.canvas", content: "<updated json>" })`
+- Search for notes referenced in canvases:
+  `obsidian_search({ query: "canvas" })`

package/prompts/obsidian-cli.md

@@ -0,0 +1,115 @@
+# Obsidian CLI Reference
+
+Use the `obsidian` CLI to interact with a running Obsidian instance. Obsidian must be open.
+
+## Command Syntax
+
+Commands follow this pattern:
+
+```bash
+obsidian <command> [key=value ...]
+```
+
+**Parameters** take a value with `=`. Quote values that contain spaces:
+
+```bash
+obsidian create name="My Note" content="Hello world"
+```
+
+**Flags** are boolean switches with no value:
+
+```bash
+obsidian create name="My Note" silent overwrite
+```
+
+For multiline content, use `\n` for newline and `\t` for tab.
+
+## File Targeting
+
+Many commands accept `file` or `path` to target a note. Without either, the active file is used.
+
+- `file=<name>` — resolves like a wikilink (name only, no path or extension needed)
+- `path=<path>` — exact path from vault root, e.g. `folder/note.md`
+
+## Vault Targeting
+
+Commands target the most recently focused vault by default. Use `vault=<name>` as the first parameter to target a specific vault:
+
+```bash
+obsidian vault="My Vault" search query="test"
+```
+
+## Common Commands
+
+| Command | Description |
+|---------|-------------|
+| `read file="Note"` | Read note contents by wikilink name |
+| `read path="folder/note.md"` | Read note contents by exact path |
+| `create name="New Note" content="..."` | Create a new note |
+| `append file="Note" content="..."` | Append content to a note |
+| `search query="term" limit=10` | Full-text vault search |
+| `search:context query="term"` | Search with surrounding line context |
+| `daily:read` | Read today's daily note |
+| `daily:append content="..."` | Append to today's daily note |
+| `daily:path` | Get file path of today's daily note |
+| `tasks daily todo` | List incomplete tasks from daily note |
+| `tasks` | List all tasks in the vault |
+| `tags sort=count counts` | List tags sorted by frequency |
+| `properties` | List all frontmatter properties in vault |
+| `properties file="Note" counts` | List properties for a specific note |
+| `property:read name="status" file="Note"` | Read a specific property value |
+| `property:set name="status" value="done" file="Note"` | Set a property |
+| `backlinks file="Note" counts` | List notes that link to this note |
+| `files folder="Projects/"` | List files in a folder |
+| `files ext=canvas` | List files by extension |
+| `recents` | List recently opened files |
+| `help` | Show all available commands |
+| `help <command>` | Show help for a specific command |
+
+## Parameter Patterns
+
+| Parameter | Purpose | Example |
+|-----------|---------|---------|
+| `file=` | Target note by wikilink name | `file="My Note"` |
+| `path=` | Target note by exact vault path | `path="Work/Projects/alpha.md"` |
+| `query=` | Search terms | `query="meeting notes"` |
+| `content=` | Text content to write or append | `content="- [ ] New task"` |
+| `name=` | Note name (create) or property name | `name="New Note"` |
+| `value=` | Property value | `value="done"` |
+| `limit=` | Max results to return | `limit=10` |
+| `sort=` | Sort order | `sort=count` |
+| `folder=` | Folder to filter by | `folder="Projects/"` |
+| `ext=` | File extension filter | `ext=canvas` |
+
+Quote any value that contains spaces. Use `\n` for newlines within `content=` values.
+
+## Output Behavior
+
+- Commands write their output to stdout
+- Errors appear on stderr
+- Use `--copy` on any command to copy output to clipboard
+- Use `silent` flag to prevent files from opening in the Obsidian UI
+- Use `total` on list commands to get a count appended to output
+
+## Using This Knowledge with MCP Tools
+
+When working with an Obsidian vault via this MCP server, use these tools instead of running the CLI directly:
+
+- Read a note: `obsidian_read({ file: "Note Name" })`
+- Read by exact path: `obsidian_read({ path: "folder/note.md" })`
+- Search with context: `obsidian_search({ query: "term", path: "folder/", limit: 5 })`
+- Read today's daily note: `obsidian_daily_read()`
+- Get daily note path: `obsidian_daily_path()`
+- Append to daily note: `obsidian_daily_append({ content: "- [ ] New task" })`
+- Create a note: `obsidian_create({ name: "New Note", content: "# Heading\n..." })`
+- List tasks from daily note: `obsidian_tasks({ daily: true, todo: true })`
+- List all vault tasks: `obsidian_tasks({})`
+- List tags by frequency: `obsidian_tags({ sort: "count" })`
+- Read all properties for a note: `obsidian_properties({ file: "Note Name" })`
+- Read a specific property: `obsidian_properties({ file: "Note Name", name: "status" })`
+- Set a property: `obsidian_property_set({ name: "status", value: "done", file: "Note Name" })`
+- List backlinks: `obsidian_backlinks({ file: "Note Name" })`
+- List files in folder: `obsidian_files({ folder: "Projects/" })`
+- List canvas files: `obsidian_files({ ext: "canvas" })`
+- List recent files: `obsidian_recents()`
+- Run any CLI command directly: `obsidian({ command: "help search" })`

package/prompts/obsidian-markdown.md

@@ -0,0 +1,224 @@
+# Obsidian Flavored Markdown Reference
+
+Obsidian extends CommonMark and GitHub Flavored Markdown with wikilinks, embeds, callouts, properties, and other vault-specific syntax. This reference covers only Obsidian-specific extensions — standard Markdown (headings, bold, italic, lists, code blocks, tables) is assumed knowledge.
+
+## Wikilinks (Internal Links)
+
+Use wikilinks for all links within the vault. Obsidian tracks renames automatically.
+
+```markdown
+[[Note Name]]                          Link to a note
+[[Note Name|Display Text]]             Custom display text
+[[Note Name#Heading]]                  Link to a specific heading
+[[Note Name#^block-id]]                Link to a specific block
+[[Note Name#^block-id|Display Text]]   Link to block with custom text
+[[#Heading in same note]]              Link to heading in current note
+```
+
+Define a block ID by appending `^block-id` at the end of a paragraph:
+
+```markdown
+This paragraph can be linked to. ^my-block-id
+```
+
+For lists or quotes, place the block ID on a separate line after the block:
+
+```markdown
+> A quote block
+
+^quote-id
+```
+
+Use `[text](url)` for external URLs only — not for vault notes.
+
+## Embeds
+
+Prefix any wikilink with `!` to embed content inline:
+
+```markdown
+![[Note Name]]                         Embed full note
+![[Note Name#Heading]]                 Embed a specific section
+![[image.png]]                         Embed an image
+![[image.png|300]]                     Embed image with pixel width
+![[document.pdf#page=3]]               Embed a specific PDF page
+![[audio.mp3]]                         Embed audio player
+```
+
+## Callouts
+
+Callouts highlight information with a colored block and icon:
+
+```markdown
+> [!note]
+> Basic callout with default title.
+
+> [!warning] Custom Title
+> Callout with a custom title.
+
+> [!tip]- Collapsed by default
+> Use `-` after the type to collapse. Use `+` to expand by default.
+
+> [!faq]+ Expanded by default
+> Starts open.
+```
+
+Common callout types: `note`, `tip`, `info`, `warning`, `danger`, `bug`, `success`, `failure`, `question`, `example`, `quote`, `abstract`, `todo`.
+
+Callouts can be nested:
+
+```markdown
+> [!note] Outer
+> > [!tip] Inner
+> > Nested callout content.
+```
+
+## Properties (Frontmatter)
+
+Properties are YAML metadata in a `---` delimited block at the top of the file:
+
+```yaml
+---
+title: My Note
+date: 2024-01-15
+tags:
+  - project
+  - active
+aliases:
+  - Alternative Name
+cssclasses:
+  - custom-class
+status: in-progress
+priority: 2
+done: false
+---
+```
+
+**Common property types:**
+
+| Type | YAML example |
+|------|-------------|
+| Text | `status: "active"` |
+| Number | `priority: 2` |
+| Date | `due: 2024-03-01` |
+| Boolean | `done: false` |
+| List | `tags:\n  - item1\n  - item2` |
+| Link | `related: "[[Other Note]]"` |
+
+**Built-in Obsidian properties:**
+- `tags` — searchable labels (`#tag` syntax, also works inline in body)
+- `aliases` — alternative note names for link suggestions
+- `cssclasses` — CSS classes applied to the note in reading view
+
+## Tags
+
+```markdown
+#tag                    Inline tag in body text
+#nested/tag             Nested tag (creates hierarchy)
+```
+
+Tags can also be defined in frontmatter under `tags`. Rules: letters, numbers (not first char), underscores, hyphens, and forward slashes.
+
+## Comments
+
+Comments are hidden in reading view:
+
+```markdown
+This is visible %%but this is hidden%% text.
+
+%%
+This entire block is hidden in reading view.
+%%
+```
+
+## Highlights
+
+```markdown
+==This text is highlighted==
+```
+
+## Math (LaTeX)
+
+```markdown
+Inline: $e^{i\pi} + 1 = 0$
+
+Block:
+$$
+\frac{a}{b} = c
+$$
+```
+
+## Diagrams (Mermaid)
+
+````markdown
+```mermaid
+graph TD
+    A[Start] --> B{Decision}
+    B -->|Yes| C[Do this]
+    B -->|No| D[Do that]
+```
+````
+
+To link Mermaid nodes to Obsidian notes, add `class NodeName internal-link;`.
+
+## Footnotes
+
+```markdown
+Text with a footnote[^1].
+
+[^1]: Footnote content goes here.
+
+Inline footnote.^[This is the inline footnote text.]
+```
+
+## Complete Note Example
+
+````markdown
+---
+title: Project Alpha
+date: 2024-01-15
+tags:
+  - project
+  - active
+status: in-progress
+---
+
+# Project Alpha
+
+This project aims to [[improve workflow]] using modern techniques.
+
+> [!important] Key Deadline
+> The first milestone is due on ==January 30th==.
+
+## Tasks
+
+- [x] Initial planning
+- [ ] Development phase
+
+## Notes
+
+The algorithm uses $O(n \log n)$ sorting. See [[Algorithm Notes#Sorting]] for details.
+
+![[Architecture Diagram.png|600]]
+
+Reviewed in [[Meeting Notes 2024-01-10#Decisions]].
+````
+
+## Using This Knowledge with MCP Tools
+
+When creating or editing notes through this MCP server, apply these patterns:
+
+- Read a note (see its markdown): `obsidian_read({ file: "Note Name" })`
+- Create a note with frontmatter:
+  ```
+  obsidian_create({
+    name: "New Note",
+    content: "---\ntags:\n  - project\nstatus: active\n---\n# Heading\n\nContent here."
+  })
+  ```
+- Append a callout to daily note:
+  ```
+  obsidian_daily_append({ content: "> [!tip] Reminder\n> Don't forget the meeting." })
+  ```
+- Set a frontmatter property: `obsidian_property_set({ name: "status", value: "done", file: "Note Name" })`
+- Search by tag: `obsidian_search({ query: "tag:#project" })`
+- Find notes linking to another: `obsidian_backlinks({ file: "Note Name" })`

package/server.js

@@ -13,7 +13,8 @@
  *
  * Requirements:
  *   - Obsidian must be running with the CLI plugin active.
- *   - The `obsidian` binary must be on PATH (or set OBSIDIAN_CLI_PATH).
+ *   - The CLI binary is auto-discovered from common macOS locations.
+ *     Set OBSIDIAN_CLI_PATH to override.
  */
 
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -24,13 +25,25 @@ import { promisify } from "node:util";
 import { readFileSync, mkdirSync, existsSync } from "node:fs";
 import { load as yamlLoad } from "js-yaml";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
 import { exec } from "node:child_process";
 
 const execFileAsync = promisify(execFile);
 const execAsync = promisify(exec);
 
-const CONFIG_DIR = join(homedir(), ".config", "mcp-obsidian-cli");
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PROMPTS_DIR = join(__dirname, "prompts");
+
+const promptContent = {
+  "obsidian-cli":      readFileSync(join(PROMPTS_DIR, "obsidian-cli.md"), "utf8"),
+  "obsidian-markdown": readFileSync(join(PROMPTS_DIR, "obsidian-markdown.md"), "utf8"),
+  "obsidian-bases":    readFileSync(join(PROMPTS_DIR, "obsidian-bases.md"), "utf8"),
+  "obsidian-canvas":   readFileSync(join(PROMPTS_DIR, "obsidian-canvas.md"), "utf8"),
+};
+
+const configBase = process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
+const CONFIG_DIR = join(configBase, "mcp-obsidian-cli");
 const CONFIG_FILE = join(CONFIG_DIR, "config.yaml");
 
 function loadConfig() {
@@ -58,8 +71,37 @@ function loadConfig() {
   return config;
 }
 
+const KNOWN_CLI_PATHS = [
+  "/Applications/Obsidian.app/Contents/MacOS/obsidian",
+  join(homedir(), "Applications/Obsidian.app/Contents/MacOS/obsidian"),
+];
+
+async function resolveCliPath(configured) {
+  if (configured !== "obsidian") return configured;
+
+  try {
+    await execAsync("which obsidian", { timeout: 2000 });
+    return configured;
+  } catch { /* not on PATH */ }
+
+  for (const p of KNOWN_CLI_PATHS) {
+    if (existsSync(p)) return p;
+  }
+
+  try {
+    const { stdout } = await execAsync(
+      "ps aux | grep -i obsidian | grep -v grep | grep -v Helper",
+      { timeout: 2000 }
+    );
+    const match = stdout.match(/(\S*\/Contents\/MacOS\/obsidian)/i);
+    if (match && existsSync(match[1])) return match[1];
+  } catch { /* no running process */ }
+
+  return configured;
+}
+
 const config = loadConfig();
-const CLI = config.cliPath;
+const CLI = await resolveCliPath(config.cliPath);
 const VAULT = config.vault;
 const TIMEOUT_MS = config.timeoutMs;
 
@@ -179,7 +221,7 @@ async function runTool(argString) {
 
 const server = new McpServer({
   name: "obsidian-mcp",
-  version: "1.0.0",
+  version: "1.1.0",
   capabilities: { tools: {} },
 });
 
@@ -205,28 +247,28 @@ Examples:
 
 server.tool(
   "obsidian_daily_read",
-  "Read today's daily note contents.",
+  "Read today's daily note contents.\n\nReturns the full markdown content of today's daily note. Returns an error if no daily note exists for today.",
   {},
   async () => runTool("daily:read"),
 );
 
 server.tool(
   "obsidian_daily_path",
-  "Get the file path of today's daily note.",
+  "Get the file path of today's daily note.\n\nReturns the vault-relative path (e.g. 'Daily/2026-04-03.md'). Useful for constructing paths for other tools.",
   {},
   async () => runTool("daily:path"),
 );
 
 server.tool(
   "obsidian_daily_append",
-  "Append content to today's daily note.",
+  "Append content to today's daily note.\n\nParameters:\n  content (required) — markdown text to append at the end of today's daily note\n\nExamples:\n  obsidian_daily_append({ content: \"- Meeting with team at 3pm\" })\n  obsidian_daily_append({ content: \"> [!tip] Remember\\n> Review PR before EOD\" })",
   { content: z.string().describe("Content to append") },
   async ({ content }) => runTool(`daily:append content="${content.replace(/"/g, '\\"')}"`),
 );
 
 server.tool(
   "obsidian_read",
-  "Read a note by file name (wikilink-style) or exact path.",
+  "Read a note by file name (wikilink-style) or exact path.\n\nParameters:\n  file (optional) — note name using wikilink resolution (e.g. 'My Note')\n  path (optional) — exact vault-relative path (e.g. 'folder/My Note.md')\n  One of file or path is required.\n\nExamples:\n  obsidian_read({ file: \"Meeting Notes\" })\n  obsidian_read({ path: \"Projects/todo.md\" })",
   {
     file: z.string().optional().describe("File name (wikilink resolution)"),
     path: z.string().optional().describe("Exact file path"),
@@ -240,7 +282,7 @@ server.tool(
 
 server.tool(
   "obsidian_search",
-  "Full-text search across the vault with line context.",
+  "Full-text search across the vault with line context.\n\nParameters:\n  query (required) — search terms, supports Obsidian query syntax\n  path (optional) — restrict results to a folder path\n  limit (optional) — max number of files to return\n\nExamples:\n  obsidian_search({ query: \"meeting notes\" })\n  obsidian_search({ query: \"project status\", path: \"Work/\", limit: 5 })",
   {
     query: z.string().describe("Search query"),
     path: z.string().optional().describe("Limit to folder"),
@@ -256,7 +298,7 @@ server.tool(
 
 server.tool(
   "obsidian_tags",
-  "List tags in the vault with counts.",
+  "List tags in the vault with counts.\n\nParameters:\n  sort (optional) — 'name' or 'count' (default: name)\n\nExamples:\n  obsidian_tags({})\n  obsidian_tags({ sort: \"count\" })",
   {
     sort: z.enum(["name", "count"]).optional().describe("Sort order"),
   },
@@ -269,7 +311,7 @@ server.tool(
 
 server.tool(
   "obsidian_tasks",
-  "List tasks. Use daily=true for today's tasks only.",
+  "List tasks from vault notes.\n\nParameters:\n  daily (optional) — true to show only today's daily note tasks\n  todo (optional) — true to show only incomplete tasks\n  done (optional) — true to show only completed tasks\n  path (optional) — filter by file path\n\nExamples:\n  obsidian_tasks({ daily: true })\n  obsidian_tasks({ todo: true, path: \"Projects/\" })",
   {
     daily: z.boolean().optional().describe("Show only daily note tasks"),
     todo: z.boolean().optional().describe("Show incomplete tasks only"),
@@ -288,7 +330,7 @@ server.tool(
 
 server.tool(
   "obsidian_properties",
-  "List or read frontmatter properties.",
+  "List or read frontmatter properties.\n\nParameters:\n  file (optional) — note name for wikilink resolution\n  path (optional) — exact file path\n  name (optional) — specific property name to read (requires file or path)\n\nExamples:\n  obsidian_properties({}) — list all properties with counts\n  obsidian_properties({ file: \"My Note\" }) — properties of a specific note\n  obsidian_properties({ file: \"My Note\", name: \"status\" }) — read one property",
   {
     file: z.string().optional().describe("File name"),
     path: z.string().optional().describe("File path"),
@@ -310,7 +352,7 @@ server.tool(
 
 server.tool(
   "obsidian_create",
-  "Create a new note.",
+  "Create a new note.\n\nParameters:\n  name (optional) — file name for the new note\n  path (optional) — vault-relative path\n  content (optional) — initial markdown content\n  template (optional) — template name to use\n\nExamples:\n  obsidian_create({ name: \"Meeting 2026-04-03\", content: \"# Meeting Notes\\n\\n- Attendees: ...\" })\n  obsidian_create({ path: \"Projects/new-idea.md\", template: \"project\" })",
   {
     name: z.string().optional().describe("File name"),
     path: z.string().optional().describe("File path"),
@@ -329,7 +371,7 @@ server.tool(
 
 server.tool(
   "obsidian_property_set",
-  "Set a frontmatter property on a note.",
+  "Set a frontmatter property on a note.\n\nParameters:\n  name (required) — property name\n  value (required) — property value\n  file (optional) — note name (wikilink resolution)\n  path (optional) — exact file path\n  One of file or path is required.\n\nExamples:\n  obsidian_property_set({ name: \"status\", value: \"done\", file: \"My Task\" })\n  obsidian_property_set({ name: \"tags\", value: \"project, active\", path: \"Work/todo.md\" })",
   {
     name: z.string().describe("Property name"),
     value: z.string().describe("Property value"),
@@ -345,7 +387,7 @@ server.tool(
 
 server.tool(
   "obsidian_backlinks",
-  "List backlinks to a note.",
+  "List backlinks to a note.\n\nParameters:\n  file (optional) — note name (wikilink resolution)\n  path (optional) — exact file path\n\nExamples:\n  obsidian_backlinks({ file: \"Project Plan\" })\n  obsidian_backlinks({ path: \"Ideas/brainstorm.md\" })",
   {
     file: z.string().optional().describe("File name"),
     path: z.string().optional().describe("File path"),
@@ -358,7 +400,7 @@ server.tool(
 
 server.tool(
   "obsidian_files",
-  "List files in the vault or a specific folder.",
+  "List files in the vault or a specific folder.\n\nParameters:\n  folder (optional) — filter by folder path\n  ext (optional) — filter by file extension (e.g. 'md', 'canvas')\n\nExamples:\n  obsidian_files({})\n  obsidian_files({ folder: \"Projects/\", ext: \"md\" })",
   {
     folder: z.string().optional().describe("Filter by folder path"),
     ext: z.string().optional().describe("Filter by extension"),
@@ -373,11 +415,52 @@ server.tool(
 
 server.tool(
   "obsidian_recents",
-  "List recently opened files.",
+  "List recently opened files.\n\nReturns the most recently opened files in the vault, ordered by last access time.",
   {},
   async () => runTool("recents"),
 );
 
+server.tool(
+  "obsidian_help",
+  "Get Obsidian reference documentation on a topic.\n\nParameters:\n  topic (required) — one of: cli, markdown, bases, canvas\n\nExamples:\n  obsidian_help({ topic: \"markdown\" }) — wikilinks, embeds, callouts, properties, tags\n  obsidian_help({ topic: \"bases\" }) — Bases YAML schema, filters, formulas, views\n  obsidian_help({ topic: \"canvas\" }) — JSON Canvas nodes, edges, colors, layout\n  obsidian_help({ topic: \"cli\" }) — CLI command syntax and parameter patterns",
+  { topic: z.enum(["cli", "markdown", "bases", "canvas"]).describe("Reference topic") },
+  async ({ topic }) => ({
+    content: [{ type: "text", text: promptContent[`obsidian-${topic}`] }],
+  }),
+);
+
+// ---- MCP Prompts -----------------------------------------------------------
+
+const promptMeta = {
+  "obsidian-cli": {
+    title: "Obsidian CLI Reference",
+    description: "CLI usage patterns, parameter syntax, and command examples for the Obsidian CLI. Adapted from kepano/obsidian-skills (MIT License, https://github.com/kepano/obsidian-skills).",
+  },
+  "obsidian-markdown": {
+    title: "Obsidian Flavored Markdown Reference",
+    description: "Wikilinks, embeds, callouts, properties, tags, and other Obsidian-specific markdown syntax. Adapted from kepano/obsidian-skills (MIT License, https://github.com/kepano/obsidian-skills).",
+  },
+  "obsidian-bases": {
+    title: "Obsidian Bases Reference",
+    description: "Bases syntax for database-like views: filters, formulas, view types, and summaries. Adapted from kepano/obsidian-skills (MIT License, https://github.com/kepano/obsidian-skills).",
+  },
+  "obsidian-canvas": {
+    title: "JSON Canvas Reference",
+    description: "JSON Canvas format for visual canvases: node types, edges, groups, and layout. Adapted from kepano/obsidian-skills (MIT License, https://github.com/kepano/obsidian-skills).",
+  },
+};
+
+for (const [name, content] of Object.entries(promptContent)) {
+  const meta = promptMeta[name];
+  server.registerPrompt(
+    name,
+    { title: meta.title, description: meta.description },
+    () => ({
+      messages: [{ role: "user", content: { type: "text", text: content } }],
+    })
+  );
+}
+
 // ---- Start ---------------------------------------------------------------
 
 async function main() {