From 7fedcd9bb602c580e9b7a331fe5b134d9c9daad1 Mon Sep 17 00:00:00 2001 From: Aaron Bockelie Date: Sun, 31 Aug 2025 00:54:07 -0500 Subject: [PATCH] docs: Simplify README with semantic value proposition focus - Replace complex technical README with cleaner, simpler version - Focus on semantic agency and graph navigation as core value - Move detailed documentation to docs/ subdirectory - Create tool-specific documentation for vault and graph operations - Emphasize why semantic MCP matters for AI knowledge access --- README-old.md | 634 +++++++++++++++++++++++++++++++++++++ README.md | 742 +++++++++----------------------------------- docs/tools/graph.md | 253 +++++++++++++++ docs/tools/vault.md | 210 +++++++++++++ 4 files changed, 1236 insertions(+), 603 deletions(-) create mode 100644 README-old.md create mode 100644 docs/tools/graph.md create mode 100644 docs/tools/vault.md diff --git a/README-old.md b/README-old.md new file mode 100644 index 0000000..d5917d4 --- /dev/null +++ b/README-old.md @@ -0,0 +1,634 @@ +# Obsidian MCP Plugin + +> **πŸ“‹ Community Plugin Status**: This plugin is currently under review for inclusion in the Obsidian Community Plugins directory. Submitted on July 10, 2025 - [PR #6991](https://github.com/obsidianmd/obsidian-releases/pull/6991) + +A high-performance Model Context Protocol (MCP) server implemented as an Obsidian plugin, providing AI tools with direct vault access through HTTP transport. + +## Overview + +This plugin brings MCP capabilities directly into Obsidian, eliminating the need for external servers or the REST API plugin. It provides semantic, AI-optimized operations that consolidate multiple tools into intelligent workflows with contextual hints. + +### What are "Semantic Tools"? + +Unlike basic tools that just return data, semantic tools are **self-guiding**. When an AI agent uses a semantic tool, it doesn't just get the requested informationβ€”it also receives smart suggestions about what to do next. This creates a natural workflow where each action leads intelligently to the next, helping AI agents complete complex tasks without getting stuck or needing constant human guidance. + +**Example**: When searching for a file, a semantic tool doesn't just return search results. It also suggests: "Found 3 files matching 'meeting notes'. Consider using `view` to read the most recent one, or `graph traverse` to explore related documents." + +![Obsidian MCP Plugin Settings](docs/Plugin_UI_July_2025.png) + +### Key Features + +- **Direct Obsidian Integration**: Runs natively within Obsidian for maximum performance +- **HTTP MCP Transport**: Compatible with Claude Desktop, Claude Code, Cline, and other MCP clients +- **Semantic Operations**: Enhanced search with Obsidian operators, intelligent fragment retrieval, and workflow guidance +- **No External Dependencies**: No need for the REST API plugin or external servers +- **High Performance**: Sub-100ms response times with direct vault access +- **Concurrent Sessions**: Support for multiple AI agents working simultaneously (v0.5.8+) +- **Worker Thread Processing**: CPU-intensive operations run in parallel threads for non-blocking performance +- **Path Exclusions**: `.mcpignore` file support for blocking sensitive files from AI access +- **Cloud Sync Friendly**: Smart retry logic handles file sync delays from iCloud, OneDrive, Dropbox, and other services + +## πŸ” Path Exclusions with .mcpignore + +Protect sensitive files and directories from AI access using `.gitignore`-style patterns. + +### Overview + +The plugin supports a `.mcpignore` file in your vault root that allows you to exclude specific files and directories from MCP operations. This provides a security layer ensuring that AI tools cannot access your private or sensitive content. + +### Setup + +1. **Enable in Settings**: Toggle "Enable Path Exclusions (.mcpignore)" in plugin settings +2. **Create Template**: Click "Create Template" to generate a starter `.mcpignore` file with examples +3. **Edit Patterns**: Use any text editor to add exclusion patterns + +### Pattern Syntax + +The `.mcpignore` file uses the same syntax as `.gitignore`: + +``` +# Directories +private/ # Excludes 'private' directory and ALL its contents +/private/ # Only excludes 'private' at vault root +work/*/confidential/ # Excludes 'confidential' dirs one level under work/ + +# Files +secrets.md # Excludes this specific file +*.private # All files ending with .private +daily/*.md # All .md files directly in daily/ + +# Negation (whitelist) +!public.private # Allow this specific file despite *.private rule +``` + +### Features + +- **Auto-reload**: Changes to `.mcpignore` take effect immediately +- **Context Menu**: Right-click any file/folder and select "Add to .mcpignore" +- **UI Controls**: Manage from plugin settings with quick access buttons +- **Security**: Blocked paths return `PATH_BLOCKED` errors with no data leakage +- **Protected**: The `.mcpignore` file itself cannot be accessed via MCP + +### Example .mcpignore + +``` +# Personal content +journal/ +diary/ +private/ + +# Work files +work/confidential/ +clients/*/contracts/ + +# Temporary files +*.tmp +*.backup +.#* + +# Allow specific files +!work/public-docs/ +``` + +## ☁️ Cloud Sync Friendly + +The plugin gracefully handles sync delays and file locking from cloud storage services. + +### Supported Services + +Works automatically with: +- **iCloud Drive** - Handles `.icloud` sync artifacts and timing conflicts +- **OneDrive** - Manages file locks and sync delays +- **Dropbox** - Handles sync markers and temporary files +- **Google Drive** - Manages sync state transitions +- **Any sync service** - Universal retry logic works with all platforms + +### How It Works + +The plugin automatically: +1. **Detects sync conflicts** - Recognizes EEXIST, EBUSY, and "file already exists" errors +2. **Retries intelligently** - Uses exponential backoff (500ms β†’ 1s β†’ 2s) +3. **Resolves timing issues** - Allows sync services time to complete operations +4. **Works transparently** - No configuration needed, just works + +### Benefits + +- **No phantom files** - Resolves "file already exists" errors for non-existent files +- **Reliable operations** - File creation, updates, and deletes work consistently +- **Zero configuration** - Automatic detection and handling +- **Cross-platform** - Same behavior on macOS, Windows, and Linux + +## Installation + +> **Note**: This plugin is currently pending review for the Obsidian Community Plugins directory. Until approved, please use the BRAT installation method below. + +### Current Installation: Via BRAT (Beta Reviewer's Auto-update Tool) + +Since this plugin is not yet in the Community Plugins directory, you'll need to use BRAT to install it: + +1. **Install BRAT**: + - Open Obsidian Settings β†’ Community Plugins + - Browse and search for "BRAT" + - Install and enable the [BRAT plugin](https://github.com/TfTHacker/obsidian42-brat) + +2. **Add This Plugin**: + - In Obsidian settings, go to BRAT settings + - Click "Add Beta Plugin" + - Enter: `https://github.com/aaronsb/obsidian-mcp-plugin` + - Click "Add Plugin" + +3. **Enable the Plugin**: + - Go to Settings β†’ Community Plugins + - Find "Obsidian MCP Plugin" and enable it + - The plugin will auto-update through BRAT + +### Future Installation: Via Community Plugins (After Approval) + +Once this plugin is approved and available in the Obsidian Community Plugins directory: + +1. Open Obsidian Settings β†’ Community Plugins +2. Click "Browse" and search for "MCP" +3. Find "Obsidian MCP Plugin" by Aaron Bockelie +4. Click "Install" then "Enable" + +> **For BRAT Users**: After the plugin is approved, you can remove it from BRAT and install it normally through Community Plugins to receive standard updates. + +## Configuration + +1. **Enable the Server**: + - Go to plugin settings + - Toggle "Enable HTTP Server" + - Default port is 3001 (configurable) + +2. **Connect Your MCP Client**: + + ### Claude Code + ```bash + claude mcp add obsidian http://localhost:3001/mcp --transport http + ``` + + ### Claude Desktop / Other Clients + + **Option 1: Direct HTTP Transport** (if your client supports it) + + For HTTP (default): + ```json + { + "mcpServers": { + "obsidian": { + "transport": { + "type": "http", + "url": "http://localhost:3001/mcp" + } + } + } + } + ``` + + For HTTPS (requires proper certificate trust): + ```json + { + "mcpServers": { + "obsidian": { + "transport": { + "type": "http", + "url": "https://localhost:3443/mcp" + } + } + } + } + ``` + Note: Direct HTTPS transport may not work with self-signed certificates. Use Option 2 with mcp-remote for HTTPS. + + **Option 2: Via mcp-remote** (recommended for Claude Desktop) + + Since Claude Desktop might not support streaming HTTP transport yet, use mcp-remote: + ```json + { + "mcpServers": { + "obsidian-vault-name": { + "command": "npx", + "args": [ + "mcp-remote", + "http://localhost:3001/mcp" + ] + } + } + } + ``` + + **⚠️ Important for HTTPS**: If using HTTPS (port 3443) with self-signed certificates, you MUST add the `NODE_TLS_REJECT_UNAUTHORIZED` environment variable. See the [HTTPS/TLS Configuration](#httpstls-configuration-v090) section below for details. + + Configuration file locations: + - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` + - Windows: `%APPDATA%\Claude\claude_desktop_config.json` + - Linux: `~/.config/Claude/claude_desktop_config.json` + + **Windows Note**: If you encounter command line parsing errors with the Authorization header, use this format instead: + ```json + { + "mcpServers": { + "obsidian-vault-name": { + "command": "npx", + "args": [ + "mcp-remote", + "http://localhost:3001/mcp", + "--header", + "Authorization:${AUTH}" + ], + "env": { + "AUTH": "Bearer YOUR_API_KEY_HERE" + } + } + } + } + ``` + This avoids Windows command line issues with spaces in arguments. + +### HTTPS/TLS Configuration (v0.9.0+) + +The plugin supports secure HTTPS connections with both self-signed and CA-signed certificates, making it ideal for various deployment scenarios including Docker containers and headless servers. + +#### Certificate Options + +1. **Self-Signed Certificates (Default)**: + - Auto-generated on first launch + - Stored in `.obsidian/plugins/semantic-vault-mcp/certificates/` + - Valid for 1 year with localhost/127.0.0.1 SANs + - Perfect for local development + +2. **Custom CA-Signed Certificates**: + - Provide your own certificate and key files + - Ideal for production environments, Docker containers, or headless servers + - No client-side certificate trust workarounds needed + - Supports standard PEM format certificates + +#### Configuration Steps + +1. **Enable HTTPS in Plugin Settings**: + - Go to plugin settings in Obsidian + - Find "HTTPS/TLS Settings" section + - Toggle "Enable HTTPS Server" + - Default HTTPS port is 3443 (auto-increments if in use) + + **For Custom Certificates**: + - Clear the auto-generated certificate paths + - Enter paths to your certificate and key files + - Supported formats: `.pem`, `.crt`, `.key` + +2. **Configure Claude Code / MCP Client**: + + **For Self-Signed Certificates**: + ```json + { + "mcpServers": { + "obsidian-vault-name": { + "command": "npx", + "args": [ + "mcp-remote", + "https://localhost:3443/mcp", + "--header", + "Authorization:${AUTH}" + ], + "env": { + "NODE_TLS_REJECT_UNAUTHORIZED": "0", + "AUTH": "Bearer YOUR_API_KEY_HERE" + } + } + } + } + ``` + Note: The `env` section is required for self-signed certificates. The Authorization header uses `${AUTH}` to avoid Windows command line issues. + + **For CA-Signed Certificates**: + ```json + { + "mcpServers": { + "obsidian-vault-name": { + "command": "npx", + "args": [ + "mcp-remote", + "https://your-domain.com:3443/mcp", + "--header", + "Authorization:${AUTH}" + ], + "env": { + "AUTH": "Bearer YOUR_API_KEY_HERE" + } + } + } + } + ``` + Note: No `NODE_TLS_REJECT_UNAUTHORIZED` needed - the certificate is trusted by default. + +#### Docker & Headless Deployment + +The HTTPS support is particularly useful for running Obsidian in headless environments: + +1. **Docker Container Setup**: + ```dockerfile + # Mount your certificates into the container + VOLUME ["/certs"] + + # Configure plugin to use mounted certificates + # Set certificate paths in plugin settings: + # - Certificate Path: /certs/server.crt + # - Key Path: /certs/server.key + ``` + +2. **Benefits for Headless Environments**: + - Secure remote access to your Obsidian vault + - No GUI needed for certificate configuration + - Proper TLS encryption for production deployments + - Compatible with reverse proxies and load balancers + +3. **Example Docker Compose**: + ```yaml + services: + obsidian: + image: your-obsidian-image + ports: + - "3443:3443" + volumes: + - ./certs:/certs:ro + - ./vault:/vault + environment: + - OBSIDIAN_CERT_PATH=/certs/server.crt + - OBSIDIAN_KEY_PATH=/certs/server.key + ``` + +#### Certificate Management Tips + +1. **Generate a Proper Certificate with Let's Encrypt**: + ```bash + certbot certonly --standalone -d your-domain.com + # Certificates will be in /etc/letsencrypt/live/your-domain.com/ + ``` + +2. **Create a Self-Signed Certificate Manually**: + ```bash + openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem \ + -days 365 -nodes -subj "/CN=localhost" + ``` + +3. **Certificate Requirements**: + - Must be in PEM format + - Private key should not be password-protected + - Include proper SANs for your domain/IP + +4. **Security Considerations**: + - Use CA-signed certificates for production + - Self-signed certificates are suitable for local development only + - Keep private keys secure and never commit them to version control + - Rotate certificates before expiration + +### Concurrent Sessions for Agent Swarms (v0.5.8+) + +Enable multiple AI agents to work with your vault simultaneously without blocking each other: + +1. **Enable in Settings**: + - Go to plugin settings + - Find "Concurrent Sessions" section + - Toggle "Enable Concurrent Sessions for Agent Swarms" + - Adjust max connections if needed (default: 32) + +2. **Architecture**: + - Each AI session gets its own isolated MCP server instance + - True parallel processing - no blocking between sessions + - Automatic session management with 1-hour timeout + - Session reuse for reconnecting clients + +3. **Monitor Active Sessions**: + - Use the `obsidian://session-info` resource to view: + - Active sessions with "This is you!" indicator + - Session age, idle time, and request counts + - Server pool utilization statistics + +4. **Use Cases**: + - Multiple Claude instances working on different parts of your vault + - AI agent teams collaborating on research or writing projects + - Parallel processing of large knowledge bases + - Non-blocking operation for time-sensitive workflows + +## Available Tools + +### πŸ—‚οΈ `vault` - File and Folder Operations +- `list` - List files and directories +- `read` - Read file content with fragments for large files +- `create` - Create new files and directories +- `update` - Update existing files +- `delete` - Delete files and folders +- `search` - Enhanced search with Obsidian operators +- `fragments` - Get relevant excerpts from files +- `move` - Move files to new locations (preserves links) +- `rename` - Rename files in place (preserves links) +- `copy` - Create copies of files +- `split` - Split files by headings, delimiter, lines, or size +- `combine` - Merge multiple files with sorting options +- `concatenate` - Simple two-file joining + +**πŸ” Search Operators**: +- `file:` - Search by filename or extension (e.g., `file:.png`) +- `path:` - Search in file paths +- `content:` - Search only in file content +- `tag:` - Search for tags +- `"exact phrase"` - Search for exact phrases +- `term1 OR term2` - Search for either term +- `/regex/flags` - Regular expression search + +### ✏️ `edit` - Smart Editing Operations +- `window` - Edit with automatic content buffering +- `append` - Append content to files +- `patch` - Intelligent patching with fuzzy matching +- `at_line` - Edit at specific line numbers +- `from_buffer` - Recover content from edit buffers + +### πŸ‘οΈ `view` - Content Viewing and Navigation +- `file` - View complete files with metadata +- `window` - View content windows with context +- `active` - Get currently active file +- `open_in_obsidian` - Open files in Obsidian + +### πŸ”„ `workflow` - AI Workflow Guidance +- `suggest` - Get contextual suggestions based on current operations + +### πŸ•ΈοΈ `graph` - Graph Traversal and Link Analysis +- `traverse` - Explore connected nodes from a starting point +- `neighbors` - Get immediate connections of a file +- `path` - Find paths between two nodes +- `statistics` - Get link counts and statistics for files +- `backlinks` - Find all incoming links to a file +- `forwardlinks` - Find all outgoing links from a file +- `search-traverse` - Search-based graph traversal with snippet chains +- `advanced-traverse` - Multi-query traversal with strategies (breadth-first, best-first, beam-search) + +**Graph Features**: +- `links/backlinks/tags` - Follow connections during traversal +- `pattern/folder/tag filters` - Filter by file patterns, folders, or tags +- `depth/max_nodes` - Control traversal depth and maximum nodes +- `relevance_scores` - Get relevance scores and snippet chains +- `orphaned/unresolved` - Support for orphaned notes and unresolved links + +### βš™οΈ `system` - System Operations +- `info` - Get vault and plugin information +- `commands` - List and execute Obsidian commands +- `fetch_web` - Fetch and convert web content to markdown + +## Configuration + +### Plugin Settings + +Access plugin settings via Obsidian Settings β†’ Community Plugins β†’ Obsidian MCP Plugin β†’ Settings + +- **HTTP Port**: Port for MCP server (default: 3001) +- **Enable Concurrent Sessions**: Allow multiple AI agents to work simultaneously (default: enabled) +- **Max Concurrent Connections**: Maximum number of parallel operations (default: 32) +- **Path Exclusions (.mcpignore)**: Enable/disable path blocking via `.mcpignore` file +- **Enable Context Menu**: Add "Add to .mcpignore" to file/folder right-click menus +- **Debug Logging**: Enable detailed console logging for troubleshooting + +### Concurrent Sessions (v0.5.8+) + +The plugin supports multiple AI agents working simultaneously through session-based connection pooling: + +- Each MCP client gets a unique session ID +- Sessions are isolated and tracked independently +- CPU-intensive operations (search, graph traversal) can run in parallel +- Worker threads prevent blocking the main Obsidian UI +- Sessions automatically expire after 1 hour of inactivity + +**Performance with Concurrent Sessions**: +- Up to 32 simultaneous operations (configurable) +- Worker threads for CPU-intensive tasks +- Non-blocking UI during heavy operations +- Automatic session cleanup and resource management + +## MCP Resources + +- **`obsidian://vault-info`** - Real-time vault metadata including file counts, active file, and plugin status +- **`obsidian://session-info`** - Active sessions and connection pool statistics (when concurrent sessions enabled) + +## Key Improvements Over External MCP Servers + +1. **Performance**: Direct vault access eliminates HTTP overhead +2. **Search**: Uses Obsidian's native search with advanced operators +3. **Integration**: Access to full Obsidian API and plugin ecosystem +4. **Simplicity**: Single plugin installation, no external dependencies +5. **Reliability**: No separate processes to manage or crash + +## Architecture + +This plugin implements the same semantic operations as [obsidian-semantic-mcp](https://github.com/aaronsb/obsidian-semantic-mcp) but runs directly within Obsidian: + +``` +Before: AI Tool β†’ MCP Server β†’ REST API Plugin β†’ Obsidian +Now: AI Tool β†’ MCP Plugin (within Obsidian) +``` + +The critical `ObsidianAPI` abstraction layer is preserved, allowing all semantic operations to work identically while gaining the performance benefits of direct integration. + +## Testing Status + +βœ… **Working Features**: +- All 6 semantic tools with all actions +- Enhanced search with Obsidian operators +- Graph traversal and link analysis +- Image viewing and file operations +- Fragment retrieval for large files +- Workflow hints and guidance +- Multi-vault support +- Port collision detection +- Cross-platform tested (Linux, Windows, macOS) + +⚑ **Performance Results**: +- File operations: <10ms (vs ~50-100ms with REST API) +- Search operations: <50ms (vs ~100-300ms) +- Zero network overhead + +## Development + +```bash +# Clone to your vault's plugins folder +git clone https://github.com/aaronsb/obsidian-mcp-plugin .obsidian/plugins/obsidian-mcp-plugin + +# Install dependencies +npm install + +# Build for development +npm run dev + +# Build for production +npm run build +``` + +## Troubleshooting + +### Tools Not Appearing in Claude Desktop + +If the MCP server connects but no tools appear in Claude Desktop: + +1. **Check your configuration URL**: Make sure you're using the correct protocol and port + - HTTP: `http://localhost:3001/mcp` + - HTTPS: `https://localhost:3443/mcp` + +2. **For HTTPS with self-signed certificates**: You MUST add `NODE_TLS_REJECT_UNAUTHORIZED`: + ```json + { + "mcpServers": { + "obsidian-vault": { + "command": "npx", + "args": ["mcp-remote", "https://localhost:3443/mcp"], + "env": { + "NODE_TLS_REJECT_UNAUTHORIZED": "0" + } + } + } + } + ``` + +3. **Restart Claude Desktop** after any configuration changes + +### Windows: "Program is not recognized" Error + +If you see `'D:\Program' is not recognized...` on Windows with Node.js in Program Files: + +**Solution**: Use the full path to npx.cmd from your npm global directory: +```json +{ + "mcpServers": { + "obsidian-vault": { + "command": "C:\\Users\\[YOUR_USERNAME]\\AppData\\Roaming\\npm\\npx.cmd", + "args": ["mcp-remote", "http://localhost:3001/mcp"] + } + } +} +``` + +### Connection Timeouts + +If you experience connection timeouts: +- Ensure the plugin is enabled in Obsidian settings +- Check that the MCP server is running (look for the status in plugin settings) +- Verify no firewall is blocking the ports (3001 for HTTP, 3443 for HTTPS) +- Try using HTTP first to rule out certificate issues + +## Support + +- **Issues**: [GitHub Issues](https://github.com/aaronsb/obsidian-mcp-plugin/issues) +- **Discussions**: [GitHub Discussions](https://github.com/aaronsb/obsidian-mcp-plugin/discussions) + +## Sponsorship + +If you find this plugin useful, please consider supporting its development: + +[![GitHub Sponsors](https://img.shields.io/badge/Sponsor-%E2%9D%A4-red?logo=github)](https://github.com/sponsors/aaronsb) + +Your support helps maintain and improve this plugin! + +## License + +MIT + +--- + +*This plugin brings the power of semantic MCP directly into Obsidian, providing AI tools with intelligent, high-performance vault access.* diff --git a/README.md b/README.md index d5917d4..954234a 100644 --- a/README.md +++ b/README.md @@ -1,634 +1,170 @@ # Obsidian MCP Plugin -> **πŸ“‹ Community Plugin Status**: This plugin is currently under review for inclusion in the Obsidian Community Plugins directory. Submitted on July 10, 2025 - [PR #6991](https://github.com/obsidianmd/obsidian-releases/pull/6991) +**Give AI semantic agency over your knowledge graph** -A high-performance Model Context Protocol (MCP) server implemented as an Obsidian plugin, providing AI tools with direct vault access through HTTP transport. +This plugin enables AI assistants (Claude, ChatGPT, etc.) to understand and navigate your Obsidian vault as a connected knowledge graph, not just isolated files. Through semantic hints and graph traversal, AI gains the agency to explore concepts, follow connections, and synthesize information across your entire vault. -## Overview +## Why Semantic MCP? -This plugin brings MCP capabilities directly into Obsidian, eliminating the need for external servers or the REST API plugin. It provides semantic, AI-optimized operations that consolidate multiple tools into intelligent workflows with contextual hints. +Traditional file access gives AI a narrow view - one document at a time. This plugin transforms that into **semantic agency**: -### What are "Semantic Tools"? +- **Graph Navigation**: AI follows links between notes, understanding relationships and context +- **Concept Discovery**: Semantic search finds related ideas across your vault +- **Contextual Awareness**: AI understands where information lives in your knowledge structure +- **Intelligent Synthesis**: Combine fragments from multiple notes to answer complex questions -Unlike basic tools that just return data, semantic tools are **self-guiding**. When an AI agent uses a semantic tool, it doesn't just get the requested informationβ€”it also receives smart suggestions about what to do next. This creates a natural workflow where each action leads intelligently to the next, helping AI agents complete complex tasks without getting stuck or needing constant human guidance. +## Quick Start -**Example**: When searching for a file, a semantic tool doesn't just return search results. It also suggests: "Found 3 files matching 'meeting notes'. Consider using `view` to read the most recent one, or `graph traverse` to explore related documents." +### 1. Install the Plugin -![Obsidian MCP Plugin Settings](docs/Plugin_UI_July_2025.png) +**Via Obsidian Community Plugins** (coming soon) +- Open Settings β†’ Community plugins +- Search for "Semantic MCP" +- Install and enable -### Key Features +**Via BRAT** (for beta testing) +- Install [BRAT](https://github.com/TfTHacker/obsidian42-brat) +- Add beta plugin: `aaronsb/obsidian-mcp-plugin` -- **Direct Obsidian Integration**: Runs natively within Obsidian for maximum performance -- **HTTP MCP Transport**: Compatible with Claude Desktop, Claude Code, Cline, and other MCP clients -- **Semantic Operations**: Enhanced search with Obsidian operators, intelligent fragment retrieval, and workflow guidance -- **No External Dependencies**: No need for the REST API plugin or external servers -- **High Performance**: Sub-100ms response times with direct vault access -- **Concurrent Sessions**: Support for multiple AI agents working simultaneously (v0.5.8+) -- **Worker Thread Processing**: CPU-intensive operations run in parallel threads for non-blocking performance -- **Path Exclusions**: `.mcpignore` file support for blocking sensitive files from AI access -- **Cloud Sync Friendly**: Smart retry logic handles file sync delays from iCloud, OneDrive, Dropbox, and other services +### 2. Configure Your AI Client -## πŸ” Path Exclusions with .mcpignore - -Protect sensitive files and directories from AI access using `.gitignore`-style patterns. - -### Overview - -The plugin supports a `.mcpignore` file in your vault root that allows you to exclude specific files and directories from MCP operations. This provides a security layer ensuring that AI tools cannot access your private or sensitive content. - -### Setup - -1. **Enable in Settings**: Toggle "Enable Path Exclusions (.mcpignore)" in plugin settings -2. **Create Template**: Click "Create Template" to generate a starter `.mcpignore` file with examples -3. **Edit Patterns**: Use any text editor to add exclusion patterns - -### Pattern Syntax - -The `.mcpignore` file uses the same syntax as `.gitignore`: - -``` -# Directories -private/ # Excludes 'private' directory and ALL its contents -/private/ # Only excludes 'private' at vault root -work/*/confidential/ # Excludes 'confidential' dirs one level under work/ - -# Files -secrets.md # Excludes this specific file -*.private # All files ending with .private -daily/*.md # All .md files directly in daily/ - -# Negation (whitelist) -!public.private # Allow this specific file despite *.private rule -``` - -### Features - -- **Auto-reload**: Changes to `.mcpignore` take effect immediately -- **Context Menu**: Right-click any file/folder and select "Add to .mcpignore" -- **UI Controls**: Manage from plugin settings with quick access buttons -- **Security**: Blocked paths return `PATH_BLOCKED` errors with no data leakage -- **Protected**: The `.mcpignore` file itself cannot be accessed via MCP - -### Example .mcpignore - -``` -# Personal content -journal/ -diary/ -private/ - -# Work files -work/confidential/ -clients/*/contracts/ - -# Temporary files -*.tmp -*.backup -.#* - -# Allow specific files -!work/public-docs/ -``` - -## ☁️ Cloud Sync Friendly - -The plugin gracefully handles sync delays and file locking from cloud storage services. - -### Supported Services - -Works automatically with: -- **iCloud Drive** - Handles `.icloud` sync artifacts and timing conflicts -- **OneDrive** - Manages file locks and sync delays -- **Dropbox** - Handles sync markers and temporary files -- **Google Drive** - Manages sync state transitions -- **Any sync service** - Universal retry logic works with all platforms - -### How It Works - -The plugin automatically: -1. **Detects sync conflicts** - Recognizes EEXIST, EBUSY, and "file already exists" errors -2. **Retries intelligently** - Uses exponential backoff (500ms β†’ 1s β†’ 2s) -3. **Resolves timing issues** - Allows sync services time to complete operations -4. **Works transparently** - No configuration needed, just works - -### Benefits - -- **No phantom files** - Resolves "file already exists" errors for non-existent files -- **Reliable operations** - File creation, updates, and deletes work consistently -- **Zero configuration** - Automatic detection and handling -- **Cross-platform** - Same behavior on macOS, Windows, and Linux - -## Installation - -> **Note**: This plugin is currently pending review for the Obsidian Community Plugins directory. Until approved, please use the BRAT installation method below. - -### Current Installation: Via BRAT (Beta Reviewer's Auto-update Tool) - -Since this plugin is not yet in the Community Plugins directory, you'll need to use BRAT to install it: - -1. **Install BRAT**: - - Open Obsidian Settings β†’ Community Plugins - - Browse and search for "BRAT" - - Install and enable the [BRAT plugin](https://github.com/TfTHacker/obsidian42-brat) - -2. **Add This Plugin**: - - In Obsidian settings, go to BRAT settings - - Click "Add Beta Plugin" - - Enter: `https://github.com/aaronsb/obsidian-mcp-plugin` - - Click "Add Plugin" - -3. **Enable the Plugin**: - - Go to Settings β†’ Community Plugins - - Find "Obsidian MCP Plugin" and enable it - - The plugin will auto-update through BRAT - -### Future Installation: Via Community Plugins (After Approval) - -Once this plugin is approved and available in the Obsidian Community Plugins directory: - -1. Open Obsidian Settings β†’ Community Plugins -2. Click "Browse" and search for "MCP" -3. Find "Obsidian MCP Plugin" by Aaron Bockelie -4. Click "Install" then "Enable" - -> **For BRAT Users**: After the plugin is approved, you can remove it from BRAT and install it normally through Community Plugins to receive standard updates. - -## Configuration - -1. **Enable the Server**: - - Go to plugin settings - - Toggle "Enable HTTP Server" - - Default port is 3001 (configurable) - -2. **Connect Your MCP Client**: - - ### Claude Code - ```bash - claude mcp add obsidian http://localhost:3001/mcp --transport http - ``` - - ### Claude Desktop / Other Clients - - **Option 1: Direct HTTP Transport** (if your client supports it) - - For HTTP (default): - ```json - { - "mcpServers": { - "obsidian": { - "transport": { - "type": "http", - "url": "http://localhost:3001/mcp" - } - } - } - } - ``` - - For HTTPS (requires proper certificate trust): - ```json - { - "mcpServers": { - "obsidian": { - "transport": { - "type": "http", - "url": "https://localhost:3443/mcp" - } - } - } - } - ``` - Note: Direct HTTPS transport may not work with self-signed certificates. Use Option 2 with mcp-remote for HTTPS. - - **Option 2: Via mcp-remote** (recommended for Claude Desktop) - - Since Claude Desktop might not support streaming HTTP transport yet, use mcp-remote: - ```json - { - "mcpServers": { - "obsidian-vault-name": { - "command": "npx", - "args": [ - "mcp-remote", - "http://localhost:3001/mcp" - ] - } - } - } - ``` - - **⚠️ Important for HTTPS**: If using HTTPS (port 3443) with self-signed certificates, you MUST add the `NODE_TLS_REJECT_UNAUTHORIZED` environment variable. See the [HTTPS/TLS Configuration](#httpstls-configuration-v090) section below for details. - - Configuration file locations: - - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` - - Windows: `%APPDATA%\Claude\claude_desktop_config.json` - - Linux: `~/.config/Claude/claude_desktop_config.json` - - **Windows Note**: If you encounter command line parsing errors with the Authorization header, use this format instead: - ```json - { - "mcpServers": { - "obsidian-vault-name": { - "command": "npx", - "args": [ - "mcp-remote", - "http://localhost:3001/mcp", - "--header", - "Authorization:${AUTH}" - ], - "env": { - "AUTH": "Bearer YOUR_API_KEY_HERE" - } - } - } - } - ``` - This avoids Windows command line issues with spaces in arguments. - -### HTTPS/TLS Configuration (v0.9.0+) - -The plugin supports secure HTTPS connections with both self-signed and CA-signed certificates, making it ideal for various deployment scenarios including Docker containers and headless servers. - -#### Certificate Options - -1. **Self-Signed Certificates (Default)**: - - Auto-generated on first launch - - Stored in `.obsidian/plugins/semantic-vault-mcp/certificates/` - - Valid for 1 year with localhost/127.0.0.1 SANs - - Perfect for local development - -2. **Custom CA-Signed Certificates**: - - Provide your own certificate and key files - - Ideal for production environments, Docker containers, or headless servers - - No client-side certificate trust workarounds needed - - Supports standard PEM format certificates - -#### Configuration Steps - -1. **Enable HTTPS in Plugin Settings**: - - Go to plugin settings in Obsidian - - Find "HTTPS/TLS Settings" section - - Toggle "Enable HTTPS Server" - - Default HTTPS port is 3443 (auto-increments if in use) - - **For Custom Certificates**: - - Clear the auto-generated certificate paths - - Enter paths to your certificate and key files - - Supported formats: `.pem`, `.crt`, `.key` - -2. **Configure Claude Code / MCP Client**: - - **For Self-Signed Certificates**: - ```json - { - "mcpServers": { - "obsidian-vault-name": { - "command": "npx", - "args": [ - "mcp-remote", - "https://localhost:3443/mcp", - "--header", - "Authorization:${AUTH}" - ], - "env": { - "NODE_TLS_REJECT_UNAUTHORIZED": "0", - "AUTH": "Bearer YOUR_API_KEY_HERE" - } - } - } - } - ``` - Note: The `env` section is required for self-signed certificates. The Authorization header uses `${AUTH}` to avoid Windows command line issues. - - **For CA-Signed Certificates**: - ```json - { - "mcpServers": { - "obsidian-vault-name": { - "command": "npx", - "args": [ - "mcp-remote", - "https://your-domain.com:3443/mcp", - "--header", - "Authorization:${AUTH}" - ], - "env": { - "AUTH": "Bearer YOUR_API_KEY_HERE" - } - } - } - } - ``` - Note: No `NODE_TLS_REJECT_UNAUTHORIZED` needed - the certificate is trusted by default. - -#### Docker & Headless Deployment - -The HTTPS support is particularly useful for running Obsidian in headless environments: - -1. **Docker Container Setup**: - ```dockerfile - # Mount your certificates into the container - VOLUME ["/certs"] - - # Configure plugin to use mounted certificates - # Set certificate paths in plugin settings: - # - Certificate Path: /certs/server.crt - # - Key Path: /certs/server.key - ``` - -2. **Benefits for Headless Environments**: - - Secure remote access to your Obsidian vault - - No GUI needed for certificate configuration - - Proper TLS encryption for production deployments - - Compatible with reverse proxies and load balancers - -3. **Example Docker Compose**: - ```yaml - services: - obsidian: - image: your-obsidian-image - ports: - - "3443:3443" - volumes: - - ./certs:/certs:ro - - ./vault:/vault - environment: - - OBSIDIAN_CERT_PATH=/certs/server.crt - - OBSIDIAN_KEY_PATH=/certs/server.key - ``` - -#### Certificate Management Tips - -1. **Generate a Proper Certificate with Let's Encrypt**: - ```bash - certbot certonly --standalone -d your-domain.com - # Certificates will be in /etc/letsencrypt/live/your-domain.com/ - ``` - -2. **Create a Self-Signed Certificate Manually**: - ```bash - openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem \ - -days 365 -nodes -subj "/CN=localhost" - ``` - -3. **Certificate Requirements**: - - Must be in PEM format - - Private key should not be password-protected - - Include proper SANs for your domain/IP - -4. **Security Considerations**: - - Use CA-signed certificates for production - - Self-signed certificates are suitable for local development only - - Keep private keys secure and never commit them to version control - - Rotate certificates before expiration - -### Concurrent Sessions for Agent Swarms (v0.5.8+) - -Enable multiple AI agents to work with your vault simultaneously without blocking each other: - -1. **Enable in Settings**: - - Go to plugin settings - - Find "Concurrent Sessions" section - - Toggle "Enable Concurrent Sessions for Agent Swarms" - - Adjust max connections if needed (default: 32) - -2. **Architecture**: - - Each AI session gets its own isolated MCP server instance - - True parallel processing - no blocking between sessions - - Automatic session management with 1-hour timeout - - Session reuse for reconnecting clients - -3. **Monitor Active Sessions**: - - Use the `obsidian://session-info` resource to view: - - Active sessions with "This is you!" indicator - - Session age, idle time, and request counts - - Server pool utilization statistics - -4. **Use Cases**: - - Multiple Claude instances working on different parts of your vault - - AI agent teams collaborating on research or writing projects - - Parallel processing of large knowledge bases - - Non-blocking operation for time-sensitive workflows - -## Available Tools - -### πŸ—‚οΈ `vault` - File and Folder Operations -- `list` - List files and directories -- `read` - Read file content with fragments for large files -- `create` - Create new files and directories -- `update` - Update existing files -- `delete` - Delete files and folders -- `search` - Enhanced search with Obsidian operators -- `fragments` - Get relevant excerpts from files -- `move` - Move files to new locations (preserves links) -- `rename` - Rename files in place (preserves links) -- `copy` - Create copies of files -- `split` - Split files by headings, delimiter, lines, or size -- `combine` - Merge multiple files with sorting options -- `concatenate` - Simple two-file joining - -**πŸ” Search Operators**: -- `file:` - Search by filename or extension (e.g., `file:.png`) -- `path:` - Search in file paths -- `content:` - Search only in file content -- `tag:` - Search for tags -- `"exact phrase"` - Search for exact phrases -- `term1 OR term2` - Search for either term -- `/regex/flags` - Regular expression search - -### ✏️ `edit` - Smart Editing Operations -- `window` - Edit with automatic content buffering -- `append` - Append content to files -- `patch` - Intelligent patching with fuzzy matching -- `at_line` - Edit at specific line numbers -- `from_buffer` - Recover content from edit buffers - -### πŸ‘οΈ `view` - Content Viewing and Navigation -- `file` - View complete files with metadata -- `window` - View content windows with context -- `active` - Get currently active file -- `open_in_obsidian` - Open files in Obsidian - -### πŸ”„ `workflow` - AI Workflow Guidance -- `suggest` - Get contextual suggestions based on current operations - -### πŸ•ΈοΈ `graph` - Graph Traversal and Link Analysis -- `traverse` - Explore connected nodes from a starting point -- `neighbors` - Get immediate connections of a file -- `path` - Find paths between two nodes -- `statistics` - Get link counts and statistics for files -- `backlinks` - Find all incoming links to a file -- `forwardlinks` - Find all outgoing links from a file -- `search-traverse` - Search-based graph traversal with snippet chains -- `advanced-traverse` - Multi-query traversal with strategies (breadth-first, best-first, beam-search) - -**Graph Features**: -- `links/backlinks/tags` - Follow connections during traversal -- `pattern/folder/tag filters` - Filter by file patterns, folders, or tags -- `depth/max_nodes` - Control traversal depth and maximum nodes -- `relevance_scores` - Get relevance scores and snippet chains -- `orphaned/unresolved` - Support for orphaned notes and unresolved links - -### βš™οΈ `system` - System Operations -- `info` - Get vault and plugin information -- `commands` - List and execute Obsidian commands -- `fetch_web` - Fetch and convert web content to markdown - -## Configuration - -### Plugin Settings - -Access plugin settings via Obsidian Settings β†’ Community Plugins β†’ Obsidian MCP Plugin β†’ Settings - -- **HTTP Port**: Port for MCP server (default: 3001) -- **Enable Concurrent Sessions**: Allow multiple AI agents to work simultaneously (default: enabled) -- **Max Concurrent Connections**: Maximum number of parallel operations (default: 32) -- **Path Exclusions (.mcpignore)**: Enable/disable path blocking via `.mcpignore` file -- **Enable Context Menu**: Add "Add to .mcpignore" to file/folder right-click menus -- **Debug Logging**: Enable detailed console logging for troubleshooting - -### Concurrent Sessions (v0.5.8+) - -The plugin supports multiple AI agents working simultaneously through session-based connection pooling: - -- Each MCP client gets a unique session ID -- Sessions are isolated and tracked independently -- CPU-intensive operations (search, graph traversal) can run in parallel -- Worker threads prevent blocking the main Obsidian UI -- Sessions automatically expire after 1 hour of inactivity - -**Performance with Concurrent Sessions**: -- Up to 32 simultaneous operations (configurable) -- Worker threads for CPU-intensive tasks -- Non-blocking UI during heavy operations -- Automatic session cleanup and resource management - -## MCP Resources - -- **`obsidian://vault-info`** - Real-time vault metadata including file counts, active file, and plugin status -- **`obsidian://session-info`** - Active sessions and connection pool statistics (when concurrent sessions enabled) - -## Key Improvements Over External MCP Servers - -1. **Performance**: Direct vault access eliminates HTTP overhead -2. **Search**: Uses Obsidian's native search with advanced operators -3. **Integration**: Access to full Obsidian API and plugin ecosystem -4. **Simplicity**: Single plugin installation, no external dependencies -5. **Reliability**: No separate processes to manage or crash - -## Architecture - -This plugin implements the same semantic operations as [obsidian-semantic-mcp](https://github.com/aaronsb/obsidian-semantic-mcp) but runs directly within Obsidian: - -``` -Before: AI Tool β†’ MCP Server β†’ REST API Plugin β†’ Obsidian -Now: AI Tool β†’ MCP Plugin (within Obsidian) -``` - -The critical `ObsidianAPI` abstraction layer is preserved, allowing all semantic operations to work identically while gaining the performance benefits of direct integration. - -## Testing Status - -βœ… **Working Features**: -- All 6 semantic tools with all actions -- Enhanced search with Obsidian operators -- Graph traversal and link analysis -- Image viewing and file operations -- Fragment retrieval for large files -- Workflow hints and guidance -- Multi-vault support -- Port collision detection -- Cross-platform tested (Linux, Windows, macOS) - -⚑ **Performance Results**: -- File operations: <10ms (vs ~50-100ms with REST API) -- Search operations: <50ms (vs ~100-300ms) -- Zero network overhead - -## Development - -```bash -# Clone to your vault's plugins folder -git clone https://github.com/aaronsb/obsidian-mcp-plugin .obsidian/plugins/obsidian-mcp-plugin - -# Install dependencies -npm install - -# Build for development -npm run dev - -# Build for production -npm run build -``` - -## Troubleshooting - -### Tools Not Appearing in Claude Desktop - -If the MCP server connects but no tools appear in Claude Desktop: - -1. **Check your configuration URL**: Make sure you're using the correct protocol and port - - HTTP: `http://localhost:3001/mcp` - - HTTPS: `https://localhost:3443/mcp` - -2. **For HTTPS with self-signed certificates**: You MUST add `NODE_TLS_REJECT_UNAUTHORIZED`: - ```json - { - "mcpServers": { - "obsidian-vault": { - "command": "npx", - "args": ["mcp-remote", "https://localhost:3443/mcp"], - "env": { - "NODE_TLS_REJECT_UNAUTHORIZED": "0" - } - } - } - } - ``` - -3. **Restart Claude Desktop** after any configuration changes - -### Windows: "Program is not recognized" Error - -If you see `'D:\Program' is not recognized...` on Windows with Node.js in Program Files: - -**Solution**: Use the full path to npx.cmd from your npm global directory: +**Claude Desktop** ```json { "mcpServers": { "obsidian-vault": { - "command": "C:\\Users\\[YOUR_USERNAME]\\AppData\\Roaming\\npm\\npx.cmd", + "command": "npx", "args": ["mcp-remote", "http://localhost:3001/mcp"] } } } ``` -### Connection Timeouts +**With Authentication** (if enabled in plugin settings) +```json +{ + "mcpServers": { + "obsidian-vault": { + "command": "npx", + "args": [ + "mcp-remote", + "https://localhost:3443/mcp", + "--header", + "Authorization:${AUTH}" + ], + "env": { + "NODE_TLS_REJECT_UNAUTHORIZED": "0", + "AUTH": "Bearer YOUR_API_KEY" + } + } + } +} +``` -If you experience connection timeouts: -- Ensure the plugin is enabled in Obsidian settings -- Check that the MCP server is running (look for the status in plugin settings) -- Verify no firewall is blocking the ports (3001 for HTTP, 3443 for HTTPS) -- Try using HTTP first to rule out certificate issues +### 3. Start Using + +Once connected, your AI can: +- Navigate your vault's link structure +- Search across all notes semantically +- Read, edit, and create notes +- Analyze your knowledge graph +- Work with Dataview queries +- Manage Obsidian Bases (database views) + +## Core Tools + +The plugin provides 8 semantic tool groups that give AI comprehensive vault access: + +| Tool | Purpose | Key Actions | +|------|---------|-------------| +| **πŸ“ vault** | File operations | list, read, create, search, move, split, combine | +| **✏️ edit** | Content modification | window editing, append, patch sections | +| **πŸ‘οΈ view** | Content display | view files, windows, active note | +| **πŸ•ΈοΈ graph** | Link navigation | traverse, find paths, analyze connections | +| **πŸ’‘ workflow** | Contextual hints | suggest next actions based on state | +| **πŸ“Š dataview** | Query notes | Execute DQL queries (if installed) | +| **πŸ—ƒοΈ bases** | Database views | Query and export Bases (if available) | +| **ℹ️ system** | Vault info | Server status, commands, web fetch | + +## Documentation + +Detailed documentation for each tool and feature: + +- [πŸ“ Vault Operations](docs/tools/vault.md) - File management and search +- [✏️ Edit Operations](docs/tools/edit.md) - Content modification strategies +- [πŸ•ΈοΈ Graph Navigation](docs/tools/graph.md) - Link traversal and analysis +- [πŸ“Š Dataview Integration](docs/tools/dataview.md) - Query language support +- [πŸ” Security & Authentication](docs/security.md) - API keys and permissions +- [πŸ”§ Configuration](docs/configuration.md) - Server settings and options +- [❓ Troubleshooting](docs/troubleshooting.md) - Common issues and solutions + +## The Semantic Advantage + +This plugin doesn't just give AI access to files - it provides **semantic understanding**: + +### Example: Research Assistant +``` +User: "Summarize my research on machine learning optimization" + +AI uses semantic tools to: +1. Search for notes with ML optimization concepts +2. Traverse graph to find related papers and techniques +3. Follow backlinks to discover applications +4. Synthesize findings from multiple connected notes +``` + +### Example: Knowledge Explorer +``` +User: "What connections exist between my notes on philosophy and cognitive science?" + +AI uses graph tools to: +1. Find notes tagged with both topics +2. Analyze shared concepts via graph traversal +3. Identify bridge notes that connect domains +4. Map the conceptual overlap +``` + +## Features + +### Semantic Search +- Advanced query operators: `tag:`, `path:`, `content:` +- Regular expressions and phrase matching +- Relevance ranking and snippet extraction + +### Graph Intelligence +- Multi-hop traversal with depth control +- Backlink and forward-link analysis +- Path finding between concepts +- Tag-based navigation + +### Content Operations +- Fuzzy text matching for edits +- Structure-aware modifications (headings, blocks) +- Batch operations (split, combine, move) +- Template support + +### Integration +- Dataview query execution +- Bases database operations +- Web content fetching +- Read-only mode for safety + +## Plugin Settings + +Access settings via: Settings β†’ Community plugins β†’ Semantic MCP + +Key configuration options: +- **Server Ports**: HTTP (3001) and HTTPS (3443) +- **Authentication**: API key protection +- **Security**: Path validation and permissions +- **Performance**: Connection pooling and caching ## Support - **Issues**: [GitHub Issues](https://github.com/aaronsb/obsidian-mcp-plugin/issues) - **Discussions**: [GitHub Discussions](https://github.com/aaronsb/obsidian-mcp-plugin/discussions) - -## Sponsorship - -If you find this plugin useful, please consider supporting its development: - -[![GitHub Sponsors](https://img.shields.io/badge/Sponsor-%E2%9D%A4-red?logo=github)](https://github.com/sponsors/aaronsb) - -Your support helps maintain and improve this plugin! +- **Sponsor**: [GitHub Sponsors](https://github.com/sponsors/aaronsb) ## License -MIT - ---- - -*This plugin brings the power of semantic MCP directly into Obsidian, providing AI tools with intelligent, high-performance vault access.* +MIT \ No newline at end of file diff --git a/docs/tools/graph.md b/docs/tools/graph.md new file mode 100644 index 0000000..8fd39aa --- /dev/null +++ b/docs/tools/graph.md @@ -0,0 +1,253 @@ +# Graph Tool Documentation + +The `graph` tool enables AI to navigate and analyze your vault's link structure, understanding connections between notes. + +## Core Concepts + +Your Obsidian vault is a **knowledge graph** where: +- **Nodes** are your notes +- **Edges** are links between notes (both explicit links and tag connections) +- **Paths** are routes through the graph connecting concepts + +## Actions + +### Basic Navigation + +#### `neighbors` +Get immediate connections of a note. +```json +{ + "action": "neighbors", + "sourcePath": "concepts/machine-learning.md", + "includeUnresolved": false // Include links to non-existent notes +} +``` + +#### `traverse` +Explore connections up to a certain depth. +```json +{ + "action": "traverse", + "sourcePath": "projects/current-project.md", + "maxDepth": 3, // How many hops from source + "maxNodes": 50, // Limit total nodes returned + "followBacklinks": true, + "followForwardLinks": true, + "followTags": true +} +``` + +### Path Finding + +#### `path` +Find connection paths between two notes. +```json +{ + "action": "path", + "sourcePath": "philosophy/consciousness.md", + "targetPath": "neuroscience/neural-networks.md" +} +``` + +### Analysis + +#### `statistics` +Get graph statistics for a note or the entire vault. +```json +{ + "action": "statistics", + "sourcePath": "index.md" // Optional - omit for vault stats +} +``` + +Returns: +- Total links (in/out) +- Connectivity score +- Central nodes +- Orphaned notes + +#### `backlinks` +Find all notes linking TO a specific note. +```json +{ + "action": "backlinks", + "sourcePath": "concepts/important-idea.md" +} +``` + +#### `forwardlinks` +Find all notes linked FROM a specific note. +```json +{ + "action": "forwardlinks", + "sourcePath": "index.md" +} +``` + +### Advanced Traversal + +#### `search-traverse` +Combine search with graph traversal - find related content across connected notes. +```json +{ + "action": "search-traverse", + "startPath": "research/ml-optimization.md", + "searchQuery": "gradient descent", + "maxDepth": 2, + "maxSnippetsPerNode": 2, + "scoreThreshold": 0.5 +} +``` + +#### `advanced-traverse` +Sophisticated traversal with multiple search queries and strategies. +```json +{ + "action": "advanced-traverse", + "sourcePath": "projects/thesis.md", + "searchQueries": ["methodology", "results", "conclusion"], + "strategy": "best-first", // breadth-first, best-first, beam-search + "beamWidth": 5, // For beam-search + "maxDepth": 4 +} +``` + +#### `tag-traverse` +Navigate through tag connections. +```json +{ + "action": "tag-traverse", + "sourcePath": "daily/2024-01-15.md", + "tagFilter": ["#project", "#important"], + "maxDepth": 3 +} +``` + +#### `tag-analysis` +Analyze tag relationships and co-occurrences. +```json +{ + "action": "tag-analysis", + "sourcePath": "index.md" // Optional +} +``` + +#### `shared-tags` +Find notes sharing tags with a source note. +```json +{ + "action": "shared-tags", + "sourcePath": "research/paper-1.md", + "minSharedTags": 2 // Minimum tags in common +} +``` + +## Traversal Strategies + +### Breadth-First +Explores all nodes at current depth before going deeper. +- **Use when**: You want comprehensive coverage +- **Best for**: Finding all related content + +### Best-First +Prioritizes nodes with highest relevance scores. +- **Use when**: You want most relevant connections +- **Best for**: Focused research on specific topics + +### Beam Search +Keeps only top N candidates at each level. +- **Use when**: You need balanced coverage with quality +- **Best for**: Large vaults where full traversal is expensive + +## Filtering Options + +### By Path +```json +{ + "fileFilter": "^research/.*\\.md$", // Regex pattern + "folderFilter": "projects/" // Only include from this folder +} +``` + +### By Tags +```json +{ + "tagFilter": ["#important", "#review"], + "tagWeight": 0.8 // How much to prioritize tag connections +} +``` + +### By Link Type +```json +{ + "followBacklinks": true, + "followForwardLinks": true, + "followTags": false, + "includeUnresolved": false, + "includeOrphans": false +} +``` + +## Use Cases + +### Research Synthesis +Find all content related to a research topic across connected notes: +```json +{ + "action": "search-traverse", + "startPath": "research/main-topic.md", + "searchQuery": "key finding", + "maxDepth": 3, + "strategy": "best-first" +} +``` + +### Knowledge Mapping +Understand the structure around a concept: +```json +{ + "action": "traverse", + "sourcePath": "concepts/central-idea.md", + "maxDepth": 2, + "followTags": true +} +``` + +### Missing Link Discovery +Find potential connections between unlinked notes: +```json +{ + "action": "shared-tags", + "sourcePath": "ideas/new-idea.md", + "minSharedTags": 3 +} +``` + +### Impact Analysis +See what would be affected by changing a note: +```json +{ + "action": "backlinks", + "sourcePath": "definitions/key-term.md" +} +``` + +## Best Practices + +### Performance Optimization + +1. **Limit depth for large vaults**: Start with depth 2-3 +2. **Use filters aggressively**: Folder and tag filters reduce search space +3. **Set maxNodes appropriately**: Balance completeness with performance + +### Effective Navigation + +1. **Start from hub notes**: Index pages or MOCs (Maps of Content) +2. **Use multiple strategies**: Try different traversal strategies for different goals +3. **Combine with search**: `search-traverse` is powerful for topic exploration + +### Graph Health + +1. **Check for orphans regularly**: Use statistics to find disconnected notes +2. **Analyze backlinks**: High backlink counts indicate important notes +3. **Monitor link depth**: Very deep requirements might indicate poor organization \ No newline at end of file diff --git a/docs/tools/vault.md b/docs/tools/vault.md new file mode 100644 index 0000000..87849d6 --- /dev/null +++ b/docs/tools/vault.md @@ -0,0 +1,210 @@ +# Vault Tool Documentation + +The `vault` tool provides comprehensive file operations for your Obsidian vault. + +## Actions + +### Basic File Operations + +#### `list` +List files in a directory. +```json +{ + "action": "list", + "directory": "path/to/folder" // Optional, defaults to root +} +``` + +#### `read` +Read a file's content. +```json +{ + "action": "read", + "path": "notes/example.md" +} +``` + +#### `create` +Create a new file. +```json +{ + "action": "create", + "path": "notes/new-note.md", + "content": "# New Note\n\nContent here..." +} +``` + +#### `update` +Replace a file's content. +```json +{ + "action": "update", + "path": "notes/existing.md", + "content": "Updated content..." +} +``` + +#### `delete` +Delete a file. +```json +{ + "action": "delete", + "path": "notes/old-note.md" +} +``` + +### Search Operations + +#### `search` +Advanced search with multiple operators. +```json +{ + "action": "search", + "query": "machine learning", + "includeContent": true // Include file content in results +} +``` + +**Search Operators:** +- `tag:#tagname` - Search by tag +- `path:folder/` - Search in specific path +- `file:filename` - Search by filename +- `content:term` - Search in content +- `"exact phrase"` - Exact phrase matching +- `/regex/` - Regular expression +- `term1 OR term2` - Boolean OR + +#### `fragments` +Get relevant fragments from files matching a query. +```json +{ + "action": "fragments", + "query": "optimization algorithms", + "strategy": "semantic", // auto, adaptive, proximity, semantic + "maxFragments": 5 +} +``` + +### File Management + +#### `move` +Move a file to a new location. +```json +{ + "action": "move", + "path": "notes/old-location.md", + "destination": "archive/new-location.md" +} +``` + +#### `rename` +Rename a file (keeping it in the same directory). +```json +{ + "action": "rename", + "path": "notes/old-name.md", + "newName": "new-name.md" +} +``` + +#### `copy` +Create a copy of a file. +```json +{ + "action": "copy", + "path": "templates/template.md", + "destination": "notes/new-from-template.md" +} +``` + +### Advanced Operations + +#### `split` +Split a file into multiple files. +```json +{ + "action": "split", + "path": "notes/large-file.md", + "splitBy": "heading", // heading, delimiter, lines, size + "level": 2, // For heading split - split at ## headers + "outputPattern": "{filename}-{index}{ext}" +} +``` + +#### `combine` +Combine multiple files into one. +```json +{ + "action": "combine", + "paths": ["notes/part1.md", "notes/part2.md", "notes/part3.md"], + "destination": "notes/combined.md", + "separator": "\n\n---\n\n", + "includeFilenames": true +} +``` + +#### `concatenate` +Append one file to another. +```json +{ + "action": "concatenate", + "path1": "notes/main.md", + "path2": "notes/addition.md", + "mode": "append" // append, prepend, or new +} +``` + +## Best Practices + +### Search Strategies + +1. **Start broad, then narrow**: Begin with simple terms, add operators to refine +2. **Use fragments for context**: When you need surrounding context, not just file names +3. **Combine operators**: `tag:#project AND path:work/ "deadline"` + +### File Organization + +1. **Use consistent naming**: Makes search and navigation easier +2. **Leverage folders**: Group related notes for targeted searches +3. **Regular maintenance**: Use split/combine to reorganize large files + +### Performance Tips + +1. **Limit search scope**: Use `path:` to search specific folders +2. **Use `includeContent: false`**: For faster searches when content isn't needed +3. **Batch operations**: Combine multiple files in one operation rather than many + +## Common Patterns + +### Research Collection +```json +// Find all research notes and combine them +{ + "action": "search", + "query": "tag:#research path:studies/", + "includeContent": false +} +// Then combine the results... +``` + +### Archive Old Notes +```json +// Move notes older than a certain date +{ + "action": "move", + "path": "daily/2023-01-15.md", + "destination": "archive/2023/01/15.md" +} +``` + +### Extract Sections +```json +// Split a large reference file by topics +{ + "action": "split", + "path": "references/all-citations.md", + "splitBy": "heading", + "level": 1, + "outputDirectory": "references/by-topic/" +} +``` \ No newline at end of file