# Clarion: MCP-сервер для AI-агентов

Агент переводит узбекские аудио и видео в текст или субтитры через MCP. Транспорт Streamable HTTP, stateless.

Адрес: `https://api.uzasr.uz/mcp`

## Аутентификация

OAuth 2.1 с PKCE. При первом подключении агент открывает браузер: пользователь входит в Clarion и разрешает доступ, ключ не нужен. Отключить агента можно в кабинете, на странице «Ключи API».

## Подключение

### Claude Code

```bash
claude mcp add --transport http clarion-mcp https://api.uzasr.uz/mcp
```

### Codex

```bash
codex mcp add clarion-mcp --url https://api.uzasr.uz/mcp
codex mcp login clarion-mcp
```

### Плагин

```bash
/plugin marketplace add rustammdev/clarion-mcp
/plugin install clarion-mcp@clarion-mcp
```

После команды откройте в Claude Code `/mcp`, выберите `clarion-mcp` → Authenticate и нажмите «Разрешить» в браузере. В Codex вход запускает `codex mcp login clarion-mcp`, а плагин сам откроет браузер при первом вызове. Подключённые агенты видны в кабинете, на странице «Ключи API».

## CI и headless

Без браузера используйте ключ API `uzasr_live_…` в заголовке `Authorization: Bearer <ключ>`. Отдельный ключ на каждый клиент.

### Claude Code

```bash
claude mcp add --transport http clarion-mcp https://api.uzasr.uz/mcp \
  --header "Authorization: Bearer $UZASR_API_KEY"
```

### Codex

```toml
[mcp_servers.clarion-mcp]
url = "https://api.uzasr.uz/mcp"
bearer_token_env_var = "UZASR_API_KEY"
```

## Порядок работы агента

1. `create_upload(file_path)` возвращает `upload_id` и готовую команду curl.
2. Агент выполняет команду в терминале: файл уходит в `PUT /v1/uploads/{id}`.
3. `transcribe(upload_id, model, format)` ждёт результат ~40 с. Не успел — возвращает `job_id`.
4. `get_transcription(job_id, format)` забирает результат. `job_id` совпадает с `upload_id`.

## Инструменты

| Инструмент | Аргументы | Что делает |
| --- | --- | --- |
| `list_models` | — | Доступные модели: `uzasr-large` — основная, `uzasr-base` — дешевле. |
| `create_upload` | file_path | Возвращает `upload_id` и команду curl для загрузки. |
| `transcribe` | upload_id, model, format | По умолчанию `model="uzasr-large"`, `format="text"`. Ждёт ~40 с, иначе возвращает `job_id`. |
| `get_transcription` | job_id, format | Забирает готовый результат. |

## Форматы

| format | Что внутри |
| --- | --- |
| `text` | Сплошной текст с пунктуацией, латиница. |
| `segments` | Строки с таймкодами начала и конца. |
| `srt` | Субтитры SubRip: кадры по таймкодам слов, до 6 с и до 84 символов. |
| `vtt` | Субтитры WebVTT, те же правила кадров. |

## Лимиты

| Ограничение | Значение |
| --- | --- |
| Размер файла | до 256 МБ |
| Длительность аудио | до 3 часов |
| Ссылка на загрузку | одноразовая, 15 минут |
| Загрузки, ждущие `transcribe`, на ключ | до 10 |

Видео больше 256 МБ сначала сожмите до аудио:

```bash
ffmpeg -i input.mp4 -vn -ac 1 -ar 16000 -c:a libopus -b:a 32k output.ogg
```

## Конфиденциальность

- **Аудио.** Хранится на сервере недолго и удаляется сразу после распознавания.
- **Транскрипт.** Удаляется через 7 дней.
- **Результат.** Уходит агенту ответом инструмента, а значит и LLM-провайдеру агента. Этот выбор остаётся за вами.