obsidian-mcp-server 1.1.1 → 1.2.1

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.1.1-blue.svg)]()
+[![Version](https://img.shields.io/badge/Version-1.2.1-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)
@@ -25,6 +25,12 @@ Requires the Local REST API plugin in Obsidian.
 - Configurable context boundaries and token limits
 - Optimized query processing
 
+### Property Management
+- YAML frontmatter parsing and validation
+- Intelligent property merging and updates
+- Automatic timestamp management
+- Custom field support
+
 ### Security & Performance
 - API key authentication and rate limiting
 - SSL verification options
@@ -120,6 +126,38 @@ obsidian_patch_content: {
 }
 ```
 
+### Property Management
+```typescript
+// Get note properties
+obsidian_get_properties: {
+  filepath: string  // Path relative to vault root
+}
+
+// Update note properties
+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,
+    type?: Array<"concept" | "architecture" | "specification" | 
+      "protocol" | "api" | "research" | "implementation" | 
+      "guide" | "reference">,
+    tags?: string[],  // Must start with #
+    status?: Array<"draft" | "in-progress" | "review" | "complete">,
+    version?: string,
+    platform?: string,
+    repository?: string,  // URL
+    dependencies?: string[],
+    sources?: string[],
+    urls?: string[],      // URLs
+    papers?: string[],
+    custom?: Record<string, unknown>
+  }
+}
+```
+
 ## Best Practices
 
 ### File Operations
@@ -134,6 +172,12 @@ obsidian_patch_content: {
 - Handle large result sets
 - Consider token limits
 
+### Property Management
+- Validate property values before updates
+- Use appropriate property types
+- Handle array merging appropriately
+- Consider custom field implications
+
 ### Error Prevention
 - Validate inputs thoroughly
 - Handle API errors gracefully

package/build/properties.js

@@ -0,0 +1,156 @@
+import { parse, stringify } from 'yaml';
+import { ObsidianPropertiesSchema } from './propertyTypes.js';
+export class PropertyManager {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Parse YAML frontmatter from note content
+     */
+    parseProperties(content) {
+        try {
+            // Extract frontmatter between --- markers
+            const match = content.match(/^---\n([\s\S]*?)\n---/);
+            if (!match) {
+                return {};
+            }
+            const frontmatter = match[1];
+            const properties = parse(frontmatter);
+            // Validate against schema
+            const result = ObsidianPropertiesSchema.safeParse(properties);
+            if (!result.success) {
+                console.warn('Property validation warnings:', result.error);
+                // Return partial valid properties rather than throwing
+                return properties;
+            }
+            return result.data;
+        }
+        catch (error) {
+            console.error('Error parsing properties:', error);
+            return {};
+        }
+    }
+    /**
+     * Generate YAML frontmatter from properties
+     */
+    generateProperties(properties) {
+        try {
+            // Remove undefined values
+            const cleanProperties = Object.fromEntries(Object.entries(properties).filter(([_, v]) => v !== undefined));
+            // Generate YAML
+            const yaml = stringify(cleanProperties);
+            return `---\n${yaml}---\n`;
+        }
+        catch (error) {
+            console.error('Error generating properties:', error);
+            throw error;
+        }
+    }
+    /**
+     * Validate property values
+     */
+    validateProperties(properties) {
+        const result = ObsidianPropertiesSchema.safeParse(properties);
+        if (result.success) {
+            return { valid: true, errors: [] };
+        }
+        return {
+            valid: false,
+            errors: result.error.errors.map(err => `${err.path.join('.')}: ${err.message}`)
+        };
+    }
+    /**
+     * Merge new properties with existing ones
+     */
+    mergeProperties(existing, updates) {
+        const merged = { ...existing };
+        for (const [key, value] of Object.entries(updates)) {
+            if (value === undefined)
+                continue;
+            const currentValue = merged[key];
+            // Special handling for arrays - merge rather than replace
+            if (Array.isArray(value) && Array.isArray(currentValue)) {
+                merged[key] = [
+                    ...new Set([...currentValue, ...value])
+                ];
+            }
+            // Special handling for custom object - deep merge
+            else if (key === 'custom' && typeof value === 'object' && value !== null) {
+                merged.custom = {
+                    ...merged.custom,
+                    ...value
+                };
+            }
+            // Default case - replace value
+            else {
+                merged[key] = value;
+            }
+        }
+        // Always update modified date
+        merged.modified = new Date().toISOString();
+        return merged;
+    }
+    /**
+     * Get properties from a note
+     */
+    async getProperties(filepath) {
+        try {
+            const content = await this.client.getFileContents(filepath);
+            const properties = this.parseProperties(content);
+            return {
+                success: true,
+                message: 'Properties retrieved successfully',
+                properties
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to get properties: ${error instanceof Error ? error.message : String(error)}`,
+                errors: [String(error)]
+            };
+        }
+    }
+    /**
+     * Update properties of a note
+     */
+    async updateProperties(filepath, newProperties) {
+        try {
+            // Validate new properties
+            const validation = this.validateProperties(newProperties);
+            if (!validation.valid) {
+                return {
+                    success: false,
+                    message: 'Invalid properties',
+                    errors: validation.errors
+                };
+            }
+            // Get existing content and properties
+            const content = await this.client.getFileContents(filepath);
+            const existingProperties = this.parseProperties(content);
+            // Merge properties
+            const mergedProperties = this.mergeProperties(existingProperties, newProperties);
+            // Generate new frontmatter
+            const newFrontmatter = this.generateProperties(mergedProperties);
+            // Replace existing frontmatter or prepend to file
+            const newContent = content.replace(/^---[\s\S]*?---\n/, '') || '';
+            const updatedContent = newFrontmatter + newContent;
+            // Update file
+            await this.client.updateContent(filepath, updatedContent);
+            return {
+                success: true,
+                message: 'Properties updated successfully',
+                properties: mergedProperties
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to update properties: ${error instanceof Error ? error.message : String(error)}`,
+                errors: [String(error)]
+            };
+        }
+    }
+}
+//# sourceMappingURL=properties.js.map

package/build/propertyTools.js

@@ -0,0 +1,186 @@
+import { BaseToolHandler } from "./tools.js";
+import { PropertyManager } from "./properties.js";
+const TOOL_NAMES = {
+    GET_PROPERTIES: "obsidian_get_properties",
+    UPDATE_PROPERTIES: "obsidian_update_properties"
+};
+export class GetPropertiesToolHandler extends BaseToolHandler {
+    propertyManager;
+    constructor(client) {
+        super(TOOL_NAMES.GET_PROPERTIES, client);
+        this.propertyManager = new PropertyManager(client);
+    }
+    getToolDescription() {
+        return {
+            name: this.name,
+            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: {
+                type: "object",
+                properties: {
+                    filepath: {
+                        type: "string",
+                        description: "Path to the note file (relative to vault root)",
+                        format: "path"
+                    }
+                },
+                required: ["filepath"]
+            }
+        };
+    }
+    async runTool(args) {
+        try {
+            const result = await this.propertyManager.getProperties(args.filepath);
+            return this.createResponse(result);
+        }
+        catch (error) {
+            return this.handleError(error);
+        }
+    }
+}
+export class UpdatePropertiesToolHandler extends BaseToolHandler {
+    propertyManager;
+    constructor(client) {
+        super(TOOL_NAMES.UPDATE_PROPERTIES, client);
+        this.propertyManager = new PropertyManager(client);
+    }
+    getToolDescription() {
+        return {
+            name: this.name,
+            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 basic metadata",
+                    args: {
+                        filepath: "path/to/note.md",
+                        properties: {
+                            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"
+                            }
+                        }
+                    }
+                }
+            ],
+            inputSchema: {
+                type: "object",
+                properties: {
+                    filepath: {
+                        type: "string",
+                        description: "Path to the note file (relative to vault root)",
+                        format: "path"
+                    },
+                    properties: {
+                        type: "object",
+                        description: "Properties to update",
+                        properties: {
+                            title: { type: "string" },
+                            created: { type: "string", format: "date-time" },
+                            modified: { type: "string", format: "date-time" },
+                            author: { type: "string" },
+                            type: {
+                                type: "array",
+                                items: {
+                                    type: "string",
+                                    enum: [
+                                        "concept",
+                                        "architecture",
+                                        "specification",
+                                        "protocol",
+                                        "api",
+                                        "research",
+                                        "implementation",
+                                        "guide",
+                                        "reference"
+                                    ]
+                                }
+                            },
+                            tags: {
+                                type: "array",
+                                items: { type: "string", pattern: "^#" }
+                            },
+                            status: {
+                                type: "array",
+                                items: {
+                                    type: "string",
+                                    enum: ["draft", "in-progress", "review", "complete"]
+                                }
+                            },
+                            version: { type: "string" },
+                            platform: { type: "string" },
+                            repository: { type: "string", format: "uri" },
+                            dependencies: {
+                                type: "array",
+                                items: { type: "string" }
+                            },
+                            sources: {
+                                type: "array",
+                                items: { type: "string" }
+                            },
+                            urls: {
+                                type: "array",
+                                items: { type: "string", format: "uri" }
+                            },
+                            papers: {
+                                type: "array",
+                                items: { type: "string" }
+                            },
+                            custom: {
+                                type: "object",
+                                additionalProperties: true
+                            }
+                        },
+                        additionalProperties: false
+                    }
+                },
+                required: ["filepath", "properties"]
+            }
+        };
+    }
+    async runTool(args) {
+        try {
+            const result = await this.propertyManager.updateProperties(args.filepath, args.properties);
+            return this.createResponse(result);
+        }
+        catch (error) {
+            return this.handleError(error);
+        }
+    }
+}
+//# sourceMappingURL=propertyTools.js.map

package/build/propertyTypes.js

@@ -0,0 +1,43 @@
+import { z } from "zod";
+// Define validation schemas
+export const PropertyTypeEnum = z.enum([
+    "concept",
+    "architecture",
+    "specification",
+    "protocol",
+    "api",
+    "research",
+    "implementation",
+    "guide",
+    "reference"
+]);
+export const StatusEnum = z.enum([
+    "draft",
+    "in-progress",
+    "review",
+    "complete"
+]);
+export const ObsidianPropertiesSchema = z.object({
+    // Basic Metadata
+    title: z.string().optional(),
+    created: z.string().datetime().optional(),
+    modified: z.string().datetime().optional(),
+    author: z.string().optional(),
+    // Classification
+    type: z.array(PropertyTypeEnum).optional(),
+    // Organization
+    tags: z.array(z.string().startsWith("#")).optional(),
+    // Technical Metadata
+    status: z.array(StatusEnum).optional(),
+    version: z.string().optional(),
+    platform: z.string().optional(),
+    repository: z.string().url().optional(),
+    dependencies: z.array(z.string()).optional(),
+    // References
+    sources: z.array(z.string()).optional(),
+    urls: z.array(z.string().url()).optional(),
+    papers: z.array(z.string()).optional(),
+    // Custom Fields
+    custom: z.record(z.unknown()).optional()
+});
+//# sourceMappingURL=propertyTypes.js.map

package/build/server.js

@@ -5,6 +5,7 @@ import { ListToolsRequestSchema, CallToolRequestSchema } from "@modelcontextprot
 import { ObsidianClient } from "./obsidian.js";
 import { ObsidianError, DEFAULT_RATE_LIMIT_CONFIG } from "./types.js";
 import { ListFilesInVaultToolHandler, ListFilesInDirToolHandler, GetFileContentsToolHandler, FindInFileToolHandler, AppendContentToolHandler, PatchContentToolHandler, ComplexSearchToolHandler } from "./tools.js";
+import { GetPropertiesToolHandler, UpdatePropertiesToolHandler } from "./propertyTools.js";
 // Load environment variables
 config();
 const API_KEY = process.env.OBSIDIAN_API_KEY;
@@ -57,7 +58,9 @@ const handlers = [
     new FindInFileToolHandler(client),
     new AppendContentToolHandler(client),
     new PatchContentToolHandler(client),
-    new ComplexSearchToolHandler(client)
+    new ComplexSearchToolHandler(client),
+    new GetPropertiesToolHandler(client),
+    new UpdatePropertiesToolHandler(client)
 ];
 handlers.forEach(handler => toolHandlers.set(handler.name, handler));
 // Create MCP server

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] }
                             ]
                         }
                     }