mcp-dbutils

# Руководство по установке *[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: Получите код проекта и создайте Docker-образ 1. Сначала получите код проекта (выберите один из следующих методов): - Клонируйте проект с GitHub: `git clone https://github.com/donghao1393/mcp-dbutils.git` - Или загрузите последнюю версию со [страницы Releases](https://github.com/donghao1393/mcp-dbutils/releases) и распакуйте её 2. Перейдите в директорию проекта: ```bash cd mcp-dbutils ``` 3. Соберите Docker-образ: ```bash docker build -t mcp/dbutils . ``` > **Примечание**: Корневая директория проекта уже содержит Dockerfile, поэтому вам не нужно создавать его вручную. Для обновления до последней версии вам потребуется получить последний код и пересобрать образ. ### Шаг 4: Настройте ваше ИИ-приложение #### Настройка 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) 1. Получите последний код проекта: ```bash git pull ``` Или загрузите последнюю версию со [страницы Releases](https://github.com/donghao1393/mcp-dbutils/releases) 2. Пересоберите ваш Docker-образ: ```bash docker build -t mcp/dbutils . ``` ### Обновление Варианта C (Smithery) ```bash npx -y @smithery/cli update @donghao1393/mcp-dbutils ``` ### Обновление Варианта D (Офлайн) 1. Загрузите последнюю версию исходного кода в среде с доступом к интернету 2. Замените файлы исходного кода в вашей офлайн-среде ## Примеры взаимодействия После успешной установки вы можете попробовать эти примеры разговоров: **Вы**: Можете ли вы перечислить все таблицы в моей базе данных? **ИИ**: Я проверю вашу базу данных. Вот таблицы в вашей базе данных: - клиенты - продукты - заказы - инвентарь **Вы**: Как выглядит таблица клиентов? **ИИ**: Таблица клиентов имеет следующую структуру: - id (целое число, первичный ключ) - имя (текст) - email (текст) - дата_регистрации (дата) - последняя_покупка (дата) **Вы**: Сколько клиентов совершили покупки в прошлом месяце? **ИИ**: Позвольте мне выполнить запрос, чтобы узнать... Согласно данным, 28 клиентов совершили покупки в прошлом месяце. Общая стоимость этих покупок составила $15,742.50.