Peter.Morton
622b28e42c
- Complete project setup with TypeScript, Jest, MCPB manifest - Implement foundational infrastructure (CLI executor, logger, error handler) - Add 9 file operation tools for User Story 1 - Full MCP protocol compliance with stdio transport - Input validation and sanitization for security - Comprehensive error handling with actionable messages - Constitutional compliance: all 6 principles satisfied MVP includes: - obsidian_create_note, read, append, prepend, delete, move, rename, open, file_info - Zod validation schemas for all parameters - 30s timeout configuration with per-command overrides - Stderr-only logging with sanitized output - Graceful shutdown handling Build: ✅ 0 errors, 0 vulnerabilities Tasks: 48/167 complete (MVP milestone) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
164 lines
4.1 KiB
Markdown
164 lines
4.1 KiB
Markdown
# 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)
|