mcp-apple-obsidian: Instructions file for Codex

MCP Apple Obsidian - Agent Guide

Project Overview

This is a comprehensive MCP server for Obsidian on macOS that provides:

• File system access to vaults and notes
• AppleScript integration for app control
• URI scheme support for native Obsidian actions
• Frontmatter/properties CRUD operations
• Tag management across notes and vaults
• Task management with Obsidian-compatible syntax

Architecture

src/mcp_apple_obsidian/
├── __init__.py      # Package entry point
├── server.py        # FastMCP server with 42 tools
├── config.py        # Configuration management
├── applescript.py   # AppleScript interface
├── uri_handler.py   # Obsidian URI scheme handler
└── vault_fs.py      # File system operations for vaults
                    # + Frontmatter/Tag/Task operations

Key Design Principles

1. Three-Layer Access: Always prefer file system > AppleScript > URI for reliability
2. Backup Safety: All write operations support automatic backups
3. Async Everything: All I/O operations are async for performance
4. Graceful Degradation: Works even when Obsidian isn't running
5. No stdout pollution: Use stderr for logging (critical for stdio transport)
6. YAML-aware: Frontmatter uses YAML for type preservation
7. Tag Flexibility: Supports both inline (#tag) and frontmatter tags
8. Task Compatibility: Tasks use Obsidian-compatible syntax

Adding New Tools

When adding tools to server.py:

1. Import any needed modules at the top
2. Use @mcp.tool() decorator
3. Use descriptive docstrings (these become tool descriptions)
4. Return strings (preferably JSON for structured data)
5. Catch exceptions and return error messages
6. Log errors to stderr

Example:

@mcp.tool()
async def my_new_tool(vault: str, param: str) -> str:
    """Clear description of what the tool does.
    
    Args:
        vault: Name or path of the vault
        param: Description of parameter
        
    Returns:
        Description of return value
    """
    try:
        result = await do_something(vault, param)
        return json.dumps(result, indent=2)
    except Exception as e:
        logger.error(f"Error in my_new_tool: {e}")
        return f"Error: {e}"