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

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

• T001 Create project directory structure per implementation plan (src/, tests/, assets/)
• T002 Initialize Node.js project with package.json (name: obsidian-mcp, version: 1.0.0, type: module)
• T003 [P] Configure TypeScript in tsconfig.json (target: ES2022, module: ESNext, strict mode, outDir: dist)
• T004 [P] Install @modelcontextprotocol/sdk dependency in package.json
• T005 [P] Install development dependencies (typescript, jest, @types/node, @types/jest, ts-jest, zod)
• T006 [P] Configure Jest for TypeScript in jest.config.js
• T007 [P] Create .mcpbignore file (exclude tests/, .git/, node_modules/, src/, tsconfig.json)
• T008 [P] Add build scripts to package.json (build: tsc, pack: mcpb pack, test: jest)
• T008a [P] Create test fixtures in tests/fixtures/ (sample notes, vaults, mock CLI responses)
• T008b [P] Create tool validation script in scripts/validate-tools.js (checks description completeness)
• T009 [P] Create README.md with installation and usage instructions
• 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

• T011 Create manifest.json at project root conforming to MCPB spec v0.3
• T012 [P] Define user_config schema in manifest.json for vault_name parameter
• T013 [P] Set server.type to "node" and entry_point to "dist/index.js" in manifest.json
• T014 [P] Configure mcp_config in manifest.json (command: node, args with ${__dirname}, env with ${user_config.vault_name})
• T015 [P] Add compatibility section to manifest.json (platforms: darwin/win32/linux, node: >=18.0.0)
• T016 Create TypeScript types in src/utils/types.ts (ToolInput, ToolOutput, ErrorResponse, etc.)
• T017 [P] Create logger utility in src/utils/logger.ts (stderr-only, sanitized parameters)
• T018 [P] Create error handler in src/utils/error-handler.ts (map CLI errors to MCP error codes)
• T019 Create CLI executor in src/cli/executor.ts (spawn with timeout, output streaming, error handling, import from src/config/timeouts.ts)
• T019a [P] Create timeout configuration in src/config/timeouts.ts (default 30s, per-command overrides map)
• T020 [P] Create CLI output parser in src/cli/parser.ts (JSON/TSV/CSV/text format support)
• T021 Create Zod validation schemas in src/validation/schemas.ts (common parameter patterns)
• T022 [P] Create parameter sanitizer in src/validation/sanitizer.ts (remove dangerous characters)
• T023 Create MCP server base in src/server.ts (initialize MCP Server with stdio transport)
• T024 Implement initialize handler in src/server.ts (return capabilities and server info)
• T025 Implement tools/list handler in src/server.ts (return all tool definitions with schemas)
• T026 Implement tools/call dispatcher in src/server.ts (route to tool implementations with validation)
• T027 Create main entry point in src/index.ts (connect server to stdio transport, handle shutdown)
• 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

• T029 [P] [US1] Create obsidian_create_note tool in src/tools/file-operations.ts
• T030 [P] [US1] Define Zod schema for create_note parameters (name, path, content, template, overwrite, open)
• T031 [P] [US1] Create obsidian_read_note tool in src/tools/file-operations.ts
• T032 [P] [US1] Define Zod schema for read_note parameters (file or path, oneOf validation)
• T033 [P] [US1] Create obsidian_append_to_note tool in src/tools/file-operations.ts
• T034 [P] [US1] Define Zod schema for append parameters (file/path, content, inline)
• T035 [P] [US1] Create obsidian_prepend_to_note tool in src/tools/file-operations.ts
• T036 [P] [US1] Create obsidian_delete_note tool in src/tools/file-operations.ts (with permanent flag)
• T037 [P] [US1] Create obsidian_move_note tool in src/tools/file-operations.ts
• T038 [P] [US1] Create obsidian_rename_note tool in src/tools/file-operations.ts
• T039 [P] [US1] Create obsidian_open_note tool in src/tools/file-operations.ts (with newtab option)
• T040 [P] [US1] Create obsidian_get_file_info tool in src/tools/file-operations.ts
• T041 [US1] Register all file operation tools in src/server.ts tools/list handler
• T042 [US1] Implement ambiguous name error handling per clarification (return error with all matching paths)
• T043 [US1] Implement wikilink-style name resolution in file operation tools
• T044 [US1] Add error message mapping for file not found errors
• 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

• 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
• 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
• T158 Verify manifest.json with mcpb pack --validate
• 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)

# 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)