mcp-dbutils

# Архитектура *[English](../../en/technical/architecture.md) | [中文](../../zh/technical/architecture.md) | [Français](../../fr/technical/architecture.md) | [Español](../../es/technical/architecture.md) | [العربية](../../ar/technical/architecture.md) | Русский* Этот документ описывает техническую архитектуру MCP Database Utilities, объясняя, как различные компоненты взаимодействуют для обеспечения безопасного доступа к базам данных для ИИ-ассистентов. ## Обзор архитектуры MCP Database Utilities спроектирован с модульной архитектурой, которая отдает приоритет безопасности, изоляции и гибкости. Система состоит из нескольких отдельных слоев, которые работают вместе для обеспечения безопасного доступа только для чтения к базам данных. ## Фундаментальная концепция: Дизайн слоев абстракции ```mermaid graph TD Client[Клиент] --> DatabaseServer[Сервер базы данных] subgraph Сервер MCP DatabaseServer DatabaseHandler[Обработчик базы данных] PostgresHandler[Обработчик PostgreSQL] SQLiteHandler[Обработчик SQLite] MySQLHandler[Обработчик MySQL] DatabaseServer --> DatabaseHandler DatabaseHandler --> PostgresHandler DatabaseHandler --> SQLiteHandler DatabaseHandler --> MySQLHandler end PostgresHandler --> PostgreSQL[(PostgreSQL)] SQLiteHandler --> SQLite[(SQLite)] MySQLHandler --> MySQL[(MySQL)] ``` Дизайн слоев абстракции является фундаментальной концепцией в архитектуре MCP Database Utilities. Подобно универсальному пульту дистанционного управления, который может управлять различными устройствами, пользователю нужно знать только базовые операции, не понимая лежащей в основе сложности. ## Основные компоненты ### 1. MCP-менеджер (API-инструменты) Этот компонент отвечает за реализацию протокола MCP и предоставление инструментов, которые может использовать ИИ. **Обязанности:** - Реализация MCP-интерфейса для интеграции с ИИ-клиентами - Предоставление доступных инструментов (list-tables, run-query и т.д.) - Управление жизненным циклом MCP-запросов - Валидация входных данных и форматирование выходных данных **Предоставляемые инструменты:** - `dbutils-list-connections`: Перечисление доступных соединений - `dbutils-list-tables`: Перечисление таблиц в базе данных - `dbutils-run-query`: Выполнение SQL-запроса (только SELECT) - `dbutils-get-stats`: Получение статистики по таблице - `dbutils-list-constraints`: Перечисление ограничений таблицы - `dbutils-explain-query`: Получение плана выполнения запроса - `dbutils-get-performance`: Получение метрик производительности - `dbutils-analyze-query`: Анализ запросов для оптимизации ### 2. Менеджер запросов Этот компонент обрабатывает входящие запросы, валидирует их и направляет к соответствующим адаптерам баз данных. **Обязанности:** - Парсинг и валидация SQL-запросов - Применение ограничений безопасности (только SELECT) - Ограничение сложности запросов и размера результатов - Управление таймаутами и отменой запросов - Оптимизация запросов, где возможно ### 3. SQL-менеджер Этот компонент отвечает за синтаксический и семантический анализ SQL-запросов. **Обязанности:** - Парсинг SQL-синтаксиса - Валидация семантики запросов - Обнаружение и блокировка неавторизованных операций (INSERT, UPDATE, DELETE и т.д.) - Идентификация упоминаемых таблиц и столбцов - Оптимизация запросов, где возможно ### 4. Менеджер соединений Этот компонент управляет соединениями с базами данных согласно конфигурации. **Обязанности:** - Чтение и валидация конфигурации соединений - Создание и поддержание пулов соединений - Управление жизненным циклом соединений - Применение параметров безопасности (SSL, таймауты и т.д.) - Мониторинг состояния соединений ### 5. Менеджер кэширования Этот компонент кэширует результаты повторяющихся запросов для улучшения производительности. **Обязанности:** - Кэширование результатов запросов - Инвалидация кэша при необходимости - Управление размером и временем жизни кэша - Оптимизация производительности для повторяющихся запросов ### 6. Адаптеры баз данных Эти компоненты предоставляют унифицированный интерфейс для различных типов баз данных. **Поддерживаемые адаптеры:** - SQLite - PostgreSQL - MySQL **Обязанности:** - Перевод общих запросов в запросы, специфичные для базы данных - Управление особенностями каждого типа базы данных - Оптимизация запросов для каждого движка базы данных - Обработка ошибок, специфичных для каждой базы данных ## Поток данных 1. **Инициализация:** - Сервис читает YAML-файл конфигурации - Соединения с базами данных конфигурируются, но не создаются - MCP-инструменты регистрируются и предоставляются 2. **Обработка запросов:** - ИИ отправляет запрос через протокол MCP - MCP-менеджер получает запрос и передает его менеджеру запросов - Менеджер запросов валидирует запрос и передает его соответствующему адаптеру - Адаптер создает соединение (или использует существующее из пула) - Запрос выполняется и результаты возвращаются - Результаты форматируются и возвращаются ИИ 3. **Обработка ошибок:** - Ошибки перехватываются на каждом уровне - Сообщения об ошибках унифицируются и делаются понятными - Ошибки безопасности логируются и блокируются - Таймауты управляются для предотвращения бесконечных запросов ## Соображения безопасности Безопасность является высшим приоритетом в архитектуре MCP Database Utilities: 1. **Строго только чтение:** - Все запросы анализируются, чтобы убедиться, что они только для чтения - Операции модификации (INSERT, UPDATE, DELETE и т.д.) блокируются - Команды DDL (CREATE, ALTER, DROP и т.д.) блокируются 2. **Изоляция:** - Каждое соединение изолировано - Транзакции только для чтения - Соединения создаются по запросу и закрываются после использования 3. **Аутентификация и авторизация:** - Учетные данные хранятся безопасно - Поддержка SSL/TLS для зашифрованных соединений - Возможность использования учетных записей баз данных только для чтения 4. **Защита от SQL-инъекций:** - Все входные данные валидируются и экранируются - Использование параметризованных запросов - Полный синтаксический анализ SQL-запросов 5. **Ограничение ресурсов:** - Таймауты для всех запросов - Ограничение размера результатов - Ограничение сложности запросов ## Масштабируемость Архитектура спроектирована для масштабируемости: 1. **Новые адаптеры:** - Может быть добавлена поддержка других типов баз данных - Общий интерфейс для всех адаптеров 2. **Новые инструменты:** - Новые MCP-инструменты могут быть легко добавлены - Последовательный интерфейс для всех инструментов 3. **Продвинутые функции:** - Поддержка материализованных представлений - Автоматическая оптимизация запросов - Продвинутый анализ производительности ## Внешние зависимости MCP Database Utilities зависит от следующих библиотек: - **SQLAlchemy**: ORM и SQL-инструменты для взаимодействия с базами данных - **PyYAML**: Парсинг YAML-файлов для конфигурации - **Psycopg2**: Адаптер PostgreSQL - **PyMySQL**: Адаптер MySQL - **Pydantic**: Валидация и сериализация данных ## Известные ограничения - Нет поддержки хранимых процедур - Нет поддержки сложных транзакций - Нет поддержки NoSQL баз данных (на данный момент) - Нет поддержки распределенных запросов между несколькими базами данных ## Будущие разработки - Поддержка других типов баз данных (MongoDB, Oracle, SQL Server и т.д.) - Улучшение возможностей анализа и оптимизации запросов - Поддержка федеративных баз данных - Административный интерфейс для управления соединениями - Продвинутые метрики и мониторинг