obsidian-mcp-server/CHANGELOG.md

Changelog

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

[1.2.0] - 2025-10-16

📁 Enhanced Parent Folder Detection (Phase 1.5)

Improved create_note tool with explicit parent folder validation and optional automatic folder creation.

Added

Parent Folder Validation (src/tools/note-tools.ts)

• Explicit parent folder detection before file creation (fail-fast)
• New createParents parameter for automatic folder creation
• Recursive parent folder creation for deeply nested paths
• Validates parent is a folder (not a file)
• Clear error messages with actionable guidance

Tool Schema Updates (src/tools/index.ts)

• Added createParents boolean parameter to create_note tool
• Default: false (safe behavior - requires parent folders to exist)
• Optional: true (convenience - auto-creates missing parent folders)
• Updated tool description with usage examples

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

• parentFolderNotFound() now suggests using createParents: true
• Provides example usage with auto-creation
• Computes grandparent path for better list_notes() suggestions
• Clear troubleshooting steps for missing parent folders

Comprehensive Test Suite (tests/parent-folder-detection.test.ts)

• 15 test cases covering all scenarios
• Tests explicit parent folder detection
• Tests recursive folder creation
• Tests error handling and edge cases
• Validates error message content

Changed

• createNote() signature: added optional createParents parameter
• Parent folder validation now happens before file creation attempt
• Error messages include createParents usage examples

Benefits

• Fail-fast behavior: Errors detected before attempting file creation
• Flexibility: Optional auto-creation with createParents: true
• Robustness: Handles deeply nested paths and all edge cases
• Backward compatible: Existing code continues to work (default: false)

🔐 Enhanced Authentication & Security (Phase 1.5)

This update significantly improves authentication security and user experience with automatic key generation and enhanced UI.

Added

Automatic API Key Generation (src/utils/auth-utils.ts)

• generateApiKey() - Cryptographically secure random key generation (32 characters)
• validateApiKey() - API key validation with strength requirements
• Uses crypto.getRandomValues() for secure randomness
• Alphanumeric + special characters (-, _) for URL-safe keys

Enhanced Settings UI (src/settings.ts)

• Auto-generate API key when authentication is enabled
• Copy to clipboard button for API key
• Regenerate key button with instant refresh
• Static, selectable API key display (full width)
• MCP client configuration snippet generator
  • Dynamically includes/excludes Authorization header based on auth status
  • Correct mcpServers format with serverUrl field
  • Copy configuration button for one-click copying
  • Partially selectable text for easy copying
• Restart warnings when authentication settings change
• Selectable connection information URLs

Security Improvements (src/server/middleware.ts)

• Defensive authentication check: rejects requests if auth enabled but no key set
• Improved error messages for authentication failures
• Fail-secure design: blocks access when misconfigured

Server Validation (src/main.ts)

• Prevents server start if authentication enabled without API key
• Clear error message guiding users to fix configuration
• Validation runs before server initialization

Changed

• API key field changed from user-editable to auto-generated display
• Configuration snippet now shows for both authenticated and non-authenticated setups
• Connection information URLs are now selectable

Security

• Fixed vulnerability where enabling authentication without API key allowed unrestricted access
• Three-layer defense: UI validation, server start validation, and middleware enforcement
• API keys are now always cryptographically secure (no weak user-chosen keys)

[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 ❤️