Detalhes do pacote

@erv-test/pg-mcp-js

danmas77MIT1.0.0

PostgreSQL Model Context Protocol (MCP) server - JavaScript implementation

postgresql, mcp, model-context-protocol, database

readme (leia-me)

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:1@192.168.1.12: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.