Metadata-Version: 2.4
Name: ktalk-mcp
Version: 0.4.0
Summary: MCP server for accessing Kontur Talk (KTalk) recordings, transcripts and summaries
Project-URL: Homepage, https://github.com/mdemyanov/ktalk-mcp
Project-URL: Repository, https://github.com/mdemyanov/ktalk-mcp
Project-URL: Issues, https://github.com/mdemyanov/ktalk-mcp/issues
Author-email: Maksim Demyanov <mdemyanov@users.noreply.github.com>
License-Expression: MIT
License-File: LICENSE
Keywords: kontur,ktalk,mcp,recordings,transcripts
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications :: Conferencing
Requires-Python: >=3.12
Requires-Dist: fastmcp>=2.0.0
Requires-Dist: httpx>=0.28.0
Requires-Dist: pydantic-settings>=2.0.0
Description-Content-Type: text/markdown

# ktalk-mcp

[![PyPI](https://img.shields.io/pypi/v/ktalk-mcp)](https://pypi.org/project/ktalk-mcp/)
[![Python](https://img.shields.io/pypi/pyversions/ktalk-mcp)](https://pypi.org/project/ktalk-mcp/)

MCP сервер для доступа к записям [Контур.Толк](https://ktalk.ru) (KTalk) из Claude Code.

Предоставляет доступ к:
- Списку записей конференций
- Деталям записи
- Транскриптам (распознанная речь по спикерам)
- Саммари и протоколам встреч

## Установка

Требуется Python 3.12+ и [uv](https://docs.astral.sh/uv/).

```bash
uv tool install ktalk-mcp
```

Или через pip:

```bash
pip install ktalk-mcp
```

## Получение session token

KTalk использует session token для авторизации API-запросов. Токен передаётся как query parameter.

1. Откройте https://your-domain.ktalk.ru в браузере
2. Войдите в свой аккаунт
3. Откройте DevTools: нажмите `F12` (или `Cmd+Option+I` на Mac)
4. Перейдите во вкладку **Application** → **Cookies** → `https://your-domain.ktalk.ru`
5. Найдите cookie с именем `sessionToken`
6. Скопируйте его значение

> **Важно:** session token имеет ограниченный срок жизни. Если MCP tool возвращает ошибку авторизации, получите новый токен по инструкции выше.

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

Добавьте в файл `~/.claude/.mcp.json` (глобально) или `.mcp.json` (в проекте):

```json
{
  "mcpServers": {
    "ktalk": {
      "command": "uvx",
      "args": ["ktalk-mcp"],
      "env": {
        "KTALK_SESSION_TOKEN": "ваш_session_token",
        "KTALK_BASE_URL": "https://your-domain.ktalk.ru"
      }
    }
  }
}
```

### Альтернативная конфигурация

Переменные окружения можно задать отдельно:

```bash
export KTALK_SESSION_TOKEN="ваш_session_token"
export KTALK_BASE_URL="https://your-domain.ktalk.ru"
```

Также поддерживается файл `.env` в рабочей директории:

```env
KTALK_SESSION_TOKEN=ваш_session_token
KTALK_BASE_URL=https://your-domain.ktalk.ru
```

## Доступные MCP Tools

### `ktalk_list_recordings`

Список записей конференций.

| Параметр | Тип | Default | Описание |
|----------|-----|---------|----------|
| `query` | str | — | Поиск по названию, комнате, автору |
| `start_from` | str | — | Начало периода (ISO 8601) |
| `start_to` | str | — | Конец периода |
| `top` | int | 30 | Количество записей (1–1000) |
| `order` | str | byTimeNewFirst | Сортировка: `byTimeNewFirst`, `byTimeOldFirst`, `byTitle`, `bySizeBigFirst`, `bySizeSmallFirst` |
| `page_token` | str | — | Токен пагинации |
| `format` | str | markdown | raw / markdown |

### `ktalk_get_recording`

Детали одной записи — автор, дата, длительность, список участников.

| Параметр | Тип | Default | Описание |
|----------|-----|---------|----------|
| `recording_key` | str | — | Ключ (ID) записи |
| `format` | str | markdown | raw / markdown |

### `ktalk_get_transcript`

Транскрипт записи — распознанная речь по спикерам с таймкодами.

Поддерживает **чанкинг** для длинных транскриптов: при превышении `chunk_size` ответ автоматически разбивается на части по границам реплик (не в середине фразы). Каждый чанк содержит метаданные для постраничного чтения.

| Параметр | Тип | Default | Описание |
|----------|-----|---------|----------|
| `recording_key` | str | — | Ключ (ID) записи |
| `format` | str | markdown | raw / markdown |
| `chunk` | int | 0 | Номер чанка. 0 = авто (целиком если маленький, первый чанк если большой). 1+ = конкретный чанк |
| `chunk_size` | int | 30000 | Макс. символов в чанке (~7500 токенов). Мягкий лимит — разрез по границам реплик |

### `ktalk_get_summary`

Полное саммари записи (краткое резюме + протокол).

| Параметр | Тип | Default | Описание |
|----------|-----|---------|----------|
| `recording_key` | str | — | Ключ (ID) записи |
| `format` | str | markdown | raw / markdown |

### `ktalk_get_summary_by_type`

Саммари конкретного типа.

| Параметр | Тип | Default | Описание |
|----------|-----|---------|----------|
| `recording_key` | str | — | Ключ (ID) записи |
| `summary_type` | str | — | `shortSummary` / `protocol` |
| `format` | str | markdown | raw / markdown |

## API

Сервер работает с KTalk Web API. Авторизация — через `sessionToken` query parameter.

| Эндпоинт | Описание |
|----------|----------|
| `GET /api/recordings` | Список записей |
| `GET /api/recordings/{id}` | Детали записи |
| `GET /api/recordings/{id}/transcript` | Транскрипт |
| `GET /api/recordings/v2/{id}/summary` | Полное саммари (v2) |
| `GET /api/recordings/{id}/summary/{type}` | Саммари по типу |

> OpenAPI спецификация `talk.public.api-api-2.json` включена как справочник, но содержит расхождения с реальным API (пути, формат авторизации, структура ответов).

## CLI реестра (`ktalk`)

Тот же пакет ставит вторую команду — `ktalk`, операционный реестр записей на
SQLite. Вся детерминированная механика (синхронизация списка записей, дедуп,
экспирация, смена статусов, рендер дашборда и markdown-зеркала, разовая
миграция) живёт в коде, а не в рассуждениях модели.

**SQLite — операционный source of truth.** Markdown-файл `registry.md` —
генерируемое read-only зеркало для git (`ktalk export`), руками не редактируется.

Путь к базе: флаг `--db PATH` > переменная `KTALK_REGISTRY_DB` > дефолт
`95_TRANSCRIPTS/.registry.db` (относительно текущего каталога). Бинарную БД
нужно добавить в `.gitignore` (`.registry.db`, `.registry.db-wal`, `.registry.db-shm`).

| Команда | Назначение |
|---|---|
| `ktalk sync [--days 7] [--json]` | Загрузить записи из KTalk, upsert новых (`new`), экспирировать `new` старше N дней → `skipped`, показать дашборд. Идемпотентно. |
| `ktalk dashboard [--json]` | Дашборд: новые записи, статистика по статусам. |
| `ktalk list [--status S] [--json]` | Список записей с фильтром по статусу. |
| `ktalk show <id> [--json]` | Детали записи: участники, статус, пути, длительность. |
| `ktalk mark-processing <id>` | Перевести в `processing`. |
| `ktalk mark-done <id> --transcript P --protocol P [--type T]` | Завершить, проставить пути и `processed_at`. |
| `ktalk mark-partial <id> [--transcript P] [--protocol P]` | Частичная обработка. |
| `ktalk mark-skipped <id>` | Пропустить вручную. |
| `ktalk set-vault-id <id> <ktalk_id> <vault_id>` | Привязать профиль к участнику. |
| `ktalk export [--out PATH] [--full]` | Сгенерировать markdown-зеркало. |
| `ktalk migrate <vault> [--dry-run] [--json]` | Разовый импорт из markdown-реестров. |

Все команды поддерживают `--json` (валидный JSON в stdout; ошибки — в stderr с
ненулевым кодом возврата). Несколько фоновых агентов могут безопасно писать
параллельно (WAL + `busy_timeout` + транзакция на операцию).

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

```bash
git clone https://github.com/mdemyanov/ktalk-mcp.git
cd ktalk-mcp
uv sync

# Запуск тестов
uv run pytest -v

# Линтинг
uv run ruff check .

# Локальный запуск сервера
KTALK_SESSION_TOKEN=... KTALK_BASE_URL=... uv run ktalk-mcp
```

## Лицензия

MIT
