# Kinozal MCP Server

MCP (Model Context Protocol) сервер для работы с торрент-трекером [kinozal.tv](https://kinozal.tv).

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

- 🔍 **Поиск торрентов** - поиск по названию с возможностью пагинации
- 📊 **Подробная информация** - получение детальных данных о торренте (название, год, жанр, качество, размер, сиды/пиры)
- ⬇️ **Скачивание торрент-файлов** - загрузка .torrent файлов на компьютер (требуется авторизация)

## Установка

### Быстрый запуск через npx (рекомендуется)

Не требует установки, запускается напрямую:

```bash
npx kinozal-mcp
```

### Глобальная установка

```bash
npm install -g kinozal-mcp
kinozal-mcp
```

### Локальная установка

```bash
npm install kinozal-mcp
```

### Установка из исходников

1. Клонируйте репозиторий:
```bash
git clone <repository-url>
cd kinozal_mcp
```

2. Установите зависимости:
```bash
npm install
```

3. Соберите проект:
```bash
npm run build
```

### Настройка авторизации

Для скачивания торрентов настройте переменные окружения:

```bash
KINOZAL_USERNAME=ваш_логин
KINOZAL_PASSWORD=ваш_пароль
```

Это позволит скачивать торренты без передачи логина/пароля в каждом запросе.

## Использование

### Настройка в Claude Desktop

Добавьте следующую конфигурацию в файл `claude_desktop_config.json`:

**MacOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

#### Вариант 1: Использование npx (рекомендуется)

```json
{
  "mcpServers": {
    "kinozal": {
      "command": "npx",
      "args": ["kinozal-mcp"],
      "env": {
        "KINOZAL_USERNAME": "ваш_логин",
        "KINOZAL_PASSWORD": "ваш_пароль"
      }
    }
  }
}
```

#### Вариант 2: Локальная установка

```json
{
  "mcpServers": {
    "kinozal": {
      "command": "node",
      "args": ["/путь/к/проекту/kinozal_mcp/build/index.js"],
      "env": {
        "KINOZAL_USERNAME": "ваш_логин",
        "KINOZAL_PASSWORD": "ваш_пароль"
      }
    }
  }
}
```

Замените путь на актуальный путь к вашему проекту.

### Использование с другими MCP клиентами

Просто запустите сервер:

```bash
npx kinozal-mcp
```

### Доступные инструменты

#### 1. search_torrents

Поиск торрентов по запросу.

**Параметры:**
- `query` (string, обязательный) - поисковый запрос (название фильма/сериала/музыки)
- `page` (number, опциональный) - номер страницы (по умолчанию: 0)

**Пример:**
```typescript
{
  "query": "matrix",
  "page": 0
}
```

**Возвращает:**
```json
[
  {
    "id": "1980167",
    "title": "Матрица (Трилогия) / The Matrix: Trilogy / 1999-2003",
    "size": "42.85 ГБ",
    "seeds": 12,
    "peers": 3,
    "comments": 11,
    "uploadDate": "23.12.2025 в 05:48",
    "uploader": "vitalikmd",
    "category": "13"
  }
]
```

#### 2. get_torrent_details

Получение подробной информации о торренте.

**Параметры:**
- `id` (string, обязательный) - ID торрента из kinozal.tv

**Пример:**
```typescript
{
  "id": "1980167"
}
```

**Возвращает:**
```json
{
  "id": "1980167",
  "title": "Матрица: Трилогия",
  "originalTitle": "The Matrix. Trilogy",
  "year": "1999-2003",
  "genre": "Фантастика, антиутопия, триллер",
  "director": "Лилли Вачовски, Лана Вачовски",
  "cast": "Киану Ривз, Лоуренс Фишборн...",
  "description": "Фильм изображает будущее...",
  "quality": "HDDVDRip (1080p)",
  "video": "MPEG-H HEVC, ~ 8000 Кбит/с, 1920x800",
  "audio": "...",
  "size": "42.85 ГБ",
  "seeds": 12,
  "peers": 3,
  "uploadDate": "10 июня 2023 в 08:06",
  "updateDate": "23 декабря 2025 в 05:48"
}
```

#### 3. download_torrent

Скачивание .torrent файла (требуется учетная запись на kinozal.tv).

**Параметры:**
- `id` (string, обязательный) - ID торрента
- `outputPath` (string, обязательный) - путь для сохранения .torrent файла
- `username` (string, опциональный) - логин на kinozal.tv (если не задан в .env)
- `password` (string, опциональный) - пароль на kinozal.tv (если не задан в .env)

**Пример 1: Использование переменных окружения (рекомендуется)**
```typescript
{
  "id": "1980167",
  "outputPath": "/Users/user/Downloads/matrix.torrent"
}
```

**Пример 2: Передача учетных данных напрямую**
```typescript
{
  "id": "1980167",
  "outputPath": "/Users/user/Downloads/matrix.torrent",
  "username": "your_username",
  "password": "your_password"
}
```

**Возвращает:**
```json
{
  "success": true,
  "message": "Torrent file downloaded successfully",
  "path": "/Users/user/Downloads/matrix.torrent"
}
```

## Структура проекта

```
kinozal_mcp/
├── src/
│   ├── index.ts          # Основной MCP сервер
│   ├── kinozal.ts        # Функции для работы с kinozal.tv
│   └── cookie-jar.ts     # Управление cookies для авторизации
├── build/                # Скомпилированные JS файлы
├── package.json
├── tsconfig.json
└── README.md
```

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

Для разработки с автоматической перекомпиляцией:

```bash
npm run watch
```

## Технические детали

- **Парсинг HTML**: Используется cheerio для извлечения данных из страниц
- **Кодировка**: kinozal.tv использует Windows-1251, данные автоматически конвертируются в UTF-8
- **Авторизация**: Для скачивания торрент-файлов используется сессионная авторизация через cookies
- **MCP SDK**: Сервер построен на [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/typescript-sdk)

## Примечания

- Для использования функции `download_torrent` необходима регистрация на [kinozal.tv](https://kinozal.tv/signup.php)
- **Рекомендуется**: Настройте `.env` файл с учетными данными для удобства и безопасности
- Учетные данные можно передавать как через `.env`, так и напрямую в параметрах инструмента
- Сервер использует публичные страницы kinozal.tv и не нарушает правила трекера
- Скачивание торрентов возможно только после авторизации

## Лицензия

MIT