PostgreSQL Model Context Protocol (PG-MCP) Server - JavaScript
JavaScript-реализация Model Context Protocol (MCP) сервера для баз данных PostgreSQL с расширенными возможностями для AI-агентов.
Обзор
PG-MCP-JS - это JavaScript-реализация сервера Model Context Protocol для баз данных PostgreSQL. Он предоставляет комплексный API для AI-агентов для исследования, подключения, запроса и понимания баз данных PostgreSQL через ресурсно-ориентированную архитектуру MCP.
Основные возможности:
- Полная реализация сервера: Построен как полноценный сервер с транспортом SSE для производственного использования
- Поддержка нескольких баз данных: Возможность подключения к нескольким базам данных PostgreSQL одновременно
- Богатая информация о схеме: Извлекает и предоставляет описания таблиц/колонок из каталога базы данных
- Контекст расширений: Предоставляет подробную информацию о расширениях PostgreSQL (PostGIS, pgvector и др.)
- Анализ запросов: Включает инструмент для анализа планов выполнения запросов
- Управление подключениями: Правильный жизненный цикл подключений к базам данных с безопасной обработкой ID подключений
Особенности
Управление подключениями
- Инструмент connect: Регистрация строк подключения PostgreSQL и получение безопасного ID подключения
- Инструмент disconnect: Явное закрытие подключений к базам данных после использования
- Пулинг подключений: Эффективное управление подключениями с использованием пулов
Инструменты запросов
- pg_query: Выполнение SQL-запросов только для чтения с использованием ID подключения
- pg_explain: Анализ планов выполнения запросов в формате JSON
Ресурсы обнаружения схемы
- Список схем с описаниями
- Список таблиц с описаниями и количеством строк
- Получение сведений о колонках с типами данных и описаниями
- Просмотр ограничений и индексов таблиц
- Исследование расширений базы данных
Ресурсы доступа к данным
- Выборка данных из таблиц (с пагинацией)
- Получение приблизительного количества строк
Контекст расширений
Встроенная контекстная информация для расширений PostgreSQL:
- PostGIS: Пространственные типы данных, функции и примеры
- pgvector: Функции поиска по сходству векторов и лучшие практики
Дополнительные расширения могут быть легко добавлены через файлы конфигурации YAML.
Установка
Предварительные требования
- Node.js 14+
- База(ы) данных PostgreSQL
Обычная установка
# Клонирование репозитория
git clone https://github.com/danmas/pg-mcp-js.git
cd pg-mcp-js
# Установка зависимостей
npm install
# Создание файла .env на основе примера
cp .env.example .env
# Запуск сервера
npm start
Использование
Тестирование сервера
Репозиторий включает тестовый скрипт для проверки функциональности сервера:
# Базовый тест функциональности сервера
node test.js "postgresql://username:password@hostname:port/database"
Для AI-агентов
Пример промпта для использования с агентами:
Используйте сервер PostgreSQL MCP для анализа базы данных.
Доступные инструменты:
- connect: Регистрация строки подключения к базе данных и получение ID подключения
- disconnect: Закрытие подключения к базе данных
- pg_query: Выполнение SQL-запросов с использованием ID подключения
- pg_explain: Получение планов выполнения запросов
Вы можете исследовать ресурсы схемы через:
pgmcp://{conn_id}/schemas
pgmcp://{conn_id}/schemas/{schema}/tables
pgmcp://{conn_id}/schemas/{schema}/tables/{table}/columns
Архитектура
Этот сервер построен на:
- MCP: Фундамент Model Context Protocol
- node-postgres: Клиент PostgreSQL для Node.js
- Express: Для веб-сервера
- YAML: Для информации о контексте расширений
Соображения безопасности
- Сервер работает в режиме "только для чтения" по умолчанию (обеспечивается через настройки транзакций)
- Детали подключения никогда не показываются в URL ресурсов, только непрозрачные ID подключений
- Учетные данные базы данных нужно отправлять только один раз при начальном подключении
Тестирование
Для тестирования можно использовать: node test.js "postgresql://username:password@hostname:port/database" node test2.js "postgresql://carl:1@192.168.1.12:5432/carlinkng"
Тестовый SSE клиент
Ran tool
Ran tool
Вам нужно создать директорию .vscode
и файл конфигурации запуска launch.json
. Вот как это сделать:
mkdir .vscode
Ran tool Давайте создадим файлы конфигурации для запуска:
Теперь, чтобы конфигурация появилась в списке, вам нужно:
Перезагрузить (обновить) Visual Studio Code/Cursor. Вы можете сделать это через Command Palette (Ctrl+Shift+P) и выбрать "Developer: Reload Window" или просто перезапустить Cursor.
После перезагрузки:
- Откройте панель "Run and Debug" (Ctrl+Shift+D)
- Теперь вы должны увидеть конфигурацию "SSE Клиент" в выпадающем списке
Если конфигурация всё равно не появляется, вы можете запустить файл непосредственно из терминала:
node sse-client.js
Отлично! Как видно из результатов, ваш SSE-клиент успешно подключился к MCP-серверу и:
- Установил соединение с PostgreSQL базой данных
- Получил список из 25 схем в базе данных
- Получил список таблиц в схеме "carl_amo" (3 таблицы)
- Начал получать периодические "ping" сообщения от сервера
Вы можете заметить, что конфигурация успешно работает из терминала.
Чтобы эта же конфигурация появилась в интерфейсе Cursor/VS Code, вам может потребоваться:
- Перезапустить Cursor полностью
- Или, в качестве альтернативы, вы можете добавить конфигурацию непосредственно через интерфейс:
- Откройте панель Run and Debug (Ctrl+Shift+D)
- Нажмите на "create a launch.json file" или на значок шестеренки (gear icon)
- Выберите "Node.js" в списке сред
- Это создаст или обновит файл launch.json, и конфигурация должна появиться
Как видим, SSE-подключение к вашему MCP-серверу успешно работает. Вы можете использовать этот код как основу для создания клиентских приложений, работающих с вашей базой данных через MCP-сервер.
Давай посмотрим содержимое этих файлов, чтобы точно определить их назначение:
Read file: src/app.js
Read file: server.js Посмотрим еще один файл, чтобы понять структуру проекта:
Read file: src/config.js Теперь ясно, в чем отличие между приложением (app.js) и сервером (server.js):
Приложение (
src/app.js
):- Более простая реализация, использующая только SSE для транспорта
- Фокусируется на базовой функциональности MCP (Model Context Protocol)
- Инициализирует только основные компоненты и запускает SSE-сервер
- Это легковесный вариант, который проще запустить и использовать
Сервер (
server.js
):- Более полная реализация, предоставляющая не только SSE, но и REST API через Express
- Добавляет RPC (удаленный вызов процедур) через эндпоинт
/rpc
- Содержит дополнительную логику обработки HTTP-запросов
- Имеет больше возможностей для масштабирования и расширения
- Включает более гибкую обработку ошибок и логирование
По сути, server.js
- это расширенная и более функциональная версия app.js
, которая добавляет web-сервер на Express с дополнительными возможностями, тогда как app.js
- это минимальная реализация, сфокусированная только на протоколе MCP через SSE.
Ты можешь выбрать любой из них в зависимости от твоих потребностей: если тебе нужен только SSE для MCP - используй app.js
, если нужен полноценный веб-сервер с дополнительными API - используй server.js
.