# Changelog

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

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [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.2.0] - 2026-04-30

### Added
- **Binary file support in `obsidian_read_note`**: Binary files are now read directly from the filesystem, bypassing the Obsidian CLI which does not support binary output
  - Uses `obsidian vault info=path` to resolve the vault root filesystem path
  - Uses `obsidian file file=<name>` to resolve wikilink-style names to vault-relative paths
  - Images (PNG, JPG, JPEG, GIF, WEBP, SVG) returned as MCP image content `{ type: "image", data, mimeType }`
  - Other binary files (PDF, ZIP, DOCX, XLSX, PPTX, etc.) returned as MCP embedded resource `{ type: "resource", resource: { uri, mimeType, blob } }`
  - Unknown extensions fall through to the CLI with a runtime binary detection fallback

## [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)

[1.1.8]: https://git.mortons.site/Peter.Morton/obsidian-mcp/releases/tag/v1.1.8
[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
[1.1.2]: https://git.mortons.site/Peter.Morton/obsidian-mcp/releases/tag/v1.1.2
[1.1.1]: https://git.mortons.site/Peter.Morton/obsidian-mcp/releases/tag/v1.1.1
[1.1.0]: https://git.mortons.site/Peter.Morton/obsidian-mcp/releases/tag/v1.1.0
[1.0.0]: https://git.mortons.site/Peter.Morton/obsidian-mcp/releases/tag/v1.0.0