CALENDAR_TOOLS.md•6.36 kB
# Calendar Tools Documentation
Этот документ описывает инструменты для работы с микросервисом календарей, добавленные в Radius MCP Server.
## Настройка
Для использования календарных инструментов есть два способа настройки аутентификации:
### Способ 1: Переменные окружения (рекомендуется)
```bash
# URL календарного API
CALENDAR_API_HOST_URL=http://localhost:8000
# или
CALENDAR_API_HOST_URL=https://your-calendar-api.com
# API ключ для аутентификации (header authorization)
CALENDAR_API_KEY=your-api-key-here
```
### Способ 2: Передача API ключа в параметрах инструмента
Каждый инструмент принимает опциональный параметр `api_key`, который имеет приоритет над переменной окружения:
```json
{
"api_key": "your-api-key-here",
// ... другие параметры
}
```
## Доступные инструменты
> **Важно:** Все инструменты поддерживают опциональный параметр `api_key` для аутентификации, который имеет приоритет над переменной окружения `CALENDAR_API_KEY`.
### 1. calendar_get_my
Получить календарь текущего пользователя с событиями за указанный период.
**Параметры:**
- `start` (string, опционально) - дата начала в формате YYYY-MM-DD
- `end` (string, опционально) - дата окончания в формате YYYY-MM-DD
- `_` (string, опционально) - дополнительный параметр (минимум 3 символа)
**Пример:**
```json
{
"start": "2024-01-01",
"end": "2024-01-31"
}
```
### 2. calendar_get_by_user
Получить календарь конкретного пользователя по ID.
**Параметры:**
- `user_id` (number, обязательно) - ID пользователя
- `start` (string, опционально) - дата/время начала
- `end` (string, опционально) - дата/время окончания
**Пример:**
```json
{
"user_id": 123,
"start": "2024-01-01",
"end": "2024-01-31"
}
```
### 3. meeting_create
Создать новую встречу.
**Параметры:**
- `title` (string, обязательно) - название встречи
- `description` (string, опционально) - описание встречи
- `place` (string, опционально) - место проведения
- `start` (string, обязательно) - дата-время начала в формате ISO
- `end` (string, обязательно) - дата-время окончания в формате ISO
- `invited` (array[number], опционально) - список ID приглашенных пользователей
- `notify` (number, опционально) - время уведомления в минутах
**Пример:**
```json
{
"title": "Планерка команды",
"description": "Еженедельная планерка",
"place": "Конференц-зал А",
"start": "2024-01-15T10:00:00Z",
"end": "2024-01-15T11:00:00Z",
"invited": [123, 456, 789],
"notify": 15
}
```
### 4. meeting_get
Получить детали встречи по ID.
**Параметры:**
- `meeting_id` (string, обязательно) - ID встречи
**Пример:**
```json
{
"meeting_id": "abc123def456"
}
```
### 5. meeting_get_user_availability
Проверить занятость пользователей на определенный период времени.
**Параметры:**
- `start` (string, обязательно) - дата-время начала в формате ISO
- `end` (string, обязательно) - дата-время окончания в формате ISO
- `user_ids` (array[number], обязательно) - список ID пользователей для проверки
- `meeting_id` (string, опционально) - исключить конкретную встречу из проверки
**Пример:**
```json
{
"start": "2024-01-15T10:00:00Z",
"end": "2024-01-15T11:00:00Z",
"user_ids": [123, 456, 789]
}
```
### 6. meeting_get_requiring_attention
Получить встречи, требующие внимания от текущего пользователя.
**Параметры:** нет
## API Endpoints
Инструменты обращаются к следующим endpoints календарного API:
- `GET /platform-calendar/api/v1/calendar/my` - мой календарь
- `GET /platform-calendar/api/v1/calendar/{user_id}` - календарь пользователя
- `POST /platform-calendar/api/v1/meeting` - создание встречи
- `GET /platform-calendar/api/v1/meeting/{meeting_id}` - получение встречи
- `GET /platform-calendar/api/v1/meeting` - проверка занятости
- `GET /platform-calendar/api/v1/meeting/requiring_attention` - встречи требующие внимания
## Аутентификация
Все запросы требуют аутентификации через header `authorization`. Ключ может быть передан двумя способами:
1. **Через переменную окружения** `CALENDAR_API_KEY` (глобально для всех запросов)
2. **Через параметр инструмента** `api_key` (имеет приоритет над переменной окружения)
Если не указан ни один из способов, инструмент вернет ошибку аутентификации.
## Обработка ошибок
Все ошибки API логируются в консоль с подробной информацией для отладки. В случае ошибки инструмент вернет сообщение об ошибке с деталями.