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>
This commit is contained in:
125
specs/001-obsidian-mcp-bundle/plan.md
Normal file
125
specs/001-obsidian-mcp-bundle/plan.md
Normal file
@@ -0,0 +1,125 @@
|
||||
# Implementation Plan: Obsidian MCP Bundle
|
||||
|
||||
**Branch**: `001-obsidian-mcp-bundle` | **Date**: 2026-03-22 | **Spec**: [spec.md](spec.md)
|
||||
**Input**: Feature specification from `/specs/001-obsidian-mcp-bundle/spec.md`
|
||||
|
||||
**Note**: This template is filled in by the `/speckit.plan` command. See `.specify/templates/plan-template.md` for the execution workflow.
|
||||
|
||||
## Summary
|
||||
|
||||
Build an MCP Bundle that exposes Obsidian CLI capabilities to AI assistants through the Model Context Protocol. The bundle will implement stdio transport communication, provide 95% coverage of Obsidian CLI commands as MCP tools, and enable users to manage their Obsidian vaults conversationally through natural language requests to AI assistants like Claude.
|
||||
|
||||
## Technical Context
|
||||
|
||||
**Language/Version**: Node.js >=18.0.0 (TypeScript 5.x)
|
||||
**Primary Dependencies**: @modelcontextprotocol/sdk, child_process (Node.js built-in)
|
||||
**Storage**: N/A (operations target user's Obsidian vault files)
|
||||
**Testing**: Jest with TypeScript support, integration tests against real Obsidian CLI
|
||||
**Target Platform**: macOS, Windows, Linux (anywhere Obsidian CLI runs)
|
||||
**Project Type**: MCP Bundle (local MCP server packaged as .mcpb file)
|
||||
**Performance Goals**: <3s for basic file operations, <5s for search queries (vaults up to 10k notes)
|
||||
**Constraints**: <30s timeout for CLI commands, stderr-only logging, no stdout pollution
|
||||
**Scale/Scope**: Support vaults with 10,000+ notes, handle 95% of Obsidian CLI commands
|
||||
|
||||
## Constitution Check
|
||||
|
||||
*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
|
||||
|
||||
### I. MCP Protocol Compliance (MANDATORY)
|
||||
✅ **PASS** - Design explicitly requires stdio transport, JSON-RPC format, proper initialize/tools/list handling per FR-001
|
||||
|
||||
### II. Manifest Integrity (MANDATORY)
|
||||
✅ **PASS** - FR-021 mandates valid manifest.json conforming to MCPB spec v0.3; FR-022 requires user_config for vault selection
|
||||
|
||||
### III. Local Execution Security
|
||||
✅ **PASS** - FR-015 requires input validation; FR-020 mandates sanitized logging; FR-022 uses user_config for vault scoping
|
||||
|
||||
### IV. Defensive Programming (NON-NEGOTIABLE)
|
||||
✅ **PASS** - FR-017 requires graceful error handling; FR-018 sets 30s timeout limits; clarifications specify error message strategies
|
||||
|
||||
### V. Structured Tool Responses
|
||||
✅ **PASS** - FR-016 mandates structured JSON responses; FR-023 requires accurate tool descriptions; FR-025 supports format options
|
||||
|
||||
### VI. Stdio Transport Standard
|
||||
✅ **PASS** - FR-020 explicitly requires stderr-only logging (never stdout); FR-001 mandates stdio transport
|
||||
|
||||
### Security & Privacy Requirements
|
||||
✅ **PASS** - All operations are local (no external services); FR-020 sanitizes logged parameters; no privacy policies needed
|
||||
|
||||
### Quality Assurance Standards
|
||||
✅ **PASS** - Testing framework defined (Jest); FR-016/FR-017 address error testing; multi-platform testing required per SC-008
|
||||
|
||||
**Overall Gate Status**: ✅ **APPROVED** - All constitutional principles satisfied. No violations to justify.
|
||||
|
||||
## Project Structure
|
||||
|
||||
### Documentation (this feature)
|
||||
|
||||
```text
|
||||
specs/001-obsidian-mcp-bundle/
|
||||
├── plan.md # This file (/speckit.plan command output)
|
||||
├── spec.md # Feature specification
|
||||
├── research.md # Phase 0 output (/speckit.plan command)
|
||||
├── data-model.md # Phase 1 output (/speckit.plan command)
|
||||
├── quickstart.md # Phase 1 output (/speckit.plan command)
|
||||
├── contracts/ # Phase 1 output (/speckit.plan command)
|
||||
│ ├── mcp-protocol.md # MCP JSON-RPC communication contract
|
||||
│ └── tools.md # Tool schemas and examples
|
||||
└── tasks.md # Phase 2 output (/speckit.tasks command - NOT created by /speckit.plan)
|
||||
```
|
||||
|
||||
### Source Code (repository root)
|
||||
|
||||
```text
|
||||
obsidian-mcp/
|
||||
├── manifest.json # MCPB manifest (required)
|
||||
├── package.json # Node.js dependencies
|
||||
├── tsconfig.json # TypeScript configuration
|
||||
├── .mcpbignore # Files to exclude from bundle
|
||||
├── src/
|
||||
│ ├── index.ts # Main entry point (MCP server)
|
||||
│ ├── server.ts # MCP server implementation
|
||||
│ ├── tools/ # Tool implementations
|
||||
│ │ ├── file-operations.ts # create, read, append, delete, move
|
||||
│ │ ├── search.ts # search, search:context
|
||||
│ │ ├── links.ts # backlinks, links, unresolved
|
||||
│ │ ├── tasks.ts # task list, toggle, mark done/todo
|
||||
│ │ ├── properties.ts # property CRUD operations
|
||||
│ │ ├── daily-notes.ts # daily note operations
|
||||
│ │ ├── tags-aliases.ts # tag and alias queries
|
||||
│ │ ├── vault-info.ts # files, folders, vault stats
|
||||
│ │ └── advanced.ts # templates, bookmarks, plugins, themes
|
||||
│ ├── cli/ # Obsidian CLI wrapper
|
||||
│ │ ├── executor.ts # CLI command execution with timeout
|
||||
│ │ └── parser.ts # CLI output parsing (JSON/TSV/CSV)
|
||||
│ ├── validation/ # Input validation
|
||||
│ │ ├── schemas.ts # Zod schemas for tool parameters
|
||||
│ │ └── sanitizer.ts # Parameter sanitization
|
||||
│ └── utils/
|
||||
│ ├── logger.ts # stderr logging utility
|
||||
│ ├── error-handler.ts # Error formatting and mapping
|
||||
│ └── types.ts # TypeScript type definitions
|
||||
├── tests/
|
||||
│ ├── integration/
|
||||
│ │ ├── file-operations.test.ts
|
||||
│ │ ├── search.test.ts
|
||||
│ │ └── mcp-protocol.test.ts
|
||||
│ └── unit/
|
||||
│ ├── cli-executor.test.ts
|
||||
│ ├── validation.test.ts
|
||||
│ └── parser.test.ts
|
||||
├── assets/
|
||||
│ └── icon.png # Bundle icon
|
||||
└── README.md # Installation and usage docs
|
||||
```
|
||||
|
||||
**Structure Decision**: Single project (MCP Bundle) - This is a Node.js application that implements an MCP server. The structure follows MCPB best practices with manifest.json at root, src/ for TypeScript source, and bundled node_modules. Tools are organized by functional category matching user stories. CLI wrapper layer abstracts Obsidian CLI execution and provides consistent error handling and timeout management.
|
||||
|
||||
## Complexity Tracking
|
||||
|
||||
> **Fill ONLY if Constitution Check has violations that must be justified**
|
||||
|
||||
| Violation | Why Needed | Simpler Alternative Rejected Because |
|
||||
|-----------|------------|-------------------------------------|
|
||||
| [e.g., 4th project] | [current need] | [why 3 projects insufficient] |
|
||||
| [e.g., Repository pattern] | [specific problem] | [why direct DB access insufficient] |
|
||||
Reference in New Issue
Block a user