# VNDB MCP Server

[![CI](https://github.com/ivanmem/vndb-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/ivanmem/vndb-mcp/actions/workflows/ci.yml)
[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)

MCP-сервер для управления списком визуальных новелл на [VNDB.org](https://vndb.org).

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

- 🔍 **Поиск ВН** по названию (поддерживает русские названия) или ID
- ➕ **Добавление в списки** с различными статусами
- 📝 **Установка оценок** и заметок
- 📋 **Просмотр списка** пользователя
- 🔄 **Изменение статуса** (Playing → Finished и т.д.)
- ❌ **Удаление из списка**

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

| Инструмент | Описание |
|------------|----------|
| `search_vn` | Поиск ВН по названию или ID |
| `add_vn_to_list` | Добавить ВН в список со статусом |
| `update_vn_status` | Изменить статус ВН в списке |
| `remove_vn_from_list` | Удалить ВН из списка |
| `get_vn_list` | Получить список ВН пользователя |
| `check_auth` | Проверка подключения и авторизации |

## Статусы

| Статус | Описание |
|--------|----------|
| `playing` | 🎮 В процессе |
| `finished` | ✅ Завершено |
| `stalled` | ⏸️ Приостановлено |
| `dropped` | ❌ Брошено |
| `planning` | 📋 Запланировано |

## Быстрый старт

### 1. Получение токена VNDB

1. Откройте https://vndb.org/u/tokens
2. Войдите в свой аккаунт
3. Создайте новый токен с разрешениями:
   - `listread` — чтение списков
   - `listwrite` — запись в списки

### 2. Установка токена

**Способ 1: Через `.env` файл**

Создайте файл `.env` в корне проекта:
```
VNDB_TOKEN=ваш-токен-здесь
```

**Способ 2: В `mcp.json`**

Откройте `mcp.json` и укажите токен в `env`:
```json
{
  "mcpServers": {
    "vndb": {
      "command": "node",
      "args": ["путь/к/server.js"],
      "env": {
        "VNDB_TOKEN": "ваш-токен-здесь"
      }
    }
  }
}
```

### 3. Установка зависимостей

```bash
npm install
```

### 4. Запуск

```bash
npm start
```

## Подключение к MCP-клиентам

### Claude Desktop

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

```json
{
  "mcpServers": {
    "vndb": {
      "command": "node",
      "args": ["C:\\путь\\к\\vndb-mcp\\server.js"],
      "env": {
        "VNDB_TOKEN": "ваш-токен"
      }
    }
  }
}
```

### VS Code

1. Установите расширение **MCP**
2. Откройте настройки MCP (`Ctrl+Shift+P` → "MCP: Open Configuration")
3. Добавьте сервер:

```json
{
  "mcpServers": {
    "vndb": {
      "command": "node",
      "args": ["${workspaceFolder}/server.js"],
      "env": {
        "VNDB_TOKEN": "ваш-токен"
      }
    }
  }
}
```

### Cursor

1. Откройте настройки MCP
2. Добавьте сервер с путём к `server.js`
3. Укажите `VNDB_TOKEN` в переменных окружения

## Примеры использования

### Поиск новеллы
```
Найди новеллу "Steins;Gate"
```

### Добавление в список
```
Добавь "Бесконечное лето" в завершённые, оценка 8/10
```

### Изменение статуса
```
Перемести "Clannad" в "В процессе"
```

### Просмотр списка
```
Покажи мой список завершённых новелл
```

## Поиск по русским названиям

Сервер автоматически ищет ВН по русскому названию через VNDB API.  
Для точного поиска используйте оригинальное название или ID (например, `v123`).

## API VNDB

- Документация: https://api.vndb.org/kana
- Лимиты: 200 запросов / 5 минут

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

- Node.js >= 18.0.0

## Лицензия

ISC