chore: bump version to 1.1.7 and update CHANGELOG

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

CHANGELOG.md

@@ -73,6 +73,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Comprehensive input schema definitions
 - Security audit of parameter handling
 
+## [1.1.7] - 2026-04-30
+
+### Fixed
+- **Binary file support in `obsidian_read_note`**: Fixed issue #9 where reading binary files (ZIP, images, compiled files, etc.) returned corrupted content due to UTF-8 decoding of raw bytes
+  - stdout is now collected as a raw `Buffer` to preserve bytes before any decoding
+  - Binary files are detected via null byte check and >10% non-printable byte ratio on first 8KB
+  - Binary content is returned as a `BASE64:<base64string>` — clients must base64-decode the value to recover the original binary file
+  - Tool description updated to document the `BASE64:` prefix convention
+
+## [1.1.6] - 2026-04-30
+
+### Fixed
+- **`obsidian_create_note` parameter semantics**: Fixed issue #8 where ambiguous `path` description led callers to pass the full file path (including filename) in `path`, causing the CLI to misbehave and the `overwrite` flag to auto-suffix filenames instead of replacing them
+  - `name` is now clearly documented as the **filename only** (e.g. `"My Note.md"`)
+  - `path` is now clearly documented as the **folder only** (e.g. `"Projects/Work"`) — never include the filename
+  - Added `required: ['name']` to the input schema
+
 ## [1.1.5] - 2026-04-28
 
 ### Fixed
@@ -143,6 +160,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Version History
 
+- **1.1.7** - Bug fix release: Binary files returned as base64 in `obsidian_read_note` (fixes #9)
+- **1.1.6** - Bug fix release: Clarify `name` vs `path` semantics in `obsidian_create_note` (fixes #8)
 - **1.1.5** - Bug fix release: Preserve `<` and `>` in note content for Mermaid/HTML (fixes #7)
 - **1.1.4** - Bug fix release: Preserve Markdown code fences (fixes #6)
 - **1.1.3** - Bug fix release: Large file chunking for obsidian_read_note; docs clarification for Obsidian must be running (fixes #4, #5)
@@ -154,6 +173,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Search & Discovery (12 tools)
   - Task & Property Management (8 tools)
 
+[1.1.7]: https://git.mortons.site/Peter.Morton/obsidian-mcp/releases/tag/v1.1.7
+[1.1.6]: https://git.mortons.site/Peter.Morton/obsidian-mcp/releases/tag/v1.1.6
 [1.1.5]: https://git.mortons.site/Peter.Morton/obsidian-mcp/releases/tag/v1.1.5
 [1.1.4]: https://git.mortons.site/Peter.Morton/obsidian-mcp/releases/tag/v1.1.4
 [1.1.3]: https://git.mortons.site/Peter.Morton/obsidian-mcp/releases/tag/v1.1.3

manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": "0.3",
   "name": "obsidian-mcp",
-  "version": "1.1.5",
+  "version": "1.1.7",
   "display_name": "Obsidian CLI Bundle",
   "description": "MCP Bundle for Obsidian CLI - Enable AI assistants to manage Obsidian vaults through conversational interface",
   "long_description": "This MCP bundle provides a comprehensive set of tools for AI assistants to interact with and manage Obsidian vaults. It includes capabilities for creating, reading, updating, and deleting notes, managing links and tags, handling tasks, and more. With this bundle, AI assistants can seamlessly integrate with Obsidian to help users organize their knowledge and workflows.",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "obsidian-mcp",
-  "version": "1.1.5",
+  "version": "1.1.7",
   "description": "MCP Bundle for Obsidian CLI - Enable AI assistants to manage Obsidian vaults through Model Context Protocol",
   "type": "module",
   "main": "dist/index.js",

src/cli/executor.ts

@@ -93,8 +93,81 @@ export async function executeCommand(cmd: CLICommand): Promise<CLIResult> {
 }
 
 /**
- * Execute Obsidian CLI command with vault context
+ * Execute an Obsidian CLI command with timeout, collecting stdout as a raw Buffer.
+ * Use this when the output may be binary (e.g. reading non-text vault files).
  */
+export async function executeCommandBinary(cmd: CLICommand): Promise<CLIResult> {
+  const timeout = cmd.timeout || getCommandTimeout(cmd.command);
+
+  return new Promise((resolve) => {
+    const child = spawn(cmd.command, cmd.args, {
+      cwd: cmd.cwd || process.cwd(),
+      shell: true,
+    });
+
+    const stdoutChunks: Buffer[] = [];
+    let stderr = '';
+    let timedOut = false;
+
+    const timeoutId = setTimeout(() => {
+      timedOut = true;
+      child.kill('SIGTERM');
+      logger.warn('CLI command timed out', { command: cmd.command, timeout });
+    }, timeout);
+
+    child.stdout?.on('data', (data: Buffer) => {
+      stdoutChunks.push(Buffer.isBuffer(data) ? data : Buffer.from(data));
+    });
+
+    child.stderr?.on('data', (data) => {
+      stderr += data.toString();
+    });
+
+    child.on('close', (code) => {
+      clearTimeout(timeoutId);
+      const stdoutBuffer = Buffer.concat(stdoutChunks);
+      resolve({
+        stdout: stdoutBuffer.toString('utf8').trim(),
+        stdoutBuffer,
+        stderr: stderr.trim(),
+        exitCode: code || 0,
+        timedOut,
+      });
+    });
+
+    child.on('error', (error) => {
+      clearTimeout(timeoutId);
+      logger.error('CLI command spawn error', { error: error.message });
+      resolve({
+        stdout: '',
+        stdoutBuffer: Buffer.alloc(0),
+        stderr: error.message,
+        exitCode: 1,
+        timedOut: false,
+      });
+    });
+  });
+}
+
+/**
+ * Execute Obsidian CLI command with vault context, collecting stdout as a raw Buffer.
+ */
+export async function executeObsidianCommandBinary(
+  subcommand: string,
+  args: string[] = [],
+  options?: { timeout?: number }
+): Promise<CLIResult> {
+  const vaultName = process.env.OBSIDIAN_VAULT;
+  if (!vaultName) {
+    throw new Error('OBSIDIAN_VAULT environment variable not set');
+  }
+  const fullArgs = [subcommand, '--vault', vaultName, ...args];
+  return executeCommandBinary({
+    command: '/Applications/Obsidian.app/Contents/MacOS/obsidian',
+    args: fullArgs,
+    timeout: options?.timeout,
+  });
+}
 export async function executeObsidianCommand(
   subcommand: string,
   args: string[] = [],

src/tools/file-operations.ts

@@ -4,7 +4,7 @@
  */
 
 import { ObsidianMCPServer, createToolHandler } from '../server.js';
-import { executeObsidianCommand } from '../cli/executor.js';
+import { executeObsidianCommand, executeObsidianCommandBinary } from '../cli/executor.js';
 import { formatForMCP } from '../cli/parser.js';
 import { handleCLIResult } from '../utils/error-handler.js';
 import { logger } from '../utils/logger.js';
@@ -19,6 +19,27 @@ import {
 import { sanitizeParameters } from '../validation/sanitizer.js';
 import { formatParam } from '../utils/cli-helpers.js';
 
+/**
+ * Detect binary content from a raw Buffer.
+ * Checks for null bytes (definitive binary marker) or a high ratio of
+ * non-printable characters in the first 8KB (catches ZIP, images, compiled files, etc.).
+ */
+function isBinaryContent(buf: Buffer): boolean {
+  if (buf.length === 0) return false;
+  const sample = buf.slice(0, 8192);
+  // Null bytes are never present in valid UTF-8 text
+  if (sample.includes(0x00)) return true;
+  let nonPrintable = 0;
+  for (let i = 0; i < sample.length; i++) {
+    const byte = sample[i];
+    // Allow tab (9), newline (10), carriage return (13), and standard printable ASCII
+    if (byte !== 9 && byte !== 10 && byte !== 13 && (byte < 32 || byte === 127)) {
+      nonPrintable++;
+    }
+  }
+  return nonPrintable / sample.length > 0.1;
+}
+
 /**
  * Register all file operation tools
  */
@@ -28,17 +49,18 @@ export async function registerFileOperationTools(server: ObsidianMCPServer): Pro
   // T029: Create note tool
   server.registerTool(
     'obsidian_create_note',
-    'Create a new note in the Obsidian vault. Optionally specify path, content, template, and whether to overwrite existing notes or open after creation.',
+    'Create a new note in the Obsidian vault. "name" is the filename only (e.g. "My Note.md"). "path" is the folder only (e.g. "Projects/Work") — do not include the filename in path. When overwrite is true the existing file is replaced.',
     {
       type: 'object',
+      required: ['name'],
       properties: {
         name: {
           type: 'string',
-          description: 'File name for the new note',
+          description: 'Filename for the new note (e.g. "My Note.md"). Do not include folder path here.',
         },
         path: {
           type: 'string',
-          description: 'Full file path (alternative to name)',
+          description: 'Folder path where the note will be created (e.g. "Projects/Work"). Do not include the filename here. Omit for vault root.',
         },
         content: {
           type: 'string',
@@ -50,7 +72,7 @@ export async function registerFileOperationTools(server: ObsidianMCPServer): Pro
         },
         overwrite: {
           type: 'boolean',
-          description: 'Overwrite if file exists (optional)',
+          description: 'Replace the file if it already exists (optional)',
         },
         open: {
           type: 'boolean',
@@ -66,14 +88,15 @@ export async function registerFileOperationTools(server: ObsidianMCPServer): Pro
       'Create a new note in the Obsidian vault',
       {
         type: 'object',
+        required: ['name'],
         properties: {
           name: {
             type: 'string',
-            description: 'File name for the new note',
+            description: 'Filename for the new note (e.g. "My Note.md"). Do not include folder path here.',
           },
           path: {
             type: 'string',
-            description: 'Full file path (alternative to name)',
+            description: 'Folder path where the note will be created (e.g. "Projects/Work"). Do not include the filename here. Omit for vault root.',
           },
           content: {
             type: 'string',
@@ -85,7 +108,7 @@ export async function registerFileOperationTools(server: ObsidianMCPServer): Pro
           },
           overwrite: {
             type: 'boolean',
-            description: 'Overwrite if file exists (optional)',
+            description: 'Replace the file if it already exists (optional)',
           },
           open: {
             type: 'boolean',
@@ -102,8 +125,6 @@ export async function registerFileOperationTools(server: ObsidianMCPServer): Pro
         const sanitized = sanitizeParameters(validated) as any;
 
         const cmdArgs: string[] = [];
-        
-        // Add name or path parameter
         if (sanitized.name) cmdArgs.push(formatParam('name', sanitized.name as string));
         if (sanitized.path) cmdArgs.push(formatParam('path', sanitized.path as string));
         if (sanitized.content) cmdArgs.push(formatParam('content', sanitized.content as string));
@@ -130,7 +151,7 @@ export async function registerFileOperationTools(server: ObsidianMCPServer): Pro
   // T031: Read note tool
   server.registerTool(
     'obsidian_read_note',
-    'Read the content of a note from the Obsidian vault. Specify either the note name (file) or full path (path). For large files (e.g. PDFs), use max_chars and offset to read in chunks and avoid exceeding context limits.',
+    'Read the content of a note from the Obsidian vault. Specify either the note name (file) or full path (path). For large files (e.g. PDFs), use max_chars and offset to read in chunks and avoid exceeding context limits. Binary files (ZIP, images, compiled files, etc.) are automatically detected and returned as a base64-encoded string prefixed with "BASE64:" — the client must base64-decode the value to recover the original binary content.',
     {
       type: 'object',
       properties: {
@@ -153,7 +174,7 @@ export async function registerFileOperationTools(server: ObsidianMCPServer): Pro
       },
     },
     createToolHandler(
-      'Read the content of a note',
+      'Read the content of a note. Binary files are returned as a base64-encoded string prefixed with "BASE64:" — decode it to recover the original binary content.',
       {
         type: 'object',
         properties: {
@@ -183,14 +204,28 @@ export async function registerFileOperationTools(server: ObsidianMCPServer): Pro
         if (sanitized.file) cmdArgs.push(formatParam('file', sanitized.file as string));
         if (sanitized.path) cmdArgs.push(formatParam('path', sanitized.path as string));
 
-        const result = await executeObsidianCommand('read', cmdArgs);
+        // Use binary-safe executor so stdout is collected as a raw Buffer,
+        // preventing UTF-8 decoding from corrupting binary file content.
+        const result = await executeObsidianCommandBinary('read', cmdArgs);
         handleCLIResult(result, { operation: 'read_note', identifier: sanitized.file || sanitized.path });
 
+        // Detect binary content from the raw buffer and return as base64
+        if (result.stdoutBuffer && isBinaryContent(result.stdoutBuffer)) {
+          return {
+            content: [
+              {
+                type: 'text',
+                text: `BASE64:${result.stdoutBuffer.toString('base64')}`,
+              },
+            ],
+          };
+        }
+
         const offset: number = validated.offset ?? 0;
         const maxChars: number = validated.max_chars ?? 50000;
-        const fullContent = result.stdout;
+        const raw = result.stdout;
-        const totalChars = fullContent.length;
+        const totalChars = raw.length;
-        const chunk = fullContent.slice(offset, offset + maxChars);
+        const chunk = raw.slice(offset, offset + maxChars);
         const isTruncated = offset + maxChars < totalChars;
 
         let text = chunk;

src/utils/types.ts

@@ -63,6 +63,7 @@ export enum ObsidianErrorType {
  */
 export interface CLIResult {
   stdout: string;
+  stdoutBuffer?: Buffer;
   stderr: string;
   exitCode: number;
   timedOut?: boolean;