obsidian-mcp-server 1.2.6 → 1.4.0

package/build/utils/errors.js

@@ -0,0 +1,59 @@
+/**
+ * Error handling utilities for the Obsidian MCP Server
+ */
+/**
+ * Error class for Obsidian MCP Server specific errors
+ */
+export class ObsidianError extends Error {
+    details;
+    errorCode;
+    constructor(message, errorCode = 50000, // Default server error code
+    details) {
+        super(message);
+        this.details = details;
+        this.name = "ObsidianError";
+        // Ensure 5-digit error code
+        if (errorCode < 10000 || errorCode > 99999) {
+            // Convert HTTP status codes to 5-digit codes
+            // 4xx -> 4xxxx
+            // 5xx -> 5xxxx
+            this.errorCode = errorCode < 1000 ? errorCode * 100 : 50000;
+        }
+        else {
+            this.errorCode = errorCode;
+        }
+    }
+    // Convert to API error format
+    toApiError() {
+        return {
+            errorCode: this.errorCode,
+            message: this.message
+        };
+    }
+}
+/**
+ * Maps HTTP status codes to internal error codes
+ */
+export function getErrorCodeFromStatus(status) {
+    switch (status) {
+        case 400: return 40000; // Bad request
+        case 401: return 40100; // Unauthorized
+        case 403: return 40300; // Forbidden
+        case 404: return 40400; // Not found
+        case 405: return 40500; // Method not allowed
+        case 409: return 40900; // Conflict
+        case 429: return 42900; // Too many requests
+        case 500: return 50000; // Internal server error
+        case 501: return 50100; // Not implemented
+        case 502: return 50200; // Bad gateway
+        case 503: return 50300; // Service unavailable
+        case 504: return 50400; // Gateway timeout
+        default:
+            if (status >= 400 && status < 500)
+                return 40000 + (status - 400) * 100;
+            if (status >= 500 && status < 600)
+                return 50000 + (status - 500) * 100;
+            return 50000;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/build/utils/index.js

@@ -0,0 +1,9 @@
+/**
+ * Exports all utility functions and classes
+ */
+export * from './errors.js';
+export * from './logging.js';
+export * from './rate-limiting.js';
+export * from './tokenization.js';
+export * from './validation.js';
+//# sourceMappingURL=index.js.map

package/build/utils/logging.js

@@ -0,0 +1,119 @@
+/**
+ * Logging utilities for the Obsidian MCP Server
+ */
+/**
+ * Log levels
+ */
+export var LogLevel;
+(function (LogLevel) {
+    LogLevel[LogLevel["ERROR"] = 0] = "ERROR";
+    LogLevel[LogLevel["WARN"] = 1] = "WARN";
+    LogLevel[LogLevel["INFO"] = 2] = "INFO";
+    LogLevel[LogLevel["DEBUG"] = 3] = "DEBUG";
+    LogLevel[LogLevel["TRACE"] = 4] = "TRACE";
+})(LogLevel || (LogLevel = {}));
+/**
+ * Default logger configuration
+ */
+const DEFAULT_CONFIG = {
+    level: process.env.NODE_ENV === 'production'
+        ? LogLevel.INFO
+        : LogLevel.DEBUG,
+    includeTimestamps: true,
+    includeLevel: true
+};
+/**
+ * Simple logger for MCP server operations
+ */
+export class Logger {
+    name;
+    config;
+    constructor(name, config = {}) {
+        this.name = name;
+        this.config = { ...DEFAULT_CONFIG, ...config };
+    }
+    /**
+     * Internal method to format and output a log message
+     */
+    log(level, message, ...args) {
+        if (level > this.config.level)
+            return;
+        const parts = [];
+        // Add timestamp if configured
+        if (this.config.includeTimestamps) {
+            parts.push(`[${new Date().toISOString()}]`);
+        }
+        // Add level if configured
+        if (this.config.includeLevel) {
+            const levelStr = LogLevel[level] || 'UNKNOWN';
+            parts.push(`[${levelStr}]`);
+        }
+        // Add component name
+        parts.push(`[${this.name}]`);
+        // Add message
+        parts.push(message);
+        // Output to console
+        const output = parts.join(' ');
+        switch (level) {
+            case LogLevel.ERROR:
+                console.error(output, ...args);
+                break;
+            case LogLevel.WARN:
+                console.warn(output, ...args);
+                break;
+            case LogLevel.INFO:
+                console.info(output, ...args);
+                break;
+            case LogLevel.DEBUG:
+            case LogLevel.TRACE:
+            default:
+                console.debug(output, ...args);
+                break;
+        }
+    }
+    /**
+     * Log an error message
+     */
+    error(message, ...args) {
+        this.log(LogLevel.ERROR, message, ...args);
+    }
+    /**
+     * Log a warning message
+     */
+    warn(message, ...args) {
+        this.log(LogLevel.WARN, message, ...args);
+    }
+    /**
+     * Log an info message
+     */
+    info(message, ...args) {
+        this.log(LogLevel.INFO, message, ...args);
+    }
+    /**
+     * Log a debug message
+     */
+    debug(message, ...args) {
+        this.log(LogLevel.DEBUG, message, ...args);
+    }
+    /**
+     * Log a trace message
+     */
+    trace(message, ...args) {
+        this.log(LogLevel.TRACE, message, ...args);
+    }
+    /**
+     * Set the log level
+     */
+    setLevel(level) {
+        this.config.level = level;
+    }
+}
+/**
+ * Create and return a namespaced logger
+ */
+export function createLogger(name, config) {
+    return new Logger(name, config);
+}
+// Create a global root logger
+export const rootLogger = createLogger('mcp-server');
+//# sourceMappingURL=logging.js.map

package/build/utils/rate-limiting.js

@@ -0,0 +1,94 @@
+/**
+ * Rate limiting utilities for the Obsidian MCP Server
+ */
+import { ObsidianError } from './errors.js';
+/**
+ * Default rate limit configuration
+ */
+export const DEFAULT_RATE_LIMIT_CONFIG = {
+    windowMs: 15 * 60 * 1000, // 15 minutes
+    maxRequests: 200
+};
+/**
+ * RateLimit manages request rate limiting for API endpoints
+ */
+export class RateLimiter {
+    config;
+    requestCounts = new Map();
+    cleanupInterval;
+    constructor(config = DEFAULT_RATE_LIMIT_CONFIG) {
+        this.config = config;
+        // Clean up expired rate limit entries periodically
+        this.cleanupInterval = setInterval(() => this.cleanup(), 60000); // Clean up every minute
+    }
+    /**
+     * Check if a request is within rate limits
+     * @param key Identifier for the rate limit bucket (e.g., toolName)
+     * @returns Whether the request is allowed
+     */
+    checkRateLimit(key) {
+        const now = Date.now();
+        const requestInfo = this.requestCounts.get(key);
+        if (!requestInfo || now > requestInfo.resetTime) {
+            // Reset counter for new window
+            this.requestCounts.set(key, {
+                count: 1,
+                resetTime: now + this.config.windowMs
+            });
+            return true;
+        }
+        if (requestInfo.count >= this.config.maxRequests) {
+            return false;
+        }
+        requestInfo.count++;
+        return true;
+    }
+    /**
+     * Check rate limit and throw an error if exceeded
+     * @param key Identifier for the rate limit bucket
+     * @throws ObsidianError if rate limit is exceeded
+     */
+    enforceRateLimit(key) {
+        if (!this.checkRateLimit(key)) {
+            throw new ObsidianError(`Rate limit exceeded for ${key}. Please try again later.`, 42900 // 42900 = Rate limit exceeded
+            );
+        }
+    }
+    /**
+     * Get information about current rate limit status
+     * @param key Identifier for the rate limit bucket
+     * @returns Rate limit information or null if no requests have been made
+     */
+    getRateLimitInfo(key) {
+        const requestInfo = this.requestCounts.get(key);
+        if (!requestInfo) {
+            return null;
+        }
+        return {
+            remaining: Math.max(0, this.config.maxRequests - requestInfo.count),
+            resetTime: requestInfo.resetTime
+        };
+    }
+    /**
+     * Clean up expired rate limit entries
+     */
+    cleanup() {
+        const now = Date.now();
+        for (const [key, info] of this.requestCounts.entries()) {
+            if (now > info.resetTime) {
+                this.requestCounts.delete(key);
+            }
+        }
+    }
+    /**
+     * Clean up resources (e.g., when shutting down)
+     */
+    dispose() {
+        if (this.cleanupInterval) {
+            clearInterval(this.cleanupInterval);
+        }
+    }
+}
+// Export a singleton instance with default configuration
+export const rateLimiter = new RateLimiter();
+//# sourceMappingURL=rate-limiting.js.map

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