Servidor MCP Haulistic

Prueba de concepto independiente del servidor MCP que expone recursos de solo lectura de productos para una organización Haulistic. La organización se selecciona al inicio con MCP_ORGANIZATION_SLUG; los clientes no pueden seleccionarla ni cambiarla.

Esta POC intencionalmente no tiene autenticación de usuario. Cualquiera que pueda acceder al endpoint MCP puede leer el catálogo público de la organización configurada.

Requisitos

• Node.js 20+

• Conectividad PostgreSQL a la base de datos Haulistic

• Un inicio de sesión PostgreSQL con acceso de solo lectura

Related MCP server: zee5-catalog-mcp

Configuración

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

El servidor falla al iniciar si MCP_ORGANIZATION_SLUG falta, se elimina, se desactiva o no existe.

Endpoints

• POST /mcp — endpoint HTTP Streamable MCP sin estado

• GET /health — verificación de preparación de la base de datos y la organización configurada

• Otros métodos en /mcp devuelven 405 Method Not Allowed

El servidor MCP expone estas plantillas de recursos:

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

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

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

Solo se devuelven los productos que están activos, listados y no eliminados. Los límites del catálogo deben estar entre 1 y 100. Las búsquedas por nombre son coincidencias parciales que no distinguen mayúsculas/minúsculas y devuelven un máximo de 20 productos.

El servidor MCP también expone estos prompts reutilizables:

• browse-product-catalog — explorar y resumir una página del catálogo

• find-products-by-name — buscar y presentar productos que coincidan con un nombre

• compare-products — comparar dos productos usando sus rutas de tienda

Rol de base de datos de solo lectura

Utilice un rol de base de datos separado para este servicio. El flujo de administración exacto depende de la plataforma de implementación, pero los privilegios deben ser equivalentes a:

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;

La aplicación también solicita default_transaction_read_only=on para cada conexión de base de datos y aplica un tiempo de espera de declaración configurable. Los permisos de la base de datos siguen siendo el límite de seguridad principal.

Compilar y ejecutar

npm run build
npm start

O compile el contenedor:

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

Implemente el servicio detrás de HTTPS, luego configure el conector personalizado de Claude con el endpoint accesible externamente, por ejemplo: https://mcp-poc.example.com/mcp. No se necesita una variable de entorno PUBLIC_MCP_URL para esta POC sin estado y sin autenticación.

Límites de la POC

• Sin OAuth ni otra autenticación de cliente

• Una organización por implementación

• Solo recursos de productos; sin herramientas mutantes

• Los DTO de productos públicos omiten intencionalmente datos del creador, notas internas, productos en borrador y eliminados, configuración de integración y marcas de tiempo internas