obsidian-mcp/CHANGELOG.md

Changelog

All notable changes to the Obsidian MCP Bundle will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

1.0.0 - 2026-03-22

Added

File Operations (User Story 1)

• obsidian_create_note - Create new notes with optional content and frontmatter properties
• obsidian_read_note - Read note content by filename or path
• obsidian_append_to_note - Append content to existing notes
• obsidian_prepend_to_note - Prepend content to existing notes
• obsidian_delete_note - Delete notes from vault
• obsidian_move_note - Move notes to different folders
• obsidian_rename_note - Rename note files
• obsidian_open_note - Open notes in Obsidian application

Search & Discovery (User Story 2)

• obsidian_search - Full-text search with query filters, path scoping, case sensitivity, and format options (text/json)
• obsidian_get_backlinks - Find all notes linking to a specific note
• obsidian_list_outgoing_links - List all links from a note to other notes
• obsidian_list_unresolved_links - Identify broken/non-existent links across vault
• obsidian_list_tags - List all tags in vault or specific note
• obsidian_search_by_tag - Find notes containing specific tags
• obsidian_get_tag_count - Count usage of specific tags
• obsidian_list_aliases - List all aliases in vault or per note
• obsidian_list_properties - List all frontmatter properties used in vault
• obsidian_get_property_count - Count usage of specific properties

Task Management (User Story 3)

• obsidian_list_tasks - List tasks with filtering by status, file, path, tags; supports multiple output formats
• obsidian_toggle_task - Toggle task completion status between done and todo
• obsidian_mark_task_done - Mark tasks as completed
• obsidian_mark_task_todo - Mark tasks as incomplete
• obsidian_update_task_status - Set custom task status characters (-, >, !, ?, etc.)

Property Management (User Story 3)

• obsidian_get_property - Read single property value from a file
• obsidian_set_property - Set or update frontmatter properties with type specification
• obsidian_remove_property - Remove properties from files

Infrastructure

• MCP Protocol: Full compliance with Model Context Protocol via @modelcontextprotocol/sdk
• MCPB Bundle: Conforms to MCPB specification v0.3 with complete manifest
• Validation: Zod schemas for all tool inputs with runtime type checking
• Error Handling: Consistent error responses with actionable messages
• Security: Input sanitization and parameter validation for all tools
• Timeout Management: 30-second timeout for CLI operations
• Parameter Quoting: Automatic quoting for filenames/values containing spaces
• Logging: stderr-only logging with sensitive data sanitization

Technical Details

• TypeScript: Fully typed codebase with strict mode enabled
• Node.js: ES2022 module format with ESNext target
• Transport: stdio JSON-RPC for MCP communication
• CLI Integration: Wrapper for Obsidian CLI with proper parameter formatting
• Bundle Format: .mcpb packaging with manifest, icons, and compiled code

Documentation

• Complete README with installation instructions for Claude Desktop extensions
• Manifest with detailed tool descriptions and parameter schemas
• Input validation and error documentation
• Development and testing guidelines

Quality

• Zero TypeScript compilation errors
• MCPB manifest validation passes
• All tools tested with Obsidian CLI
• Comprehensive input schema definitions
• Security audit of parameter handling

[1.1.9] - 2026-04-30

Fixed

• Images returned as MCP image content type: Updated binary file handling so image files (PNG, JPG, JPEG, GIF, WEBP, SVG) are returned as { type: "image", data: "<base64>", mimeType: "..." } per the MCP 2025-11-25 spec for image content in tool results
  • Non-image binary files (PDF, ZIP, DOCX, etc.) continue to use the embedded resource format { type: "resource", resource: { uri, mimeType, blob } }

1.1.8 - 2026-04-30

Fixed

• Binary files returned as MCP embedded resource: Updated issue #9 fix to use the proper MCP EmbeddedResource format instead of a BASE64: text prefix
  • Binary files are now returned as { type: "resource", resource: { uri, mimeType, blob } }
  • uri is constructed as obsidian://<vault>/<path>
  • mimeType is detected from the file extension (PDF, ZIP, images, Office formats, audio/video; defaults to application/octet-stream)
  • blob contains the base64-encoded raw bytes

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

• Mermaid Arrows and HTML Preserved: Fixed issue #7 where < and > were being stripped from note content, breaking Mermaid diagram connectors (->>, -->, <|, >>) and HTML tags
  • < and > are only meaningful as shell redirects at the command level — inside double-quoted strings (how all values are passed) they are completely inert
  • Removed from DANGEROUS_CHARS in both sanitizeString and sanitizePath

1.1.4 - 2026-04-28

Fixed

• Markdown Code Fence Preservation: Fixed issue #6 where backticks were being stripped from note content, destroying Markdown code fences (```)
  • Backticks are now escaped as \` inside double-quoted CLI parameter strings instead of being removed
  • This preserves code fences and inline code in note content while still preventing shell command substitution via backticks
  • Affects all tools that pass content: create, append, prepend, etc.

1.1.3 - 2026-04-17

Fixed

• Large File Chunking: Fixed issue #5 where reading large files (e.g. PDFs) caused a "Tool result is too large" error in Claude Desktop
  • obsidian_read_note now returns at most 50,000 characters by default (configurable up to 500,000)
  • New max_chars parameter caps the number of characters returned per call (default: 50000, max: 500000)
  • New offset parameter enables pagination — pass the offset from the truncation message to read the next chunk
  • When truncated, the response includes a message stating the total size and the exact offset to use for the next call

Documentation

• Obsidian Must Be Running: Clarified in README (issue #4) that the Obsidian application must be open and running before any MCP tools are used
  • Added prominent callout in Prerequisites section
  • Expanded Troubleshooting entry with explanation of root cause and fix

1.1.2 - 2026-04-14

Fixed

• Ampersand in Filenames: Fixed issue #2 where files with & in their names (e.g., "Research & Development.md") were causing search and file-not-found errors
  • Single ampersands are now preserved in filenames and paths
  • Security maintained: Dangerous && command operators are still blocked by injection pattern detection
  • Also preserves parentheses (), brackets [], and braces {} which are safe in quoted CLI arguments
  • Affects all file operations and search tools

1.1.1 - 2026-04-10

Fixed

• Quote Escaping: Fixed critical bug where note content was being truncated when containing double quotes
  • Content like "Bot QM" is now properly escaped and passed to the CLI without truncation
  • Internal double quotes are escaped as \" before being wrapped in parameter quotes
  • Prevents shell from misinterpreting quote boundaries in parameter values
  • Affects all tools that pass content: create, append, prepend, search queries, etc.

1.1.0 - 2026-04-10

Fixed

• Square Brackets Preservation: Fixed critical bug where square brackets [ and ] were being removed from note content during sanitization
  • Wikilinks ([[link]]) now work correctly when creating or modifying notes
  • Task checkboxes (- [ ] Task and - [x] Done) are properly preserved
  • Array notation and date formats with brackets are no longer corrupted
  • Security: Square brackets are safe because parameter values are quoted and passed as array arguments to the CLI
  • All dangerous shell metacharacters (;, |, $(), backticks, etc.) are still properly blocked

[Unreleased]

Planned

• Additional vault navigation tools (User Story 4 - deferred)
• Advanced features like templates and daily notes (User Story 5 - deferred)
• Performance optimizations for large vaults
• Expanded test coverage
• Multi-vault support enhancements

---

Version History

• 1.1.8 - Bug fix release: Binary files returned as MCP embedded resource (fixes #9)
• 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)
• 1.1.2 - Bug fix release: Ampersand support in filenames (fixes #2)
• 1.1.1 - Bug fix release: Quote escaping in note content
• 1.1.0 - Bug fix release: Square brackets preservation in note content
• 1.0.0 - Initial release with 28 MCP tools across 3 user stories
  • File Operations (8 tools)
  • Search & Discovery (12 tools)
  • Task & Property Management (8 tools)