obsidian-mcp/specs/001-obsidian-mcp-bundle/spec.md

# Feature Specification: Obsidian MCP Bundle

**Feature Branch**: `001-obsidian-mcp-bundle`  
**Created**: 2026-03-22  
**Status**: Draft  
**Input**: User description: "Build an MCP Bundle for Obsidian CLI. Use the command 'obsidian help' to list all the features that should be supported with the MCP."

## Clarifications

### Session 2026-03-22

- Q: When multiple notes exist with the same name in different folders, how should the system resolve which note to operate on? → A: Return an error with list of matching paths, requiring user to specify exact path
- Q: When the user requests an operation but Obsidian application is not running, what should happen? → A: Immediately return error message instructing user to start Obsidian manually
- Q: When the AI modifies a file that the user is actively editing in Obsidian, what should the system do to prevent data loss? → A: Rely on Obsidian's built-in conflict detection; save immediately and let Obsidian prompt user if conflict occurs
- Q: What level of detail should be logged to stderr for debugging operations? → A: Operation type, parameters (sanitized), timestamp, success/failure

## User Scenarios & Testing *(mandatory)*

### User Story 1 - File Operations via AI (Priority: P1)

AI assistants can read, create, append, and modify Obsidian notes through natural language requests, enabling users to manage their knowledge base conversationally without leaving their AI chat interface.

**Why this priority**: Core value proposition - enables basic note-taking workflows that represent 80% of common use cases (reading existing notes, creating new ones, appending to daily notes).

**Independent Test**: Can be fully tested by asking an AI to "create a new note about MCP bundles", "read my daily note", or "append a reminder to my todo list" and verifying the operations execute correctly in Obsidian.

**Acceptance Scenarios**:

1. **Given** a user is chatting with an AI assistant, **When** they say "create a new note called 'Meeting Notes' with the agenda items", **Then** Obsidian creates the note with the specified content
2. **Given** a note exists in the vault, **When** the user asks "what does my project roadmap say?", **Then** the AI reads and summarizes the note content
3. **Given** a user wants to add a task, **When** they say "add 'buy groceries' to my daily note", **Then** the content is appended to today's daily note
4. **Given** a user mentions a note name, **When** the AI needs to read it, **Then** the system resolves the note by name (wikilink-style) without requiring exact paths

---

### User Story 2 - Search and Discovery (Priority: P2)

AI assistants can search vault content, find related notes via backlinks, discover tags and properties, and help users navigate their knowledge graph, making information retrieval conversational and context-aware.

**Why this priority**: Unlocks the power of Obsidian's graph structure - users can ask "what notes link to this?", "find all notes about project X", or "show me unresolved links" without learning search syntax.

**Independent Test**: Ask the AI "find all notes mentioning 'quarterly goals'", "what links to my project overview?", or "list all notes tagged with #important" and verify accurate search results.

**Acceptance Scenarios**:

1. **Given** a vault with multiple notes, **When** the user asks "search for notes about machine learning", **Then** the AI returns relevant notes with context snippets
2. **Given** a note has backlinks, **When** the user asks "what notes reference this article?", **Then** the AI lists all incoming links with counts
3. **Given** the user wants to explore tags, **When** they ask "what are my most used tags?", **Then** the AI returns tags sorted by frequency
4. **Given** unresolved links exist, **When** the user asks "what broken links do I have?", **Then** the AI lists all wikilinks pointing to non-existent notes

---

### User Story 3 - Task and Property Management (Priority: P3)

AI assistants can create, toggle, and query tasks across the vault, manage note properties (frontmatter), and help users maintain structured metadata, enabling task tracking and note organization through conversation.

**Why this priority**: Enhances productivity workflows - users can manage tasks and metadata without context-switching, but builds on top of basic file operations.

**Independent Test**: Ask the AI "show me all incomplete tasks", "mark the task on line 15 as done", or "set the 'status' property to 'in-progress'" and verify task/property updates.

**Acceptance Scenarios**:

1. **Given** multiple notes with tasks, **When** the user asks "list all my todo items", **Then** the AI returns incomplete tasks grouped by file
2. **Given** a task exists at a specific location, **When** the user says "mark that task as done", **Then** the task status toggles to completed
3. **Given** a note needs metadata, **When** the user says "set the 'author' property to 'John Doe'", **Then** the frontmatter is updated
4. **Given** the user wants to track properties, **When** they ask "what properties exist in my vault?", **Then** the AI lists all unique property names with counts

---

### Edge Cases

- **Ambiguous note names**: When multiple notes with the same name exist in different folders, the system MUST return an error listing all matching paths and require the user to specify the exact path to disambiguate
- **Obsidian not running**: When Obsidian application is not running, the system MUST immediately return a clear error message instructing the user to start Obsidian before retrying the operation
- **Concurrent edits**: When AI modifies a file that the user is actively editing, the system MUST save immediately and rely on Obsidian's built-in conflict detection to prompt the user if a conflict occurs
- **File doesn't exist**: When a user requests an operation on a file that doesn't exist, the system MUST return a structured error with `code: "FILE_NOT_FOUND"` and include the requested path in the message (e.g., "Note 'ideas.md' not found in vault 'MyVault'")
- **CLI error communication**: All errors from Obsidian CLI MUST be captured via stderr, mapped to MCP error codes (see FR-011), and returned with actionable messages that do not leak sensitive information
- **Vault sync paused**: When vault sync is paused and an operation is attempted, the system MUST allow the operation to proceed (sync status does not block local file operations) but log a warning if the operation modifies files
- **Special characters in note names**: The system MUST pass note names to Obsidian CLI without modification, allowing Obsidian to handle special character validation according to its own rules (fail-fast if CLI rejects)
- **Invalid vault name**: When user configuration specifies a vault that doesn't exist, the system MUST return error `code: "VAULT_NOT_FOUND"` during the first operation attempt with message listing available vaults from `obsidian vault list`

## Requirements *(mandatory)*

### Functional Requirements

- **FR-001**: Bundle MUST implement MCP protocol via stdio transport using @modelcontextprotocol/sdk
- **FR-002**: Bundle MUST provide tools for all core Obsidian CLI file operations (create, read, append, prepend, delete, move, rename)
- **FR-003**: Bundle MUST support vault-specific targeting via user configuration (vault name parameter)
- **FR-004**: Bundle MUST expose search functionality (full-text search, search with context)
- **FR-005**: Bundle MUST provide backlinks, links, and unresolved links queries
- **FR-006**: Bundle MUST support task operations (list, toggle, mark done/todo)
- **FR-007**: Bundle MUST handle property management (read, set, remove, list properties)
- **FR-008**: Bundle MUST provide tag and alias listing with optional counts
- **FR-009**: Bundle MUST validate all user inputs before passing to Obsidian CLI
- **FR-010**: Bundle MUST return structured JSON responses for all tool calls
- **FR-011**: Bundle MUST handle errors gracefully and return actionable error messages; when Obsidian is not running, MUST instruct user to start application
- **FR-012**: Bundle MUST use timeout limits for all CLI command executions (default 30 seconds)
- **FR-013**: Bundle MUST support file resolution by name (wikilink-style) and exact path; when multiple files match a name, MUST return error with all matching paths
- **FR-014**: Bundle MUST log debugging information to stderr only (never stdout); logs MUST include operation type, sanitized parameters (removing sensitive data like vault paths and note content), timestamp, and success/failure status
- **FR-015**: Bundle MUST include valid manifest.json conforming to MCPB spec v0.3
- **FR-016**: Bundle MUST declare required vault directory in user_config
- **FR-017**: Bundle MUST include tool descriptions that accurately reflect Obsidian CLI capabilities
- **FR-018**: Bundle MUST handle optional parameters with sensible defaults
- **FR-019**: Bundle MUST support output format options where Obsidian CLI provides them (json, tsv, csv)

### Key Entities

- **Vault**: An Obsidian knowledge base consisting of markdown files and folders, identified by name or path
- **Note**: A markdown file within the vault, addressable by filename (wikilink resolution) or exact path
- **Tool**: An MCP tool representing a single Obsidian CLI command with defined input schema and output format
- **User Configuration**: Vault selection parameter allowing users to specify which Obsidian vault to target
- **Task**: A markdown checkbox item with status (todo, done, custom), line number reference, and parent file
- **Property**: Frontmatter metadata key-value pair (text, list, number, checkbox, date, datetime types)
- **Link**: A connection between notes (outgoing links, backlinks, unresolved links)
- **Tag**: A categorization marker (e.g., #project, #important) with occurrence tracking

## Success Criteria *(mandatory)*

### Measurable Outcomes

- **SC-001**: Users can perform basic note operations (create, read, append) in under 3 seconds per operation
- **SC-002**: Search queries return results with context in under 5 seconds for vaults up to 10,000 notes
- **SC-003**: All tool calls return structured responses that AI models can reliably parse (100% JSON validity)
- **SC-004**: Error messages enable users to self-resolve issues in 90% of common failure scenarios (missing note, invalid vault, command timeout)
- **SC-005**: Bundle installs successfully via single-click in Claude Desktop without requiring manual configuration beyond vault selection
- **SC-006**: All implemented Obsidian CLI commands have corresponding MCP tools with accurate parameter mapping
- **SC-007**: Tool descriptions are clear enough that AI assistants select the correct tool on first attempt for common requests (measured by user satisfaction)
- **SC-008**: Bundle works consistently across all platforms where Obsidian CLI is available (macOS, Windows, Linux)

## Assumptions

- Obsidian CLI is installed and accessible in the system PATH
- Users have at least one Obsidian vault configured
- Obsidian application is running when bundle operations are executed (required for CLI to work)
- Users understand basic Obsidian concepts (vault, note, wikilink, frontmatter)
- Network connectivity is not required (all operations are local)
- File system permissions allow reading/writing vault files
- Obsidian's built-in conflict detection handles concurrent file modifications between AI and user edits