Haulistic MCP Server

Eigenständiger Proof-of-Concept MCP-Server, der schreibgeschützte Produktressourcen für eine Haulistic-Organisation bereitstellt. Die Organisation wird beim Start mit MCP_ORGANIZATION_SLUG ausgewählt; Clients können sie nicht auswählen oder ändern.

Dieser POC hat absichtlich keine Benutzerauthentifizierung. Jeder, der den MCP-Endpunkt erreichen kann, kann den öffentlichen Katalog der konfigurierten Organisation lesen.

Anforderungen

• Node.js 20+

• PostgreSQL-Konnektivität zur Haulistic-Datenbank

• Ein PostgreSQL-Login mit schreibgeschütztem Zugriff

Related MCP server: zee5-catalog-mcp

Einrichtung

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

Der Server startet nicht, wenn MCP_ORGANIZATION_SLUG fehlt, gelöscht, deaktiviert ist oder nicht existiert.

Endpunkte

• POST /mcp — zustandsloser MCP Streamable-HTTP-Endpunkt

• GET /health — Datenbank- und Konfigurations-Organisations-Bereitschaftsprüfung

• Andere Methoden auf /mcp geben 405 Method Not Allowed zurück

Der MCP-Server stellt diese Ressourcenvorlagen bereit:

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

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

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

Es werden nur Produkte zurückgegeben, die aktiv, gelistet und nicht gelöscht sind. Kataloglimits müssen zwischen 1 und 100 liegen. Namenssuchen sind case-insensitive Teilübereinstimmungen und geben maximal 20 Produkte zurück.

Der MCP-Server stellt auch diese wiederverwendbaren Prompts bereit:

• browse-product-catalog — eine Katalogseite durchsuchen und zusammenfassen

• find-products-by-name — Produkte finden und präsentieren, die einem Namen entsprechen

• compare-products — zwei Produkte anhand ihrer Storefront-Routen vergleichen

Schreibgeschützte Datenbankrolle

Verwenden Sie für diesen Dienst eine separate Datenbankrolle. Der genaue Verwaltungsablauf hängt von der Bereitstellungsplattform ab, aber die Berechtigungen sollten äquivalent sein zu:

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;

Die Anwendung fordert außerdem default_transaction_read_only=on für jede Datenbankverbindung an und wendet ein konfigurierbares Statement-Timeout an. Datenbankberechtigungen bleiben die primäre Sicherheitsgrenze.

Erstellen und Ausführen

npm run build
npm start

Oder den Container erstellen:

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

Stellen Sie den Dienst hinter HTTPS bereit und konfigurieren Sie dann den benutzerdefinierten Claude-Connector mit dem extern erreichbaren Endpunkt, zum Beispiel: https://mcp-poc.example.com/mcp. Eine Umgebungsvariable PUBLIC_MCP_URL wird für diesen nicht authentifizierten, zustandslosen POC nicht benötigt.

POC-Grenzen

• Kein OAuth oder andere Client-Authentifizierung

• Eine Organisation pro Bereitstellung

• Nur Produktressourcen; keine mutierenden Tools

• Öffentliche Produkt-DTOs lassen absichtlich Erstellerdaten, interne Notizen, Entwurfs- und gelöschte Produkte, Integrationskonfiguration und interne Zeitstempel weg