mcp-obsidian-cli 1.0.1 → 1.2.0

package/server.js

@@ -22,43 +22,30 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { z } from "zod";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
-import { readFileSync, mkdirSync, existsSync } from "node:fs";
-import { load as yamlLoad } from "js-yaml";
+import { readFileSync, existsSync } from "node:fs";
 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";
+import { loadConfig, parseArgs, text, errorResult } from "./lib/helpers.js";
 
 const execFileAsync = promisify(execFile);
 const execAsync = promisify(exec);
 
+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() {
-  const defaults = { vault: "", cliPath: "obsidian", timeoutMs: 15000 };
-  let config = { ...defaults };
-
-  if (existsSync(CONFIG_FILE)) {
-    try {
-      const content = readFileSync(CONFIG_FILE, "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;
-}
 
 const KNOWN_CLI_PATHS = [
   "/Applications/Obsidian.app/Contents/MacOS/obsidian",
@@ -89,35 +76,20 @@ async function resolveCliPath(configured) {
   return configured;
 }
 
-const config = loadConfig();
+const config = loadConfig(CONFIG_FILE);
 const CLI = await resolveCliPath(config.cliPath);
 const VAULT = config.vault;
 const TIMEOUT_MS = config.timeoutMs;
 
 async function checkObsidianRunning() {
   try {
-    const { stdout: psOut } = await execAsync("ps aux | grep -i obsidian | grep -v grep | grep -v Helper", { timeout: 2000 });
-    const obsidianRunning = psOut.includes("/Applications/Obsidian.app");
-    if (!obsidianRunning) {
-      return { running: false, version: null };
-    }
-    const { stdout } = await execFileAsync(CLI, ["version"], { timeout: 2000 });
-    const hasStartupMsg = stdout.includes("Loaded updated app package") || 
-                          stdout.includes("Checking for update") ||
-                          stdout.includes("App is up to date") ||
-                          stdout.includes("Latest version is");
-    if (hasStartupMsg) {
-      return { running: false, version: null };
-    }
-    if (stdout.includes("(installer")) {
-      const match = stdout.match(/(\d+\.\d+\.\d+)/);
-      if (match) {
-        return { running: true, version: match[1] };
-      }
-    }
-    return { running: false, version: null };
-  } catch (err) {
-    return { running: false, version: null };
+    const { stdout } = await execAsync(
+      "ps aux | grep -i obsidian | grep -v grep | grep -v Helper",
+      { timeout: 2000 }
+    );
+    return stdout.includes("/Applications/Obsidian.app");
+  } catch {
+    return false;
   }
 }
 
@@ -129,8 +101,8 @@ async function checkObsidianRunning() {
  * Run the Obsidian CLI with the given argument string.
  * Returns { stdout, stderr } or throws on non-zero exit / timeout.
  */
-async function run(argString) {
-  const args = parseArgs(argString);
+async function run(input) {
+  const args = Array.isArray(input) ? [...input] : parseArgs(input);
   if (VAULT) args.push(`vault=${VAULT}`);
 
   try {
@@ -166,35 +138,10 @@ async function run(argString) {
   }
 }
 
-/**
- * Minimal arg parser: splits on whitespace but respects key="value with spaces".
- */
-function parseArgs(str) {
-  const args = [];
-  const re = /(?:[^\s"]+|"[^"]*")+/g;
-  let m;
-  while ((m = re.exec(str)) !== null) {
-    args.push(m[0]);
-  }
-  return args;
-}
-
-/** Standard MCP text result. */
-function text(content) {
-  return { content: [{ type: "text", text: content }] };
-}
 
-/** Standard MCP error result. */
-function errorResult(content, code = "EXECUTION_ERROR") {
-  return {
-    content: [{ type: "text", text: content }],
-    isError: true,
-  };
-}
-
-/** Run CLI, return MCP result. */
-async function runTool(argString) {
-  const { stdout, stderr, error } = await run(argString);
+/** Run CLI, return MCP result. Accepts a command string or an args array. */
+async function runTool(input) {
+  const { stdout, stderr, error } = await run(input);
   if (error) {
     return errorResult(error.message, error.type);
   }
@@ -210,7 +157,7 @@ async function runTool(argString) {
 
 const server = new McpServer({
   name: "obsidian-mcp",
-  version: "1.0.0",
+  version: "1.2.0",
   capabilities: { tools: {} },
 });
 
@@ -236,71 +183,73 @@ 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, '\\"')}"`),
+  async ({ content }) => runTool(["daily:append", `content=${content}`]),
 );
 
 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"),
   },
   async ({ file, path }) => {
     if (!file && !path) return text("Error: provide file= or path=");
-    const arg = file ? `file="${file}"` : `path="${path}"`;
-    return runTool(`read ${arg}`);
+    const args = ["read"];
+    if (file) args.push(`file=${file}`);
+    if (path) args.push(`path=${path}`);
+    return runTool(args);
   },
 );
 
 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"),
     limit: z.number().optional().describe("Max files to return"),
   },
   async ({ query, path, limit }) => {
-    let cmd = `search:context query="${query.replace(/"/g, '\\"')}"`;
-    if (path) cmd += ` path="${path}"`;
-    if (limit) cmd += ` limit=${limit}`;
-    return runTool(cmd);
+    const args = ["search:context", `query=${query}`];
+    if (path) args.push(`path=${path}`);
+    if (limit) args.push(`limit=${limit}`);
+    return runTool(args);
   },
 );
 
 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"),
   },
   async ({ sort }) => {
-    let cmd = "tags counts";
-    if (sort) cmd += ` sort=${sort}`;
-    return runTool(cmd);
+    const args = ["tags", "counts"];
+    if (sort) args.push(`sort=${sort}`);
+    return runTool(args);
   },
 );
 
 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"),
@@ -308,18 +257,18 @@ server.tool(
     path: z.string().optional().describe("Filter by file path"),
   },
   async ({ daily, todo, done, path }) => {
-    let cmd = "tasks";
-    if (daily) cmd += " daily";
-    if (todo) cmd += " todo";
-    if (done) cmd += " done";
-    if (path) cmd += ` path="${path}"`;
-    return runTool(cmd);
+    const args = ["tasks"];
+    if (daily) args.push("daily");
+    if (todo) args.push("todo");
+    if (done) args.push("done");
+    if (path) args.push(`path=${path}`);
+    return runTool(args);
   },
 );
 
 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"),
@@ -327,21 +276,22 @@ server.tool(
   },
   async ({ file, path, name }) => {
     if (name && (file || path)) {
-      // Read a specific property from a specific file
-      const target = file ? `file="${file}"` : `path="${path}"`;
-      return runTool(`property:read name="${name}" ${target}`);
+      const args = ["property:read", `name=${name}`];
+      if (file) args.push(`file=${file}`);
+      if (path) args.push(`path=${path}`);
+      return runTool(args);
     }
-    let cmd = "properties";
-    if (file) cmd += ` file="${file}"`;
-    if (path) cmd += ` path="${path}"`;
-    cmd += " counts";
-    return runTool(cmd);
+    const args = ["properties"];
+    if (file) args.push(`file=${file}`);
+    if (path) args.push(`path=${path}`);
+    args.push("counts");
+    return runTool(args);
   },
 );
 
 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"),
@@ -349,18 +299,18 @@ server.tool(
     template: z.string().optional().describe("Template to use"),
   },
   async ({ name, path, content, template }) => {
-    let cmd = "create";
-    if (name) cmd += ` name="${name}"`;
-    if (path) cmd += ` path="${path}"`;
-    if (template) cmd += ` template="${template}"`;
-    if (content) cmd += ` content="${content.replace(/"/g, '\\"')}"`;
-    return runTool(cmd);
+    const args = ["create"];
+    if (name) args.push(`name=${name}`);
+    if (path) args.push(`path=${path}`);
+    if (template) args.push(`template=${template}`);
+    if (content) args.push(`content=${content}`);
+    return runTool(args);
   },
 );
 
 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"),
@@ -368,57 +318,103 @@ server.tool(
     path: z.string().optional().describe("File path"),
   },
   async ({ name, value, file, path: filePath }) => {
-    const target = file ? `file="${file}"` : filePath ? `path="${filePath}"` : "";
-    if (!target) return text("Error: provide file= or path=");
-    return runTool(`property:set name="${name}" value="${value.replace(/"/g, '\\"')}" ${target}`);
+    if (!file && !filePath) return text("Error: provide file= or path=");
+    const args = ["property:set", `name=${name}`, `value=${value}`];
+    if (file) args.push(`file=${file}`);
+    if (filePath) args.push(`path=${filePath}`);
+    return runTool(args);
   },
 );
 
 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"),
   },
   async ({ file, path }) => {
-    const target = file ? `file="${file}"` : path ? `path="${path}"` : "";
-    return runTool(`backlinks ${target} counts`);
+    const args = ["backlinks"];
+    if (file) args.push(`file=${file}`);
+    if (path) args.push(`path=${path}`);
+    args.push("counts");
+    return runTool(args);
   },
 );
 
 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"),
   },
   async ({ folder, ext }) => {
-    let cmd = "files";
-    if (folder) cmd += ` folder="${folder}"`;
-    if (ext) cmd += ` ext=${ext}`;
-    return runTool(cmd);
+    const args = ["files"];
+    if (folder) args.push(`folder=${folder}`);
+    if (ext) args.push(`ext=${ext}`);
+    return runTool(args);
   },
 );
 
 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() {
-  const { running, version } = await checkObsidianRunning();
+  const running = await checkObsidianRunning();
   if (!running) {
     console.error("Error: Obsidian is not running. Please open Obsidian and try again.");
     process.exit(1);
   }
   const transport = new StdioServerTransport();
-  console.error(`obsidian-mcp server running on stdio (Obsidian ${version})`);
+  console.error("obsidian-mcp server running on stdio");
   await server.connect(transport);
 }
 

package/.claude/settings.local.json

@@ -1,15 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(node:*)",
-      "Bash(git checkout:*)",
-      "Bash(git push:*)",
-      "Bash(gh api:*)",
-      "Bash(gh pr:*)",
-      "Bash(git pull:*)",
-      "Bash(git stash:*)",
-      "Bash(npm version:*)",
-      "Bash(npm publish:*)"
-    ]
-  }
-}