# Руководство по установке

*[English](../en/installation.md) | [中文](../zh/installation.md) | [Français](../fr/installation.md) | [Español](../es/installation.md) | [العربية](../ar/installation.md) | Русский*

Этот документ предоставляет простые и понятные шаги для установки и настройки MCP Database Utilities, позволяя вашему ИИ-ассистенту безопасно получать доступ к вашим базам данных и анализировать их.

## Что такое MCP?

MCP (Model Context Protocol) — это протокол, который позволяет ИИ-приложениям (таким как Claude) использовать внешние инструменты. MCP Database Utilities — один из таких инструментов, который позволяет ИИ читать содержимое вашей базы данных без изменения каких-либо данных.

## Перед началом работы

Перед началом установки убедитесь, что у вас есть:

- ИИ-приложение, совместимое с MCP (например, Claude Desktop, Cursor и т.д.)
- Хотя бы одна база данных, к которой вы хотите, чтобы ИИ имел доступ (SQLite, MySQL или PostgreSQL)

## Выберите метод установки

Мы предлагаем четыре простых метода установки. Выберите тот, который лучше всего подходит для вас:

| Метод установки | Лучше всего подходит для | Преимущества |
|---------|---------|------|
| **Вариант A: Использование uvx** | Большинства пользователей | Простой и быстрый, рекомендуемый |
| **Вариант B: Использование Docker** | Пользователей, предпочитающих контейнеризованные приложения | Изолированная среда |
| **Вариант C: Использование Smithery** | Пользователей Claude Desktop | Установка в один клик, самый простой |
| **Вариант D: Офлайн-установка** | Пользователей в средах без интернета | Не требуется сетевое подключение |

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

### Шаг 1: Установите инструмент uv

**На Mac или Linux**:
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

**На Windows**:
```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

После установки проверьте, что он работает, введя эту команду в вашем терминале:
```bash
uv --version
```
Вы должны увидеть что-то вроде `uv 0.5.5` в выводе.

### Шаг 2: Создайте файл конфигурации базы данных

1. Создайте файл с именем `config.yaml` на вашем компьютере
2. Скопируйте следующее содержимое в файл (выберите то, что соответствует вашему типу базы данных):

**Пример базы данных SQLite**:
```yaml
connections:
  my_sqlite:
    type: sqlite
    path: C:/path/to/your/database.db
```

**Пример базы данных PostgreSQL**:
```yaml
connections:
  my_postgres:
    type: postgres
    host: localhost
    port: 5432
    dbname: my_database
    user: postgres_user
    password: postgres_password
```

**Пример базы данных MySQL**:
```yaml
connections:
  my_mysql:
    type: mysql
    host: localhost
    port: 3306
    database: my_database
    user: mysql_user
    password: mysql_password
```

> Пожалуйста, замените примерную информацию реальными данными вашей базы данных. Для дополнительных опций конфигурации см. [Руководство по конфигурации](configuration.md).

### Шаг 3: Настройте ваше ИИ-приложение

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

1. Откройте приложение Claude Desktop
2. Нажмите на иконку настроек в левом нижнем углу
3. Выберите "MCP Servers"
4. Нажмите "Add Server"
5. Добавьте следующую конфигурацию:

```json
"dbutils": {
  "command": "uvx",
  "args": [
    "mcp-dbutils",
    "--config",
    "C:/Users/YourUsername/config.yaml"
  ]
}
```

> Важно: Замените `C:/Users/YourUsername/config.yaml` на реальный путь к файлу конфигурации, который вы создали на Шаге 2.

#### Настройка Cursor

1. Откройте приложение Cursor
2. Перейдите в "Settings" → "MCP"
3. Нажмите "Add MCP Server"
4. Заполните следующую информацию:
   - Name: `Database Utility MCP`
   - Type: `Command` (по умолчанию)
   - Command: `uvx mcp-dbutils --config C:/Users/YourUsername/config.yaml`

> Важно: Замените `C:/Users/YourUsername/config.yaml` на реальный путь к файлу конфигурации, который вы создали на Шаге 2.

## Вариант B: Использование Docker

### Шаг 1: Установите Docker

Если у вас не установлен Docker, загрузите и установите его с [docker.com](https://www.docker.com/products/docker-desktop/).

### Шаг 2: Создайте файл конфигурации базы данных

Так же, как Шаг 2 в Варианте A, создайте файл `config.yaml`.

### Шаг 3: Настройте ваше ИИ-приложение

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

1. Откройте приложение Claude Desktop
2. Нажмите на иконку настроек в левом нижнем углу
3. Выберите "MCP Servers"
4. Нажмите "Add Server"
5. Добавьте следующую конфигурацию:

```json
"dbutils": {
  "command": "docker",
  "args": [
    "run",
    "-i",
    "--rm",
    "-v",
    "C:/Users/YourUsername/config.yaml:/app/config.yaml",
    "mcp/dbutils",
    "--config",
    "/app/config.yaml"
  ]
}
```

> Важно: Замените `C:/Users/YourUsername/config.yaml` на реальный путь к файлу конфигурации, который вы создали на Шаге 2.

#### Настройка Cursor

1. Откройте приложение Cursor
2. Перейдите в "Settings" → "MCP"
3. Нажмите "Add MCP Server"
4. Заполните следующую информацию:
   - Name: `Database Utility MCP`
   - Type: `Command` (по умолчанию)
   - Command: `docker run -i --rm -v C:/Users/YourUsername/config.yaml:/app/config.yaml mcp/dbutils --config /app/config.yaml`

> Важно: Замените `C:/Users/YourUsername/config.yaml` на реальный путь к файлу конфигурации, который вы создали на Шаге 2.

## Вариант C: Использование Smithery (Один клик для Claude)

Если вы используете Claude Desktop, это самый простой метод установки:

1. Убедитесь, что у вас установлен Node.js
2. Откройте терминал или командную строку
3. Выполните следующую команду:

```bash
npx -y @smithery/cli install @donghao1393/mcp-dbutils --client claude
```

4. Следуйте инструкциям на экране для завершения установки

Этот метод автоматически обрабатывает всю конфигурацию, поэтому вам не нужно вручную редактировать какие-либо файлы.

## Вариант D: Офлайн-установка

Если вам нужно использовать инструмент в среде без доступа к интернету, или вы хотите использовать определенную версию:

### Шаг 1: Получите исходный код

В среде с доступом к интернету:
1. Загрузите исходный код с GitHub: `git clone https://github.com/donghao1393/mcp-dbutils.git`
2. Или загрузите zip-файл со [страницы релизов](https://github.com/donghao1393/mcp-dbutils/releases)
3. Скопируйте загруженные файлы в вашу офлайн-среду

### Шаг 2: Создайте файл конфигурации базы данных

Так же, как Шаг 2 в Варианте A, создайте файл `config.yaml`.

### Шаг 3: Настройте ваше ИИ-приложение

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

1. Откройте приложение Claude Desktop
2. Нажмите на иконку настроек в левом нижнем углу
3. Выберите "MCP Servers"
4. Нажмите "Add Server"
5. Добавьте следующую конфигурацию:

```json
"dbutils": {
  "command": "uv",
  "args": [
    "--directory",
    "C:/Users/YourUsername/mcp-dbutils",
    "run",
    "mcp-dbutils",
    "--config",
    "C:/Users/YourUsername/config.yaml"
  ]
}
```

> Важно: Замените пути на реальные пути к вашей директории с исходным кодом и файлу конфигурации.

## Проверка вашей установки

После завершения установки давайте проверим, что все работает правильно:

### Тестирование соединения

1. Откройте ваше ИИ-приложение (Claude Desktop или Cursor)
2. Спросите ваш ИИ: **"Можете ли вы проверить, способны ли вы подключиться к моей базе данных?"**
3. Если настроено правильно, ИИ ответит, что успешно подключился к вашей базе данных

### Попробуйте простые команды

После подключения вы можете попробовать эти простые команды:

- **"Перечислите все таблицы в моей базе данных"**
- **"Опишите структуру таблицы клиентов"**
- **"Запросите 5 самых дорогих продуктов в таблице продуктов"**

## Устранение распространенных проблем

### Проблема 1: ИИ не может найти команду uvx

**Симптом**: ИИ отвечает "команда uvx не найдена" или подобная ошибка

**Решение**:
1. Подтвердите, что uv правильно установлен: Выполните `uv --version` в вашем терминале
2. Если установлен, но вы все еще получаете ошибки, это может быть проблема с переменной среды:
   - В Windows проверьте, включает ли переменная среды PATH директорию установки uv
   - В Mac/Linux вам может потребоваться перезапустить ваш терминал или выполнить `source ~/.bashrc` или `source ~/.zshrc`

### Проблема 2: Не удается подключиться к базе данных

**Симптом**: ИИ сообщает, что не может подключиться к вашей базе данных

**Решение**:
1. **Проверьте, запущена ли ваша база данных**: Убедитесь, что ваш сервер базы данных запущен
2. **Проверьте информацию о подключении**: Внимательно проверьте хост, порт, имя пользователя и пароль в вашем config.yaml
3. **Проверьте настройки сети**:
   - Если вы используете Docker, для локальных баз данных используйте `host.docker.internal` в качестве имени хоста
   - Убедитесь, что брандмауэры не блокируют соединение

### Проблема 3: Ошибка пути к файлу конфигурации

**Симптом**: ИИ сообщает, что не может найти файл конфигурации

**Решение**:
1. **Используйте абсолютные пути**: Убедитесь, что вы используете полные абсолютные пути в конфигурации вашего ИИ-приложения
2. **Проверьте разрешения файла**: Убедитесь, что файл конфигурации доступен для чтения текущему пользователю
3. **Избегайте специальных символов**: Не используйте специальные символы или пробелы в пути, или используйте кавычки, если необходимо

### Проблема 4: Проблемы с путем к базе данных SQLite

**Симптом**: Соединение не удается при использовании SQLite

**Решение**:
1. **Проверьте путь к файлу**: Убедитесь, что файл базы данных SQLite существует и путь правильный
2. **Проверьте разрешения**: Убедитесь, что файл базы данных имеет разрешения на чтение
3. **При использовании Docker**: Убедитесь, что вы правильно смонтировали путь к файлу SQLite

## Обновление до последней версии

Регулярные обновления предоставляют новые функции и исправления безопасности. Выберите метод обновления, соответствующий вашему методу установки:

### Обновление Варианта A (uvx)

Когда вы запускаете MCP Database Utilities с помощью команды `uvx` (например, `uvx mcp-dbutils`), она автоматически использует последнюю версию без необходимости ручных обновлений.

Если вы используете традиционный метод установки (не команду `uvx`), вы можете обновить вручную с помощью:

```bash
uv pip install -U mcp-dbutils
```

### Обновление Варианта B (Docker)

```bash
docker pull mcp/dbutils:latest
```

### Обновление Варианта C (Smithery)

```bash
npx -y @smithery/cli update @donghao1393/mcp-dbutils
```

### Обновление Варианта D (Офлайн)

1. Загрузите последнюю версию исходного кода в среде с доступом к интернету
2. Замените файлы исходного кода в вашей офлайн-среде

## Примеры взаимодействия

После успешной установки вы можете попробовать эти примеры разговоров:

**Вы**: Можете ли вы перечислить все таблицы в моей базе данных?

**ИИ**: Я проверю вашу базу данных. Вот таблицы в вашей базе данных:
- клиенты
- продукты
- заказы
- инвентарь

**Вы**: Как выглядит таблица клиентов?

**ИИ**: Таблица клиентов имеет следующую структуру:
- id (целое число, первичный ключ)
- имя (текст)
- email (текст)
- дата_регистрации (дата)
- последняя_покупка (дата)

**Вы**: Сколько клиентов совершили покупки в прошлом месяце?

**ИИ**: Позвольте мне выполнить запрос, чтобы узнать... Согласно данным, 28 клиентов совершили покупки в прошлом месяце. Общая стоимость этих покупок составила $15,742.50.
