obsidian-mcp-server 1.1.0

package/.github/workflows/publish.yml

@@ -0,0 +1,35 @@
+name: Publish Package to npm
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '18.x'
+          registry-url: 'https://registry.npmjs.org'
+          scope: '@cyanheads'
+      
+      - name: Install dependencies
+        run: npm ci
+      
+      - name: Build
+        run: npm run build
+      
+      - name: Publish to npm
+        # Requires NPM_TOKEN secret to be set in repository settings
+        # Generate token at https://www.npmjs.com/settings/[username]/tokens
+        # and add to repository secrets with read/write packages permission
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/README.md

@@ -0,0 +1,171 @@
+# Obsidian MCP Server
+
+[![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.0-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)
+
+A Model Context Protocol server designed for LLMs to interact with Obsidian vaults. Built with TypeScript and featuring secure API communication, efficient file operations, and comprehensive search capabilities, it enables AI assistants to seamlessly manage knowledge bases through a clean, flexible tool interface.
+
+The Model Context Protocol (MCP) enables AI models to interact with external tools and resources through a standardized interface. This server implements MCP to provide LLMs with secure, token-aware access to Obsidian vaults.
+
+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
+- Resource monitoring and cleanup
+
+### Search System
+- Full-text and JsonLogic-based complex search
+- Configurable context boundaries and token limits
+- Optimized query processing
+
+### Security & Performance
+- API key authentication and rate limiting
+- SSL verification options
+- Resource management and health monitoring
+
+## Installation
+
+1. Install Node.js (LTS recommended)
+2. Enable Local REST API plugin in Obsidian
+3. Clone and build:
+```bash
+git clone git@github.com:cyanheads/obsidian-mcp-server.git
+cd obsidian-mcp-server
+npm install
+npm run build
+```
+
+Or install from npm:
+```bash
+npm install obsidian-mcp-server
+```
+
+## Configuration
+
+Add to your MCP client settings:
+
+```json
+{
+  "mcpServers": {
+    "obsidian": {
+      "command": "node",
+      "args": ["/path/to/obsidian-mcp-server/build/index.js"],
+      "env": {
+        "OBSIDIAN_API_KEY": "your-api-key-here",
+        "NODE_ENV": "production"
+      }
+    }
+  }
+}
+```
+
+Environment configuration:
+- `OBSIDIAN_VERIFY_SSL`: Enable SSL verification (default: false)
+- `RATE_LIMIT_WINDOW_MS`: Rate limit window in ms (default: 15 minutes)
+- `RATE_LIMIT_MAX_REQUESTS`: Max requests per window (default: 200)
+- `MAX_TOKENS`: Maximum tokens per response (default: 20000)
+- `TOOL_TIMEOUT_MS`: Tool execution timeout (default: 60000)
+
+## Tools
+
+### File Management
+```typescript
+// List vault contents
+obsidian_list_files_in_vault: {}
+
+// List directory contents
+obsidian_list_files_in_dir: {
+  dirpath: string  // Path relative to vault root
+}
+
+// Get file contents
+obsidian_get_file_contents: {
+  filepath: string  // Path relative to vault root
+}
+```
+
+### Search Operations
+```typescript
+// Text search with context
+obsidian_find_in_file: {
+  query: string,
+  contextLength?: number  // Default: 10
+}
+
+// Advanced search with JsonLogic
+obsidian_complex_search: {
+  query: JsonLogicQuery  // Example: {"glob": ["*.md", {"var": "path"}]}
+}
+```
+
+### Content Modification
+```typescript
+// Append to file
+obsidian_append_content: {
+  filepath: string,  // Path relative to vault root
+  content: string    // Content to append
+}
+
+// Update file content
+obsidian_patch_content: {
+  filepath: string,  // Path relative to vault root
+  content: string    // New content (replaces existing)
+}
+```
+
+## Best Practices
+
+### File Operations
+- Use atomic operations
+- Validate content before modifications
+- Implement proper error handling
+- Monitor operation performance
+
+### Search Implementation
+- Optimize query specificity
+- Control context boundaries
+- Handle large result sets
+- Consider token limits
+
+### Error Prevention
+- Validate inputs thoroughly
+- Handle API errors gracefully
+- Monitor error patterns
+- Check rate limits
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Submit a Pull Request
+
+For bugs and features, create an issue at [https://github.com/cyanheads/obsidian-mcp-server/issues](https://github.com/cyanheads/obsidian-mcp-server/issues).
+
+## Publishing
+
+The package is automatically published to npm when version tags are pushed:
+
+```bash
+# Update version in package.json
+npm version patch  # or minor, or major
+git push --follow-tags
+```
+
+This will trigger the GitHub Action to build and publish the package.
+
+## License
+
+Apache License 2.0
+
+---
+
+<div align="center">
+Built with the Model Context Protocol
+</div>

package/build/index.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import { run } from "./server.js";
+// Main entry point
+if (import.meta.url === `file://${process.argv[1]}`) {
+    run().catch((error) => {
+        console.error("Failed to start server:", error);
+        process.exit(1);
+    });
+}
+export { run };
+//# sourceMappingURL=index.js.map

package/build/obsidian.js

@@ -0,0 +1,197 @@
+import axios from "axios";
+import { ObsidianError, DEFAULT_OBSIDIAN_CONFIG } from "./types.js";
+import { Agent } from "node:https";
+import { readFileSync } from "fs";
+import { fileURLToPath } from 'url';
+import { dirname, join } from "path";
+// Get package version for user agent
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const packagePath = join(__dirname, '..', '..', 'package.json');
+const VERSION = (() => {
+    try {
+        const pkg = JSON.parse(readFileSync(packagePath, 'utf-8'));
+        return pkg.version;
+    }
+    catch (error) {
+        console.warn('Could not read package.json version:', error);
+        return '1.1.0'; // Fallback version
+    }
+})();
+export class ObsidianClient {
+    client;
+    config;
+    constructor(config) {
+        if (!config.apiKey) {
+            throw new ObsidianError("API key is required", 401);
+        }
+        // Combine defaults with provided config
+        this.config = {
+            ...DEFAULT_OBSIDIAN_CONFIG,
+            verifySSL: config.verifySSL ?? process.env.NODE_ENV === 'production', // Enable SSL verification in production by default
+            apiKey: config.apiKey,
+            timeout: config.timeout ?? 5000,
+            maxContentLength: config.maxContentLength ?? 50 * 1024 * 1024, // 50MB
+            maxBodyLength: config.maxBodyLength ?? 50 * 1024 * 1024 // 50MB
+        };
+        // Configure HTTPS agent
+        const httpsAgent = new Agent({
+            rejectUnauthorized: this.config.verifySSL
+        });
+        const axiosConfig = {
+            baseURL: this.getBaseUrl(),
+            headers: {
+                ...this.getHeaders(),
+                // Security headers
+                'X-Content-Type-Options': 'nosniff',
+                'X-Frame-Options': 'DENY',
+                'X-XSS-Protection': '1; mode=block',
+                'Strict-Transport-Security': 'max-age=31536000; includeSubDomains'
+            },
+            validateStatus: (status) => status >= 200 && status < 300,
+            timeout: this.config.timeout,
+            maxRedirects: 5,
+            maxContentLength: this.config.maxContentLength,
+            maxBodyLength: this.config.maxBodyLength,
+            httpsAgent,
+            // Additional security configurations
+            xsrfCookieName: 'XSRF-TOKEN',
+            xsrfHeaderName: 'X-XSRF-TOKEN',
+            withCredentials: true,
+            decompress: true
+        };
+        if (!this.config.verifySSL) {
+            console.warn("WARNING: SSL verification is disabled. This is not recommended for production use.", process.env.NODE_ENV === 'production' ? "Consider enabling SSL verification." : "This is acceptable for local development only.");
+        }
+        this.client = axios.create(axiosConfig);
+    }
+    getBaseUrl() {
+        return `${this.config.protocol}://${this.config.host}:${this.config.port}`;
+    }
+    getHeaders() {
+        const headers = {
+            Authorization: `Bearer ${this.config.apiKey}`,
+            'Accept': 'application/json',
+            'User-Agent': `obsidian-mcp-server/${VERSION}`
+        };
+        // Sanitize headers
+        return Object.fromEntries(Object.entries(headers).map(([key, value]) => [
+            key,
+            this.sanitizeHeader(value)
+        ]));
+    }
+    sanitizeHeader(value) {
+        // Remove any potentially harmful characters from header values
+        return value.replace(/[^\w\s\-\._~:/?#\[\]@!$&'()*+,;=]/g, '');
+    }
+    validateFilePath(filepath) {
+        // Prevent path traversal attacks
+        const normalizedPath = filepath.replace(/\\/g, '/');
+        if (normalizedPath.includes('../') || normalizedPath.includes('..\\')) {
+            throw new ObsidianError('Invalid file path: Path traversal not allowed', 400);
+        }
+        // Additional path validations
+        if (normalizedPath.startsWith('/') || /^[a-zA-Z]:/.test(normalizedPath)) {
+            throw new ObsidianError('Invalid file path: Absolute paths not allowed', 400);
+        }
+    }
+    async safeRequest(operation) {
+        try {
+            return await operation();
+        }
+        catch (error) {
+            if (axios.isAxiosError(error)) {
+                const axiosError = error;
+                const response = axiosError.response;
+                const errorData = response?.data;
+                const code = errorData?.errorCode ?? response?.status ?? 500;
+                const message = errorData?.message ?? axiosError.message ?? "Unknown error";
+                throw new ObsidianError(message, code, errorData);
+            }
+            throw error;
+        }
+    }
+    async listFilesInVault() {
+        return this.safeRequest(async () => {
+            const requestId = crypto.randomUUID();
+            console.debug(`[${requestId}] Listing vault files`);
+            const response = await this.client.get("/vault/");
+            return response.data.files;
+        });
+    }
+    async listFilesInDir(dirpath) {
+        this.validateFilePath(dirpath);
+        return this.safeRequest(async () => {
+            const requestId = crypto.randomUUID();
+            console.debug(`[${requestId}] Listing files in directory: ${dirpath}`);
+            const response = await this.client.get(`/vault/${dirpath}/`);
+            return response.data.files;
+        });
+    }
+    async getFileContents(filepath) {
+        this.validateFilePath(filepath);
+        return this.safeRequest(async () => {
+            const requestId = crypto.randomUUID();
+            console.debug(`[${requestId}] Getting file contents: ${filepath}`);
+            const response = await this.client.get(`/vault/${filepath}`);
+            return response.data;
+        });
+    }
+    async search(query, contextLength = 100) {
+        return this.safeRequest(async () => {
+            const requestId = crypto.randomUUID();
+            console.debug(`[${requestId}] Performing simple search: ${query}`);
+            const response = await this.client.post("/search/simple/", undefined, {
+                params: {
+                    query,
+                    contextLength
+                }
+            });
+            return response.data;
+        });
+    }
+    async appendContent(filepath, content) {
+        this.validateFilePath(filepath);
+        if (!content || typeof content !== 'string') {
+            throw new ObsidianError('Invalid content: Content must be a non-empty string', 400);
+        }
+        return this.safeRequest(async () => {
+            const requestId = crypto.randomUUID();
+            console.debug(`[${requestId}] Appending content to: ${filepath}`);
+            await this.client.post(`/vault/${filepath}`, content, {
+                headers: {
+                    "Content-Type": "text/markdown"
+                }
+            });
+        });
+    }
+    async updateContent(filepath, content) {
+        this.validateFilePath(filepath);
+        if (!content || typeof content !== 'string') {
+            throw new ObsidianError('Invalid content: Content must be a non-empty string', 400);
+        }
+        return this.safeRequest(async () => {
+            const requestId = crypto.randomUUID();
+            console.debug(`[${requestId}] Updating content in: ${filepath}`);
+            await this.client.put(`/vault/${filepath}`, content, {
+                headers: {
+                    "Content-Type": "text/markdown"
+                }
+            });
+        });
+    }
+    async searchJson(query) {
+        return this.safeRequest(async () => {
+            const requestId = crypto.randomUUID();
+            console.debug(`[${requestId}] Performing complex search with query:`, JSON.stringify(query));
+            const response = await this.client.post("/search/", query, {
+                headers: {
+                    "Content-Type": "application/vnd.olrapi.jsonlogic+json",
+                    "Accept": "application/json"
+                }
+            });
+            return response.data;
+        });
+    }
+}
+//# sourceMappingURL=obsidian.js.map

package/build/server.js

@@ -0,0 +1,211 @@
+import { config } from "dotenv";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { ListToolsRequestSchema, CallToolRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+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";
+// Load environment variables
+config();
+const API_KEY = process.env.OBSIDIAN_API_KEY;
+if (!API_KEY) {
+    throw new Error("OBSIDIAN_API_KEY environment variable is required");
+}
+// Get rate limit config from environment or use defaults
+const rateLimitConfig = {
+    windowMs: parseInt(process.env.RATE_LIMIT_WINDOW_MS ?? String(DEFAULT_RATE_LIMIT_CONFIG.windowMs)),
+    maxRequests: parseInt(process.env.RATE_LIMIT_MAX_REQUESTS ?? String(DEFAULT_RATE_LIMIT_CONFIG.maxRequests))
+};
+// Request tracking for rate limiting
+const requestCounts = new Map();
+function checkRateLimit(toolName) {
+    const now = Date.now();
+    const requestInfo = requestCounts.get(toolName);
+    if (!requestInfo || now > requestInfo.resetTime) {
+        // Reset counter for new window
+        requestCounts.set(toolName, {
+            count: 1,
+            resetTime: now + rateLimitConfig.windowMs
+        });
+        return true;
+    }
+    if (requestInfo.count >= rateLimitConfig.maxRequests) {
+        return false;
+    }
+    requestInfo.count++;
+    return true;
+}
+// Clean up expired rate limit entries periodically
+const cleanupInterval = setInterval(() => {
+    const now = Date.now();
+    for (const [tool, info] of requestCounts.entries()) {
+        if (now > info.resetTime) {
+            requestCounts.delete(tool);
+        }
+    }
+}, 60000); // Clean up every minute
+// Initialize Obsidian client
+const client = new ObsidianClient({
+    apiKey: API_KEY,
+    verifySSL: process.env.NODE_ENV === 'production' // Enable SSL verification in production
+});
+const toolHandlers = new Map();
+const handlers = [
+    new ListFilesInVaultToolHandler(client),
+    new ListFilesInDirToolHandler(client),
+    new GetFileContentsToolHandler(client),
+    new FindInFileToolHandler(client),
+    new AppendContentToolHandler(client),
+    new PatchContentToolHandler(client),
+    new ComplexSearchToolHandler(client)
+];
+handlers.forEach(handler => toolHandlers.set(handler.name, handler));
+// Create MCP server
+const server = new Server({
+    name: "obsidian-mcp-server",
+    version: process.env.npm_package_version ?? "1.1.0" // Use version from package.json
+}, {
+    capabilities: {
+        tools: {},
+        resources: {}
+    }
+});
+// Set up request handlers
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    const tools = [];
+    for (const handler of toolHandlers.values()) {
+        tools.push(handler.getToolDescription());
+    }
+    return { tools };
+});
+// Add validation helper
+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') {
+            // Prevent path traversal
+            if (value.includes('../') || value.includes('..\\')) {
+                errors.push(`Field ${key} contains invalid path traversal`);
+            }
+            // Prevent absolute paths
+            if (value.startsWith('/') || /^[a-zA-Z]:/.test(value)) {
+                errors.push(`Field ${key} must be a relative path`);
+            }
+        }
+    }
+    return { valid: errors.length === 0, errors };
+}
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    const handler = toolHandlers.get(name);
+    if (!handler) {
+        throw new ObsidianError(`Unknown tool: ${name}`, 404);
+    }
+    // Check rate limit
+    if (!checkRateLimit(name)) {
+        throw new ObsidianError(`Rate limit exceeded for tool: ${name}. Please try again later.`, 429);
+    }
+    // Add timeout handling
+    const timeoutMs = parseInt(process.env.TOOL_TIMEOUT_MS ?? '60000'); // 60 second default timeout
+    const timeoutPromise = new Promise((_, reject) => {
+        setTimeout(() => {
+            reject(new ObsidianError(`Tool execution timed out after ${timeoutMs}ms`, 408));
+        }, timeoutMs);
+    });
+    try {
+        // Validate arguments against tool's schema
+        const toolDescription = handler.getToolDescription();
+        const validationResult = validateToolArguments(args, toolDescription.inputSchema);
+        if (!validationResult.valid) {
+            throw new ObsidianError(`Invalid tool arguments: ${validationResult.errors.join(', ')}`, 400);
+        }
+        // Race between tool execution and timeout
+        const content = await Promise.race([
+            handler.runTool(args),
+            timeoutPromise
+        ]);
+        return { content };
+    }
+    catch (error) {
+        if (error instanceof ObsidianError) {
+            // Check if the operation actually succeeded despite the error
+            if (error.code === 204) {
+                return {
+                    content: [{
+                            type: "text",
+                            text: "Operation completed successfully"
+                        }]
+                };
+            }
+            throw error;
+        }
+        // Enhanced error logging
+        console.error("Tool execution error:", {
+            name: error instanceof Error ? error.name : 'Unknown',
+            message: error instanceof Error ? error.message : String(error),
+            stack: error instanceof Error ? error.stack : undefined,
+            toolName: name,
+            args
+        });
+        if (error instanceof Error) {
+            throw new ObsidianError(`Tool '${name}' execution failed: ${error.message}`, 500, { originalError: error.stack });
+        }
+        throw new ObsidianError("Tool execution failed with unknown error", 500, { error });
+    }
+});
+// Error handler
+server.onerror = (error) => {
+    console.error("[MCP Error]", error);
+};
+// Handle shutdown
+process.on("SIGINT", async () => {
+    clearInterval(cleanupInterval); // Clean up rate limit interval
+    await server.close();
+    process.exit(0);
+});
+// Export the run function
+export async function run() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("Obsidian MCP server running on stdio");
+}
+//# sourceMappingURL=server.js.map