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](#1-executive-summary)
2. [System Overview](#2-system-overview)
3. [Architecture](#3-architecture)
4. [Domain Model](#4-domain-model)
5. [Use Cases](#5-use-cases)
6. [API Specification](#6-api-specification)
7. [Data Model](#7-data-model)
8. [Infrastructure Design](#8-infrastructure-design)
9. [Security & Performance](#9-security--performance)
10. [Testing Strategy](#10-testing-strategy)
11. [Deployment](#11-deployment)
12. [Implementation Roadmap](#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

```mermaid
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

```mermaid
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

```mermaid
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

```mermaid
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

```mermaid
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) interface{}
        +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

```mermaid
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

```mermaid
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:**
```json
{
  "path": "string (required)",
  "format": "markdown|json (default: json)"
}
```

**Output Schema:**
```json
{
  "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:**
```json
{
  "path": "string (required)",
  "content": "string",
  "frontmatter": "object",
  "create_dirs": "boolean (default: true)"
}
```

**Output:** Created note object

#### `update_note`

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

#### `delete_note`

**Input Schema:**
```json
{
  "path": "string (required)",
  "confirm": "boolean (default: false)"
}
```

#### `rename_note`

**Input Schema:**
```json
{
  "old_path": "string (required)",
  "new_path": "string (required)",
  "update_links": "boolean (default: true)"
}
```

### 6.3 Search Operations

#### `search_content`

**Input Schema:**
```json
{
  "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:**
```json
{
  "results": [
    {
      "path": "string",
      "matches": [
        {
          "line": "number",
          "content": "string",
          "context_before": "string",
          "context_after": "string"
        }
      ],
      "score": "number"
    }
  ],
  "total": "number"
}
```

#### `search_by_tags`

**Input Schema:**
```json
{
  "tags": ["string"],
  "mode": "all|any (default: any)",
  "include_nested": "boolean (default: true)"
}
```

#### `search_by_frontmatter`

**Input Schema:**
```json
{
  "filters": "object",
  "operator": "and|or (default: and)"
}
```

### 6.4 Link Operations

#### `get_backlinks`

**Input Schema:**
```json
{
  "path": "string (required)",
  "include_context": "boolean (default: true)"
}
```

**Output Schema:**
```json
{
  "note": "string",
  "backlinks": [
    {
      "from": "string",
      "context": "string",
      "line": "number"
    }
  ],
  "count": "number"
}
```

#### `get_outlinks`

**Input Schema:**
```json
{
  "path": "string (required)",
  "resolve": "boolean (default: true)"
}
```

#### `get_graph`

**Input Schema:**
```json
{
  "path": "string (required)",
  "depth": "number (default: 1)",
  "max_nodes": "number (default: 100)"
}
```

**Output Schema:**
```json
{
  "nodes": [{"path": "string", "title": "string"}],
  "edges": [{"from": "string", "to": "string"}]
}
```

#### `find_broken_links`

**Input Schema:**
```json
{
  "path": "string (optional, check specific note or entire vault)"
}
```

#### `update_links`

**Input Schema:**
```json
{
  "old_path": "string (required)",
  "new_path": "string (required)",
  "dry_run": "boolean (default: false)"
}
```

### 6.5 Tag Operations

#### `get_all_tags`

**Input Schema:**
```json
{
  "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:**
```json
{
  "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

```mermaid
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

```mermaid
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

```mermaid
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

```mermaid
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

```mermaid
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

```mermaid
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):**
```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

```mermaid
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

```yaml
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:**
```bash
OBSIDIAN_MCP_LOG_LEVEL=debug obsidian-mcp
```

**Enable profiling:**
```bash
OBSIDIAN_MCP_PROFILE=true obsidian-mcp
# Access: http://localhost:6060/debug/pprof/
```

**Verbose git operations:**
```yaml
git:
  verbose: true
```

### G.3 Health Checks

**Check vault accessibility:**
```bash
obsidian-mcp --health
```

**Check git status:**
```bash
obsidian-mcp --git-status
```

**Check index status:**
```bash
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.