obsidian-mcp-server 1.3.0 → 1.4.0

package/build/utils/tokenization.js

@@ -0,0 +1,62 @@
+/**
+ * Token counting utilities for the Obsidian MCP Server
+ */
+import { encoding_for_model } from "tiktoken";
+// Load token limits from environment or use defaults
+export const MAX_TOKENS = parseInt(process.env.MAX_TOKENS ?? '20000');
+export const TRUNCATION_MESSAGE = "\n\n[Response truncated due to length]";
+/**
+ * Handles token counting and text truncation to stay within token limits
+ */
+export class TokenCounter {
+    tokenizer = encoding_for_model("gpt-4"); // This is strictly for token counting, not for LLM inference
+    isShuttingDown = false;
+    constructor() {
+        // Clean up tokenizer when process exits
+        const cleanup = () => {
+            if (!this.isShuttingDown) {
+                this.isShuttingDown = true;
+                if (this.tokenizer) {
+                    this.tokenizer.free();
+                }
+            }
+        };
+        process.on('exit', cleanup);
+        process.on('SIGINT', cleanup);
+        process.on('SIGTERM', cleanup);
+        process.on('uncaughtException', cleanup);
+    }
+    /**
+     * Count the number of tokens in a string
+     */
+    countTokens(text) {
+        return this.tokenizer.encode(text).length;
+    }
+    /**
+     * Truncate text to stay within token limit
+     */
+    truncateToTokenLimit(text, limit = MAX_TOKENS) {
+        const tokens = this.tokenizer.encode(text);
+        if (tokens.length <= limit) {
+            return text;
+        }
+        // Reserve tokens for truncation message
+        const messageTokens = this.tokenizer.encode(TRUNCATION_MESSAGE);
+        const availableTokens = limit - messageTokens.length;
+        // Decode truncated tokens back to text
+        const truncatedText = this.tokenizer.decode(tokens.slice(0, availableTokens));
+        return truncatedText + TRUNCATION_MESSAGE;
+    }
+    /**
+     * Clean up resources
+     */
+    cleanup() {
+        if (this.tokenizer && !this.isShuttingDown) {
+            this.isShuttingDown = true;
+            this.tokenizer.free();
+        }
+    }
+}
+// Export a singleton instance
+export const tokenCounter = new TokenCounter();
+//# sourceMappingURL=tokenization.js.map

package/build/utils/validation.js

@@ -0,0 +1,88 @@
+/**
+ * Validation utilities for the Obsidian MCP Server
+ */
+/**
+ * Validates a file path to prevent path traversal attacks and other security issues
+ * @param filepath The path to validate
+ * @throws Error if the path is invalid
+ */
+export function validateFilePath(filepath) {
+    // Prevent path traversal attacks
+    const normalizedPath = filepath.replace(/\\/g, '/');
+    if (normalizedPath.includes('../') || normalizedPath.includes('..\\')) {
+        throw new Error('Invalid file path: Path traversal not allowed');
+    }
+    // Additional path validations
+    if (normalizedPath.startsWith('/') || /^[a-zA-Z]:/.test(normalizedPath)) {
+        throw new Error('Invalid file path: Absolute paths not allowed');
+    }
+}
+/**
+ * Sanitizes a header value to prevent header injection attacks
+ * @param value The header value to sanitize
+ * @returns The sanitized header value
+ */
+export function sanitizeHeader(value) {
+    // Remove any potentially harmful characters from header values
+    return value.replace(/[^\w\s\-\._~:/?#\[\]@!$&'()*+,;=]/g, '');
+}
+/**
+ * Validates tool arguments against a JSON schema
+ * @param args The arguments to validate
+ * @param schema The JSON schema to validate against
+ * @returns Validation result with errors if any
+ */
+export function validateToolArguments(args, schema) {
+    if (typeof args !== 'object' || args === null) {
+        return { valid: false, errors: ['Arguments must be an object'] };
+    }
+    const errors = [];
+    const required = schema.required || [];
+    // Check required fields
+    for (const field of required) {
+        if (!(field in args)) {
+            errors.push(`Missing required field: ${field}`);
+        }
+    }
+    // Check field types
+    const properties = schema.properties || {};
+    for (const [key, value] of Object.entries(args)) {
+        const propSchema = properties[key];
+        if (!propSchema) {
+            errors.push(`Unknown field: ${key}`);
+            continue;
+        }
+        // Skip validation for undefined optional fields
+        if (value === undefined && !required.includes(key)) {
+            continue;
+        }
+        // Type validation
+        if (propSchema.type === 'string' && typeof value !== 'string') {
+            errors.push(`Field ${key} must be a string`);
+        }
+        else if (propSchema.type === 'number' && typeof value !== 'number') {
+            errors.push(`Field ${key} must be a number`);
+        }
+        else if (propSchema.type === 'boolean' && typeof value !== 'boolean') {
+            errors.push(`Field ${key} must be a boolean`);
+        }
+        else if (propSchema.type === 'array' && !Array.isArray(value)) {
+            errors.push(`Field ${key} must be an array`);
+        }
+        // Enum validation
+        if (propSchema.enum && value !== undefined && !propSchema.enum.includes(value)) {
+            errors.push(`Field ${key} must be one of: ${propSchema.enum.join(', ')}`);
+        }
+        // Format validation for paths
+        if (propSchema.format === 'path' && typeof value === 'string') {
+            try {
+                validateFilePath(value);
+            }
+            catch (error) {
+                errors.push(`Field ${key}: ${error.message}`);
+            }
+        }
+    }
+    return { valid: errors.length === 0, errors };
+}
+//# sourceMappingURL=validation.js.map

package/examples/README.md

@@ -0,0 +1,48 @@
+# Obsidian MCP Server Tool Examples
+
+This directory contains example requests and responses for each tool provided by the obsidian-mcp-server. These examples demonstrate the capabilities and expected output format of each tool.
+
+## Tools
+
+### 1. [List Files in Vault](list-files-in-vault.md)
+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.
+
+### 2. [List Files in Directory](list-files-in-dir.md)
+Lists all files and directories that exist in a specific Obsidian directory. Returns a hierarchical structure showing files, folders, and their relationships.
+
+### 3. [Get File Contents](get-file-contents.md)
+Return the content of a single file in your vault. Supports markdown files, text files, and other readable formats.
+
+### 4. [Find in File](find-in-file.md)
+Full-text search across all files in the vault. Returns matching files with surrounding context for each match.
+
+### 5. [Append Content](append-content.md)
+Append content to a new or existing file in the vault. Useful for adding new sections, notes, or updates to existing documents.
+
+### 6. [Patch Content](patch-content.md)
+Update the entire content of an existing note or create a new one. Provides complete control over file contents.
+
+### 7. [Complex Search](complex-search.md)
+File path pattern matching using JsonLogic queries. Supports operations like glob pattern matching and variable access.
+
+### 8. [Get Properties](get-properties.md)
+Get properties (title, tags, status, etc.) from an Obsidian note's YAML frontmatter. Returns all available properties including custom fields.
+
+### 9. [Update Properties](update-properties.md)
+Update properties in an Obsidian note's YAML frontmatter. Intelligently merges arrays and handles custom fields.
+
+## Resources
+
+### Direct Resources
+- obsidian://tags - List of all tags used across the Obsidian vault with their usage counts
+
+## Production Readiness
+
+All tools have been tested and demonstrate:
+- Proper input validation and error handling
+- Comprehensive and well-structured responses
+- Consistent output formatting
+- Practical applicability to real-world Obsidian vault management
+- Deep integration with Obsidian's features and capabilities
+
+The examples serve as both documentation and test cases, showing the expected behavior and quality of responses for each tool.

package/examples/append-content.md

@@ -0,0 +1,63 @@
+# Append Content Tool Example
+
+## Request 1 (Append to Existing Note)
+```json
+{
+  "filepath": "Projects/Project Alpha/Notes/Meeting Notes.md",
+  "content": "\n\n## Team Meeting - 2024-01-25\n\n### Discussion Points\n- Reviewed project timeline\n- Discussed technical challenges\n- Assigned new tasks\n\n### Action Items\n- [ ] Update documentation\n- [ ] Schedule follow-up meeting\n- [ ] Share progress report"
+}
+```
+
+## Response 1
+```json
+{
+  "success": true,
+  "message": "Content appended successfully"
+}
+```
+
+## Request 2 (Create New Note)
+```json
+{
+  "filepath": "Daily Notes/2024-01-25.md",
+  "content": "---\ntitle: Daily Note - January 25, 2024\ntags: [daily-notes]\ndate: 2024-01-25\n---\n\n# Daily Notes\n\n## Tasks\n- [ ] Review project updates\n- [ ] Team meeting at 2 PM\n- [ ] Update documentation\n\n## Notes\n- Started work on new feature\n- Discussed timeline with team\n- Reviewed technical specifications"
+}
+```
+
+## Response 2
+```json
+{
+  "success": true,
+  "message": "File created and content appended successfully"
+}
+```
+
+## Example Use Cases
+
+1. **Meeting Notes**
+   - Add new meeting minutes to existing notes
+   - Create structured meeting summaries
+   - Track action items and decisions
+
+2. **Daily Notes**
+   - Create daily journal entries
+   - Add to existing daily logs
+   - Maintain consistent note structure
+
+3. **Project Documentation**
+   - Add new sections to documentation
+   - Update progress logs
+   - Append new requirements or specifications
+
+## Notes
+- Can append to existing files or create new ones
+- Preserves existing content in the file
+- Maintains proper markdown formatting
+- Supports YAML frontmatter
+- Handles various content types:
+  * Meeting notes
+  * Daily logs
+  * Task lists
+  * Documentation updates
+- File path is relative to vault root
+- Creates parent directories if needed

package/examples/complex-search.md

@@ -0,0 +1,117 @@
+# Complex Search Tool Example
+
+## Request 1 (Simple Glob Pattern)
+```json
+{
+  "query": {
+    "glob": ["*.md", {"var": "path"}]
+  }
+}
+```
+
+## Response 1
+```json
+{
+  "matches": [
+    "README.md",
+    "Projects/Project Alpha/Documentation/Requirements.md",
+    "Daily Notes/2024-01-25.md",
+    "Templates/Meeting Note.md"
+  ]
+}
+```
+
+## Request 2 (Complex Pattern)
+```json
+{
+  "query": {
+    "and": [
+      {
+        "glob": ["Projects/**/*.md", {"var": "path"}]
+      },
+      {
+        "in": [
+          "Documentation",
+          {"var": "path"}
+        ]
+      }
+    ]
+  }
+}
+```
+
+## Response 2
+```json
+{
+  "matches": [
+    "Projects/Project Alpha/Documentation/Requirements.md",
+    "Projects/Project Alpha/Documentation/Architecture.md",
+    "Projects/Project Beta/Documentation/API.md"
+  ]
+}
+```
+
+## Example Use Cases
+
+1. **File Organization**
+   - Find files by pattern matching
+   - Filter by path components
+   - Combine multiple search criteria
+
+2. **Content Management**
+   - Locate files in specific directories
+   - Filter by file extensions
+   - Find files matching complex patterns
+
+3. **Project Navigation**
+   - Search within project directories
+   - Find documentation files
+   - Filter by file location
+
+## Notes
+- Uses JsonLogic for query construction
+- Supports glob pattern matching
+- Can combine multiple conditions
+- Available operations:
+  * glob: Pattern matching for paths
+  * var: Variable access (path)
+  * and/or: Logical operations
+  * in: Membership testing
+- Path is relative to vault root
+- Returns matching file paths
+- Useful for complex file filtering
+
+## Common Patterns
+
+1. **Find All Markdown Files**
+```json
+{
+  "glob": ["**/*.md", {"var": "path"}]
+}
+```
+
+2. **Files in Specific Directory**
+```json
+{
+  "glob": ["Projects/Project Alpha/**/*", {"var": "path"}]
+}
+```
+
+3. **Multiple Extensions**
+```json
+{
+  "or": [
+    {"glob": ["**/*.md", {"var": "path"}]},
+    {"glob": ["**/*.txt", {"var": "path"}]}
+  ]
+}
+```
+
+4. **Exclude Pattern**
+```json
+{
+  "and": [
+    {"glob": ["**/*.md", {"var": "path"}]},
+    {"not": {"glob": ["**/Archive/**", {"var": "path"}]}}
+  ]
+}

package/examples/find-in-file.md

@@ -0,0 +1,94 @@
+# Find in File Tool Example
+
+## Request 1 (Many Results)
+```json
+{
+  "query": "tags:",
+  "contextLength": 20
+}
+```
+
+## Response 1
+```json
+{
+  "message": "Found 34 files with matches. Showing file names only:",
+  "results": [
+    {
+      "filename": "Projects/Project Alpha/Documentation/Requirements.md",
+      "matchCount": 1
+    },
+    {
+      "filename": "Projects/Project Beta/Specifications.md",
+      "matchCount": 2
+    },
+    {
+      "filename": "Daily Notes/2024-01-25.md",
+      "matchCount": 1
+    }
+  ]
+}
+```
+
+## Request 2 (Few Results)
+```json
+{
+  "query": "priority: high",
+  "contextLength": 50
+}
+```
+
+## Response 2
+```json
+{
+  "results": [
+    {
+      "filename": "Projects/Project Alpha/tasks.md",
+      "matches": [
+        {
+          "line": 15,
+          "content": "---\ntitle: Critical Tasks\ntags: [tasks, urgent]\npriority: high\n---\n\n# High Priority Tasks",
+          "matchStart": 45,
+          "matchEnd": 57
+        }
+      ]
+    },
+    {
+      "filename": "Areas/Work/Deadlines.md",
+      "matches": [
+        {
+          "line": 8,
+          "content": "## Q1 Deliverables\n- [ ] Feature launch (priority: high)\n- [ ] Security audit",
+          "matchStart": 35,
+          "matchEnd": 47
+        }
+      ]
+    }
+  ]
+}
+```
+
+## Example Use Cases
+
+1. **Content Search**
+   - Find notes with specific tags or properties
+   - Search for keywords across the vault
+   - Locate specific metadata patterns
+
+2. **Task Management**
+   - Find high-priority tasks
+   - Search for incomplete items
+   - Locate notes with specific status
+
+3. **Knowledge Discovery**
+   - Find related content across notes
+   - Search for specific topics or references
+   - Identify patterns in note metadata
+
+## Notes
+- Returns either file list or detailed matches based on result count
+- Provides line numbers for precise location
+- Shows surrounding context for each match
+- Context length is customizable
+- Supports searching in frontmatter and note content
+- Results include match position information
+- Can search across all vault files

package/examples/get-file-contents.md

@@ -0,0 +1,72 @@
+# Get File Contents Tool Example
+
+## Request
+```json
+{
+  "filepath": "Projects/Project Alpha/Documentation/Requirements.md"
+}
+```
+
+## Response
+```markdown
+---
+title: Project Requirements
+tags: [project, requirements, documentation]
+status: [in-progress]
+created: 2024-01-20
+modified: 2024-01-25
+---
+
+# Project Requirements Document
+
+## Overview
+This document outlines the key requirements for Project Alpha.
+
+## Features
+1. User Authentication
+   - [ ] Login system
+   - [ ] Password recovery
+   - [ ] Two-factor authentication
+
+2. Data Management
+   - [ ] Database integration
+   - [ ] Backup system
+   - [x] Data validation
+
+## Related Documents
+- [[Architecture Overview]]
+- [[Technical Specifications]]
+- [[Meeting Notes/Kickoff Meeting]]
+
+## References
+![[project-diagram.png]]
+
+#project-alpha #documentation #requirements
+```
+
+## Example Use Cases
+
+1. **Content Retrieval**
+   - Access note contents for reading or processing
+   - Extract metadata from YAML frontmatter
+   - Parse markdown formatting
+
+2. **Document Analysis**
+   - Review document structure
+   - Extract links and references
+   - Process task lists and status
+
+3. **Integration**
+   - Import content into other systems
+   - Process notes programmatically
+   - Extract specific sections or metadata
+
+## Notes
+- Returns raw markdown content including YAML frontmatter
+- Preserves all formatting, links, and special syntax
+- Handles various Obsidian-specific markdown features:
+  * Wiki-style links: [[Page Name]]
+  * Tags: #tag-name
+  * Embedded content: ![[file.png]]
+  * Task lists: - [ ] todo item
+- File path is relative to vault root

package/examples/get-properties.md

@@ -0,0 +1,89 @@
+# Get Properties Tool Example
+
+## Request
+```json
+{
+  "filepath": "Projects/Project Alpha/Documentation/Requirements.md"
+}
+```
+
+## Response
+```json
+{
+  "properties": {
+    "title": "Project Requirements",
+    "tags": ["project", "requirements", "documentation"],
+    "status": ["in-progress"],
+    "created": "2024-01-20",
+    "modified": "2024-01-25",
+    "type": ["technical", "specification"],
+    "author": "Team Lead",
+    "version": "1.0",
+    "reviewers": ["Tech Lead", "Product Manager"],
+    "priority": "high"
+  }
+}
+```
+
+## Example Use Cases
+
+1. **Metadata Management**
+   - Extract note properties
+   - Review document metadata
+   - Track document status
+
+2. **Content Organization**
+   - Get tags for categorization
+   - Check document status
+   - Review creation/modification dates
+
+3. **Project Tracking**
+   - Monitor document versions
+   - Track review status
+   - Identify document owners
+
+## Notes
+- Extracts YAML frontmatter from markdown files
+- Returns structured JSON object
+- Supports various property types:
+  * Strings
+  * Arrays
+  * Dates
+  * Numbers
+  * Boolean values
+- Common properties:
+  * title: Document title
+  * tags: Categorization tags
+  * status: Document status
+  * created/modified: Timestamps
+  * type: Content type
+  * author: Content creator
+  * version: Document version
+  * custom fields: Any additional metadata
+
+## Property Types
+1. **Basic Properties**
+   ```yaml
+   title: "Document Title"
+   author: "John Doe"
+   version: 1.0
+   ```
+
+2. **Array Properties**
+   ```yaml
+   tags: [project, documentation]
+   status: [draft, review]
+   reviewers: [Alice, Bob]
+   ```
+
+3. **Date Properties**
+   ```yaml
+   created: 2024-01-20
+   due: 2024-02-01
+   ```
+
+4. **Custom Properties**
+   ```yaml
+   priority: high
+   department: Engineering
+   confidential: true

package/examples/list-files-in-dir.md

@@ -0,0 +1,55 @@
+# List Files in Directory Tool Example
+
+## Request
+```json
+{
+  "dirpath": "Projects/Project Alpha"
+}
+```
+
+## Response
+```
+Documentation/
+  Documentation/Requirements.md
+  Documentation/Architecture.md
+Notes/
+  Notes/Meeting Notes.md
+  Notes/Research.md
+Resources/
+  Resources/Images/
+  Resources/References/
+tasks.md
+timeline.md
+```
+
+## Example Use Cases
+
+1. **Project Organization**
+   - Browse project-specific files and folders
+   - Navigate through project documentation
+   - Find relevant project resources
+
+2. **Content Discovery**
+   - Locate specific project documents
+   - Access meeting notes and research
+   - Review project structure
+
+3. **Knowledge Management**
+   - Organize project materials
+   - Track project documentation
+   - Maintain clear folder hierarchies
+
+## Notes
+- Returns contents of a specific directory path
+- Shows both subdirectories and files
+- Directory paths end with a forward slash (/)
+- Results are alphabetically sorted
+- Empty directories are included in the results
+- Path is relative to vault root
+
+## Common Directory Structures
+The example shows a typical project organization:
+- Documentation/ - Project requirements and architecture
+- Notes/ - Meeting notes and research findings
+- Resources/ - Project assets and references
+- Root level files for quick access to important information