# Obsidian MCP Bundle

An MCP (Model Context Protocol) Bundle that exposes Obsidian CLI capabilities to AI assistants, enabling conversational note management through natural language.

## Features

- 📝 **File Operations**: Create, read, update, delete notes
- 🔍 **Search & Discovery**: Full-text search, tag queries, backlink navigation
- ✅ **Task Management**: Create, update, and track tasks
- 🏷️ **Properties & Metadata**: Manage note properties, tags, and aliases
- 📅 **Daily Notes**: Create and navigate daily notes
- 🔖 **Bookmarks**: Manage bookmarked notes
- 🎨 **Customization**: Plugin and theme management
- 🔄 **Vault Navigation**: List files, folders, and navigate hierarchies

## Installation

### Prerequisites

- Node.js >= 18.0.0
- Obsidian CLI installed and configured
- Obsidian application installed

### Install via Claude Desktop

1. Download the latest `.mcpb` file from releases
2. Open Claude Desktop settings
3. Add the bundle to your MCP servers configuration
4. Configure your vault name in the settings

### Manual Installation

```bash
# Install dependencies
npm install

# Build the bundle
npm run build

# Package as .mcpb file
npm run pack
```

## Configuration

The bundle requires a `vault_name` parameter to target your Obsidian vault:

```json
{
  "mcpServers": {
    "obsidian-mcp": {
      "bundle": "path/to/obsidian-mcp.mcpb",
      "user_config": {
        "vault_name": "MyVault"
      }
    }
  }
}
```

## Usage Examples

### With Claude Desktop

```
You: "Create a new note called 'Meeting Notes' with today's date"
Assistant: [Uses obsidian_create_note tool]

You: "Search for all notes about project planning"
Assistant: [Uses obsidian_search tool]

You: "Add a task to my daily note: Review PR #123"
Assistant: [Uses obsidian_add_task tool]
```

## Available Tools

The bundle provides 95+ MCP tools covering:

- **File Operations**: create_note, read_note, append_to_note, delete_note, move_note, rename_note, open_note, get_file_info
- **Search**: search (content), search_tags, search_properties
- **Links**: get_backlinks, get_outbound_links, get_unresolved_links
- **Tasks**: add_task, list_tasks, update_task
- **Properties**: get_properties, add_property, update_property, remove_property
- **Tags**: get_tags, add_tag, remove_tag
- **Navigation**: list_files, list_folders, get_folder_info
- **Daily Notes**: create_daily_note, goto_daily_note
- **And more**: templates, bookmarks, plugins, themes, history, sync

See full tool documentation in the [contracts/tools.md](specs/001-obsidian-mcp-bundle/contracts/tools.md) file.

## Development

```bash
# Install dependencies
npm install

# Run in development mode (watch for changes)
npm run dev

# Run tests
npm test

# Validate tool descriptions
npm run validate-tools

# Build for production
npm run build
```

## Architecture

- **Transport**: stdio (JSON-RPC over standard input/output)
- **Validation**: Zod schemas for all tool parameters
- **Error Handling**: Graceful error messages with actionable guidance
- **Timeout Management**: 30-second default timeout for CLI commands
- **Logging**: Sanitized stderr-only logging (no stdout pollution)

## Performance

- File operations: < 3 seconds
- Search queries: < 5 seconds (vaults up to 10,000 notes)
- CLI timeout: 30 seconds (configurable per command)

## Platform Support

- macOS
- Windows
- Linux

## License

MIT

## Contributing

Contributions are welcome! Please ensure:

1. All tools follow MCP protocol standards
2. Input validation uses Zod schemas
3. Errors provide actionable messages
4. Tests pass with `npm test`
5. Tool descriptions are clear and complete

## Troubleshooting

### "Obsidian not running" error

Start the Obsidian application before using MCP tools.

### "Vault not found" error

Ensure the `vault_name` in your configuration matches exactly (case-sensitive).

### Timeout errors

Increase timeout in `src/config/timeouts.ts` for slow operations.

## Resources

- [MCP Protocol Specification](https://modelcontextprotocol.io)
- [MCPB Bundle Format](https://github.com/anthropics/mcpb)
- [Obsidian CLI Documentation](https://help.obsidian.md/CLI)