verint.com/obsidian-mcp
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 2 Wiki Activity
Files
c5e42adac08da6168543e7bfd625167195b0b78f
obsidian-mcp/specs/001-obsidian-mcp-bundle/spec.md
Peter.Morton 622b28e42c feat: implement Obsidian MCP Bundle MVP (Phase 1-3) 
- 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>
2026-03-22 11:21:38 -05:00

14 KiB
Raw Blame History

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

User Story 4 - Vault Navigation and Info (Priority: P4)

AI assistants can list files and folders, show vault statistics, open specific notes, and provide information about the vault structure, helping users understand and navigate their knowledge base.

Why this priority: Utility features that enhance user experience but aren't essential for core workflows.

Independent Test: Ask the AI "how many notes do I have?", "list files in my Projects folder", or "open my weekly review note" and verify accurate responses.

Acceptance Scenarios:

  1. Given a user wants vault statistics, When they ask "how big is my vault?", Then the AI returns file count, folder count, and total size
  2. Given a folder contains notes, When the user asks "what's in my Archive folder?", Then the AI lists all files in that directory
  3. Given the user wants to open a note, When they say "open my project roadmap", Then Obsidian opens the specified note
  4. Given the user wants recent activity, When they ask "what notes did I open recently?", Then the AI returns the recent files list

User Story 5 - Advanced Features (Priority: P5)

AI assistants can work with templates, daily notes, bookmarks, plugins, themes, and Obsidian-specific features, providing power users with comprehensive CLI access through natural language.

Why this priority: Serves power users and advanced workflows but not critical for initial adoption.

Independent Test: Ask the AI "insert my meeting template", "list enabled plugins", or "what's my active theme?" and verify correct execution.

Acceptance Scenarios:

  1. Given templates exist, When the user says "insert my standup template", Then the template content is inserted into the active file
  2. Given the user manages plugins, When they ask "what plugins are enabled?", Then the AI returns the list of active plugins
  3. Given a user wants bookmark management, When they say "bookmark this search query", Then a bookmark is created
  4. Given the user tracks file history, When they ask "show versions of this note", Then the AI lists available file history versions

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-017), 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 support daily note operations (open, append, prepend, read)
  • FR-009: Bundle MUST provide tag and alias listing with optional counts
  • FR-010: Bundle MUST support file and folder listing with filtering options
  • FR-011: Bundle MUST handle template operations (list, read, insert)
  • FR-012: Bundle MUST provide bookmark management (create, list)
  • FR-013: Bundle MUST expose plugin information (list, enabled status)
  • FR-014: Bundle MUST support theme queries (active theme, list themes)
  • FR-015: Bundle MUST validate all user inputs before passing to Obsidian CLI
  • FR-016: Bundle MUST return structured JSON responses for all tool calls
  • FR-017: Bundle MUST handle errors gracefully and return actionable error messages; when Obsidian is not running, MUST instruct user to start application
  • FR-018: Bundle MUST use timeout limits for all CLI command executions (default 30 seconds)
  • FR-019: 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-020: 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-021: Bundle MUST include valid manifest.json conforming to MCPB spec v0.3
  • FR-022: Bundle MUST declare required vault directory in user_config
  • FR-023: Bundle MUST include tool descriptions that accurately reflect Obsidian CLI capabilities
  • FR-024: Bundle MUST handle optional parameters with sensible defaults
  • FR-025: 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: 95% of 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
Reference in New Issue View Git Blame Copy Permalink