mcp-obsidian-cli 1.0.1 → 1.2.0

package/lib/helpers.js

@@ -0,0 +1,62 @@
+/**
+ * Pure helper functions extracted from server.js for testability.
+ */
+
+import { readFileSync, existsSync } from "node:fs";
+import { load as yamlLoad } from "js-yaml";
+
+/**
+ * Load config from YAML file with env var overrides.
+ * @param {string} configFile - Path to the YAML config file.
+ * @returns {{ vault: string, cliPath: string, timeoutMs: number }}
+ */
+export function loadConfig(configFile) {
+  const defaults = { vault: "", cliPath: "obsidian", timeoutMs: 15000 };
+  let config = { ...defaults };
+
+  if (existsSync(configFile)) {
+    try {
+      const content = readFileSync(configFile, "utf8");
+      const fileConfig = yamlLoad(content);
+      if (fileConfig) {
+        if (fileConfig.vault) config.vault = fileConfig.vault;
+        if (fileConfig.cliPath) config.cliPath = fileConfig.cliPath;
+        if (fileConfig.timeoutMs) config.timeoutMs = fileConfig.timeoutMs;
+      }
+    } catch (err) {
+      console.error("Warning: failed to load config file:", err.message);
+    }
+  }
+
+  if (process.env.OBSIDIAN_VAULT) config.vault = process.env.OBSIDIAN_VAULT;
+  if (process.env.OBSIDIAN_CLI_PATH) config.cliPath = process.env.OBSIDIAN_CLI_PATH;
+  if (process.env.OBSIDIAN_TIMEOUT_MS) config.timeoutMs = parseInt(process.env.OBSIDIAN_TIMEOUT_MS, 10);
+
+  return config;
+}
+
+/**
+ * Minimal arg parser: splits on whitespace but respects key="value with spaces".
+ */
+export function parseArgs(str) {
+  const args = [];
+  const re = /(?:[^\s"]+|"[^"]*")+/g;
+  let m;
+  while ((m = re.exec(str)) !== null) {
+    args.push(m[0].replace(/"([^"]*)"/g, "$1"));
+  }
+  return args;
+}
+
+/** Standard MCP text result. */
+export function text(content) {
+  return { content: [{ type: "text", text: content }] };
+}
+
+/** Standard MCP error result. */
+export function errorResult(content, code = "EXECUTION_ERROR") {
+  return {
+    content: [{ type: "text", text: content }],
+    isError: true,
+  };
+}

package/package.json

@@ -1,15 +1,20 @@
 {
   "name": "mcp-obsidian-cli",
-  "version": "1.0.1",
+  "version": "1.2.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",
+    "lib/",
+    "prompts/"
+  ],
   "scripts": {
     "start": "node server.js",
-    "test": "node --test test/run.test.js"
+    "test": "node --test test/*.test.js"
   },
   "engines": {
     "node": ">=18"

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