trck-mcp

MCP-сервер для внутреннего сервиса трекинга времени. Позволяет LLM-агентам трекать время через естественный язык.

Пример: «Затрекай в проект PRJ, задачу Dev, 2 часа на сегодня»

Возможности

• Таймшиты — создание, просмотр, обновление, удаление записей времени
• Проекты и задачи — список проектов пользователя с задачами (для маппинга имён → ID)
• Запросы на открытие дат — создание и просмотр запросов на разблокировку прошлых дат
• Сумма часов — сводка по часам за период

Требования

• Node.js >= 18
• npm
• Доступ к Keycloak (SSO) для авторизации

Установка

npm install @redcollar/trck-mcp
# или через npx
npx @redcollar/trck-mcp

Настройка Keycloak

В Keycloak для клиента <CLIENT_ID> (realm <REALM>) необходимо добавить в Valid Redirect URIs:

http://localhost:9876/callback

Сервер при авторизации поднимает HTTP-сервер на фиксированном порту (по умолчанию 9876) и использует redirect URI http://localhost:9876/callback. Порт настраивается через переменную TRCK_CALLBACK_PORT — если меняете порт, не забудьте обновить Valid Redirect URIs в Keycloak.

Важно: Keycloak поддерживает wildcard только в конце path (http://host/path/*), но не в порту. Поэтому используется фиксированный порт, а не случайный.

Где настроить

1. Открыть Keycloak Admin Console → Realm <REALM> → Clients → <CLIENT_ID>
2. В разделе Valid Redirect URIs добавить http://localhost:9876/callback
3. Сохранить

Подключение к MCP-клиенту

OpenCode / Claude Desktop / Cursor

{
  "mcpServers": {
    "trck": {
      "command": "npx",
      "args": ["@redcollar/trck-mcp"],
      "env": {
        "TRCK_API_URL": "<API_URL>",
        "TRCK_KEYCLOAK_URL": "<KEYCLOAK_URL>",
        "TRCK_KEYCLOAK_REALM": "<REALM>",
        "TRCK_CLIENT_ID": "<CLIENT_ID>"
      }
    }
  }
}

Переменные окружения

| Переменная | По умолчанию | Описание | |---|---|---| | TRCK_API_URL | <API_URL> | Base URL API трекера | | TRCK_KEYCLOAK_URL | <KEYCLOAK_URL> | Base URL Keycloak | | TRCK_KEYCLOAK_REALM | <REALM> | Realm в Keycloak | | TRCK_CLIENT_ID | <CLIENT_ID> | Client ID в Keycloak | | TRCK_CALLBACK_PORT | 9876 | Порт для OAuth callback сервера |

Для dev-окружения можно не указывать env — все дефолты уже настроены.

Авторизация

При первом вызове любого инструмента:

1. Сервер откроет браузер со страницей логина Keycloak
2. После входа Keycloak редиректит на http://localhost:9876/callback
3. Токены сохраняются в ~/.trck-mcp/tokens.json
4. При следующих запусках повторный логин не нужен (используется refresh token)

MCP Tools

| Tool | Описание | Чтение/Запись | |---|---|---| | get_my_timesheets | Таймшиты за неделю (weekNumber, year) | read | | get_my_month_hours | Сумма часов за период (dateFrom, dateTo) | read | | create_timesheet | Создать запись (projectId, taskId, date, time) | write | | update_timesheet | Обновить запись (id, time, description?) | write | | delete_timesheet | Удалить запись (id) | write (destructive) | | get_approved_dates | Одобренные даты для прошлых периодов | read | | get_my_projects | Проекты с задачами (для маппинга имён → ID) | read | | get_my_requests | Мои запросы на открытие дат | read | | create_request | Запрос на открытие даты (projectId, dateToOpen, comment) | write |

Разработка

npm run dev    # TypeScript watch mode
npm run build  # Сборка
npm start      # Запуск (stdio)