Metadata-Version: 2.4
Name: mcp-duckvault
Version: 0.2.1
Summary: DuckVault-MCP: Obsidian-DuckDB RAG System with MCP Server
Project-URL: Homepage, https://github.com/caron14/mcp-duckvault
Project-URL: Repository, https://github.com/caron14/mcp-duckvault
Project-URL: Issues, https://github.com/caron14/mcp-duckvault/issues
Author-email: caron14 <caron14@users.noreply.github.com>
License: MIT
License-File: LICENSE
Keywords: duckdb,mcp,obsidian,rag,vector-search
Requires-Python: >=3.11
Requires-Dist: click>=8.0.0
Requires-Dist: duckdb>=1.5.1
Requires-Dist: mcp[cli]>=1.27.0
Requires-Dist: pandas>=3.0.2
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: sentence-transformers>=5.4.0
Requires-Dist: tqdm>=4.66.0
Requires-Dist: watchdog>=6.0.0
Provides-Extra: dev
Requires-Dist: black>=24.0.0; extra == 'dev'
Requires-Dist: isort>=5.13.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# DuckVault-MCP

DuckVault-MCP is an MCP (Model Context Protocol) server that provides a RAG (Retrieval-Augmented Generation) system for your Obsidian Vault using DuckDB and vector search.

## Features

- **Local Vector Search**: Uses `sentence-transformers` (`intfloat/multilingual-e5-small`) for local embeddings.
- **Obsidian URI Links**: Includes direct links to open notes in Obsidian from search results.
- **Incremental Indexing**: Uses MD5 hashing to only update modified files.
- **Real-time Monitoring**: Uses `watchdog` to index changes as you edit your notes.
- **Progress Indicators**: Displays a progress bar during initial indexing for large vaults.
- **Fast Search**: Leverages DuckDB with the `vss` extension and HNSW indexing for millisecond-level retrieval.
- **MCP Compatible**: Works seamlessly with AI agents like Claude Code or Cursor.

## Installation

```bash
# Using uv (recommended)
uv tool install mcp-duckvault

# From GitHub directly
uv tool install git+https://github.com/caron14/mcp-obsidian-duckdb.git

# From PyPI (once published)
pip install mcp-duckvault
```

## Usage

Start the MCP server by pointing it to your Obsidian Vault:

```bash
duckvault /path/to/your/obsidian/vault
```

**Options**
- `--db-path`: Path to the DuckDB file (default: `~/.duckvault/vault.db`).
- `--sync-only`: Perform a full sync of the vault and exit.
- `-v, --verbose`: Enable verbose logging.

### CLI Examples

**Basic usage:**
```bash
duckvault /path/to/your/obsidian/vault
```

**Custom database path:**
Specify a custom location for the DuckDB index file.
```bash
duckvault /path/to/your/obsidian/vault --db-path ./vault_index.db
```

**Sync only (Headless mode):**
Index all files and exit without starting the MCP server.
```bash
duckvault /path/to/your/obsidian/vault --sync-only
```

### Example Queries for AI Agents

Once connected, you can interact with your vault using natural language through an AI agent:

- **Semantic Search**: "Find notes about machine learning projects and list the key concepts mentioned."
- **Filtered Search**: "Search for notes about 'meeting' with the tag #work and summarize the action items."
- **Stay Updated**: "What are the most important notes I've worked on in the last 3 days?"
- **Cross-Note Analysis**: "Based on my recent notes about 'React', how has my understanding of Hooks evolved?"

### Excluding Files (`.vaultignore`)

To exclude specific files or directories from being indexed, create a `.vaultignore` file in the root of your Obsidian Vault. The syntax is similar to `.gitignore`.

By default, `.obsidian` and `.trash` are always excluded.

Example `.vaultignore`:
```text
# Exclude specific folders
private/
drafts/

# Exclude specific file types
*.tmp
*.log
```

## Registration for AI Agents

This server is MCP (Model Context Protocol) compliant and can be used with the following agents after you have installed it via `uv tool install` or `pip install`.

**Note**: Please specify the vault path as an **absolute path** (e.g., `/Users/username/Documents/MyVault`).

### Claude Desktop (macOS)
Add the following to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "duckvault": {
      "command": "duckvault",
      "args": [
        "/absolute/path/to/your/obsidian/vault"
      ]
    }
  }
}
```

### Claude Code
You can add the server persistently using the CLI command (recommended) or by editing the configuration file.

**Using the CLI command:**
```bash
claude mcp add duckvault -- duckvault /absolute/path/to/your/obsidian/vault
```

**By editing the configuration file:**
Add to `~/.claude.json`:

```json
{
  "mcpServers": {
    "duckvault": {
      "command": "duckvault",
      "args": [
        "/absolute/path/to/your/obsidian/vault"
      ]
    }
  }
}
```

### Gemini CLI
You can add the server persistently using the CLI command (recommended) or by editing the configuration file.

**Using the CLI command:**
```bash
gemini mcp add duckvault --scope user duckvault /absolute/path/to/your/obsidian/vault
```

**By editing the configuration file:**
Add to the `mcpServers` section of your configuration file (`~/.gemini/settings.json`).

```json
{
  "mcpServers": {
    "duckvault": {
      "command": "duckvault",
      "args": [
        "/absolute/path/to/your/obsidian/vault"
      ]
    }
  }
}
```

### GitHub Copilot (in the CLI)
GitHub Copilot in the CLI supports MCP servers. You can add the server using the interactive `/mcp` command or by editing the configuration file.

**Using the CLI command:**
1. Start an interactive session: `copilot` (or `gh copilot chat`).
2. Run the `/mcp add` command and follow the prompts.

**By editing the configuration file:**
Add to `~/.copilot/mcp-config.json`:

```json
{
  "mcpServers": {
    "duckvault": {
      "command": "duckvault",
      "args": [
        "/absolute/path/to/your/obsidian/vault"
      ]
    }
  }
}
```
```

## MCP Tools

The server exposes the following tools to AI agents:

1. `search_notes(query: str, tag: Optional[str] = None, limit: int = 5)`: Search for relevant notes using natural language.
2. `list_recent_notes(days: int = 7)`: List notes that were recently updated.

## License

MIT
