Peter.Morton
622b28e42c
- 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>
126 lines
6.7 KiB
Markdown
126 lines
6.7 KiB
Markdown
# 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] |
|