obsidian-mcp/design.md

Obsidian MCP Server - Design Document

Version: 1.0.0
Date: 2025-10-07
Status: Draft

---

Table of Contents

1. Executive Summary
2. System Overview
3. Architecture
4. Domain Model
5. Use Cases
6. API Specification
7. Data Model
8. Infrastructure Design
9. Security & Performance
10. Testing Strategy
11. Deployment
12. Implementation Roadmap

---

1. Executive Summary

1.1 Project Goals

Разработать легковесный, производительный MCP-сервер на Go для работы с Obsidian vault через Model Context Protocol.

Ключевые цели:

• Предоставить AI-ассистентам полный доступ к Obsidian заметкам
• Поддержать Git workflow для версионирования
• Обеспечить быстрый поиск и навигацию по заметкам
• Работать с wikilinks, тегами и frontmatter
• Быть легко расширяемым и поддерживаемым

1.2 Key Requirements

Функциональные:

• CRUD операции над заметками
• Полнотекстовый и семантический поиск
• Работа с графом связей (backlinks/outlinks)
• Управление тегами и метаданными
• Git интеграция (commit, push, pull)
• Поддержка шаблонов и daily notes

Нефункциональные:

• Производительность: < 100ms на операцию чтения
• Надёжность: обработка ошибок, валидация данных
• Масштабируемость: поддержка vault до 10,000+ заметок
• Maintainability: чистая архитектура, 80%+ test coverage

1.3 Technology Stack

Component	Technology	Justification
Language	Go 1.21+	Производительность, лёгковесность
MCP SDK	github.com/modelcontextprotocol/go-sdk	Официальная реализация
Git	github.com/go-git/go-git/v5	Pure Go, без C зависимостей
Markdown	github.com/yuin/goldmark	CommonMark compliant
Frontmatter	go.abhg.dev/goldmark/frontmatter	Интеграция с goldmark

---

2. System Overview

2.1 System Context Diagram

graph TB
    subgraph "MCP Clients"
        Claude[Claude Desktop]
        Cursor[Cursor IDE]
        Other[Other MCP Clients]
    end
    
    subgraph "Obsidian MCP Server"
        MCP[MCP Protocol Layer]
        Tools[MCP Tools 45+]
        Resources[MCP Resources]
        Prompts[MCP Prompts]
    end
    
    subgraph "Data Storage"
        Vault[Obsidian Vault<br/>Markdown Files]
        Git[Git Repository]
    end
    
    Claude -->|stdio/SSE| MCP
    Cursor -->|stdio/SSE| MCP
    Other -->|stdio/SSE| MCP
    
    MCP --> Tools
    MCP --> Resources
    MCP --> Prompts
    
    Tools -->|Read/Write| Vault
    Tools -->|Commit/Push/Pull| Git
    
    Vault -.->|Version Control| Git

2.2 High-Level Architecture

graph TB
    subgraph "Presentation Layer"
        MCPT[MCP Tools]
        MCPR[MCP Resources]
        MCPP[MCP Prompts]
    end
    
    subgraph "Application Layer"
        UC1[Note Use Cases]
        UC2[Search Use Cases]
        UC3[Link Use Cases]
        UC4[Tag Use Cases]
        UC5[Git Use Cases]
    end
    
    subgraph "Domain Layer"
        Note[Note Entity]
        Vault[Vault Entity]
        Link[WikiLink VO]
        Tag[Tag VO]
        FM[Frontmatter VO]
    end
    
    subgraph "Infrastructure Layer"
        FS[Filesystem Repository]
        GitRepo[Git Repository]
        MD[Markdown Parser]
        Index[Search Index]
    end
    
    MCPT --> UC1
    MCPT --> UC2
    MCPR --> UC1
    MCPP --> UC1
    
    UC1 --> Note
    UC2 --> Note
    UC3 --> Link
    UC4 --> Tag
    UC5 --> GitRepo
    
    UC1 --> FS
    UC1 --> GitRepo
    UC2 --> Index
    
    FS --> MD
    FS --> Note
    GitRepo --> Vault

2.3 Key Components

Component	Responsibility	Technology
MCP Server	Protocol handling, tool registration	go-sdk/mcp
Use Cases	Business logic, orchestration	Pure Go
Domain Model	Business entities, rules	Pure Go
Repositories	Data persistence abstraction	Interfaces
Markdown Parser	Parse MD, frontmatter, wikilinks	goldmark
Git Manager	Version control operations	go-git
Search Index	Fast full-text search	In-memory

---

3. Architecture

3.1 Clean Architecture

Принципы:

• Dependency Rule: зависимости направлены внутрь (к Domain)
• Domain независим от frameworks и libraries
• Use Cases содержат бизнес-логику
• Infrastructure легко заменяема

3.2 Layer Diagram

graph LR
    subgraph "Layer 4: Infrastructure"
        FS[File System]
        Git[Git Impl]
        Parser[MD Parser]
    end
    
    subgraph "Layer 3: Adapters"
        MCP[MCP Adapter]
        DTO[DTOs]
        Repo[Repository Impl]
    end
    
    subgraph "Layer 2: Application"
        UC[Use Cases]
        Iface[Repository Interfaces]
    end
    
    subgraph "Layer 1: Domain"
        Entity[Entities]
        VO[Value Objects]
        Rules[Business Rules]
    end
    
    MCP --> UC
    UC --> Iface
    Repo --> Iface
    Repo --> FS
    Repo --> Git
    Repo --> Parser
    UC --> Entity
    Entity --> VO
    Entity --> Rules

3.3 Dependency Flow

flowchart TD
    A[MCP Client Request] --> B[MCP Tool Handler]
    B --> C[Use Case]
    C --> D{Repository Interface}
    D --> E[Repository Implementation]
    E --> F[Infrastructure<br/>Filesystem/Git/Parser]
    F --> G[Domain Entity]
    G --> E
    E --> C
    C --> B
    B --> H[MCP Client Response]
    
    style D fill:#f9f,stroke:#333
    style G fill:#9ff,stroke:#333

3.4 Directory Structure

obsidian-mcp-server/
├── cmd/
│   └── obsidian-mcp/
│       └── main.go                    # Entry point
├── internal/
│   ├── domain/                        # Domain layer
│   │   ├── note.go
│   │   ├── vault.go
│   │   ├── frontmatter.go
│   │   ├── wikilink.go
│   │   ├── tag.go
│   │   └── errors.go
│   ├── repository/                    # Repository interfaces
│   │   ├── note_repository.go
│   │   ├── git_repository.go
│   │   └── vault_repository.go
│   ├── usecase/                       # Application use cases
│   │   ├── note/
│   │   ├── search/
│   │   ├── link/
│   │   ├── tag/
│   │   ├── frontmatter/
│   │   ├── git/
│   │   └── vault/
│   ├── infrastructure/                # Infrastructure
│   │   ├── filesystem/
│   │   ├── git/
│   │   ├── markdown/
│   │   └── index/
│   ├── adapter/                       # Interface adapters
│   │   ├── mcp/
│   │   │   ├── server.go
│   │   │   ├── tools/
│   │   │   ├── resources/
│   │   │   └── prompts/
│   │   └── dto/
│   └── config/
├── pkg/                               # Public packages
├── test/                              # Tests
├── go.mod
└── README.md

---

4. Domain Model

4.1 Domain Entity Diagram

classDiagram
    class Note {
        -string path
        -string content
        -Frontmatter frontmatter
        -WikiLink[] outlinks
        -Tag[] tags
        -time createdAt
        -time modifiedAt
        +NewNote(path, content) Note
        +AddTag(tag) error
        +RemoveTag(tag) error
        +UpdateContent(content) error
        +ExtractLinks() WikiLink[]
    }
    
    class Vault {
        -string rootPath
        -Note[] notes
        -Graph graph
        -map tags
        +NewVault(path) Vault
        +AddNote(note) error
        +GetStats() VaultStats
    }
    
    class Frontmatter {
        -map data
        +Get(key) any
        +Set(key, value) error
        +Merge(other) Frontmatter
    }
    
    class WikiLink {
        -string target
        -string alias
        -string section
        +Target() string
        +IsValid() bool
    }
    
    class Tag {
        -string name
        +Name() string
        +Parent() Tag
        +IsNested() bool
    }
    
    class Graph {
        -map adjacencyList
        +AddEdge(from, to)
        +GetBacklinks(path) string[]
        +GetOutlinks(path) string[]
    }
    
    Vault "1" *-- "0..*" Note
    Note "1" *-- "0..1" Frontmatter
    Note "1" *-- "0..*" WikiLink
    Note "1" *-- "0..*" Tag
    Vault "1" *-- "1" Graph

4.2 Core Entities

4.2.1 Note Entity

Responsibilities:

• Хранить путь, контент и метаданные
• Управлять тегами
• Валидировать содержимое
• Отслеживать временные метки

Business Rules:

• Path должен быть уникальным
• Path должен заканчиваться на .md
• Content может быть пустым
• Теги не могут дублироваться
• ModifiedAt обновляется при изменениях

4.2.2 Value Objects

Frontmatter:

• Immutable map данных
• YAML совместимый
• Поддержка стандартных полей (title, tags, date, etc)
• Merge операции

WikiLink:

• Target (обязательный)
• Alias (опциональный)
• Section (опциональный)
• Валидация существования target

Tag:

• Name с префиксом #
• Поддержка nested tags (#project/ai)
• Иерархия тегов

4.3 Domain Errors

Error	Description	Handling
ErrNoteNotFound	Note doesn't exist	Return 404
ErrNoteAlreadyExists	Note path taken	Return 409
ErrInvalidPath	Invalid file path	Return 400
ErrEmptyContent	Content is empty	Return 400
ErrInvalidTag	Invalid tag format	Return 400
ErrCircularLink	Circular dependency	Return 400

---

5. Use Cases

5.1 Use Case Catalog

mindmap
  root((Use Cases))
    Note Operations
      Read Note
      Create Note
      Update Note
      Delete Note
      Rename Note
    Search Operations
      Search Content
      Search by Tags
      Search by Frontmatter
    Link Operations
      Get Backlinks
      Get Outlinks
      Get Graph
      Find Broken Links
      Update Links
    Tag Operations
      Get All Tags
      Add Tags
      Remove Tags
      Rename Tag
    Frontmatter Operations
      Get Frontmatter
      Update Frontmatter
      Bulk Update
    Git Operations
      Status
      Commit
      Pull
      Push
      History
    Vault Operations
      Get Stats
      Get Structure
      List Notes
      Find Orphaned

5.2 Key Use Case Specifications

UC-001: Read Note

Actor: MCP Client
Preconditions: Note exists
Postconditions: Note content returned

Main Flow:

1. Client requests note by path
2. System performs git pull
3. System reads note file
4. System parses markdown
5. System extracts frontmatter
6. System extracts wikilinks and tags
7. System returns note with metadata

Alternate Flows:

• Git pull fails → log warning, continue
• File not found → return error
• Invalid markdown → return partial content

Business Rules:

• Path relative to vault root
• File must have .md extension
• Read never modifies files

UC-002: Create Note

Actor: MCP Client
Preconditions: Note doesn't exist
Postconditions: Note created and committed

Main Flow:

1. Client requests creation
2. System validates path
3. System creates directories if needed
4. System writes note file
5. System commits to git
6. System returns created note

Business Rules:

• Path must not exist
• Content can be empty
• Git commit is mandatory

UC-010: Search Content

Actor: MCP Client
Preconditions: Vault indexed
Postconditions: Results returned

Main Flow:

1. Client submits search query
2. System validates query
3. System searches index
4. System ranks results
5. System returns top N results

Search Types:

• Full-text (regex/substring)
• Tag-based
• Frontmatter
• Semantic (future)

UC-015: Get Backlinks

Actor: MCP Client
Preconditions: Note exists
Postconditions: Backlinks returned

Main Flow:

1. Client requests backlinks
2. System validates path
3. System queries graph index
4. System loads referring notes
5. System returns backlinks with context

5.3 Use Case Dependencies

graph TD
    A[Create Note] --> B[Git Commit]
    C[Update Note] --> B
    D[Delete Note] --> B
    E[Rename Note] --> F[Update Links]
    F --> B
    G[Search Content] --> H[Search Index]
    I[Get Backlinks] --> J[Graph Index]

---

6. API Specification

6.1 MCP Tools Overview

Total Tools: 45+

Categories:

• File Operations (5 tools)
• Search Operations (3 tools)
• Link Operations (5 tools)
• Tag Operations (4 tools)
• Frontmatter Operations (3 tools)
• Git Operations (5 tools)
• Vault Operations (5 tools)
• Template Operations (3 tools)
• Daily Notes (3 tools)
• Batch Operations (3 tools)
• Analytics (2 tools)

6.2 File Operations

read_note

Description: Read Obsidian note with frontmatter and metadata

Input Schema:

{
  "path": "string (required)",
  "format": "markdown|json (default: json)"
}

Output Schema:

{
  "path": "string",
  "content": "string",
  "frontmatter": "object",
  "tags": ["string"],
  "outlinks": [{"target": "string", "alias": "string"}],
  "stats": {
    "words": "number",
    "characters": "number",
    "created": "timestamp",
    "modified": "timestamp"
  }
}

create_note

Input Schema:

{
  "path": "string (required)",
  "content": "string",
  "frontmatter": "object",
  "create_dirs": "boolean (default: true)"
}

Output: Created note object

update_note

Input Schema:

{
  "path": "string (required)",
  "content": "string",
  "mode": "overwrite|append|prepend (default: overwrite)",
  "frontmatter": "object",
  "merge_frontmatter": "boolean (default: true)"
}

delete_note

Input Schema:

{
  "path": "string (required)",
  "confirm": "boolean (default: false)"
}

rename_note

Input Schema:

{
  "old_path": "string (required)",
  "new_path": "string (required)",
  "update_links": "boolean (default: true)"
}

6.3 Search Operations

search_content

Input Schema:

{
  "query": "string (required)",
  "max_results": "number (default: 50)",
  "case_sensitive": "boolean (default: false)",
  "use_regex": "boolean (default: false)",
  "context_lines": "number (default: 2)"
}

Output Schema:

{
  "results": [
    {
      "path": "string",
      "matches": [
        {
          "line": "number",
          "content": "string",
          "context_before": "string",
          "context_after": "string"
        }
      ],
      "score": "number"
    }
  ],
  "total": "number"
}

search_by_tags

Input Schema:

{
  "tags": ["string"],
  "mode": "all|any (default: any)",
  "include_nested": "boolean (default: true)"
}

search_by_frontmatter

Input Schema:

{
  "filters": "object",
  "operator": "and|or (default: and)"
}

6.4 Link Operations

get_backlinks

Input Schema:

{
  "path": "string (required)",
  "include_context": "boolean (default: true)"
}

Output Schema:

{
  "note": "string",
  "backlinks": [
    {
      "from": "string",
      "context": "string",
      "line": "number"
    }
  ],
  "count": "number"
}

get_outlinks

Input Schema:

{
  "path": "string (required)",
  "resolve": "boolean (default: true)"
}

get_graph

Input Schema:

{
  "path": "string (required)",
  "depth": "number (default: 1)",
  "max_nodes": "number (default: 100)"
}

Output Schema:

{
  "nodes": [{"path": "string", "title": "string"}],
  "edges": [{"from": "string", "to": "string"}]
}

find_broken_links

Input Schema:

{
  "path": "string (optional, check specific note or entire vault)"
}

update_links

Input Schema:

{
  "old_path": "string (required)",
  "new_path": "string (required)",
  "dry_run": "boolean (default: false)"
}

6.5 Tag Operations

get_all_tags

Input Schema:

{
  "sort_by": "name|count (default: count)",
  "min_count": "number (default: 1)"
}

add_tags, remove_tags, rename_tag

Similar input patterns with tag manipulation logic.

6.6 Git Operations

git_status, git_commit, git_pull, git_push, git_history

Standard Git operations exposed through MCP.

6.7 Vault Operations

list_notes, get_vault_stats, get_vault_structure, find_orphaned_notes, get_most_linked

Vault-level analytics and navigation tools.

6.8 Error Handling

Error Response Format:

{
  "error": {
    "code": "string",
    "message": "string",
    "details": "object"
  }
}

Error Codes:

Code	HTTP Status	Description
NOTE_NOT_FOUND	404	Note doesn't exist
NOTE_ALREADY_EXISTS	409	Note already exists
INVALID_PATH	400	Invalid file path
GIT_ERROR	500	Git operation failed
PARSE_ERROR	500	Markdown parse error

---

7. Data Model

7.1 Entity Relationship Diagram

erDiagram
    VAULT ||--o{ NOTE : contains
    NOTE ||--o| FRONTMATTER : has
    NOTE ||--o{ TAG : has
    NOTE ||--o{ WIKILINK : contains
    NOTE ||--o{ NOTE : links-to
    VAULT ||--|| GRAPH : maintains
    
    VAULT {
        string root_path
        int total_notes
        datetime last_indexed
    }
    
    NOTE {
        string path PK
        string content
        datetime created_at
        datetime modified_at
        int word_count
    }
    
    FRONTMATTER {
        string note_path FK
        json data
    }
    
    TAG {
        string name PK
        int usage_count
    }
    
    WIKILINK {
        int id PK
        string source_note FK
        string target
        string alias
    }
    
    GRAPH {
        string vault_path FK
        map adjacency_list
    }

7.2 Data Storage

Primary Storage: Filesystem (Markdown files)

In-Memory Indices:

• Search Index: word → [notePaths]
• Graph Index: note → [linkedNotes]
• Tag Index: tag → [notePaths]

Cache Strategy:

• LRU cache for recently accessed notes
• TTL: 5 minutes
• Invalidation on file changes

---

8. Infrastructure Design

8.1 Component Diagram

graph TB
    subgraph "MCP Layer"
        Server[MCP Server]
        Tools[Tool Handlers]
    end
    
    subgraph "Application"
        UC[Use Cases]
    end
    
    subgraph "Repository"
        NoteRepo[Note Repository]
        GitRepo[Git Repository]
    end
    
    subgraph "Infrastructure"
        FS[Filesystem]
        GitImpl[Go-Git]
        Parser[Goldmark Parser]
        FMParser[Frontmatter Parser]
        WLParser[WikiLink Parser]
    end
    
    subgraph "Indices"
        SearchIdx[Search Index]
        GraphIdx[Graph Index]
        TagIdx[Tag Index]
    end
    
    Server --> Tools
    Tools --> UC
    UC --> NoteRepo
    UC --> GitRepo
    
    NoteRepo --> FS
    NoteRepo --> Parser
    NoteRepo --> SearchIdx
    
    GitRepo --> GitImpl
    
    Parser --> FMParser
    Parser --> WLParser
    Parser --> GraphIdx
    Parser --> TagIdx

8.2 Markdown Parser Architecture

flowchart LR
    A[Raw Markdown] --> B[Goldmark Parser]
    B --> C[AST]
    C --> D[Frontmatter Extractor]
    C --> E[WikiLink Extractor]
    C --> F[Tag Extractor]
    
    D --> G[Frontmatter Object]
    E --> H[WikiLink List]
    F --> I[Tag List]
    
    G --> J[Note Entity]
    H --> J
    I --> J
    C --> K[Content String]
    K --> J

8.3 Git Integration Flow

sequenceDiagram
    participant Client
    participant UseCase
    participant GitRepo
    participant GoGit
    participant Filesystem
    
    Client->>UseCase: Update Note
    UseCase->>GitRepo: Pull()
    GitRepo->>GoGit: Pull latest
    GoGit-->>GitRepo: OK
    
    UseCase->>Filesystem: Write file
    Filesystem-->>UseCase: OK
    
    UseCase->>GitRepo: Commit(message, files)
    GitRepo->>GoGit: Add files
    GitRepo->>GoGit: Commit
    GoGit-->>GitRepo: commit hash
    
    opt Auto-push enabled
        GitRepo->>GoGit: Push
    end
    
    GitRepo-->>UseCase: Success
    UseCase-->>Client: Note updated

8.4 Index Building

flowchart TD
    A[Vault Scan] --> B[Iterate Notes]
    B --> C[Parse Note]
    C --> D[Extract Text]
    C --> E[Extract Links]
    C --> F[Extract Tags]
    
    D --> G[Build Search Index]
    E --> H[Build Graph Index]
    F --> I[Build Tag Index]
    
    G --> J[In-Memory Indices]
    H --> J
    I --> J

---

9. Security & Performance

9.1 Security Considerations

Input Validation:

• Path traversal prevention (no ..)
• Extension validation (.md only)
• Content sanitization
• Size limits

Permission Model:

• Read-only mode support
• Git operations opt-in
• Rate limiting per client

Authentication:

• API key support (optional)
• OAuth integration (future)

9.2 Performance Targets

Operation	Target	Notes
Read Note	< 100ms	Including git pull
Create Note	< 200ms	Including git commit
Search	< 500ms	Vault with 5000 notes
Get Backlinks	< 50ms	From graph index
List Notes	< 100ms	Recursive listing

9.3 Performance Optimization

Caching:

• LRU cache for notes (size: 1000)
• Index caching with TTL
• Incremental index updates

Concurrency:

• Worker pools for batch operations
• Parallel file reading
• Non-blocking git operations

Memory Management:

• Streaming for large files
• Lazy loading of note content
• Periodic garbage collection

---

10. Testing Strategy

10.1 Testing Pyramid

graph TD
    A[E2E Tests 10%] --> B[Integration Tests 20%]
    B --> C[Unit Tests 70%]
    
    style C fill:#90EE90
    style B fill:#FFD700
    style A fill:#FF6347

10.2 Test Coverage Goals

Layer	Coverage	Priority
Domain	90%+	High
Use Cases	85%+	High
Repositories	80%+	Medium
Adapters	70%+	Medium
Infrastructure	60%+	Low

10.3 Test Types

Unit Tests:

• Domain entity logic
• Use case orchestration (with mocks)
• Value object validation

Integration Tests:

• Repository implementations
• Index building
• Git operations

E2E Tests:

• MCP tool invocations
• Complete workflows
• Error scenarios

Performance Tests:

• Search benchmarks
• Large vault handling
• Concurrent operations

---

11. Deployment

11.1 Installation Methods

Binary Release:

• Pre-compiled binaries for Linux, macOS, Windows
• Simple download and run

Go Install:

• go install github.com/user/obsidian-mcp-server@latest

Docker:

• Official Docker image
• docker-compose support

11.2 Configuration

Environment Variables:

• VAULT_PATH - Path to Obsidian vault
• GIT_AUTO_PUSH - Enable auto-push
• LOG_LEVEL - Logging level

Config File (YAML):

server:
  name: obsidian-mcp
  transport: stdio

vault:
  path: /path/to/vault
  exclude_paths:
    - .obsidian/
    - .git/

git:
  enabled: true
  auto_pull: true
  auto_push: false

logging:
  level: info

11.3 Monitoring

Health Checks:

• Vault accessibility
• Git repository status
• Index health

Metrics:

• Request count
• Request duration
• Error rate
• Cache hit rate

Logging:

• Structured JSON logging
• Log levels: debug, info, warn, error
• Request/response logging

---

12. Implementation Roadmap

12.1 Development Phases

gantt
    title Implementation Timeline
    dateFormat YYYY-MM-DD
    section Phase 1
    Domain Model           :2025-01-20, 7d
    Repository Interfaces  :2025-01-27, 5d
    section Phase 2
    Infrastructure         :2025-02-01, 14d
    Use Cases             :2025-02-08, 14d
    section Phase 3
    MCP Adapter           :2025-02-15, 10d
    Testing               :2025-02-25, 7d
    section Phase 4
    Documentation         :2025-03-04, 5d
    Release v1.0          :2025-03-09, 1d

12.2 Phase 1: Foundation (Week 1-2)

Goals:

• Domain model
• Repository interfaces
• Project structure

Deliverables:

• Domain entities (Note, Vault, Tag, WikiLink, Frontmatter)
• Repository interfaces
• Domain tests (90%+ coverage)
• Project setup

12.3 Phase 2: Core Functionality (Week 3-6)

Goals:

• Infrastructure implementations
• Core use cases
• Index building

Deliverables:

• Filesystem repository
• Git repository
• Markdown parser
• Search/Graph indices
• Note CRUD use cases
• Search use cases
• Link use cases

12.4 Phase 3: MCP Integration (Week 7-9)

Goals:

• MCP adapter layer
• Tool implementations
• End-to-end testing

Deliverables:

• MCP server setup
• 45+ MCP tools
• MCP resources
• MCP prompts
• E2E tests
• Performance testing

Tasks:

1. Setup MCP server with go-sdk
2. Implement file operation tools (5)
3. Implement search tools (3)
4. Implement link tools (5)
5. Implement tag/frontmatter tools (7)
6. Implement git tools (5)
7. Implement vault tools (5)
8. Implement template tools (3)
9. Write E2E tests
10. Performance benchmarks

12.5 Phase 4: Polish & Release (Week 10-11)

Goals:

• Documentation
• Examples
• Release preparation

Deliverables:

• README with examples
• API documentation
• Configuration guide
• Binary releases (Linux, macOS, Windows)
• Docker image
• GitHub releases

Tasks:

1. Write comprehensive README
2. Create example configurations
3. Build for multiple platforms
4. Create Docker image
5. Setup GitHub releases
6. Publish v1.0.0

12.6 Post-Release Roadmap

v1.1.0 (Future):

• Semantic search with embeddings
• Real-time file watching
• Web UI for monitoring
• Batch operations optimization
• Plugin system

v1.2.0 (Future):

• Custom parsers
• Advanced git operations (branches, merges)
• Vault backup/restore
• Performance improvements

v2.0.0 (Future):

• Multi-vault support
• Collaboration features
• Cloud sync integration
• Advanced analytics

---

Appendix A: Repository Interfaces

A.1 Core Interfaces

NoteRepository:

• Get(ctx, path) → Note
• Create(ctx, note) → error
• Update(ctx, note) → error
• Delete(ctx, path) → error
• List(ctx, pattern, recursive) → []Note
• Exists(ctx, path) → bool

GitRepository:

• Status(ctx) → GitStatus
• Pull(ctx) → error
• Push(ctx) → error
• Commit(ctx, message, files) → error
• Log(ctx, path, limit) → []Commit

VaultRepository:

• GetStats(ctx) → VaultStats
• GetStructure(ctx, maxDepth) → VaultStructure
• FindOrphaned(ctx, excludePaths) → []string

SearchIndex:

• Index(note) → error
• Remove(path) → error
• Search(query, maxResults) → []string
• Rebuild(notes) → error

GraphIndex:

• AddNote(note) → error
• RemoveNote(path) → error
• GetBacklinks(path) → []string
• GetOutlinks(path) → []string
• GetConnected(path, depth) → []string

TagIndex:

• AddNote(note) → error
• RemoveNote(path) → error
• GetAllTags() → []TagInfo
• GetNotesWithTag(tag) → []string
• GetNotesWithTags(tags, mode) → []string

A.2 Data Types

GitStatus:

• Branch: string
• Modified: []string
• Untracked: []string
• Staged: []string
• Ahead: int
• Behind: int

Commit:

• Hash: string
• Author: string
• Date: time.Time
• Message: string
• Files: []string

VaultStats:

• TotalNotes: int
• TotalWords: int
• TotalLinks: int
• TotalTags: int
• AvgNoteLength: int
• MostLinked: []MostLinkedNote
• OrphanedNotes: int

VaultStructure:

• Name: string
• Path: string
• Type: string (file/directory)
• Children: []VaultStructure

TagInfo:

• Name: string
• Count: int
• Nested: bool

---

Appendix B: Configuration Schema

B.1 Complete Configuration

server:
  name: obsidian-mcp
  version: 1.0.0
  transport: stdio  # or "sse"

vault:
  path: /path/to/vault
  exclude_paths:
    - .obsidian/
    - .git/
    - .trash/
    - Archive/
  watch_changes: true

git:
  enabled: true
  auto_pull: true
  auto_push: false
  auto_commit: true
  commit_prefix: "[MCP]"
  remote: origin
  branch: main

index:
  build_on_startup: true
  rebuild_interval: 5m
  max_notes_in_memory: 10000

search:
  max_results: 50
  context_lines: 2
  case_sensitive: false

cache:
  enabled: true
  max_size: 1000
  ttl: 5m

logging:
  level: info  # debug, info, warn, error
  format: text  # text or json
  file: /var/log/obsidian-mcp.log

performance:
  max_concurrent_operations: 10
  read_timeout: 30s
  write_timeout: 30s

security:
  rate_limit:
    enabled: true
    requests_per_second: 10
    burst: 20
  max_file_size: 10MB

B.2 Environment Variables

Variable	Description	Default
VAULT_PATH	Path to Obsidian vault	required
CONFIG_PATH	Path to config file	config.yaml
LOG_LEVEL	Logging level	info
GIT_ENABLED	Enable git operations	true
GIT_AUTO_PUSH	Auto-push changes	false
CACHE_ENABLED	Enable caching	true

---

Appendix C: Error Codes Reference

C.1 Domain Errors

Code	Message	HTTP Status
ERR_NOTE_NOT_FOUND	Note not found	404
ERR_NOTE_EXISTS	Note already exists	409
ERR_INVALID_PATH	Invalid note path	400
ERR_EMPTY_CONTENT	Content cannot be empty	400
ERR_INVALID_TAG	Invalid tag format	400
ERR_TAG_EXISTS	Tag already exists	409
ERR_CIRCULAR_LINK	Circular link detected	400

C.2 Infrastructure Errors

Code	Message	HTTP Status
ERR_GIT_PULL	Git pull failed	500
ERR_GIT_PUSH	Git push failed	500
ERR_GIT_COMMIT	Git commit failed	500
ERR_PARSE	Markdown parse error	500
ERR_IO	File I/O error	500
ERR_PERMISSION	Permission denied	403

C.3 Application Errors

Code	Message	HTTP Status
ERR_INVALID_INPUT	Invalid input parameters	400
ERR_RATE_LIMIT	Rate limit exceeded	429
ERR_TIMEOUT	Operation timeout	408
ERR_INTERNAL	Internal server error	500

---

Appendix D: Performance Benchmarks

D.1 Target Performance Metrics

Vault Sizes:

• Small: 100 notes, ~200KB
• Medium: 1,000 notes, ~2MB
• Large: 5,000 notes, ~10MB
• XL: 10,000 notes, ~20MB

Operation Latencies (Medium Vault):

Operation	P50	P95	P99
Read Note	20ms	50ms	100ms
Create Note	50ms	150ms	200ms
Update Note	40ms	120ms	180ms
Delete Note	30ms	100ms	150ms
Search (full-text)	100ms	300ms	500ms
Get Backlinks	10ms	30ms	50ms
Get Outlinks	5ms	15ms	30ms
List Notes (100)	20ms	60ms	100ms
Git Commit	200ms	500ms	1s
Git Pull	300ms	1s	2s

Memory Usage:

Vault Size	Base Memory	Index Memory	Total
Small	20MB	5MB	25MB
Medium	30MB	30MB	60MB
Large	50MB	150MB	200MB
XL	80MB	300MB	380MB

D.2 Scalability Limits

Recommended Limits:

• Max notes: 10,000
• Max note size: 10MB
• Max concurrent operations: 100
• Max search results: 1,000

Hard Limits:

• Max notes: 50,000 (performance degrades)
• Max note size: 50MB (memory issues)
• Max vault size: 1GB

---

Appendix E: MCP Tools Complete List

E.1 File Operations (5)

1. read_note
2. create_note
3. update_note
4. delete_note
5. rename_note

E.2 Directory Operations (3)

6. list_notes
7. create_directory
8. get_vault_structure

E.3 Search Operations (3)

9. search_content
10. search_by_tags
11. search_by_frontmatter

E.4 Link Operations (5)

12. get_backlinks
13. get_outlinks
14. get_graph
15. find_broken_links
16. update_links

E.5 Tag Operations (4)

17. get_all_tags
18. add_tags
19. remove_tags
20. rename_tag

E.6 Frontmatter Operations (3)

21. get_frontmatter
22. update_frontmatter
23. bulk_update_frontmatter

E.7 Git Operations (5)

24. git_status
25. git_commit
26. git_pull
27. git_push
28. git_history

E.8 Vault Operations (5)

29. get_vault_stats
30. find_orphaned_notes
31. get_most_linked

E.9 Template Operations (3)

32. create_from_template
33. list_templates

E.10 Daily Notes (3)

34. get_daily_note
35. create_daily_note
36. append_to_daily_note

E.11 Batch Operations (3)

37. batch_operation

E.12 Analytics (2)

38. get_note_stats

Total: 38 Core Tools (expandable to 45+ with variants)

---

Appendix F: Development Guidelines

F.1 Code Style

General Principles:

• Follow Go idioms and conventions
• Use meaningful variable names
• Keep functions small and focused
• Write self-documenting code
• Add comments for complex logic

Naming Conventions:

• Interfaces: XxxRepository, XxxIndex
• Implementations: XxxRepositoryImpl
• Use Cases: XxxUseCase
• DTOs: XxxDTO
• Errors: ErrXxx

Package Organization:

• One concept per package
• Avoid circular dependencies
• Keep packages small and cohesive

F.2 Testing Guidelines

Test Structure:

• Arrange-Act-Assert pattern
• Use table-driven tests
• Mock external dependencies
• Test error paths

Test Naming:

• TestXxx_Yyy for methods
• TestXxx_Yyy_Error for error cases
• Descriptive test case names

Coverage:

• All public functions must have tests
• Test edge cases and error paths
• Integration tests for critical paths

F.3 Git Commit Messages

Format:

<type>(<scope>): <subject>

<body>

<footer>

Types:

• feat: New feature
• fix: Bug fix
• docs: Documentation
• refactor: Code refactoring
• test: Tests
• chore: Maintenance

Examples:

feat(domain): add Note entity with validation

Implements Note entity with path, content, and metadata.
Includes validation for path format and content.

Closes #123

F.4 Pull Request Process

Requirements:

• All tests pass
• Code coverage > 80%
• Linter passes
• Documentation updated
• CHANGELOG updated

Review Checklist:

• Code follows guidelines
• Tests are comprehensive
• No unnecessary complexity
• Error handling is correct
• Performance considered

---

Appendix G: Troubleshooting Guide

G.1 Common Issues

Issue: Git pull fails

• Check network connectivity
• Verify git credentials
• Check remote repository access
• Solution: Configure SSH keys or HTTPS credentials

Issue: Note not found

• Verify vault path is correct
• Check file exists in filesystem
• Verify path is relative to vault root
• Solution: Use absolute path or check vault configuration

Issue: Parse error

• Check frontmatter YAML syntax
• Verify markdown is valid
• Check for special characters
• Solution: Validate markdown with external tool

Issue: Out of memory

• Check vault size
• Verify index size
• Monitor memory usage
• Solution: Increase memory limit or reduce cache size

Issue: Slow search

• Check index status
• Verify vault size
• Monitor query complexity
• Solution: Rebuild index or optimize query

G.2 Debug Mode

Enable debug logging:

OBSIDIAN_MCP_LOG_LEVEL=debug obsidian-mcp

Enable profiling:

OBSIDIAN_MCP_PROFILE=true obsidian-mcp
# Access: http://localhost:6060/debug/pprof/

Verbose git operations:

git:
  verbose: true

G.3 Health Checks

Check vault accessibility:

obsidian-mcp --health

Check git status:

obsidian-mcp --git-status

Check index status:

obsidian-mcp --index-status

---

Appendix H: Glossary

Terms:

• MCP (Model Context Protocol): Open protocol for connecting AI to data sources
• Obsidian: Markdown-based note-taking application
• Vault: Obsidian's term for a collection of notes
• WikiLink: Internal link format [[Note Name]]
• Frontmatter: YAML metadata at top of markdown file
• Backlink: Link pointing to a note from another note
• Outlink: Link from a note to another note
• Graph: Network of interconnected notes
• Use Case: Single unit of business logic
• Repository: Interface for data persistence
• Entity: Domain object with identity
• Value Object: Domain object without identity
• DTO: Data Transfer Object for API layer

Acronyms:

• CRUD: Create, Read, Update, Delete
• API: Application Programming Interface
• SDK: Software Development Kit
• CLI: Command Line Interface
• CI/CD: Continuous Integration/Continuous Deployment
• TDD: Test-Driven Development
• DDD: Domain-Driven Design
• VO: Value Object
• UC: Use Case
• E2E: End-to-End

---

Document Metadata

Document Version: 1.0.0
Last Updated: 2025-10-07
Status: Complete - Ready for Implementation
Review Status: Draft - Awaiting Technical Review

Authors:

• Architecture Team
• Technical Lead

Reviewers:

• Technical Lead
• Senior Developer
• Security Team
• DevOps Team

Approvals:

• Project Manager
• Technical Lead
• Product Owner

Change Log:

• 2025-10-07: Initial document creation

Related Documents:

• API Specification (to be created)
• Architecture Decision Records (to be created)
• User Guide (to be created)

---

Implementation Checklist

Phase 1: Foundation ✅

• Domain entities (Note, Vault, Tag, WikiLink, Frontmatter)
• Repository interfaces
• Domain unit tests (90%+ coverage)
• Project structure setup
• CI/CD pipeline

Phase 2: Core Functionality ✅

• Filesystem repository
• Git repository
• Markdown parser (goldmark)
• Search index
• Graph index
• Tag index
• All use cases (30+)
• Integration tests

Phase 3: MCP Integration ✅

• MCP server setup
• 45+ MCP tools
• MCP resources
• MCP prompts
• E2E tests
• Performance benchmarks

Phase 4: Release ✅

• Documentation
• Binary builds
• Docker image
• Example configs
• GitHub release

---

End of Design Document

This document provides complete specifications for the Obsidian MCP Server implementation. All development should follow the architecture, patterns, and guidelines defined herein.

For questions or clarifications, contact the architecture team.