MCP-сервер ActivityWatch

Сервер протокола Model Context Protocol (MCP), который подключается к ActivityWatch, позволяя LLM, таким как Claude, взаимодействовать с вашими данными трекинга времени.

Возможности

• Список бакетов (List Buckets): Просмотр всех доступных бакетов ActivityWatch

• Выполнение запросов (Run Queries): Выполнение мощных запросов на языке AQL (ActivityWatch Query Language)

• Получение необработанных событий (Get Raw Events): Получение событий напрямую из любого бакета

• Получение настроек (Get Settings): Доступ к конфигурационным настройкам ActivityWatch

Related MCP server: Amplitude MCP Server

Установка

Вы можете установить MCP-сервер ActivityWatch через npm или собрав его самостоятельно.

Установка через npm (скоро)

# Global installation
npm install -g activitywatch-mcp-server

# Or install locally
npm install activitywatch-mcp-server

Сборка из исходного кода

1. Клонируйте этот репозиторий:

   git clone https://github.com/8bitgentleman/activitywatch-mcp-server.git
   cd activitywatch-mcp-server

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

   npm install

3. Соберите проект:

   npm run build

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

• Установленный и запущенный ActivityWatch

• Node.js (версии 14 или выше)

• Claude for Desktop (или любой другой MCP-клиент)

Использование

Использование с Claude for Desktop

1. Откройте файл конфигурации Claude for Desktop:

   • Windows: %APPDATA%\Claude\claude_desktop_config.json

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

2. Добавьте конфигурацию MCP-сервера:

   {
   "mcpServers": {
       "activitywatch": {
       "command": "activitywatch-mcp-server",
       "args": []
       }
   }
   }

   Если вы собрали сервер из исходного кода, используйте:

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

3. Перезапустите Claude for Desktop

4. Найдите значок MCP в интерфейсе Claude, чтобы убедиться, что всё работает

Использование rootless-контейнера podman в Linux с Gemini CLI

Сначала соберите образ с помощью команды:

version=$(npm pkg get version | tr -d '"')
podman build . -t activitywatch-mcp-server:${version}

В этом примере используется переопределение для случая, когда Activity Watch недоступен по адресу 127.0.0.1 (см. следующий раздел). Если это не требуется, вы можете опустить переменную окружения AW_API_BASE.

{
  "mcpServers": {
    "activitywatch-mcp-server": {
      "command": "/usr/bin/podman",
      "args": [
        "run",
        "--rm",
        "--interactive",
        "--userns=keep-id",
        "-e",
        "AW_API_BASE",
        "localhost/activitywatch-mcp-server:1.2.1"
      ],
      "env": {
        "AW_API_BASE": "http://mydesktop.local:5600/api/0"
      }
    }
  }
}

Переопределение хоста/порта сервера ActivityWatch

Если вы хотите запустить этот MCP-сервер из подсистемы Windows для Linux (WSL), например, внутри контейнера, сервер AW, запущенный в Windows, будет недоступен по адресу 127.0.0.1. Чтобы переопределить стандартное подключение к localhost, используйте переменную окружения AW_API_BASE или флаг --aw-api-base, как показано ниже:

# Using environment variable
export AW_API_BASE=http://mydesktop.local:5600/api/0
node dist/index.js

# Or using command-line flag
node dist/index.js --aw-api-base=http://mydesktop.local:5600/api/0

ПРИМЕЧАНИЕ: Сервер AW может быть требователен к имени, используемому для подключения, но он примет имя, соответствующее имени компьютера, на котором он запущен, с суффиксом .local.

Примеры запросов

Вот несколько примеров запросов, которые вы можете попробовать в Claude:

• Список всех ваших бакетов: "Какие у меня есть бакеты ActivityWatch?"

• Получение сводки использования приложений: "Можешь показать, какими приложениями я пользовался больше всего сегодня?"

• Просмотр истории посещений: "На каких сайтах я провел больше всего времени сегодня?"

• Проверка продуктивности: "Сколько времени я сегодня провел в приложениях для продуктивности?"

• Просмотр настроек: "Каковы мои настройки ActivityWatch?" или "Можешь проверить конкретную настройку в ActivityWatch?"

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

list-buckets

Выводит список всех доступных бакетов ActivityWatch с опциональной фильтрацией по типу.

Параметры:

• type (опционально): Фильтрация бакетов по типу (например, "window", "web", "afk")

• includeData (опционально): Включить данные бакета в ответ

run-query

Выполнение запроса на языке запросов ActivityWatch (AQL).

Параметры:

• timeperiods: Период(ы) времени для запроса, отформатированные как массив строк. Для диапазонов дат используйте формат: ["2024-10-28/2024-10-29"]

• query: Массив операторов запроса на языке AQL, где каждый элемент — это полный запрос с операторами, разделенными точкой с запятой

• name (опционально): Имя запроса (используется для кэширования)

ВАЖНО: Каждая строка запроса должна содержать полный запрос с несколькими операторами, разделенными точкой с запятой.

Пример формата запроса:

{
  "timeperiods": ["2024-10-28/2024-10-29"],
  "query": ["events = query_bucket('aw-watcher-window_UNI-qUxy6XHnLkk'); RETURN = events;"]
}

Обратите внимание:

• timeperiods должны содержать предварительно отформатированные диапазоны дат с косой чертой

• Каждый элемент в массиве query — это полный запрос со всеми операторами

get-events

Получение необработанных событий из бакета ActivityWatch.

Параметры:

• bucketId: ID бакета, из которого нужно получить события

• start (опционально): Дата/время начала в формате ISO

• end (опционально): Дата/время окончания в формате ISO

• limit (опционально): Максимальное количество возвращаемых событий

get-settings

Получение настроек ActivityWatch с сервера.

Параметры:

• key (опционально): Получить конкретный ключ настроек вместо всех настроек

Примеры языка запросов

ActivityWatch использует простой язык запросов. Вот несколько распространенных шаблонов:

// Get window events
window_events = query_bucket(find_bucket("aw-watcher-window_"));
RETURN = window_events;

// Get only when not AFK
afk_events = query_bucket(find_bucket("aw-watcher-afk_"));
not_afk = filter_keyvals(afk_events, "status", ["not-afk"]);
window_events = filter_period_intersect(window_events, not_afk);
RETURN = window_events;

// Group by app
window_events = query_bucket(find_bucket("aw-watcher-window_"));
events_by_app = merge_events_by_keys(window_events, ["app"]);
RETURN = sort_by_duration(events_by_app);

// Filter by app name
window_events = query_bucket(find_bucket("aw-watcher-window_"));
code_events = filter_keyvals(window_events, "app", ["Code"]);
RETURN = code_events;

Конфигурация

По умолчанию сервер подключается к API ActivityWatch по адресу http://localhost:5600. Если ваш экземпляр ActivityWatch запущен на другом хосте или порту, вы можете переопределить его, как описано в разделе "Переопределение хоста/порта сервера ActivityWatch" выше.

Устранение неполадок

ActivityWatch не запущен

Если ActivityWatch не запущен, сервер будет выдавать ошибки подключения. Убедитесь, что ActivityWatch запущен и доступен по указанному адресу хоста/порта (http://localhost:5600, если вы его не переопределили).

Ошибки запросов

Если вы столкнулись с ошибками запросов:

1. Проверьте синтаксис запроса

2. Убедитесь, что ID бакетов верны

3. Проверьте, содержат ли периоды времени (timeperiods) данные

4. Проверьте логи ActivityWatch для получения дополнительной информации

Проблемы с форматированием запросов Claude/MCP

Если Claude сообщает об ошибках при выполнении запросов через этот MCP-сервер, скорее всего, это связано с проблемами форматирования. Убедитесь, что ваш запрос в промптах соответствует этому точному формату:

{
  "timeperiods": ["2024-10-28/2024-10-29"],
  "query": ["events = query_bucket('aw-watcher-window_UNI-qUxy6XHnLkk'); RETURN = events;"]
}

Распространенные проблемы:

• Периоды времени отформатированы неправильно (должны быть "start/end" в виде одной строки внутри массива)

• Операторы запроса разделены на отдельные элементы массива вместо того, чтобы быть объединенными в одну строку

Самая распространенная проблема форматирования

Самая частая ошибка — когда Claude разбивает каждый оператор запроса на отдельный элемент массива, вот так:

{
  "query": [
    "browser_events = query_bucket('aw-watcher-web');",
    "afk_events = query_bucket('aw-watcher-afk');",
    "RETURN = events;"
  ],
  "timeperiods": ["2024-10-28/2024-10-29"]
}

Это НЕВЕРНО. Вместо этого все операторы должны находиться в одной строке внутри массива:

{
  "timeperiods": ["2024-10-28/2024-10-29"],
  "query": ["browser_events = query_bucket('aw-watcher-web'); afk_events = query_bucket('aw-watcher-afk'); RETURN = events;"]
}

При составлении промптов для Claude

При составлении промптов для Claude будьте очень точны в отношении формата и используйте примеры. Например, скажите:

"Выполни запрос с timeperiods ["2024-10-28/2024-10-29"] и query ["statement1; statement2; RETURN = result;"]. Важно: убедитесь, что ВСЕ операторы запроса находятся в одной строке внутри массива, а не разделены на отдельные элементы массива."

Вклад в проект

Мы приветствуем ваш вклад! Пожалуйста, не стесняйтесь присылать Pull Request.

Лицензия

MIT