# Tasks: Obsidian MCP Bundle **Input**: Design documents from `/specs/001-obsidian-mcp-bundle/` **Prerequisites**: plan.md (required), spec.md (required for user stories), research.md, data-model.md, contracts/ **Tests**: This project does NOT explicitly request TDD. Tests are NOT included in the task breakdown below. **Organization**: Tasks are grouped by user story to enable independent implementation and testing of each story. ## Format: `[ID] [P?] [Story] Description` - **[P]**: Can run in parallel (different files, no dependencies) - **[Story]**: Which user story this task belongs to (e.g., US1, US2, US3, US4, US5) - Include exact file paths in descriptions ## Path Conventions - **MCP Bundle project**: All paths at repository root (obsidian-mcp/) - Source code in `src/`, tests in `tests/`, bundle config at root --- ## Phase 1: Setup (Shared Infrastructure) **Purpose**: Project initialization and basic structure - [X] T001 Create project directory structure per implementation plan (src/, tests/, assets/) - [X] T002 Initialize Node.js project with package.json (name: obsidian-mcp, version: 1.0.0, type: module) - [X] T003 [P] Configure TypeScript in tsconfig.json (target: ES2022, module: ESNext, strict mode, outDir: dist) - [X] T004 [P] Install @modelcontextprotocol/sdk dependency in package.json - [X] T005 [P] Install development dependencies (typescript, jest, @types/node, @types/jest, ts-jest, zod) - [X] T006 [P] Configure Jest for TypeScript in jest.config.js - [X] T007 [P] Create .mcpbignore file (exclude tests/, .git/, node_modules/, src/, tsconfig.json) - [X] T008 [P] Add build scripts to package.json (build: tsc, pack: mcpb pack, test: jest) - [X] T008a [P] Create test fixtures in tests/fixtures/ (sample notes, vaults, mock CLI responses) - [X] T008b [P] Create tool validation script in scripts/validate-tools.js (checks description completeness) - [X] T009 [P] Create README.md with installation and usage instructions - [X] T010 [P] Add LICENSE file (choose appropriate license) --- ## Phase 2: Foundational (Blocking Prerequisites) **Purpose**: Core infrastructure that MUST be complete before ANY user story can be implemented **⚠️ CRITICAL**: No user story work can begin until this phase is complete - [X] T011 Create manifest.json at project root conforming to MCPB spec v0.3 - [X] T012 [P] Define user_config schema in manifest.json for vault_name parameter - [X] T013 [P] Set server.type to "node" and entry_point to "dist/index.js" in manifest.json - [X] T014 [P] Configure mcp_config in manifest.json (command: node, args with ${__dirname}, env with ${user_config.vault_name}) - [X] T015 [P] Add compatibility section to manifest.json (platforms: darwin/win32/linux, node: >=18.0.0) - [X] T016 Create TypeScript types in src/utils/types.ts (ToolInput, ToolOutput, ErrorResponse, etc.) - [X] T017 [P] Create logger utility in src/utils/logger.ts (stderr-only, sanitized parameters) - [X] T018 [P] Create error handler in src/utils/error-handler.ts (map CLI errors to MCP error codes) - [X] T019 Create CLI executor in src/cli/executor.ts (spawn with timeout, output streaming, error handling, import from src/config/timeouts.ts) - [X] T019a [P] Create timeout configuration in src/config/timeouts.ts (default 30s, per-command overrides map) - [X] T020 [P] Create CLI output parser in src/cli/parser.ts (JSON/TSV/CSV/text format support) - [X] T021 Create Zod validation schemas in src/validation/schemas.ts (common parameter patterns) - [X] T022 [P] Create parameter sanitizer in src/validation/sanitizer.ts (remove dangerous characters) - [X] T023 Create MCP server base in src/server.ts (initialize MCP Server with stdio transport) - [X] T024 Implement initialize handler in src/server.ts (return capabilities and server info) - [X] T025 Implement tools/list handler in src/server.ts (return all tool definitions with schemas) - [X] T026 Implement tools/call dispatcher in src/server.ts (route to tool implementations with validation) - [X] T027 Create main entry point in src/index.ts (connect server to stdio transport, handle shutdown) - [X] T028 [P] Add graceful shutdown handling in src/index.ts (EOF, exit notification, cleanup) **Checkpoint**: Foundation ready - user story implementation can now begin in parallel --- ## Phase 3: User Story 1 - File Operations via AI (Priority: P1) 🎯 MVP **Goal**: Enable basic note-taking workflows (create, read, append, modify notes) **Independent Test**: Ask AI "create a note called Test", "read my Test note", "append 'hello' to Test", verify in Obsidian ### Implementation for User Story 1 - [X] T029 [P] [US1] Create obsidian_create_note tool in src/tools/file-operations.ts - [X] T030 [P] [US1] Define Zod schema for create_note parameters (name, path, content, template, overwrite, open) - [X] T031 [P] [US1] Create obsidian_read_note tool in src/tools/file-operations.ts - [X] T032 [P] [US1] Define Zod schema for read_note parameters (file or path, oneOf validation) - [X] T033 [P] [US1] Create obsidian_append_to_note tool in src/tools/file-operations.ts - [X] T034 [P] [US1] Define Zod schema for append parameters (file/path, content, inline) - [X] T035 [P] [US1] Create obsidian_prepend_to_note tool in src/tools/file-operations.ts - [X] T036 [P] [US1] Create obsidian_delete_note tool in src/tools/file-operations.ts (with permanent flag) - [X] T037 [P] [US1] Create obsidian_move_note tool in src/tools/file-operations.ts - [X] T038 [P] [US1] Create obsidian_rename_note tool in src/tools/file-operations.ts - [X] T039 [P] [US1] Create obsidian_open_note tool in src/tools/file-operations.ts (with newtab option) - [X] T040 [P] [US1] Create obsidian_get_file_info tool in src/tools/file-operations.ts - [X] T041 [US1] Register all file operation tools in src/server.ts tools/list handler - [X] T042 [US1] Implement ambiguous name error handling per clarification (return error with all matching paths) - [X] T043 [US1] Implement wikilink-style name resolution in file operation tools - [X] T044 [US1] Add error message mapping for file not found errors - [X] T045 [US1] Add error message mapping for Obsidian not running per clarification **Checkpoint**: At this point, User Story 1 should be fully functional and testable independently --- ## Phase 4: User Story 2 - Search and Discovery (Priority: P2) **Goal**: Enable search, backlinks, tags, and graph navigation **Independent Test**: Ask AI "search for machine learning", "what links to Projects?", "list my tags", verify results ### Implementation for User Story 2 - [ ] T046 [P] [US2] Create obsidian_search tool in src/tools/search.ts - [ ] T047 [P] [US2] Define Zod schema for search parameters (query, folder, limit, caseSensitive) - [ ] T048 [P] [US2] Create obsidian_search_with_context tool in src/tools/search.ts - [ ] T049 [P] [US2] Create obsidian_get_backlinks tool in src/tools/links.ts - [ ] T050 [P] [US2] Define Zod schema for backlinks parameters (file/path, counts) - [ ] T051 [P] [US2] Create obsidian_get_outgoing_links tool in src/tools/links.ts - [ ] T052 [P] [US2] Create obsidian_list_unresolved_links tool in src/tools/links.ts - [ ] T053 [P] [US2] Create obsidian_list_tags tool in src/tools/tags-aliases.ts - [ ] T054 [P] [US2] Define Zod schema for list_tags parameters (file, path, counts, sortBy) - [ ] T055 [P] [US2] Create obsidian_get_tag_info tool in src/tools/tags-aliases.ts - [ ] T056 [P] [US2] Create obsidian_list_aliases tool in src/tools/tags-aliases.ts - [ ] T057 [P] [US2] Create obsidian_list_properties tool in src/tools/properties.ts (vault-wide properties) - [ ] T058 [P] [US2] Create obsidian_get_property_count tool in src/tools/properties.ts - [ ] T059 [P] [US2] Create obsidian_list_deadends tool in src/tools/links.ts (notes with no outgoing links) - [ ] T060 [P] [US2] Create obsidian_list_orphans tool in src/tools/file-operations.ts (notes with no incoming links) - [ ] T061 [US2] Register all search and discovery tools in src/server.ts tools/list handler - [ ] T062 [US2] Implement search result formatting (parse JSON/TSV output from CLI) - [ ] T063 [US2] Add pagination support for large search results **Checkpoint**: At this point, User Stories 1 AND 2 should both work independently --- ## Phase 5: User Story 3 - Task and Property Management (Priority: P3) **Goal**: Enable task tracking and frontmatter property management **Independent Test**: Ask AI "show my tasks", "mark task done", "set status property", verify updates ### Implementation for User Story 3 - [ ] T064 [P] [US3] Create obsidian_list_tasks tool in src/tools/tasks.ts - [ ] T065 [P] [US3] Define Zod schema for list_tasks parameters (file, path, status, verbose) - [ ] T066 [P] [US3] Create obsidian_toggle_task tool in src/tools/tasks.ts - [ ] T067 [P] [US3] Define Zod schema for task reference (ref: "path:line" or file+line) - [ ] T068 [P] [US3] Create obsidian_mark_task_done tool in src/tools/tasks.ts - [ ] T069 [P] [US3] Create obsidian_mark_task_todo tool in src/tools/tasks.ts - [ ] T070 [P] [US3] Create obsidian_update_task_status tool in src/tools/tasks.ts (custom status characters) - [ ] T071 [P] [US3] Create obsidian_get_property tool in src/tools/properties.ts (read single property) - [ ] T072 [P] [US3] Define Zod schema for property operations (name, value, type, file/path) - [ ] T073 [P] [US3] Create obsidian_set_property tool in src/tools/properties.ts - [ ] T074 [P] [US3] Create obsidian_remove_property tool in src/tools/properties.ts - [ ] T075 [P] [US3] Create obsidian_list_note_properties tool in src/tools/properties.ts (single file properties) - [ ] T076 [P] [US3] Create obsidian_daily_tasks tool in src/tools/tasks.ts (daily note tasks) - [ ] T077 [P] [US3] Create obsidian_active_file_tasks tool in src/tools/tasks.ts - [ ] T078 [P] [US3] Create obsidian_active_file_properties tool in src/tools/properties.ts - [ ] T079 [US3] Register all task and property tools in src/server.ts tools/list handler - [ ] T080 [US3] Implement task status parsing (handle empty, "x", and custom characters) - [ ] T081 [US3] Implement property type inference from value (text, number, checkbox, date, list) **Checkpoint**: All core user stories (1-3) should now be independently functional --- ## Phase 6: User Story 4 - Vault Navigation and Info (Priority: P4) **Goal**: Enable file/folder listing and vault statistics **Independent Test**: Ask AI "how many notes?", "list Projects folder", "open Weekly Review", verify responses ### Implementation for User Story 4 - [ ] T082 [P] [US4] Create obsidian_list_files tool in src/tools/vault-info.ts - [ ] T083 [P] [US4] Define Zod schema for list_files parameters (folder, extension) - [ ] T084 [P] [US4] Create obsidian_list_folders tool in src/tools/vault-info.ts - [ ] T085 [P] [US4] Create obsidian_get_folder_info tool in src/tools/vault-info.ts - [ ] T086 [P] [US4] Create obsidian_get_vault_info tool in src/tools/vault-info.ts - [ ] T087 [P] [US4] Define Zod schema for vault info query (info: name|path|files|folders|size|all) - [ ] T088 [P] [US4] Create obsidian_list_vaults tool in src/tools/vault-info.ts - [ ] T089 [P] [US4] Create obsidian_list_recents tool in src/tools/vault-info.ts (recently opened files) - [ ] T090 [P] [US4] Create obsidian_get_outline tool in src/tools/vault-info.ts (headings in file) - [ ] T091 [P] [US4] Create obsidian_get_wordcount tool in src/tools/vault-info.ts - [ ] T092 [P] [US4] Create obsidian_random_note tool in src/tools/vault-info.ts (open random) - [ ] T093 [P] [US4] Create obsidian_random_read tool in src/tools/vault-info.ts (read random) - [ ] T094 [P] [US4] Create obsidian_get_version tool in src/tools/vault-info.ts (Obsidian version) - [ ] T095 [P] [US4] Create obsidian_reload_vault tool in src/tools/vault-info.ts - [ ] T096 [P] [US4] Create obsidian_list_workspace_tabs tool in src/tools/vault-info.ts - [ ] T097 [US4] Register all vault navigation tools in src/server.ts tools/list handler - [ ] T098 [US4] Implement folder tree formatting for list_folders output - [ ] T099 [US4] Implement vault statistics aggregation (file count, size calculation) **Checkpoint**: All user stories 1-4 should be independently functional --- ## Phase 7: User Story 5 - Advanced Features (Priority: P5) **Goal**: Enable templates, daily notes, bookmarks, plugins, themes, history, sync, bases **Independent Test**: Ask AI "insert meeting template", "list plugins", "show my daily note", verify operations ### Implementation for User Story 5 #### Daily Notes (6 tools) - [ ] T100 [P] [US5] Create obsidian_open_daily_note tool in src/tools/daily-notes.ts - [ ] T101 [P] [US5] Create obsidian_daily_append tool in src/tools/daily-notes.ts - [ ] T102 [P] [US5] Create obsidian_daily_prepend tool in src/tools/daily-notes.ts - [ ] T103 [P] [US5] Create obsidian_daily_read tool in src/tools/daily-notes.ts - [ ] T104 [P] [US5] Create obsidian_daily_path tool in src/tools/daily-notes.ts - [ ] T105 [P] [US5] Define Zod schema for daily note operations (content, inline, open, paneType) #### Templates & Bookmarks (8 tools) - [ ] T106 [P] [US5] Create obsidian_list_templates tool in src/tools/advanced.ts - [ ] T107 [P] [US5] Create obsidian_read_template tool in src/tools/advanced.ts - [ ] T108 [P] [US5] Create obsidian_insert_template tool in src/tools/advanced.ts - [ ] T109 [P] [US5] Create obsidian_create_bookmark tool in src/tools/advanced.ts - [ ] T110 [P] [US5] Create obsidian_list_bookmarks tool in src/tools/advanced.ts - [ ] T111 [P] [US5] Create obsidian_bookmark_file tool in src/tools/advanced.ts - [ ] T112 [P] [US5] Create obsidian_bookmark_search tool in src/tools/advanced.ts - [ ] T113 [P] [US5] Create obsidian_bookmark_url tool in src/tools/advanced.ts #### Plugins & Themes (12 tools) - [ ] T114 [P] [US5] Create obsidian_list_plugins tool in src/tools/advanced.ts - [ ] T115 [P] [US5] Create obsidian_list_enabled_plugins tool in src/tools/advanced.ts - [ ] T116 [P] [US5] Create obsidian_get_plugin_info tool in src/tools/advanced.ts - [ ] T117 [P] [US5] Create obsidian_enable_plugin tool in src/tools/advanced.ts - [ ] T118 [P] [US5] Create obsidian_disable_plugin tool in src/tools/advanced.ts - [ ] T119 [P] [US5] Create obsidian_list_themes tool in src/tools/advanced.ts - [ ] T120 [P] [US5] Create obsidian_get_active_theme tool in src/tools/advanced.ts - [ ] T121 [P] [US5] Create obsidian_set_theme tool in src/tools/advanced.ts - [ ] T122 [P] [US5] Create obsidian_list_css_snippets tool in src/tools/advanced.ts - [ ] T123 [P] [US5] Create obsidian_enable_snippet tool in src/tools/advanced.ts - [ ] T124 [P] [US5] Create obsidian_disable_snippet tool in src/tools/advanced.ts - [ ] T125 [P] [US5] Create obsidian_restricted_mode_status tool in src/tools/advanced.ts #### File History & Sync (12 tools) - [ ] T126 [P] [US5] Create obsidian_list_file_versions tool in src/tools/advanced.ts - [ ] T127 [P] [US5] Create obsidian_read_version tool in src/tools/advanced.ts - [ ] T128 [P] [US5] Create obsidian_restore_version tool in src/tools/advanced.ts - [ ] T129 [P] [US5] Create obsidian_list_files_with_history tool in src/tools/advanced.ts - [ ] T130 [P] [US5] Create obsidian_open_history tool in src/tools/advanced.ts - [ ] T131 [P] [US5] Create obsidian_list_sync_versions tool in src/tools/advanced.ts - [ ] T132 [P] [US5] Create obsidian_read_sync_version tool in src/tools/advanced.ts - [ ] T133 [P] [US5] Create obsidian_restore_sync_version tool in src/tools/advanced.ts - [ ] T134 [P] [US5] Create obsidian_get_sync_status tool in src/tools/advanced.ts - [ ] T135 [P] [US5] Create obsidian_pause_sync tool in src/tools/advanced.ts - [ ] T136 [P] [US5] Create obsidian_resume_sync tool in src/tools/advanced.ts - [ ] T137 [P] [US5] Create obsidian_list_sync_deleted tool in src/tools/advanced.ts #### Bases & Commands (7 tools) - [ ] T138 [P] [US5] Create obsidian_list_bases tool in src/tools/advanced.ts - [ ] T139 [P] [US5] Create obsidian_list_base_views tool in src/tools/advanced.ts - [ ] T140 [P] [US5] Create obsidian_query_base tool in src/tools/advanced.ts - [ ] T141 [P] [US5] Create obsidian_create_base_item tool in src/tools/advanced.ts - [ ] T142 [P] [US5] Create obsidian_list_commands tool in src/tools/advanced.ts - [ ] T143 [P] [US5] Create obsidian_execute_command tool in src/tools/advanced.ts - [ ] T144 [P] [US5] Create obsidian_get_hotkey tool in src/tools/advanced.ts #### Integration - [ ] T145 [US5] Register all advanced feature tools in src/server.ts tools/list handler - [ ] T146 [US5] Implement template variable resolution ({{variable}} syntax) - [ ] T147 [US5] Add plugin/theme installation validation - [ ] T148 [US5] Implement bookmark type detection (file/folder/search/url) **Checkpoint**: All user stories should now be independently functional (95 tools total) --- ## Phase 8: Polish & Cross-Cutting Concerns **Purpose**: Improvements that affect multiple user stories - [X] T149 [P] Add bundle icon (icon.png) to assets/ directory - [ ] T150 [P] Create comprehensive README.md with all 95 tools documented - [ ] T151 [P] Add CHANGELOG.md following semver conventions - [X] T152 [P] Update manifest.json tools array with accurate descriptions - [ ] T153 [P] Tool description quality review for all 95 tools: Each description includes what it does, when to use it, expected outcome; parameter descriptions specify format, constraints, examples; error scenarios documented; validation via `npm run validate-tools` (uses T008b script); peer review by non-author - [ ] T154 [P] Add output format support (json/tsv/csv) where CLI provides it - [ ] T155 [P] Implement consistent error response structure across all tools - [ ] T156 [P] Add comprehensive parameter sanitization for security - [ ] T157 [P] Optimize CLI command construction for performance - [X] T158 Verify manifest.json with `mcpb pack --validate` - [X] T159 Run TypeScript build (`npm run build`) and verify no errors - [ ] T160 Test bundle packaging with `npm run pack` (creates .mcpb file) - [ ] T161 Validate quickstart.md scenarios against implemented tools - [ ] T162 [P] Add platform-specific testing (macOS, Windows, Linux) - [ ] T163 [P] Performance benchmarking suite: SC-001 file operations (read/write/delete) <3s on 1000-note vault; SC-002 search queries <5s for 10k-note vault with 100+ matches; test with actual vault data (use test-fixtures/large-vault/ from T008); generate performance report comparing results to success criteria - [ ] T164 [P] Security audit of input validation and error messages - [ ] T165 Final manifest.json review for MCPB spec v0.3 compliance --- ## Dependencies & Execution Order ### Phase Dependencies - **Setup (Phase 1)**: No dependencies - can start immediately - **Foundational (Phase 2)**: Depends on Setup completion - BLOCKS all user stories - **User Stories (Phase 3-7)**: All depend on Foundational phase completion - User stories can then proceed in parallel (if staffed) - Or sequentially in priority order (P1 → P2 → P3 → P4 → P5) - **Polish (Phase 8)**: Depends on all desired user stories being complete ### User Story Dependencies - **User Story 1 (P1)**: Can start after Foundational (Phase 2) - No dependencies on other stories - **User Story 2 (P2)**: Can start after Foundational (Phase 2) - Independent of US1 but builds on same CLI infrastructure - **User Story 3 (P3)**: Can start after Foundational (Phase 2) - Independent of US1/US2 - **User Story 4 (P4)**: Can start after Foundational (Phase 2) - Independent of US1/US2/US3 - **User Story 5 (P5)**: Can start after Foundational (Phase 2) - Independent of all others ### Within Each User Story - Tools marked [P] can be implemented in parallel (different files, no dependencies) - Registration tasks depend on tool implementation tasks completing - Error handling and formatting tasks depend on tool implementation ### Parallel Opportunities - All Setup tasks marked [P] can run in parallel (10 tasks in Phase 1) - All Foundational tasks marked [P] can run in parallel (18 tasks in Phase 2) - Once Foundational phase completes, all 5 user stories can start in parallel (if team capacity allows) - Within each user story, most tool implementations marked [P] can run in parallel: - US1: 12 parallel tool tasks - US2: 14 parallel tool tasks - US3: 14 parallel tool tasks - US4: 14 parallel tool tasks - US5: 43 parallel tool tasks --- ## Parallel Example: User Story 1 (File Operations) ```bash # After Foundational phase completes, launch all file operation tools together: Task: "T029 [P] [US1] Create obsidian_create_note tool in src/tools/file-operations.ts" Task: "T030 [P] [US1] Define Zod schema for create_note parameters..." Task: "T031 [P] [US1] Create obsidian_read_note tool in src/tools/file-operations.ts" Task: "T032 [P] [US1] Define Zod schema for read_note parameters..." # ... all 12 [P] tasks can run simultaneously # Then do sequential integration: Task: "T041 [US1] Register all file operation tools in src/server.ts" Task: "T042 [US1] Implement ambiguous name error handling..." ``` --- ## Implementation Strategy ### MVP First (User Story 1 Only) 1. Complete Phase 1: Setup (10 tasks) 2. Complete Phase 2: Foundational (18 tasks) - CRITICAL, blocks all stories 3. Complete Phase 3: User Story 1 (17 tasks) 4. **STOP and VALIDATE**: Test User Story 1 independently with AI assistant 5. Package and test installation in Claude Desktop **MVP Deliverable**: Basic file operations (create, read, append, delete, move, rename) working end-to-end. Users can manage notes conversationally. ### Incremental Delivery 1. Complete Setup + Foundational → Foundation ready (28 tasks) 2. Add User Story 1 → Test independently → Package/Demo (17 tasks) - **MVP!** 3. Add User Story 2 → Test independently → Package/Demo (18 tasks) 4. Add User Story 3 → Test independently → Package/Demo (18 tasks) 5. Add User Story 4 → Test independently → Package/Demo (18 tasks) 6. Add User Story 5 → Test independently → Package/Demo (49 tasks) 7. Polish → Final package (17 tasks) Each increment adds value without breaking previous stories. ### Parallel Team Strategy With multiple developers after Foundational phase completes: - Developer A: User Story 1 (file operations) - Developer B: User Story 2 (search & discovery) - Developer C: User Story 3 (tasks & properties) - Developer D: User Story 4 (vault navigation) - Developer E: User Story 5 (advanced features) Stories complete and integrate independently. --- ## Notes - [P] tasks = different files, no dependencies (can execute in parallel) - [Story] label maps task to specific user story for traceability - Each user story should be independently completable and testable - Commit after each task or logical group - Stop at any checkpoint to validate story independently - Total tasks: **165 tasks** - Tasks per user story: US1=17, US2=18, US3=18, US4=18, US5=49 - Parallel opportunities: ~97 tasks can run in parallel within phases - Estimated MVP scope: 45 tasks (Setup + Foundational + US1)