# Create a top-level folder
add_folder {
  "name": "Work Projects"
}

# Create a nested folder (by name or ID)
add_folder {
  "name": "Q1 2025",
  "parentFolderName": "Work Projects"
}

add_folder {
  "name": "Marketing",
  "parentFolderId": "folderId123"
}

# Create a project in a folder (by name or ID)
add_project {
  "name": "New Website",
  "folderName": "Work Projects"
}

add_project {
  "name": "Mobile App",
  "folderId": "folderId123"
}

# Inbox perspective
get_inbox_tasks {"hideCompleted": true}

# Flagged tasks (filter by project name or ID)
get_flagged_tasks {"projectFilter": "SEO Project"}
get_flagged_tasks {"projectId": "abc123xyz"}

# Forecast (next 7 days)
get_forecast_tasks {"days": 7, "hideCompleted": true}

# Tasks by tag name (single or multiple)
get_tasks_by_tag {"tagName": "AI", "exactMatch": false}
get_tasks_by_tag {"tagName": ["work", "urgent", "focus"]}

# Tasks by tag ID (single or multiple)
get_tasks_by_tag {"tagId": "tagId123"}
get_tasks_by_tag {"tagId": ["tagId1", "tagId2"]}

# Tasks by multiple tags (AND - all of these tags)
get_tasks_by_tag {"tagName": ["home", "errands"], "tagMatchMode": "all"}

# Include dropped/inactive tags in search
get_tasks_by_tag {"tagId": "droppedTagId", "includeDropped": true}

# List all tags (fast - ~400ms)
list_tags {}

# List all tags with task counts (slower - ~15s)
list_tags {"showTaskCounts": true}

# Include dropped/inactive tags
list_tags {"includeDropped": true}

# Time management view (30min tasks due this week)
filter_tasks {
  "taskStatus": ["Available", "Next"],
  "estimateMax": 30,
  "dueThisWeek": true
}

# Deep work view (60+ minute tasks with notes)
filter_tasks {
  "estimateMin": 60,
  "hasNote": true,
  "taskStatus": ["Available"]
}

# Project overdue tasks (filter by name or ID)
filter_tasks {
  "projectFilter": "Website Redesign",
  "taskStatus": ["Overdue", "DueSoon"]
}

# Find untagged tasks (useful after bulk tag cleanup)
filter_tasks {
  "untagged": true,
  "taskStatus": ["Available", "Next"]
}

# Filter by project ID and tag ID (for programmatic use)
filter_tasks {
  "projectId": "projectId123",
  "tagId": ["tagId1", "tagId2"],
  "taskStatus": ["Available"]
}

# Daily repeating task
add_omnifocus_task {
  "name": "Daily standup notes",
  "projectName": "Work",
  "dueDate": "2025-01-15",
  "repetitionRule": {
    "frequency": "daily"
  }
}

# Weekly task on Mon/Wed/Fri
add_omnifocus_task {
  "name": "Exercise",
  "dueDate": "2025-01-15",
  "repetitionRule": {
    "frequency": "weekly",
    "daysOfWeek": [1, 3, 5]
  }
}

# Monthly task on the 15th, repeat from completion
add_omnifocus_task {
  "name": "Pay bills",
  "dueDate": "2025-01-15",
  "repetitionRule": {
    "frequency": "monthly",
    "dayOfMonth": 15,
    "repeatFrom": "completion"
  }
}

# First Monday of every month (weekday-of-month pattern)
add_omnifocus_task {
  "name": "Prepare for monthly HOA meeting",
  "dueDate": "2026-02-02",
  "repetitionRule": {
    "frequency": "monthly",
    "weekdayOfMonth": {
      "week": 1,
      "day": 1
    },
    "repeatFrom": "due"
  }
}

# Last Friday of every month
add_omnifocus_task {
  "name": "Monthly expense report",
  "dueDate": "2026-01-31",
  "repetitionRule": {
    "frequency": "monthly",
    "weekdayOfMonth": {
      "week": -1,
      "day": 5
    }
  }
}

# Third Wednesday of every 2 months
add_omnifocus_task {
  "name": "Quarterly planning prep",
  "dueDate": "2026-01-21",
  "repetitionRule": {
    "frequency": "monthly",
    "interval": 2,
    "weekdayOfMonth": {
      "week": 3,
      "day": 3
    }
  }
}

# Edit task to add/remove repetition
edit_item {
  "id": "taskId123",
  "itemType": "task",
  "newRepetitionRule": {"frequency": "weekly", "interval": 2}
}

# Remove repetition from a task
edit_item {
  "id": "taskId123",
  "itemType": "task",
  "newRepetitionRule": null
}

# Move a task to a different project (by ID)
edit_item {
  "id": "taskId123",
  "itemType": "task",
  "newProjectId": "projectId456"
}

# Move a project to a different folder (by ID)
edit_item {
  "id": "projectId123",
  "itemType": "project",
  "newFolderId": "folderId456"
}

# List all your custom perspectives
list_custom_perspectives {"format": "detailed"}

# Get tasks from custom perspective by name
get_custom_perspective_tasks {
  "perspectiveName": "Today's Work",  # Your custom perspective name
  "showHierarchy": true,              # Enable tree display
  "hideCompleted": true,
  "ignoreFocus": true                 # Clear Focus mode to see all tasks (default: true)
}

# Get tasks from custom perspective by ID
get_custom_perspective_tasks {
  "perspectiveId": "perspectiveId123",
  "showHierarchy": true
}

# Examples with different perspectives
get_custom_perspective_tasks {
  "perspectiveName": "Today Review",
  "showHierarchy": true
}

get_custom_perspective_tasks {
  "perspectiveName": "Weekly Planning",
  "showHierarchy": false  # Flat display
}

# Example output (flat view):
# 1. **Review quarterly goals** [ID: j-Q4cm6ewVF]
#    Tags: planning
#    Due: 1/31/2025

# Example output (hierarchical view):
# ├─ **Launch Product Campaign**
# │  ID: abc123xyz
# │  Tags: Campaign, Priority
# │  Due: 2/15/2025

# Get tasks from multiple projects at once
batch_filter_tasks {
  "projectNames": ["Website Redesign", "Marketing Campaign", "Q1 Planning"],
  "taskStatus": ["Available", "Next", "Blocked"],
  "limit": 50
}

# Filter by project IDs for reliability
batch_filter_tasks {
  "projectIds": ["projectId1", "projectId2", "projectId3"],
  "taskStatus": ["Available", "Overdue"],
  "flagged": true
}

# Combine with due date filters
batch_filter_tasks {
  "projectNames": ["Daily Tasks", "Weekly Review"],
  "dueThisWeek": true,
  "sortBy": "dueDate"
}

# Batch add multiple tasks/projects (by name or ID)
batch_add_items {
  "items": [
    {
      "type": "task",
      "name": "Website Technical SEO",
      "projectName": "SEO Project",  # or use projectId
      "note": "Optimize technical aspects"
    },
    {
      "type": "task",
      "name": "Page Speed Optimization",
      "parentTaskName": "Website Technical SEO",  # or use parentTaskId
      "estimatedMinutes": 180,
      "flagged": true
    },
    {
      "type": "project",
      "name": "New Project",
      "folderId": "folderId123"  # or use folderName
    }
  ]
}

# Batch edit multiple items
batch_edit_items {
  "edits": [
    {
      "id": "taskId1",
      "itemType": "task",
      "newStatus": "completed"
    },
    {
      "id": "taskId2",
      "itemType": "task",
      "newDueDate": "2025-02-01",
      "newFlagged": true,
      "newProjectId": "projectId123"  # Move task to another project by ID
    },
    {
      "id": "projectId1",
      "itemType": "project",
      "newNote": "Updated via batch edit",
      "newFolderName": "Work Projects"  # Move project to another folder by name
    }
  ]
}

# Batch update tags (works on both tasks AND projects, auto-creates missing tags)
batch_edit_items {
  "edits": [
    {
      "id": "taskId1",
      "itemType": "task",
      "addTags": ["urgent", "review"],
      "removeTags": ["someday"]
    },
    {
      "id": "projectId1",
      "itemType": "project",
      "addTags": ["Q1", "active"]
    },
    {
      "id": "taskId2",
      "itemType": "task",
      "replaceTags": ["priority", "work"]
    }
  ]
}

# Batch remove multiple items
batch_remove_items {
  "items": [
    {"id": "taskId1", "itemType": "task"},
    {"id": "taskId2", "itemType": "task"},
    {"name": "Old Project", "itemType": "project"}
  ]
}

# Get all projects due for review
get_projects_for_review {
  "includeOnHold": false,
  "limit": 50
}

# Mark a single project as reviewed
edit_item {
  "id": "projectId123",
  "itemType": "project",
  "markReviewed": true
}

# Set a project's review interval to 14 days
edit_item {
  "id": "projectId123",
  "itemType": "project",
  "newReviewInterval": 14
}

# Batch mark multiple projects as reviewed (by ID)
batch_mark_reviewed {
  "projectIds": ["projectId1", "projectId2", "projectId3"]
}

# Batch mark by project names
batch_mark_reviewed {
  "projectNames": ["Marketing Campaign", "Website Redesign"]
}

# View project review info
get_project_by_id {
  "projectName": "My Project"
}
# Returns: reviewInterval, nextReviewDate, lastReviewDate

# Simple task
add_omnifocus_task {
  "name": "Review quarterly goals",
  "projectName": "Planning",
  "dueDate": "2025-01-31"
}

# Create parent task
add_omnifocus_task {
  "name": "Launch Product Campaign",
  "projectName": "Marketing",
  "dueDate": "2025-02-15",
  "tags": ["Campaign", "Priority"]
}

# Add subtasks
add_omnifocus_task {
  "name": "Design landing page",
  "parentTaskName": "Launch Product Campaign",
  "estimatedMinutes": 240,
  "flagged": true
}

# Find high-priority work
filter_tasks {
  "flagged": true,
  "taskStatus": ["Available"],
  "estimateMax": 120,
  "hasEstimate": true
}

# Today's completed work
filter_tasks {
  "completedToday": true,
  "taskStatus": ["Completed"],
  "sortBy": "project"
}

# List your custom perspectives
list_custom_perspectives {"format": "detailed"}

# Access a custom perspective with hierarchy
get_custom_perspective_tasks {
  "perspectiveName": "Today Review",
  "showHierarchy": true,
  "hideCompleted": true
}

# Quick flat view of weekly planning
get_custom_perspective_tasks {
  "perspectiveName": "Weekly Planning",
  "showHierarchy": false
}

# Simple text search across names and notes
search_tasks {
  "query": "budget report"
}

# Search with match modes
search_tasks {
  "query": "meeting budget",
  "matchMode": "anyWord"  # matches either "meeting" or "budget"
}

search_tasks {
  "query": "quarterly review",
  "matchMode": "allWords",  # must contain both words
  "includeCompleted": true
}

# Search within a specific project
search_tasks {
  "query": "design",
  "projectName": "Website Redesign",
  "searchIn": "name"  # only search task names, not notes
}

# Create a copy of a template project
duplicate_project {
  "sourceProjectName": "Sprint Template",
  "newName": "Sprint 15"
}

# Duplicate with date shifting (great for recurring workflows)
duplicate_project {
  "sourceProjectName": "Weekly Review Checklist",
  "newName": "Week 3 Review",
  "shiftDates": {
    "referenceDate": "2026-01-20",
    "basedOn": "defer"
  }
}

# Duplicate into a specific folder
duplicate_project {
  "sourceProjectId": "templateProjectId123",
  "newName": "Q1 Marketing Campaign",
  "folderName": "2026 Projects",
  "clearCompleted": true,
  "copyTags": true
}

# Reactivate a dropped tag
edit_tag {
  "tagName": "prep",
  "newStatus": "active"
}

# Put a tag on hold (tasks with this tag become blocked)
edit_tag {
  "tagName": "office",
  "newStatus": "onHold"
}

# Rename a tag
edit_tag {
  "tagId": "tagId123",
  "newName": "high-priority"
}

# Move tag to a different parent
edit_tag {
  "tagName": "errands",
  "newParentTagName": "personal"
}

# Make a tag top-level (remove from parent)
edit_tag {
  "tagName": "urgent",
  "newParentTagId": ""
}

# ❌ Inefficient - 5 API calls
filter_tasks { "projectFilter": "Project A", "taskStatus": [...] }
filter_tasks { "projectFilter": "Project B", "taskStatus": [...] }
filter_tasks { "projectFilter": "Project C", "taskStatus": [...] }
# ... etc

# ✅ Efficient - 1 API call
batch_filter_tasks {
  "projectNames": ["Project A", "Project B", "Project C", "Project D", "Project E"],
  "taskStatus": ["Available", "Next", "Blocked", "DueSoon", "Overdue"],
  "limit": 100
}

# Check MCP status
claude mcp list

# Verify server version
get_server_version

# Test basic connection
get_inbox_tasks

# Test custom perspective features
list_custom_perspectives

# Get all health metrics in ONE call (replaces 6+ separate calls)
get_system_health

# Get completion stats by project for last month
get_completion_stats {
  "completedAfter": "2026-01-01",
  "completedBefore": "2026-02-01",
  "groupBy": "project"
}

# Get completion stats by tag
get_completion_stats {
  "completedAfter": "2026-01-01",
  "completedBefore": "2026-02-01",
  "groupBy": "tag"
}

# Fast count-only query (no task data returned)
filter_tasks {
  "taskStatus": ["Available", "Next"],
  "countOnly": true
}