Пользовательский сервер PostgreSQL MCP для RAGmonsters
Обзор
Этот репозиторий демонстрирует более продвинутый подход к интеграции больших языковых моделей (LLM) с базами данных с использованием Model Context Protocol (MCP). В то время как общие серверы MCP PostgreSQL позволяют LLM исследовать базы данных с помощью сырых SQL-запросов, этот проект использует другой подход, создавая настраиваемый сервер MCP , который предоставляет API, специфичный для домена, адаптированный к потребностям приложения.
В этой реализации используется FastMCP — высокопроизводительная реализация протокола контекста модели, которая обеспечивает повышенную эффективность и надежность инструментального взаимодействия с LLM.
Этот проект использует набор данных RAGmonsters в качестве своей основы. RAGmonsters — это проект с открытым исходным кодом, который предоставляет богатый, вымышленный набор данных монстров с различными атрибутами, способностями и отношениями — специально разработанный для демонстрации и тестирования систем Retrieval-Augmented Generation (RAG).
Проблема с общим доступом к базе данных MCP
Универсальные серверы MCP PostgreSQL предоставляют LLM-специалистам инструмент query , который позволяет им:
- Изучите схемы баз данных
- Формулируйте SQL-запросы на основе вопросов на естественном языке
- Выполнить эти запросы к базе данных
Хотя этот подход работает, он имеет ряд ограничений для реальных приложений:
- Когнитивная нагрузка : LLM должен понимать всю схему базы данных.
- Неэффективность : для ответа на один вопрос часто требуется несколько SQL-запросов.
- Проблемы безопасности : доступ к необработанному SQL-запросу требует тщательной разработки оперативных данных для предотвращения атак с использованием инъекций.
- Производительность : Сложные запросы могут быть неэффективными, если LLM не понимает стратегию индексации базы данных.
- Пробел в знаниях предметной области : LLM не понимает бизнес-правил и ограничений, специфичных для предметной области.
О наборе данных RAGmonsters
RAGmonsters — это открытый набор данных, специально разработанный для тестирования и демонстрации систем Retrieval-Augmented Generation (RAG). Он содержит информацию о вымышленных монстрах с богатыми атрибутами, способностями и отношениями, что делает его идеальным для демонстраций запросов на естественном языке.
Версия RAGmonsters для PostgreSQL предоставляет хорошо структурированную реляционную базу данных с несколькими таблицами и связями, включая:
- Монстры с различными характеристиками (сила атаки, защита, здоровье и т. д.)
- Способности, которыми могут обладать монстры
- Элементы (огонь, вода, земля и т. д.) со сложными взаимоотношениями
- Места обитания монстров
- Эволюционные цепочки и взаимоотношения между монстрами
Этот богатый, взаимосвязанный набор данных идеально подходит для демонстрации возможностей API, специфичных для домена, по сравнению с общим доступом SQL.
Наше решение: API MCP для конкретных доменов
Этот проект демонстрирует, как создать пользовательский сервер MCP, который предоставляет API более высокого уровня, специфичный для домена, для набора данных RAGmonsters. Вместо того, чтобы выставлять возможности чистого SQL, наш сервер MCP предлагает специально созданные функции, которые:
- Абстрактная сложность базы данных : скрыть базовую схему и детали SQL
- Предоставляйте операции, специфичные для домена : предлагайте функции, которые соответствуют бизнес-концепциям
- Оптимизация для распространенных запросов : внедрение эффективных шаблонов запросов для часто задаваемых вопросов.
- Внедрение бизнес-правил : внедрение доменно-специфической логики и ограничений
- Повышение безопасности : ограничение поверхности атаки путем удаления прямого доступа SQL.
Веб-интерфейс
Проект включает два основных интерфейса для взаимодействия с набором данных RAGmonsters:
Интерфейс проводника
Ориентированный на данные интерфейс для изучения и фильтрации набора данных RAGmonsters через API MCP:
- Просмотрите всех монстров с фильтрацией по категории, среде обитания и редкости.
- Посмотреть подробную информацию о каждом монстре
- Интерактивный пользовательский интерфейс, созданный с помощью Bootstrap
Интерфейс чата
Интерфейс на естественном языке для взаимодействия с набором данных RAGmonsters:
- Задавайте вопросы о монстрах на естественном языке
- Получайте ответы в формате Markdown с расширенным форматированием
- Работает на основе шаблона агента LangGraph ReAct
- Полная интеграция с инструментами MCP
Этот интерфейс позволяет пользователям:
- Просмотреть всех монстров в наборе данных
- Фильтровать монстров по среде обитания, категории и редкости
- Просматривайте подробную информацию о каждом монстре, включая его способности, возможности, сильные и слабые стороны.
Пример: API, специфичный для домена, и универсальный SQL
Общий подход MCP PostgreSQL:
User: "What are the top 3 monsters with the highest attack power that are vulnerable to fire?"
LLM: (Must understand schema, joins, and SQL syntax)
1. First query to understand the schema
2. Second query to find monsters with attack power
3. Third query to find vulnerabilities
4. Final query to join and filter results
Наш индивидуальный подход к MCP-серверу:
User: "What are the top 3 monsters with the highest attack power that are vulnerable to fire?"
LLM: (Uses our domain-specific API)
1. Single call: getMonsters({ vulnerableTo: "fire", sortBy: "attackPower", limit: 3 })
Структура проекта
├── .env.example # Example environment variables
├── package.json # Node.js project configuration
├── README.md # This documentation
├── img/ # Images for documentation
├── scripts/
│ ├── testMcpServer.js # Test script for the MCP server
│ └── testLogger.js # Logger for test script
├── src/
│ ├── index.js # Main application server
│ ├── mcp-server/ # Custom MCP server implementation with FastMCP
│ │ ├── index.js # Server entry point
│ │ ├── tools/ # Domain-specific tools
│ │ │ ├── index.js # Tool registration
│ │ │ └── monsters.js # Monster-related operations
│ │ └── utils/ # Helper utilities
│ │ └── logger.js # Logging functionality
│ ├── llm.js # LangChain integration for LLM
│ └── public/ # Web interface files
│ ├── index.html # Monster explorer interface
│ └── chat.html # Chat interface for LLM interactions
Функции
- Пользовательский сервер MCP с FastMCP : высокопроизводительный API-интерфейс для домена данных RAGmonsters
- Оптимизированные запросы : готовые эффективные операции с базой данных
- Уровень бизнес-логики : правила и ограничения домена, встроенные в API
- Структурированный формат ответа : последовательные ответы JSON для потребления LLM
- Комплексное ведение журнала : подробное ведение журнала для отладки и мониторинга.
- Тестовый набор : скрипты для проверки функциональности сервера и интеграции LLM
- Интеграция LLM :
- Интеграция LangChain.js с OpenAI и другими совместимыми поставщиками LLM
- Шаблон агента LangGraph ReAct для эффективного использования инструмента
- Автоматическая обработка вызовов и ответов инструментов
- Веб-интерфейсы :
- Интерфейс проводника для просмотра и фильтрации монстров
- Интерфейс чата с поддержкой Markdown для взаимодействия на естественном языке
Функции
- Интеграция LangChain.js : полностью интегрированное взаимодействие LLM с инструментами MCP
- Веб-интерфейс : интерфейсы обозревателя и чата для взаимодействия с набором данных RAGmonsters
- Готовность к развертыванию : настроено для простого развертывания на таких платформах, как Clever Cloud.
Преимущества этого подхода
- Улучшенная производительность : оптимизированные запросы и стратегии кэширования.
- Лучший пользовательский опыт : более точные и быстрые ответы
- Сокращенное использование токенов : LLM не нужно обрабатывать сложную информацию SQL или схемы.
- Повышенная безопасность : отсутствие прямого доступа к SQL означает снижение риска атак путем внедрения
- Поддерживаемость : изменения в схеме базы данных не требуют переподготовки LLM.
- Масштабируемость : может обрабатывать более крупные и сложные базы данных.
Начиная
Установка
- Клонировать этот репозиторий
- Установка зависимостей:
npm install - Скопируйте
.env.example в .env и настройте строку подключения PostgreSQL и ключи LLM API. - Запустите тестовый скрипт сервера MCP:
npm run test - Запустите скрипт интеграционного теста LLM:
npm run test:llm - Запустите сервер:
npm start
Доступные инструменты
Сервер MCP предоставляет следующие инструменты:
- getMonsters — получение списка монстров с возможностью фильтрации, сортировки и разбиения на страницы
- Параметры: фильтры (категория, местообитание, редкость), сортировка (поле, направление), лимит, смещение
- Возвращает: Массив объектов-монстров с базовой информацией.
- getMonsterById — получить подробную информацию о конкретном монстре по ID
- Параметры: monsterId
- Возвращает: Подробный объект-монстр со всеми атрибутами, силами, способностями, сильными и слабыми сторонами.
- add - Простая утилита для сложения двух чисел (для тестирования)
- Параметры: а, б
- Возвращает: сумму двух чисел.
Архитектура интеграции LLM
В этом проекте используется современный подход к интеграции LLM с предметно-ориентированными инструментами:
Шаблон агента LangGraph ReAct
Приложение использует шаблон агента LangGraph ReAct (Reasoning and Acting), который:
- Обрабатывает запросы пользователей для понимания намерений
- Определяет, какие инструменты использовать на основе запроса
- Автоматически запускает соответствующие инструменты
- Синтезирует результаты в последовательный ответ
- При необходимости выполняет многошаговые рассуждения
Тестирование интеграции LLM
Проект включает в себя тестовый скрипт, демонстрирующий, как использовать LangChain.js для интеграции LLM с сервером MCP:
Этот скрипт:
- Подключается к серверу MCP с помощью StdioClientTransport
- Загружает все доступные инструменты MCP с помощью адаптеров MCP LangChain
- Создает агент LangChain с API OpenAI
- Обрабатывает запросы на естественном языке о монстрах
- Демонстрирует, как LLM вызывает инструменты для извлечения информации.
- Регистрирует подробную информацию о взаимодействии
Вы можете изменить тестовые запросы в скрипте, чтобы исследовать различные возможности системы. Скрипт находится по адресу scripts/testLlmWithMcpServer.js .
Предпосылки
- Node.js 23 или более поздняя версия
- База данных PostgreSQL с данными RAGmonsters
- Доступ к API LLM (например, OpenAI)
- Пакет FastMCP (включен в зависимости)
Переменные среды
Создайте файл .env со следующими переменными:
# PostgreSQL connection string
POSTGRESQL_ADDON_URI=postgres://username:password@host:port/database
# LLM API configuration
LLM_API_KEY=your_openai_api_key
LLM_API_MODEL=gpt-4o-mini
LLM_API_URL=https://api.openai.com/v1
Конфигурация LLM
- LLM_API_KEY : Ваш ключ API OpenAI или ключ совместимого поставщика
- LLM_API_MODEL : модель для использования (по умолчанию: gpt-4o-mini)
- LLM_API_URL : конечная точка API (по умолчанию: конечная точка OpenAI)
Приложение поддерживает любой API, совместимый с OpenAI, включая самостоятельные модели и альтернативных поставщиков.
Развертывание в Clever Cloud
Использование Clever Cloud CLI
- Установите Clever Cloud CLI:
npm install -g clever-tools
- Войдите в свою учетную запись Clever Cloud:
- Создайте новую заявку:
clever create --type node <APP_NAME>
- Добавьте свой домен (необязательно, но рекомендуется):
clever domain add <YOUR_DOMAIN_NAME>
- Создайте дополнение PostgreSQL и свяжите его со своим приложением:
clever addon create <APP_NAME>-pg --plan dev
clever service link-addon <APP_NAME>-pg
POSTGRESQL_ADDON_URI в вашем приложении. - Установите необходимые переменные среды:
clever env set LLM_API_KEY "your-openai-api-key"
clever env set LLM_API_MODEL "gpt-4o-mini" # Optional, defaults to gpt-4o-mini
clever env set LLM_API_URL "https://api.your-llm-provider.com" # Optional, for alternative OpenAI-compatible providers
- Разверните свое приложение:
- Откройте ваше приложение:
Использование консоли Clever Cloud
Вы также можете выполнить развертывание непосредственно из консоли Clever Cloud :
- Создайте новое приложение в консоли
- Выберите Node.js в качестве среды выполнения.
- Создайте дополнение PostgreSQL и свяжите его со своим приложением
- Задайте необходимые переменные среды в консоли:
LLM_API_KEY : Ваш ключ API OpenAILLM_API_MODEL : (Необязательно) модель для использования, по умолчанию gpt-4o-mini
- Разверните свое приложение с помощью интеграции Git или GitHub
Важные примечания
- Переменная среды
POSTGRESQL_ADDON_URI автоматически устанавливается Clever Cloud, когда вы подключаете надстройку PostgreSQL к своему приложению. - Для работы приложения требуется Node.js 20 или более поздней версии, доступной в Clever Cloud.
- Приложение будет автоматически запущено на порту 8080, который является портом по умолчанию для приложений Node.js в Clever Cloud.
Лицензия
Данный проект лицензирован по лицензии MIT — подробности см. в файле LICENSE.
Благодарности