obsidian-mcp-server/CHANGELOG.md

Changelog

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

[1.1.0] - 2025-10-16

🎯 Phase 1.1: Path Normalization & Error Handling

This release focuses on robustness, cross-platform compatibility, and significantly improved error messages.

Added

Path Utilities (src/utils/path-utils.ts)

• PathUtils.normalizePath() - Cross-platform path normalization (Windows/macOS/Linux)
• PathUtils.isValidVaultPath() - Path validation with security checks
• PathUtils.resolveFile() / resolveFolder() - Type-safe path resolution
• PathUtils.fileExists() / folderExists() - Existence checking
• PathUtils.getPathType() - Determine if path is file or folder
• PathUtils.ensureMarkdownExtension() - Auto-add .md extension
• PathUtils.getParentPath() / getBasename() - Path manipulation
• PathUtils.joinPath() - Safe path joining
• Handles backslashes, drive letters, trailing slashes automatically
• Prevents directory traversal attacks (.. paths)

Enhanced Error Messages (src/utils/error-messages.ts)

• Context-aware error messages with troubleshooting tips
• Dynamic list_notes() suggestions based on path context
• Operation-specific guidance (read, create, update, delete)
• Clear examples of correct path formats
• Platform-specific notes (case sensitivity on macOS/Linux)
• ErrorMessages.fileNotFound() - File not found with discovery tips
• ErrorMessages.folderNotFound() - Folder not found with navigation tips
• ErrorMessages.invalidPath() - Invalid path with format examples
• ErrorMessages.pathAlreadyExists() - Conflict resolution guidance
• ErrorMessages.parentFolderNotFound() - Parent folder missing with verification steps
• ErrorMessages.cannotDeleteFolder() - Folder deletion attempt with alternatives
• ErrorMessages.notAFile() / notAFolder() - Type mismatch errors
• ErrorMessages.operationFailed() - Generic operation failures

Testing Infrastructure

• Jest testing framework configured
• 43 unit tests for PathUtils (all passing)
• Mock Obsidian API for testing (tests/__mocks__/obsidian.ts)
• Test coverage for cross-platform path handling
• Integration tests with mock App/Vault
• npm test / npm run test:watch / npm run test:coverage scripts

Documentation

• docs/TOOL_SELECTION_GUIDE.md - Comprehensive 400+ line guide
  • Decision table for tool selection
  • Path format guidelines (correct vs incorrect)
  • Common scenarios with step-by-step examples
  • Troubleshooting decision tree
  • Best practices checklist
  • Quick reference card
• docs/ERROR_MESSAGE_IMPROVEMENTS.md - Error message enhancement documentation
• docs/TOOL_DESCRIPTION_IMPROVEMENTS.md - AI agent tool description improvements
• tests/README.md - Testing setup and guidelines
• PHASE_1.1_IMPLEMENTATION.md - Complete implementation summary

Changed

All Tool Implementations Enhanced

• readNote() - Path validation, better error messages, folder detection
• createNote() - Path normalization, conflict detection, parent folder validation
• updateNote() - Enhanced validation, clearer error messages
• deleteNote() - Folder detection with specific error message
• listNotes() - Path validation, folder verification, better errors

Tool Descriptions for AI Agents

• All 7 MCP tool descriptions significantly enhanced
• Critical constraints stated upfront (e.g., "only files, NOT folders")
• Workflow guidance (e.g., "use list_notes() first if unsure")
• Path requirements clearly documented in every parameter
• Multiple concrete examples per tool
• Failure modes explicitly stated
• Self-documenting for AI agents without external docs

Error Message Consistency

• All errors now include vault-relative path reminders
• Case sensitivity noted for macOS/Linux
• Context-specific list_notes() commands
• Operation-appropriate tool suggestions
• Consistent formatting across all tools

Fixed

• Cross-platform paths - Windows backslashes now handled correctly
• Path validation - Prevents invalid characters and directory traversal
• Delete folder error - Now clearly states "cannot delete folders" instead of confusing message
• Parent folder detection - Clear message when parent folder missing during create
• Error message contradictions - All error headers and bodies now consistent

Technical Details

New Dependencies

• jest: ^29.x (dev)
• @types/jest: ^29.x (dev)
• ts-jest: ^29.x (dev)

Test Coverage

• 43 unit tests passing
• PathUtils: 100% coverage
• Cross-platform scenarios tested
• Mock Obsidian API for isolated testing

Build

• All TypeScript compilation successful
• No breaking changes to existing APIs
• Backward compatible with v1.0.0

Developer Experience

• Centralized path handling logic
• Type-safe path operations
• Comprehensive test suite
• Clear error messages reduce support burden
• Self-documenting code

---

[1.0.0] - 2025-10-16

🎉 Initial Release

Added

Core Features

• MCP (Model Context Protocol) server implementation
• HTTP transport with Express.js
• JSON-RPC 2.0 message handling
• Protocol version 2024-11-05 support

MCP Tools

• read_note - Read note content from vault
• create_note - Create new notes
• update_note - Update existing notes
• delete_note - Delete notes
• search_notes - Search notes by content or filename
• list_notes - List all notes or notes in specific folder
• get_vault_info - Get vault metadata and statistics

Server Features

• Configurable HTTP server (default port: 3000)
• Localhost-only binding (127.0.0.1)
• Health check endpoint (/health)
• MCP endpoint (/mcp)
• Auto-start option

Security

• Origin header validation (DNS rebinding protection)
• Optional Bearer token authentication
• CORS configuration with allowed origins
• Request validation and error handling

User Interface

• Settings panel with full configuration
• Status bar indicator showing server state
• Ribbon icon for quick server toggle
• Start/Stop/Restart commands
• Real-time server status display
• Connection information display

Documentation

• Comprehensive README with examples
• Quick Start Guide
• Implementation Summary
• Test client script
• Example MCP requests
• Security considerations

Developer Tools

• TypeScript implementation
• esbuild bundler
• Test client for validation
• Health check endpoint

Technical Details

Dependencies

• express: ^4.18.2
• cors: ^2.8.5
• obsidian: latest

Build

• TypeScript 4.7.4
• esbuild 0.17.3
• Output: 828KB bundled

Compatibility

• Obsidian minimum version: 0.15.0
• Desktop only (requires Node.js HTTP server)
• Protocol: MCP 2024-11-05

Known Limitations

• Desktop only (not available on mobile)
• Single vault per server instance
• No WebSocket support (HTTP only)
• No SSL/TLS (localhost only)

---

Future Roadmap

See ROADMAP.md for detailed implementation plans.

Phase 1: Foundation (P0-P1)

• Path Normalization - Consistent path handling across platforms
• Error Message Improvements - Clear, actionable error messages with troubleshooting tips
• Enhanced Authentication - Secure API key management, multiple keys with labels, expiration, rate limiting, audit logging, and permission scopes
• API Unification - Standardize parameter naming and return structured, typed results
• Discovery Endpoints - Add stat and exists tools for exploring vault structure

Phase 2: Enhanced Operations (P1-P2)

• Write Operations & Concurrency - ETag-based version control, partial updates (frontmatter, sections)
• Conflict Resolution - Create notes with conflict strategies (error, overwrite, rename)
• File Rename/Move - Rename or move files with automatic wikilink updates
• Enhanced List Operations - Filtering, recursion control, pagination, frontmatter summaries
• Advanced Search - Regex search, snippet extraction, glob filtering

Phase 3: Advanced Features (P2-P3)

• Frontmatter Parsing - Read and update frontmatter without modifying content
• Linking & Backlinks - Wikilink validation, resolution, and backlink queries
• Waypoint Support - Tools for working with Waypoint plugin markers
• Excalidraw Support - Specialized tool for reading Excalidraw drawings

Future Considerations

• Resources API - Expose notes as MCP resources
• Prompts API - Templated prompts for common operations
• Batch Operations - Multiple operations in single request
• WebSocket Transport - Real-time updates and notifications
• Graph API - Enhanced graph visualization and traversal
• Tag & Canvas APIs - Query tags and manipulate canvas files
• Dataview Integration - Query vault using Dataview syntax
• Performance Enhancements - Indexing, caching, streaming for large vaults

---

Version History

Version	Date	Notes
1.1.0	2025-10-16	Phase 1.1: Path normalization, enhanced error messages, testing infrastructure
1.0.0	2025-10-16	Initial release

---

Upgrade Guide

From 1.0.0 to 1.1.0

This is a backward-compatible update. Simply update the plugin:

1. Backup your settings (optional, but recommended)
2. Update the plugin files
3. Restart Obsidian or reload the plugin

What's New:

• Better error messages with troubleshooting tips
• Improved cross-platform path handling
• Enhanced tool descriptions for AI agents
• No configuration changes required

Breaking Changes: None - fully backward compatible

From Development to 1.0.0

If you were using a development version:

1. Backup your settings
2. Disable the plugin
3. Delete the old plugin folder
4. Install version 1.0.0
5. Re-enable and reconfigure

Breaking Changes

None (initial release)

---

Support

For issues, questions, or contributions:

• Check the README.md for documentation
• Review QUICKSTART.md for setup help
• Check existing issues before creating new ones
• Include version number in bug reports

---

Credits

• MCP Protocol: https://modelcontextprotocol.io
• Obsidian API: https://github.com/obsidianmd/obsidian-api
• Built with TypeScript, Express.js, and ❤️