obsidian-mcp-server 1.2.0 → 1.2.2

package/README.md

@@ -2,7 +2,7 @@
 
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue.svg)](https://www.typescriptlang.org/)
 [![Model Context Protocol](https://img.shields.io/badge/MCP-1.4.0-green.svg)](https://modelcontextprotocol.io/)
-[![Version](https://img.shields.io/badge/Version-1.2.0-blue.svg)]()
+[![Version](https://img.shields.io/badge/Version-1.2.2-blue.svg)]()
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 [![Status](https://img.shields.io/badge/Status-Stable-blue.svg)]()
 [![GitHub](https://img.shields.io/github/stars/cyanheads/obsidian-mcp-server?style=social)](https://github.com/cyanheads/obsidian-mcp-server)
@@ -16,25 +16,21 @@ Requires the Local REST API plugin in Obsidian.
 ## Features
 
 ### File Operations
-- Path-based file/directory management with atomic updates
-- Content read/write operations with validation
+- Atomic file/directory operations with validation
 - Resource monitoring and cleanup
 
 ### Search System
-- Full-text and JsonLogic-based complex search
-- Configurable context boundaries and token limits
-- Optimized query processing
+- Full-text and JsonLogic search with context control
+- Optimized query processing with token limits
 
 ### Property Management
-- YAML frontmatter parsing and validation
-- Intelligent property merging and updates
-- Automatic timestamp management
+- YAML frontmatter parsing and intelligent merging
+- Automatic timestamps (created by Obsidian, modified by server)
 - Custom field support
 
 ### Security & Performance
-- API key authentication and rate limiting
-- SSL verification options
-- Resource management and health monitoring
+- API key auth with rate limiting and SSL options
+- Resource monitoring and health checks
 
 ## Installation
 
@@ -138,9 +134,8 @@ obsidian_update_properties: {
   filepath: string,  // Path relative to vault root
   properties: {
     title?: string,
-    created?: string,  // ISO date
-    modified?: string, // ISO date (auto-updated)
     author?: string,
+    // Note: created/modified timestamps are managed automatically
     type?: Array<"concept" | "architecture" | "specification" | 
       "protocol" | "api" | "research" | "implementation" | 
       "guide" | "reference">,
@@ -161,28 +156,21 @@ obsidian_update_properties: {
 ## Best Practices
 
 ### File Operations
-- Use atomic operations
-- Validate content before modifications
-- Implement proper error handling
-- Monitor operation performance
+- Use atomic operations with validation
+- Handle errors and monitor performance
 
 ### Search Implementation
-- Optimize query specificity
-- Control context boundaries
-- Handle large result sets
-- Consider token limits
+- Optimize queries and control context size
+- Handle large results within token limits
 
 ### Property Management
-- Validate property values before updates
-- Use appropriate property types
-- Handle array merging appropriately
-- Consider custom field implications
+- Use appropriate types and validate updates
+- Handle arrays and custom fields properly
+- Never set timestamps (managed automatically)
 
 ### Error Prevention
-- Validate inputs thoroughly
-- Handle API errors gracefully
-- Monitor error patterns
-- Check rate limits
+- Validate inputs and handle errors gracefully
+- Monitor patterns and respect rate limits
 
 ## Contributing
 

package/build/propertyTools.js

@@ -13,13 +13,19 @@ export class GetPropertiesToolHandler extends BaseToolHandler {
     getToolDescription() {
         return {
             name: this.name,
-            description: "Get properties from an Obsidian note's frontmatter.",
+            description: "Get properties (title, tags, status, etc.) from an Obsidian note's YAML frontmatter. Returns all available properties including custom fields.",
             examples: [
                 {
                     description: "Get properties from a note",
                     args: {
                         filepath: "path/to/note.md"
                     }
+                },
+                {
+                    description: "Get properties from a documentation file",
+                    args: {
+                        filepath: "docs/architecture.md"
+                    }
                 }
             ],
             inputSchema: {
@@ -54,16 +60,40 @@ export class UpdatePropertiesToolHandler extends BaseToolHandler {
     getToolDescription() {
         return {
             name: this.name,
-            description: "Update properties in an Obsidian note's frontmatter.",
+            description: "Update properties in an Obsidian note's YAML frontmatter. Intelligently merges arrays (tags, type, status), handles custom fields, and automatically updates the modified timestamp. Existing properties not included in the update are preserved.",
             examples: [
                 {
-                    description: "Update note properties",
+                    description: "Update basic metadata",
                     args: {
                         filepath: "path/to/note.md",
                         properties: {
-                            title: "New Title",
-                            tags: ["#tag1", "#tag2"],
-                            status: ["in-progress"]
+                            title: "Architecture Overview",
+                            author: "Development Team",
+                            type: ["architecture", "specification"]
+                        }
+                    }
+                },
+                {
+                    description: "Update tags and status",
+                    args: {
+                        filepath: "docs/feature.md",
+                        properties: {
+                            tags: ["#feature", "#in-development", "#high-priority"],
+                            status: ["in-progress"],
+                            version: "2.0.0"
+                        }
+                    }
+                },
+                {
+                    description: "Add custom fields",
+                    args: {
+                        filepath: "projects/project-x.md",
+                        properties: {
+                            custom: {
+                                priority: "high",
+                                reviewedBy: ["Alice", "Bob"],
+                                dueDate: "2025-03-01"
+                            }
                         }
                     }
                 }

package/build/tools.js

@@ -101,11 +101,31 @@ export class ListFilesInVaultToolHandler extends BaseToolHandler {
     getToolDescription() {
         return {
             name: this.name,
-            description: "Lists all files and directories in the root directory of your Obsidian vault.",
+            description: "Lists all files and directories in the root directory of your Obsidian vault. Returns a hierarchical structure of files and folders, including metadata like file type.",
             examples: [
                 {
                     description: "List all files in vault",
                     args: {}
+                },
+                {
+                    description: "Example response",
+                    args: {},
+                    response: [
+                        {
+                            "path": "Daily Notes",
+                            "type": "folder",
+                            "children": [
+                                { "path": "Daily Notes/2025-01-24.md", "type": "file" }
+                            ]
+                        },
+                        {
+                            "path": "Projects",
+                            "type": "folder",
+                            "children": [
+                                { "path": "Projects/MCP.md", "type": "file" }
+                            ]
+                        }
+                    ]
                 }
             ],
             inputSchema: {
@@ -132,13 +152,36 @@ export class ListFilesInDirToolHandler extends BaseToolHandler {
     getToolDescription() {
         return {
             name: this.name,
-            description: "Lists all files and directories that exist in a specific Obsidian directory.",
+            description: "Lists all files and directories that exist in a specific Obsidian directory. Returns a hierarchical structure showing files, folders, and their relationships. Useful for exploring vault organization and finding specific files.",
             examples: [
                 {
                     description: "List files in Documents folder",
                     args: {
                         dirpath: "Documents"
                     }
+                },
+                {
+                    description: "Example response structure",
+                    args: {
+                        dirpath: "Projects"
+                    },
+                    response: [
+                        {
+                            "path": "Projects/Active",
+                            "type": "folder",
+                            "children": [
+                                { "path": "Projects/Active/ProjectA.md", "type": "file" },
+                                { "path": "Projects/Active/ProjectB.md", "type": "file" }
+                            ]
+                        },
+                        {
+                            "path": "Projects/Archive",
+                            "type": "folder",
+                            "children": [
+                                { "path": "Projects/Archive/OldProject.md", "type": "file" }
+                            ]
+                        }
+                    ]
                 }
             ],
             inputSchema: {
@@ -171,7 +214,21 @@ export class GetFileContentsToolHandler extends BaseToolHandler {
     getToolDescription() {
         return {
             name: this.name,
-            description: "Return the content of a single file in your vault.",
+            description: "Return the content of a single file in your vault. Supports markdown files, text files, and other readable formats. Returns the raw content including any YAML frontmatter.",
+            examples: [
+                {
+                    description: "Get content of a markdown note",
+                    args: {
+                        filepath: "Projects/research.md"
+                    }
+                },
+                {
+                    description: "Get content of a configuration file",
+                    args: {
+                        filepath: "configs/settings.yml"
+                    }
+                }
+            ],
             inputSchema: {
                 type: "object",
                 properties: {
@@ -202,17 +259,43 @@ export class FindInFileToolHandler extends BaseToolHandler {
     getToolDescription() {
         return {
             name: this.name,
-            description: "Simple search that returns filenames of documents matching a specified text query across all files in the vault.",
+            description: "Full-text search across all files in the vault. Returns matching files with surrounding context for each match. Useful for finding specific content, references, or patterns across notes.",
+            examples: [
+                {
+                    description: "Search for a specific term",
+                    args: {
+                        query: "neural networks",
+                        contextLength: 20
+                    }
+                },
+                {
+                    description: "Search with default context",
+                    args: {
+                        query: "#todo"
+                    },
+                    response: [
+                        {
+                            "filename": "Projects/AI.md",
+                            "matches": [
+                                {
+                                    "context": "Research needed:\n#todo Implement transformer architecture\nDeadline: Next week",
+                                    "match": { "start": 15, "end": 45 }
+                                }
+                            ]
+                        }
+                    ]
+                }
+            ],
             inputSchema: {
                 type: "object",
                 properties: {
                     query: {
                         type: "string",
-                        description: "Text to search for in the vault."
+                        description: "Text pattern to search for. Can include tags, keywords, or phrases."
                     },
                     contextLength: {
                         type: "integer",
-                        description: "How much context to use for matching (default: 10)",
+                        description: "Number of characters to include before and after each match for context (default: 10)",
                         default: 10
                     }
                 },
@@ -334,23 +417,45 @@ export class ComplexSearchToolHandler extends BaseToolHandler {
     getToolDescription() {
         return {
             name: this.name,
-            description: "Complex search for documents using a JsonLogic query.",
+            description: "Advanced search functionality using JsonLogic queries. Enables complex file filtering based on paths, metadata, modification times, and content patterns. Supports logical operations, date comparisons, and pattern matching.",
             examples: [
                 {
-                    description: "Find all markdown files",
+                    description: "Find markdown files in a specific folder",
+                    args: {
+                        query: {
+                            "and": [
+                                { "glob": ["Projects/*.md", { "var": "path" }] },
+                                { "contains": [{ "var": "content" }, "#active"] }
+                            ]
+                        }
+                    }
+                },
+                {
+                    description: "Find recently modified documentation",
                     args: {
                         query: {
-                            "glob": ["*.md", { "var": "path" }]
+                            "and": [
+                                { "glob": ["docs/*.md", { "var": "path" }] },
+                                { ">=": [
+                                        { "var": "mtime" },
+                                        { "date": "-7 days" }
+                                    ] },
+                                { "!=": [{ "var": "size" }, 0] }
+                            ]
                         }
                     }
                 },
                 {
-                    description: "Find files modified in last week",
+                    description: "Find files by multiple criteria",
                     args: {
                         query: {
-                            ">=": [
-                                { "var": "mtime" },
-                                { "date": "-7 days" }
+                            "and": [
+                                { "or": [
+                                        { "glob": ["*.md", { "var": "path" }] },
+                                        { "glob": ["*.txt", { "var": "path" }] }
+                                    ] },
+                                { "contains": [{ "var": "content" }, "TODO"] },
+                                { "<": [{ "var": "size" }, 10000] }
                             ]
                         }
                     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "obsidian-mcp-server",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "description": "Model Context Protocol server for Obsidian integration with token-aware response handling",
   "main": "build/index.js",
   "type": "module",

package/src/propertyTools.ts

@@ -29,13 +29,19 @@ export class GetPropertiesToolHandler extends BaseToolHandler<GetPropertiesArgs>
   getToolDescription(): Tool {
     return {
       name: this.name,
-      description: "Get properties from an Obsidian note's frontmatter.",
+      description: "Get properties (title, tags, status, etc.) from an Obsidian note's YAML frontmatter. Returns all available properties including custom fields.",
       examples: [
         {
           description: "Get properties from a note",
           args: {
             filepath: "path/to/note.md"
           }
+        },
+        {
+          description: "Get properties from a documentation file",
+          args: {
+            filepath: "docs/architecture.md"
+          }
         }
       ],
       inputSchema: {
@@ -73,16 +79,40 @@ export class UpdatePropertiesToolHandler extends BaseToolHandler<UpdatePropertie
   getToolDescription(): Tool {
     return {
       name: this.name,
-      description: "Update properties in an Obsidian note's frontmatter.",
+      description: "Update properties in an Obsidian note's YAML frontmatter. Intelligently merges arrays (tags, type, status), handles custom fields, and automatically updates the modified timestamp. Existing properties not included in the update are preserved.",
       examples: [
         {
-          description: "Update note properties",
+          description: "Update basic metadata",
           args: {
             filepath: "path/to/note.md",
             properties: {
-              title: "New Title",
-              tags: ["#tag1", "#tag2"],
-              status: ["in-progress"]
+              title: "Architecture Overview",
+              author: "Development Team",
+              type: ["architecture", "specification"]
+            }
+          }
+        },
+        {
+          description: "Update tags and status",
+          args: {
+            filepath: "docs/feature.md",
+            properties: {
+              tags: ["#feature", "#in-development", "#high-priority"],
+              status: ["in-progress"],
+              version: "2.0.0"
+            }
+          }
+        },
+        {
+          description: "Add custom fields",
+          args: {
+            filepath: "projects/project-x.md",
+            properties: {
+              custom: {
+                priority: "high",
+                reviewedBy: ["Alice", "Bob"],
+                dueDate: "2025-03-01"
+              }
             }
           }
         }

package/src/tools.ts

@@ -138,11 +138,31 @@ export class ListFilesInVaultToolHandler extends BaseToolHandler<Record<string,
   getToolDescription(): Tool {
     return {
       name: this.name,
-      description: "Lists all files and directories in the root directory of your Obsidian vault.",
+      description: "Lists all files and directories in the root directory of your Obsidian vault. Returns a hierarchical structure of files and folders, including metadata like file type.",
       examples: [
         {
           description: "List all files in vault",
           args: {}
+        },
+        {
+          description: "Example response",
+          args: {},
+          response: [
+            {
+              "path": "Daily Notes",
+              "type": "folder",
+              "children": [
+                { "path": "Daily Notes/2025-01-24.md", "type": "file" }
+              ]
+            },
+            {
+              "path": "Projects",
+              "type": "folder",
+              "children": [
+                { "path": "Projects/MCP.md", "type": "file" }
+              ]
+            }
+          ]
         }
       ],
       inputSchema: {
@@ -171,13 +191,36 @@ export class ListFilesInDirToolHandler extends BaseToolHandler<ListFilesArgs> {
   getToolDescription(): Tool {
     return {
       name: this.name,
-      description: "Lists all files and directories that exist in a specific Obsidian directory.",
+      description: "Lists all files and directories that exist in a specific Obsidian directory. Returns a hierarchical structure showing files, folders, and their relationships. Useful for exploring vault organization and finding specific files.",
       examples: [
         {
           description: "List files in Documents folder",
           args: {
             dirpath: "Documents"
           }
+        },
+        {
+          description: "Example response structure",
+          args: {
+            dirpath: "Projects"
+          },
+          response: [
+            {
+              "path": "Projects/Active",
+              "type": "folder",
+              "children": [
+                { "path": "Projects/Active/ProjectA.md", "type": "file" },
+                { "path": "Projects/Active/ProjectB.md", "type": "file" }
+              ]
+            },
+            {
+              "path": "Projects/Archive",
+              "type": "folder",
+              "children": [
+                { "path": "Projects/Archive/OldProject.md", "type": "file" }
+              ]
+            }
+          ]
         }
       ],
       inputSchema: {
@@ -212,7 +255,21 @@ export class GetFileContentsToolHandler extends BaseToolHandler<FileContentsArgs
   getToolDescription(): Tool {
     return {
       name: this.name,
-      description: "Return the content of a single file in your vault.",
+      description: "Return the content of a single file in your vault. Supports markdown files, text files, and other readable formats. Returns the raw content including any YAML frontmatter.",
+      examples: [
+        {
+          description: "Get content of a markdown note",
+          args: {
+            filepath: "Projects/research.md"
+          }
+        },
+        {
+          description: "Get content of a configuration file",
+          args: {
+            filepath: "configs/settings.yml"
+          }
+        }
+      ],
       inputSchema: {
         type: "object",
         properties: {
@@ -245,17 +302,43 @@ export class FindInFileToolHandler extends BaseToolHandler<SearchArgs> {
   getToolDescription(): Tool {
     return {
       name: this.name,
-      description: "Simple search that returns filenames of documents matching a specified text query across all files in the vault.",
+      description: "Full-text search across all files in the vault. Returns matching files with surrounding context for each match. Useful for finding specific content, references, or patterns across notes.",
+      examples: [
+        {
+          description: "Search for a specific term",
+          args: {
+            query: "neural networks",
+            contextLength: 20
+          }
+        },
+        {
+          description: "Search with default context",
+          args: {
+            query: "#todo"
+          },
+          response: [
+            {
+              "filename": "Projects/AI.md",
+              "matches": [
+                {
+                  "context": "Research needed:\n#todo Implement transformer architecture\nDeadline: Next week",
+                  "match": { "start": 15, "end": 45 }
+                }
+              ]
+            }
+          ]
+        }
+      ],
       inputSchema: {
         type: "object",
         properties: {
           query: {
             type: "string",
-            description: "Text to search for in the vault."
+            description: "Text pattern to search for. Can include tags, keywords, or phrases."
           },
           contextLength: {
             type: "integer",
-            description: "How much context to use for matching (default: 10)",
+            description: "Number of characters to include before and after each match for context (default: 10)",
             default: 10
           }
         },
@@ -383,23 +466,45 @@ export class ComplexSearchToolHandler extends BaseToolHandler<ComplexSearchArgs>
   getToolDescription(): Tool {
     return {
       name: this.name,
-      description: "Complex search for documents using a JsonLogic query.",
+      description: "Advanced search functionality using JsonLogic queries. Enables complex file filtering based on paths, metadata, modification times, and content patterns. Supports logical operations, date comparisons, and pattern matching.",
       examples: [
         {
-          description: "Find all markdown files",
+          description: "Find markdown files in a specific folder",
+          args: {
+            query: {
+              "and": [
+                {"glob": ["Projects/*.md", {"var": "path"}]},
+                {"contains": [{"var": "content"}, "#active"]}
+              ]
+            }
+          }
+        },
+        {
+          description: "Find recently modified documentation",
           args: {
             query: {
-              "glob": ["*.md", {"var": "path"}]
+              "and": [
+                {"glob": ["docs/*.md", {"var": "path"}]},
+                {">=": [
+                  {"var": "mtime"},
+                  {"date": "-7 days"}
+                ]},
+                {"!=": [{"var": "size"}, 0]}
+              ]
             }
           }
         },
         {
-          description: "Find files modified in last week",
+          description: "Find files by multiple criteria",
           args: {
             query: {
-              ">=": [
-                {"var": "mtime"},
-                {"date": "-7 days"}
+              "and": [
+                {"or": [
+                  {"glob": ["*.md", {"var": "path"}]},
+                  {"glob": ["*.txt", {"var": "path"}]}
+                ]},
+                {"contains": [{"var": "content"}, "TODO"]},
+                {"<": [{"var": "size"}, 10000]}
               ]
             }
           }