# Obsidian MCP Server

A Model Context Protocol (MCP) server that provides seamless integration with Obsidian vaults via direct filesystem access, enabling AI assistants to interact with your notes and knowledge base.

## Features

- **Note Management**: Create, read, update, and delete notes
- **Folder Operations**: Create, rename, move, and delete folders
- **Vault Search**: Search with glob patterns, regex, tags, frontmatter, and relevance scoring
- **Intelligent Caching**: Multi-layer caching with optional LMDB persistence
- **Real-Time Monitoring**: File watching for automatic cache invalidation

## Quick Start

### Installation

```bash
npm install
npm run build
```

### Configuration

Add to your MCP client configuration:

```json
{
  "mcpServers": {
    "obsidian": {
      "command": "node",
      "args": ["/path/to/obsidian-mcp/build/index.js"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/path/to/your/vault"
      }
    }
  }
}
```

See [Configuration Reference](docs/configuration.md) for all options.

## Available Tools

| Tool                                                        | Description                             |
| ----------------------------------------------------------- | --------------------------------------- |
| [`list_notes`](docs/tools/list_notes.md)                    | List all notes in the vault             |
| [`read_note`](docs/tools/read_note.md)                      | Read the content of a note              |
| [`create_note`](docs/tools/create_note.md)                  | Create a new note                       |
| [`update_note`](docs/tools/update_note.md)                  | Update an existing note                 |
| [`delete_note`](docs/tools/delete_note.md)                  | Delete a note                           |
| [`get_note_metadata`](docs/tools/get_note_metadata.md)      | Get frontmatter and tags                |
| [`search_vault`](docs/tools/search_vault.md)                | Search with required query              |
| [`advanced_search_vault`](docs/tools/advanced_search_vault.md) | Advanced search with all options     |
| [`search_vault_stream`](docs/tools/search_vault_stream.md)  | Streaming search for large vaults       |
| [`manage_folder`](docs/tools/manage_folder.md)              | Create, rename, move, or delete folders |
| [`get_cache_stats`](docs/tools/get_cache_stats.md)          | Get cache performance statistics        |

See [Tools Reference](docs/tools/README.md) for detailed documentation.

## Architecture

```mermaid
flowchart TB
    subgraph tools [MCP Tools]
        T1[search_vault]
        T2[read_note]
        T3[list_notes]
    end
    
    subgraph caching [Caching Layer]
        FC[FileListCache]
        CC[ContentCache]
        SC[SearchResultCache]
        PC[PersistentCache]
    end
    
    subgraph optimization [Search Optimization]
        II[InvertedIndex]
        PT[PathTrie]
    end
    
    subgraph fs [Filesystem]
        V[(Obsidian Vault)]
        FW[FileWatcher]
    end
    
    T1 --> SC
    T1 --> II
    T1 --> PT
    T2 --> CC
    T3 --> FC
    
    CC --> PC
    FC --> PC
    SC --> PC
    
    FW --> FC
    FW --> CC
    FW --> II
    
    V --> FW
```

See [Features Reference](docs/features/README.md) for detailed architecture documentation.

## Performance Features

| Feature                                                 | Description                                | Default  |
| ------------------------------------------------------- | ------------------------------------------ | -------- |
| [File List Cache](docs/features/file-list-cache.md)     | Cache folder listings                      | 60s TTL  |
| [Content Cache](docs/features/content-cache.md)         | LRU cache for file contents                | 100 entries |
| [Search Result Cache](docs/features/search-result-cache.md) | Cache search query results             | 50 entries |
| [Persistent Cache](docs/features/persistent-cache.md)   | LMDB-backed persistence                    | Enabled  |
| [Inverted Index](docs/features/inverted-index.md)       | Fast word-to-files lookup                  | Enabled  |
| [Path Trie](docs/features/path-trie.md)                 | Efficient glob pattern matching            | Enabled  |
| [File Watcher](docs/features/file-watcher.md)           | Real-time cache invalidation               | Enabled  |
| [Cache Warmup](docs/features/cache-warmup.md)           | Pre-load cache on startup                  | Disabled |

## Configuration Quick Reference

| Variable                           | Default             | Description                          |
| ---------------------------------- | ------------------- | ------------------------------------ |
| `OBSIDIAN_VAULT_PATH`              | Required            | Path to your Obsidian vault          |
| `OBSIDIAN_ENABLE_PERSISTENT_CACHE` | `true`              | Enable LMDB persistence              |
| `OBSIDIAN_ENABLE_INVERTED_INDEX`   | `true`              | Enable fast text search index        |
| `OBSIDIAN_ENABLE_PATH_TRIE`        | `true`              | Enable fast glob matching            |
| `OBSIDIAN_ENABLE_CACHE_WARMUP`     | `false`             | Pre-load cache on startup            |

See [Configuration Reference](docs/configuration.md) for all environment variables.

## Development

```bash
# Build
npm run build

# Development mode
npm run dev

# Run tests
npm test
```

### Project Structure

```
src/
├── config/                    # Configuration management
├── handlers/                  # MCP request handlers
├── services/
│   ├── cache/                 # Caching services
│   ├── search/                # Search optimization services
│   ├── fileSystem.ts          # Core filesystem operations
│   ├── FileWatcher.ts         # File change monitoring
│   └── FrontmatterParser.ts   # YAML frontmatter parsing
├── types/                     # TypeScript type definitions
├── index.ts                   # Entry point
└── server.ts                  # Main server class
```

## Documentation

- [Tools Reference](docs/tools/README.md) - All available MCP tools
- [Features Reference](docs/features/README.md) - Internal features and architecture
- [Configuration Reference](docs/configuration.md) - All environment variables

## Security

- Operations are restricted to the configured vault path
- Path traversal protection is implemented
- Consider running in a sandboxed environment for production use

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request