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.

Основные возможности:

1. Полная реализация сервера: Построен как полноценный сервер с транспортом SSE для производственного использования
2. Поддержка нескольких баз данных: Возможность подключения к нескольким базам данных PostgreSQL одновременно
3. Богатая информация о схеме: Извлекает и предоставляет описания таблиц/колонок из каталога базы данных
4. Контекст расширений: Предоставляет подробную информацию о расширениях PostgreSQL (PostGIS, pgvector и др.)
5. Анализ запросов: Включает инструмент для анализа планов выполнения запросов
6. Управление подключениями: Правильный жизненный цикл подключений к базам данных с безопасной обработкой 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:[email protected]:5432/carlinkng"

Тестовый SSE клиент

Ran tool

Ran tool Вам нужно создать директорию .vscode и файл конфигурации запуска launch.json. Вот как это сделать:

mkdir .vscode

Ran tool Давайте создадим файлы конфигурации для запуска:

Теперь, чтобы конфигурация появилась в списке, вам нужно:

1. Перезагрузить (обновить) Visual Studio Code/Cursor. Вы можете сделать это через Command Palette (Ctrl+Shift+P) и выбрать "Developer: Reload Window" или просто перезапустить Cursor.

2. После перезагрузки:

   • Откройте панель "Run and Debug" (Ctrl+Shift+D)
   • Теперь вы должны увидеть конфигурацию "SSE Клиент" в выпадающем списке

Если конфигурация всё равно не появляется, вы можете запустить файл непосредственно из терминала:

node sse-client.js

Отлично! Как видно из результатов, ваш SSE-клиент успешно подключился к MCP-серверу и:

1. Установил соединение с PostgreSQL базой данных
2. Получил список из 25 схем в базе данных
3. Получил список таблиц в схеме "carl_amo" (3 таблицы)
4. Начал получать периодические "ping" сообщения от сервера

Вы можете заметить, что конфигурация успешно работает из терминала.

Чтобы эта же конфигурация появилась в интерфейсе Cursor/VS Code, вам может потребоваться:

1. Перезапустить Cursor полностью
2. Или, в качестве альтернативы, вы можете добавить конфигурацию непосредственно через интерфейс:
   • Откройте панель 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):

1. Приложение (src/app.js):

   • Более простая реализация, использующая только SSE для транспорта
   • Фокусируется на базовой функциональности MCP (Model Context Protocol)
   • Инициализирует только основные компоненты и запускает SSE-сервер
   • Это легковесный вариант, который проще запустить и использовать

2. Сервер (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.