mcp-obsidian-cli 1.0.1 → 1.2.0

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" })`