LifeOS MCP Server

Last updated: 2025-11-05

A Model Context Protocol (MCP) server for managing the LifeOS Obsidian vault. Provides AI assistants with structured access to create, read, and search notes while maintaining YAML compliance and organizational standards.

Features

• YAML-Compliant Note Creation: Automatically follows LifeOS YAML rules
• Custom YAML Rules Integration: Reference your own YAML frontmatter guidelines
• PARA Method Organization: Respects Projects/Areas/Resources/Archives structure
• Template System: Integration with 11+ LifeOS templates (restaurant, article, person, etc.)
• Search Engine: Full-text search with relevance scoring and context extraction
• Obsidian Integration: Clickable links that open notes directly in Obsidian
• Daily Notes Management: Create and manage daily journal entries
• Analytics Dashboard: Telemetry with visual insights (⚠️ currently buggy, not recommended for use)
• Universal Tools: Consolidates 6 search tools into 1, with auto-routing
• iCloud Sync Resilience: Automatic retry logic for file operations on macOS
• Backward Compatibility: All 11 legacy tool aliases continue to work with deprecation warnings via dedicated handler module (MCP-97) and hybrid dispatch fallback

Platform Support

✅ Supported Platforms:

• macOS - Primary development platform
• Linux - Full support (production deployments)
• WSL2 - Windows users via Unix subsystem

MCP Client Compatibility:

• Claude Desktop (macOS, Linux, Windows via WSL2)
• Cursor IDE (macOS, Linux, Windows via WSL2)
• Raycast (macOS only)
• Custom MCP clients on Unix systems

❌ Not Supported:

• Native Windows (cmd.exe, PowerShell)

Windows Users: This project officially supports Unix-only platforms. For Windows compatibility, install WSL2 for a full Unix environment. All features work seamlessly in WSL2. See WSL2 Setup Guide for detailed installation instructions.

Rationale: See ADR-007: Unix-Only Platform Support for the full decision context.

Quick Start

Automated Setup (Recommended)

# Clone and run automated setup
git clone https://github.com/shayonpal/mcp-for-lifeos.git
cd mcp-for-lifeos
chmod +x scripts/setup.sh
./scripts/setup.sh

The setup script will install dependencies, generate configuration, and build the application.

Manual Installation

npm install
npm run build

📖 For detailed deployment instructions, see Deployment Guide

Configuration

1. Copy src/config.example.ts to src/config.ts
2. Update the vault paths to match your Obsidian vault location
3. Customize the PEOPLE_MAPPINGS for your specific contacts
4. Optional: Set yamlRulesPath to reference your YAML frontmatter guidelines

export const LIFEOS_CONFIG: LifeOSConfig = {
  vaultPath: '/path/to/your/obsidian/vault',
  templatesPath: '/path/to/your/obsidian/vault/Templates',
  yamlRulesPath: '/path/to/your/vault/YAML Rules.md', // Optional
  // ... other paths
};

Tool Mode Configuration

Control which MCP tools are registered using the TOOL_MODE environment variable:

• consolidated-only (default): Only modern consolidated tools (13 tools) - clean, focused tool list
• consolidated-with-aliases: Both consolidated and legacy tools (24 tools) - maximum compatibility
• legacy-only: Only legacy tools (21 tools) - for legacy integrations

Default behavior (no configuration needed):

• ✅ Modern consolidated tools (search, create_note, list)
• ✅ Core utilities (10 always-available tools)
• ❌ Legacy tool aliases hidden

Tool Name Change (MCP-60):

• create_note_smart has been renamed to create_note (smart functionality is now default)
• Legacy create_note_smart alias available in consolidated-with-aliases mode

To restore legacy tools, set in your MCP client configuration:

{
  "mcpServers": {
    "lifeos": {
      "command": "node",
      "args": ["/path/to/build/index.js"],
      "env": {
        "VAULT_PATH": "/path/to/vault",
        "TOOL_MODE": "consolidated-with-aliases"
      }
    }
  }
}

📖 For complete configuration options, see Configuration Guide

Available Tools

Recommended: Consolidated Tools

search - Universal search with auto-routing for all search operations

• Supports modes: auto, advanced, quick, content_type, recent, pattern
• Natural language queries (e.g., "Quebec barbecue restaurants")
• Automatic token budget management

create_note - Smart note creation with automatic template detection

• Auto-detects templates from title/content
• Handles YAML validation and folder placement

list - Universal listing for folders, daily notes, templates, YAML properties

• Auto-detection of list type
• Supports concise and detailed formats

Core Operations

Note Management:

• create_note - Create notes with YAML frontmatter and templates
• read_note - Read existing notes
• edit_note - Edit notes with frontmatter merging
• get_daily_note - Get or create daily notes
• move_items - Move notes and folders
• rename_note - Atomic note renaming with vault-wide link updates, dry-run preview, and crash recovery
• insert_content - Insert content at specific locations

Utilities:

• diagnose_vault - Diagnose vault issues
• get_server_version - Get server version and capabilities
• get_yaml_rules - Retrieve custom YAML rules

Search:

• advanced_search - Full-text search with metadata filters
• list_yaml_properties - Discover YAML properties
• list_yaml_property_values - Analyze property values

📖 For complete tools documentation, see Tools API Reference

Client Integration

Claude Desktop

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "lifeos": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-for-lifeos/dist/src/index.js"],
      "env": {
        "ENABLE_WEB_INTERFACE": "false"
      }
    }
  }
}

Raycast

Use @lifeos-mcp to mention the server in AI chats and commands for quick vault search and note creation.

Cursor IDE

Access vault context directly in Agent Mode to research existing knowledge while coding.

📖 For complete integration guides, see Integrations Guide

Template System

The server includes intelligent template integration with 11+ templates:

• restaurant, article, person, daily, reference
• medicine, application, book, place, fleeting, moc

Templates automatically process Templater syntax and place notes in correct PARA folders.

# Auto-detect template from title
create_note title: "Pizza Palace"  # → restaurant template

# Explicit template
create_note title: "My Article" template: "article"

📖 For template system details, see Templates Guide

Analytics Dashboard

⚠️ IMPORTANT: The analytics dashboard is currently buggy and should not be used.

The analytics system has known issues affecting data collection and visualization. Work is underway to fix these issues. Until then, we recommend disabling analytics:

{
  "mcpServers": {
    "lifeos": {
      "env": {
        "DISABLE_USAGE_ANALYTICS": "true"
      }
    }
  }
}

Status: Analytics collection and dashboard temporarily unreliable. Use with caution or disable entirely.

📊 For complete analytics documentation, see analytics/README.md

Documentation

Guides

• 📖 Deployment Guide - Complete setup and deployment instructions
• ⚙️ Configuration Guide - Detailed configuration options
• 🔧 Templates Guide - Template system and customization
• 🔌 Integrations Guide - Client integration (Claude Desktop, Raycast, Cursor)
• 🐛 Troubleshooting Guide - Common issues and solutions
• 📱 Raycast Integration - Raycast-specific setup
• 💻 Cursor Integration - Cursor IDE-specific setup

API Reference

• 🔧 Tools API Reference - Complete tool documentation with parameters and examples

Analytics

• 📊 Analytics Dashboard - Analytics configuration and insights

Development

# Development mode with auto-reload
npm run dev

# Build for production
npm run build

# Run tests
npm test

# Type checking
npm run typecheck

Testing

# All tests
npm test

# Unit tests only
npm run test:unit

# Integration tests only
npm run test:integration

Versioning

The server follows semantic versioning (MAJOR.MINOR.PATCH):

• MAJOR: Incompatible API changes
• MINOR: New functionality (backward compatible)
• PATCH: Bug fixes (backward compatible)

All API responses include version metadata for compatibility checking.

YAML Compliance

The server automatically enforces LifeOS YAML rules:

• Uses source field for URLs (not url or URL)
• Maintains location format: Country [CODE] (e.g., Canada [CA])
• Never edits auto-managed fields (date created, date modified)
• Validates YAML syntax and provides error reporting
• Supports flexible tag formats: string, array, or YAML list

File Naming Convention

Notes use natural file naming that preserves readability:

• Preserves: Spaces, punctuation, numbers, parentheses
• Removes: Square brackets [], colons :, semicolons ;
• Example: "Book Review - The 48 Laws of Power" → "Book Review - The 48 Laws of Power.md"

Support and Contributing

• 🐛 Issues: Report bugs and request features via GitHub Issues
• 💬 Discussions: Join community discussions in the repository
• 📖 Documentation: Check docs/ for guides and references

License

This project is licensed under the GNU General Public License v3.0. See LICENSE.md for details.

Copyright (C) 2025 Shayon Pal
AgileCode Studio - https://agilecode.studio