omnifocus-mcp

MCP-сервер для OmniFocus, который предоставляет LLM-клиентам полный JavaScript API Omni Automation.

Только macOS. Требуется, чтобы OmniFocus был запущен на той же машине. Вся реализация выполняет сниппеты OmniJS внутри OmniFocus через osascript -l JavaScript — без генерации строк AppleScript, без ограничений словаря сценариев.

Предварительные требования

• macOS (Omni Automation доступен только в macOS; сервер не запустится на других платформах)

• OmniFocus установлен и запущен

• Node.js ≥ 20

Related MCP server: OmniFocus MCP Server

Установка

Пакет опубликован в npm как @scardis/omnifocus-mcp.

Через npx (установка не требуется)

Добавьте в конфигурацию вашего MCP-клиента (например, Claude Desktop claude_desktop_config.json):

{
  "mcpServers": {
    "omnifocus": {
      "command": "npx",
      "args": ["-y", "@scardis/omnifocus-mcp"]
    }
  }
}

Из исходного кода

git clone https://github.com/steveardis/omnifocus-mcp.git
cd omnifocus-mcp
npm install
npm run build

Затем настройте вашего MCP-клиента:

{
  "mcpServers": {
    "omnifocus": {
      "command": "node",
      "args": ["/absolute/path/to/omnifocus-mcp/dist/server.js"]
    }
  }
}

Доступные инструменты

Чтение

Запись

Модель адресации

Каждая сущность, возвращаемая этим сервером, содержит стабильное поле id (id.primaryKey из OmniFocus). Используйте этот ID в последующих вызовах вместо имён. Имена могут быть неоднозначными; ID — нет.

Если у вас есть имя, но нет ID, используйте resolve_name. Он возвращает список — если возвращено несколько кандидатов, просмотрите поле path и попросите пользователя устранить неоднозначность перед выполнением любой операции записи.

Сравнение с другими MCP-серверами для OmniFocus

Существуют две известные альтернативы: themotionmachine/OmniFocus-MCP и jqlts1/omnifocus-mcp-enhanced (форк предыдущего с дополнительными инструментами).

API скриптования. Альтернативы используют словарь сценариев JXA или AppleScript для управления OmniFocus. Этот сервер делает один вызов JXA — Application('OmniFocus').evaluateJavascript() — и выполняет всю логику как OmniJS (Omni Automation) внутри OmniFocus. Это даёт доступ ко всей поверхности API Omni Automation (правила повторения, интервалы проверки, представления, прогноз, вложения, автоматизация URL и т.д.), а не к более ограниченному словарю сценариев.

Внедрение аргументов. Альтернативы формируют команды osascript через строковую интерполяцию, которая может ломаться на апострофах, кавычках, обратных слешах и юникоде в именах. Этот сервер сериализует все аргументы с помощью JSON.stringify в JS-литерал.

Адресация сущностей. Альтернативы адресуют сущности в основном по имени. Этот сервер возвращает стабильный id (id.primaryKey) для каждой сущности и предоставляет resolve_name для сопоставления имени с кандидатами ID — возвращая все совпадения с полными путями, а не молча выбирая одно при неоднозначности имён.

Полный CRUD. Этот сервер поддерживает создание, изменение, завершение, отмену, удаление и перемещение задач, проектов, папок и тегов — а также правила повторения и дату планирования OmniFocus 4.

Разработка

# Type-check without building
npm run typecheck

# Run unit tests (no OmniFocus required)
npm test

# Build
npm run build

Тестирование

Модульные тесты (OmniFocus не требуется)

npm test

Интеграционные тесты

⚠️ Интеграционные тесты работают с вашей реальной базой данных OmniFocus.

Каждый запуск тестов создаёт временную папку верхнего уровня с именем __MCP_TEST_<uuid>__ и удаляет её при завершении. Если запуск тестов был прерван до завершения, выполните скрипт очистки:

npm run test:cleanup-fixtures

⚠️ Предупреждение о синхронизации: По умолчанию интеграционные тесты отказываются запускаться, если включена синхронизация OmniFocus, чтобы тестовые данные не распространялись на другие ваши устройства. Сначала отключите синхронизацию OmniFocus или установите MCP_TEST_ALLOW_SYNC=1, чтобы согласиться (тестовые данные будут синхронизироваться):

# Default (refuses if sync enabled)
npm run test:integration

# With sync enabled (use carefully)
MCP_TEST_ALLOW_SYNC=1 npm run test:integration

Очистка устаревших тестовых данных

npm run test:cleanup-fixtures

Это удаляет все папки __MCP_TEST_*__ и осиротевшие проекты/теги __mcp_*__, оставшиеся в OmniFocus после прерванных запусков тестов.

Участие в разработке

Вклад приветствуется! Вот как начать:

1. Сделайте форк и клонируйте репозиторий

2. Установите зависимости: npm install

3. Запустите модульные тесты (OmniFocus не нужен): npm test

4. Запустите интеграционные тесты (требуются macOS и OmniFocus): npm run test:integration

Перед отправкой PR

• npm run typecheck — должен проходить без ошибок

• npm test — все модульные тесты должны проходить

• npm run test:integration — все интеграционные тесты должны проходить (только macOS)

• Держите изменения сфокусированными — одна функция или исправление на PR

Обзор архитектуры

Сервер выполняет сниппеты OmniJS внутри OmniFocus через osascript -l JavaScript. Каждый инструмент состоит из трёх слоёв:

• Схема (src/schemas/shapes.ts) — схемы Zod для проверки ввода и разбора вывода

• Сниппет (src/snippets/*.js) — код OmniJS, который выполняется внутри OmniFocus. Обычный JavaScript ES5 (без импортов, без TypeScript). Аргументы внедряются через плейсхолдер __ARGS__.

• Обработчик инструмента (src/tools/*.ts) — проверяет ввод, вызывает runSnippet(), разбирает результат

При добавлении нового инструмента:

1. Определите схемы ввода/вывода в src/schemas/shapes.ts и экспортируйте их из src/schemas/index.ts

2. Создайте сниппет OmniJS в src/snippets/

3. Добавьте имя сниппета в ALLOWED_SNIPPETS в src/runtime/snippetLoader.ts

4. Создайте обработчик инструмента в src/tools/ и зарегистрируйте его в src/tools/index.ts

5. Добавьте модульные тесты для схем и интеграционные тесты, которые выполняются с OmniFocus

Написание сниппетов OmniJS

Сниппеты выполняются в JavaScript-среде OmniFocus, а не в Node.js. Ключевые ограничения:

• JavaScript в стиле ES5 — используйте var, function(){}, без стрелочных функций в старых версиях OmniFocus

• Без импортов — все глобальные объекты OmniJS (flattenedTasks, flattenedProjects, moveTasks и т.д.) доступны напрямую

• Возвращайте JSON — всегда return JSON.stringify({ ok: true, data: ... })

• Паттерн ошибок — выбрасывайте именованные ошибки (NotFoundError, ValidationError), которые мост перехватывает и оборачивает

Лицензия

MIT