Сервер MCP Haulistic

Автономный proof-of-concept MCP-сервер, предоставляющий ресурсы продуктов только для чтения для одной организации Haulistic. Организация выбирается при запуске с помощью MCP_ORGANIZATION_SLUG; клиенты не могут выбрать или изменить её.

Этот POC намеренно не имеет аутентификации пользователей. Любой, кто может достичь MCP-эндпоинта, может читать публичный каталог для настроенной организации.

Требования

• Node.js 20+

• Подключение к PostgreSQL для базы данных Haulistic

• Логин PostgreSQL с доступом только для чтения

Related MCP server: zee5-catalog-mcp

Настройка

cp .env.example .env
npm install
npm run dev

Сервер не запускается, если MCP_ORGANIZATION_SLUG отсутствует, удалён, деактивирован или не существует.

Эндпоинты

• POST /mcp — stateless MCP Streamable HTTP эндпоинт

• GET /health — проверка готовности базы данных и настроенной организации

• Другие методы на /mcp возвращают 405 Method Not Allowed

MCP-сервер предоставляет следующие шаблоны ресурсов:

• haulistic://products/catalog/{offset}/{limit}

• haulistic://products/by-name/{productName}

• haulistic://products/by-route/{productRoute}

Возвращаются только активные, опубликованные и не удалённые продукты. Лимиты каталога должны быть от 1 до 100. Поиск по имени — это частичное совпадение без учёта регистра, возвращающее не более 20 продуктов.

MCP-сервер также предоставляет следующие повторно используемые промпты:

• browse-product-catalog — просмотр и обобщение страницы каталога

• find-products-by-name — поиск и представление продуктов, соответствующих имени

• compare-products — сравнение двух продуктов по их витринным маршрутам

Роль базы данных только для чтения

Используйте отдельную роль базы данных для этого сервиса. Точный процесс администрирования зависит от платформы развёртывания, но привилегии должны быть эквивалентны:

CREATE ROLE mcp_reader LOGIN PASSWORD 'replace-with-a-secret';
GRANT CONNECT ON DATABASE haulistic TO mcp_reader;
GRANT USAGE ON SCHEMA public TO mcp_reader;
GRANT SELECT ON TABLE
  "Organization",
  "Products",
  "ProductRoutes",
  "ProductOption",
  "ProductOptionValue"
TO mcp_reader;
ALTER ROLE mcp_reader SET default_transaction_read_only = on;

Приложение также запрашивает default_transaction_read_only=on для каждого подключения к базе данных и применяет настраиваемый тайм-аут оператора. Разрешения базы данных остаются основной границей безопасности.

Сборка и запуск

npm run build
npm start

Или соберите контейнер:

docker build -t haulistic-mcp-server .
docker run --rm -p 8080:8080 --env-file .env haulistic-mcp-server

Разверните сервис за HTTPS, затем настройте пользовательский коннектор Claude с внешне доступным эндпоинтом, например: https://mcp-poc.example.com/mcp. Переменная окружения PUBLIC_MCP_URL не требуется для этого неаутентифицированного stateless POC.

Границы POC

• Без OAuth или другой аутентификации клиентов

• Одна организация на развёртывание

• Только ресурсы продуктов; без изменяющих инструментов

• Публичные DTO продуктов намеренно опускают данные создателя, внутренние заметки, черновики и удалённые продукты, конфигурацию интеграции и внутренние временные метки