npm package: @redcollar/trck-mcp
Description: MCP server for trck time-tracking service
Latest version: 1.0.0

# trck-mcp

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

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

## Возможности

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

## Требования

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

## Установка

```bash
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

```json
{
  "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 |

## Разработка

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