# Obsidian Family Hub MCP Server - Design Document
**Version:** 1.0
**Date:** 2025-06-22
**Author:** Design Team
## 1. Architecture Overview
### System Architecture
```
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ MCP Client │────│ Obsidian Nexus │────│ Obsidian Vault │
│ (Claude Code) │ │ MCP Server │ │ File System │
└─────────────────┘ └──────────────────┘ └─────────────────┘
│
┌──────────────┐
│ LLM Provider │
│ (Anthropic) │
└──────────────┘
```
### Core Components
1. **MCP Server Layer**: Handles MCP protocol communication
2. **Entity Processor**: "Sense" stage - extracts entities and determines actions
3. **Action Dispatcher**: "Sort" stage - executes Chronicle Logging or Thematic Synthesis
4. **Vault Manager**: File system operations with atomic writes
5. **LLM Interface**: Abstracted LLM calls with error handling
## 2. File System Structure
### Obsidian Vault Layout
```
FamilyVault/
├── config/
│ └── obsidian-nexus.yaml
├── Daily Notes/
│ └── 2025-06-22.md
├── Family/
│ ├── Leo.md
│ ├── Mia.md
│ └── Chloe.md
├── Themes/
│ ├── Leo-Medical.md
│ ├── Mia-Allergy.md
│ └── School-Reports.md
├── inbox/
│ ├── processed/
│ └── failed/
└── .obsidian/
└── (Obsidian configuration)
```
### File Templates
#### Daily Note Template
```markdown
# {{date}}
## Family Log
- {{timestamp}} | {{person}} | {{summary}}
## Quick Actions
- [ ] {{action_items}}
---
*Generated by Obsidian Nexus*
```
#### Person Note Template
```markdown
# {{person}}
## Recent Activity
- {{timestamp}} | {{summary}}
## Active Themes
- [[{{theme_note_name}}]]
---
*Last updated: {{timestamp}}*
```
#### Theme Note Template
```markdown
# {{theme_title}}
## Summary
{{llm_generated_summary}}
## Timeline
- {{timestamp}} | {{entry}}
## Related
- [[{{person}}]]
---
*Theme identified: {{created_date}}*
```
## 3. Data Flow Architecture
### Primary Flow: textDocument/ingest
```mermaid
graph TD
A[Raw Content Input] --> B[Entity Extraction LLM]
B --> C{Contains Theme Keywords?}
C -->|No| D[Chronicle Logging]
C -->|Yes| E[Thematic Synthesis]
D --> F[Update Daily Note]
D --> G[Update Person Note]
E --> H[Find/Create Theme Note]
E --> I[LLM Integration]
I --> J[Update Theme Note]
F --> K[Return Success Response]
G --> K
J --> K
```
### Error Handling Flow
```mermaid
graph TD
A[Processing Error] --> B{Error Type}
B -->|LLM Error| C[Save to inbox/failed/]
B -->|File Error| D[Retry with Backup]
B -->|Config Error| E[Log Error & Exit]
C --> F[Include Error Details]
D --> G{Retry Success?}
G -->|No| C
G -->|Yes| H[Continue Processing]
```
## 4. Entity Extraction Logic
### Stage 1: Sense (Entity Extraction)
**LLM Prompt Template:**
```
Analyze the following text and extract:
1. People mentioned (from: Nick, Sarah, Leo, Mia, Chloe)
2. Theme keywords (from: doctor, dentist, appointment, teacher, school report, allergy, invoice, medical)
3. Dates and times
4. Action items
5. Summary (1-2 sentences)
Text: {content}
Respond in JSON format:
{
"people": ["person1", "person2"],
"themes": ["theme1", "theme2"],
"dates": ["2025-06-22"],
"actions": ["action1"],
"summary": "Brief summary of content"
}
```
### Stage 2: Sort (Action Dispatcher)
**Decision Matrix:**
| Condition | Action | Target Files |
|-----------|--------|--------------|
| No themes detected | Chronicle Logging | Daily Note + Person Notes |
| Themes detected | Thematic Synthesis | Theme Note + Person Notes |
| Processing error | Failsafe Storage | inbox/failed/ |
## 5. API Implementation Details
### Tool Specifications
#### 1. textDocument/ingest
```typescript
interface IngestParams {
content: string;
source?: {
type: "email" | "whatsapp" | "manual";
from?: string;
};
}
interface IngestResult {
actions: Array<{
type: "CHRONICLE_LOG" | "THEME_SYNTHESIS";
noteUri: string;
summary: string;
}>;
}
```
#### 2. vault/discoverThemes
```typescript
interface DiscoverThemesParams {
targetUri: string;
}
interface DiscoverThemesResult {
suggestedThemes: Array<{
proposedTitle: string;
summary: string;
supportingExcerpts: string[];
}>;
}
```
#### 3. vault/query
```typescript
interface QueryParams {
query: string;
}
interface QueryResult {
answer: string;
sources: Array<{
noteUri: string;
excerpt: string;
}>;
}
```
## 6. Configuration Management
### Config File Schema (obsidian-nexus.yaml)
```yaml
# Vault configuration
vault_path: "/Users/Nick/Documents/Obsidian/FamilyVault"
# LLM configuration
llm:
provider: "anthropic" # "anthropic" | "openai"
api_key: "${ANTHROPIC_API_KEY}" # Environment variable
model: "claude-3-sonnet-20240229"
max_tokens: 4000
timeout: 30000 # milliseconds
# Entity configuration
entities:
people: ["Nick", "Sarah", "Leo", "Mia", "Chloe"]
theme_keywords:
- "doctor"
- "dentist"
- "appointment"
- "teacher"
- "school report"
- "allergy"
- "invoice"
- "medical"
# File templates
templates:
daily_note: "Daily Notes/{{date}}.md"
person_note: "Family/{{person}}.md"
theme_note: "Themes/{{theme}}.md"
# Performance settings
performance:
max_response_time: 5000 # milliseconds
retry_attempts: 3
backup_enabled: true
```
## 7. Error Handling & Reliability
### Atomic File Operations
1. **Write to temporary file** (.tmp extension)
2. **Verify write success**
3. **Atomic rename** to target file
4. **Cleanup temporary files**
### Failure Modes & Recovery
| Failure Mode | Detection | Recovery Strategy |
|--------------|-----------|-------------------|
| LLM timeout | Response timeout | Save to failed/ with retry flag |
| File locked | File system error | Exponential backoff retry |
| Invalid config | Startup validation | Exit with clear error message |
| Vault not found | Path validation | Create vault structure |
### Backup Strategy
- **Incremental backups** of modified files
- **Failed processing log** with full context
- **Rollback capability** for corrupted files
## 8. Performance Considerations
### Optimization Strategies
1. **LLM Call Batching**: Process multiple inputs in single calls when possible
2. **File Caching**: Keep frequently accessed files in memory
3. **Lazy Loading**: Load configuration and templates on demand
4. **Connection Pooling**: Reuse LLM API connections
### Performance Targets
- **P95 Response Time**: < 5 seconds (including LLM processing)
- **Memory Usage**: < 100MB at idle
- **File I/O**: < 50ms per operation
- **Startup Time**: < 2 seconds
## 9. Security Model
### Local-First Architecture
- **No network listeners** (stdio transport only)
- **Local file system access** restricted to vault path
- **API keys** stored in environment variables
- **No telemetry** or external logging
### Data Protection
- **Read-only vault discovery** (no modification without explicit user action)
- **Input sanitization** for file paths and content
- **Atomic writes** to prevent data corruption
- **Failed processing preservation** (never lose user data)
## 10. Development Phases
### Phase 1: Core Infrastructure (Week 1)
- [ ] MCP server framework
- [ ] Configuration management
- [ ] Basic file operations
- [ ] LLM interface abstraction
### Phase 2: Core Features (Week 2)
- [ ] Entity extraction pipeline
- [ ] Chronicle logging implementation
- [ ] Thematic synthesis implementation
- [ ] Error handling & recovery
### Phase 3: Advanced Features (Week 3)
- [ ] Theme discovery
- [ ] Vault querying
- [ ] Performance optimization
- [ ] Comprehensive testing
### Phase 4: Production Ready (Week 4)
- [ ] Documentation
- [ ] Error monitoring
- [ ] Performance tuning
- [ ] User acceptance testing
## 11. Testing Strategy
### Unit Tests
- Entity extraction accuracy
- File operation atomicity
- Configuration validation
- Error handling coverage
### Integration Tests
- End-to-end ingest workflow
- LLM provider integration
- Vault structure creation
- Multi-user scenarios
### Performance Tests
- Response time under load
- Memory usage profiling
- File system stress tests
- Concurrent operation handling
## 12. Future Considerations
### Extensibility Points
- **Plugin architecture** for custom processors
- **Multiple vault support** for different families
- **Export/import** for vault migration
- **Advanced querying** with vector search
### Monitoring & Observability
- **Processing metrics** (success/failure rates)
- **Performance metrics** (response times, throughput)
- **User behavior analytics** (most used features)
- **Error tracking** with context preservation
---
*This design document serves as the blueprint for implementing the Obsidian Family Hub MCP Server, ensuring alignment with the product specification while providing clear technical guidance for development.*
