obsidian-mcp-server/RELEASE_NOTES_v1.1.0.md

Release Notes: Version 1.1.0

Release Date: October 16, 2025
Type: Minor Version (Feature Release)
Compatibility: Fully backward compatible with v1.0.0

🎯 Overview

Version 1.1.0 implements Phase 1.1 of the roadmap, focusing on robustness, cross-platform compatibility, and significantly improved user experience through enhanced error messages and path handling.

✨ What's New

Path Normalization & Validation

Cross-platform path handling that works seamlessly on Windows, macOS, and Linux:

• Automatic conversion of backslashes to forward slashes
• Windows drive letter handling
• Leading/trailing slash normalization
• Security: Prevents directory traversal attacks
• Case sensitivity awareness (macOS/Linux vs Windows)

Enhanced Error Messages

Actionable error messages that help users fix issues quickly:

• Context-aware troubleshooting tips
• Dynamic suggestions (e.g., "Use list_notes('folder') to see available files")
• Clear examples of correct path formats
• Platform-specific guidance
• Operation-specific recommendations

Example:

Parent folder does not exist: "projects/2024/q4"

Cannot create "projects/2024/q4/report.md" because its parent folder is missing.

Troubleshooting tips:
• Create the parent folder first using Obsidian
• Verify the folder path with list_notes("projects/2024")
• Check that the parent folder path is correct (vault-relative, case-sensitive on macOS/Linux)
• Note: Automatic parent folder creation is not currently enabled

Improved Tool Descriptions

AI agents now receive comprehensive guidance directly in the MCP schema:

• Critical constraints stated upfront
• Workflow suggestions (e.g., "use list_notes() first if unsure")
• Multiple concrete examples per tool
• Failure modes explicitly documented
• Self-documenting without external docs

Testing Infrastructure

Professional testing setup for reliability:

• Jest testing framework configured
• 43 unit tests (all passing)
• Mock Obsidian API for isolated testing
• Cross-platform test coverage
• Easy to run: npm test

Comprehensive Documentation

New documentation for users and developers:

• Tool Selection Guide (400+ lines) - Complete guide on choosing the right tool
• Error Message Improvements - Documentation of all enhancements
• Tool Description Improvements - AI agent guidance documentation
• Testing Guide - How to run and write tests
• Phase 1.1 Implementation Summary - Technical details

🔧 Technical Improvements

New Utilities

PathUtils class (src/utils/path-utils.ts):

• 15+ utility methods for path operations
• Type-safe file/folder resolution
• Existence checking
• Path manipulation (parent, basename, join)
• Markdown extension handling

ErrorMessages class (src/utils/error-messages.ts):

• 11 specialized error message generators
• Dynamic context-based suggestions
• Consistent formatting
• Reusable across all tools

Updated Tool Implementations

All tools now use the new utilities:

• ✅ readNote() - Enhanced validation and error messages
• ✅ createNote() - Parent folder validation, conflict detection
• ✅ updateNote() - Better error handling
• ✅ deleteNote() - Folder detection with clear error
• ✅ listNotes() - Path validation and verification

🐛 Bug Fixes

• Windows path handling - Backslashes now converted automatically
• Delete folder error - Clear message instead of confusing "not a folder" error
• Parent folder detection - Specific guidance when parent missing
• Error contradictions - All error messages now internally consistent
• Path validation - Prevents invalid characters and security issues

📊 Statistics

• New Files: 8 (utilities, tests, mocks, docs)
• Modified Files: 5 (tool implementations, package.json, manifest)
• Lines Added: ~2,500+
• Test Coverage: 43 tests, 100% PathUtils coverage
• Documentation: 1,000+ lines of new documentation

🚀 Upgrade Instructions

For Users

1. Backup settings (optional, but recommended)
2. Update plugin files to v1.1.0
3. Restart Obsidian or reload the plugin
4. No configuration changes needed - fully backward compatible

For Developers

1. Install new dev dependencies:

   npm install
   

2. Run tests:

   npm test
   

3. Build:

   npm run build
   

⚠️ Breaking Changes

None - Version 1.1.0 is fully backward compatible with v1.0.0.

All existing integrations will continue to work without modification. The improvements are additive and enhance the existing functionality.

📈 Roadmap Progress

Completed ✅

• Phase 1.1 - Path Normalization & Error Handling (100%)
  • Path utilities ✅
  • Enhanced error messages ✅
  • Tool implementation updates ✅
  • Testing infrastructure ✅

Next Up 🔜

• Phase 1.5 - Enhanced Authentication & Security

  • Secure API key management
  • Multiple API keys with labels
  • Key expiration and rotation
  • Rate limiting
  • Audit logging

• Phase 2 - API Unification & Typed Results

  • Standardize parameter naming
  • Structured, typed responses
  • Better consistency

🎓 Learning Resources

New Documentation

• Read docs/TOOL_SELECTION_GUIDE.md for comprehensive tool usage guide
• Check docs/ERROR_MESSAGE_IMPROVEMENTS.md for error message details
• See tests/README.md for testing setup and guidelines

Quick Reference

┌─────────────────────────────────────────────────────────┐
│  OBSIDIAN MCP TOOL QUICK REFERENCE                      │
├─────────────────────────────────────────────────────────┤
│  List folder:    list_notes("folder")                   │
│  Read file:      read_note("folder/file.md")            │
│  Create file:    create_note("path.md", "content")      │
│  Update file:    update_note("path.md", "new content")  │
│  Delete file:    delete_note("path.md")                 │
│  Search:         search_notes("query")                  │
│  Vault info:     get_vault_info()                       │
├─────────────────────────────────────────────────────────┤
│  ✓ Paths are vault-relative (no leading /)             │
│  ✓ Use forward slashes: folder/file.md                 │
│  ✓ Case-sensitive on macOS/Linux                       │
│  ✓ Include file extensions: .md, .png, etc.            │
└─────────────────────────────────────────────────────────┘

💡 Tips for AI Agents

If you're an AI agent using this plugin:

1. Always use list_notes() first when unsure about paths
2. Read before updating - Use read_note() then update_note() for partial changes
3. Verify parent folders - Use list_notes() to check folders exist before creating files
4. Pay attention to error messages - They include specific troubleshooting steps
5. Use vault-relative paths - No leading slashes, include file extensions

🙏 Acknowledgments

Thanks to all testers and users who provided feedback that shaped these improvements!

📞 Support

• Documentation: See README.md and docs/ folder
• Issues: Report bugs with version number (1.1.0)
• Questions: Check TOOL_SELECTION_GUIDE.md first

---

Full Changelog: See CHANGELOG.md for complete details.