ustore-backoffice-mcp

Ein MCP-Server für die XMPie uStore BackOffice REST API unter https://produproduce.mysite.com/ustorebackofficerestapi.

Status: funktionsfähig, Ende-zu-Ende gegen die Live-API verifiziert. Die Spezifikation lädt (52 Pfade / 63 Operationen über 15 Tag-Gruppen), die Anmeldung gelingt, und ustore_call_endpoint GET /v1/admin/stores liefert HTTP 200. Die Schreibschutz-Sperre verweigert DELETE korrekt.

Design

Der Server hardcodiert keine Endpunkte. Beim ersten Gebrauch ruft er das eigene OpenAPI-3.0-Dokument der API ab und stellt darüber fünf Tools bereit:

Dies ist die gleiche Form wie bei den MSSQL-MCP-Servern (list_databases → list_tables → describe_table → query), und es hält die Anzahl der Tools gering, unabhängig davon, wie viele Endpunkte die API bereitstellt. Es übersteht auch uStore-Upgrades – neue Endpunkte erscheinen automatisch beim nächsten Spezifikations-Refresh.

Schreibvorgänge sind standardmäßig deaktiviert. Nicht-GET-Methoden werden abgelehnt, bis USTORE_ALLOW_WRITES=true auf dem Serverprozess gesetzt ist.

Related MCP server: mcp-db-server

Setup

Muss auf einem Host mit internem Netzwerkzugriff auf produproduce ausgeführt werden.

cd /opt/mcp/ustore-backoffice-mcp
npm install
cp .env.example .env
$EDITOR .env          # credentials — the base URL and spec URL are preset
npm run probe         # optional: re-confirm the spec URL and auth handshake

Der Authentifizierungs-Handshake ist gegen die Live-API bestätigt und ist bereits der Standard:

POST {base}/v1/admin/auth/login   {"email": "...", "password": "..."}
  -> 200 {"Token": "..."}

Authorization: uStoreBackoffice <token>     # on every subsequent request

Beachten Sie, dass der Anmeldetext email verwendet, nicht username, und das Token-Feld ist großgeschrieben Token. Das Schema ist wörtlich uStoreBackoffice – die API lehnt jedes andere Präfix mit {"Errors":[{"Message":"Invalid security token."}]} ab.

Die Spezifikations-URL ist ebenfalls bestätigt und voreingestellt:

USTORE_SPEC_URL=https://produproduce.mysite.com/ustorebackofficerestapi/ustore-oas3

Sie muss explizit gesetzt werden – diese Bereitstellung liefert OAS3 unter /ustore-oas3, und die Pfade, die loadSpec() sonst abfragen würde, geben alle 404 zurück.

Dann:

npm run http          # or: npm run stdio

Überprüfen:

$ curl -s localhost:8931/healthz
{"ok":true,"target":"https://produproduce.mysite.com/ustorebackofficerestapi"}

/healthz beweist nur, dass der Prozess läuft. Um zu bestätigen, dass der API-Teil funktioniert, rufen Sie ustore_server_info von einem Client auf – es meldet das aufgelöste Authentifizierungsschema und die Anzahl der Operationen und schlägt laut fehl, wenn die Anmeldung defekt ist.

Deployment

pm2

pm2 start index.js --name ustore-mcp --node-args="--enable-source-maps"
pm2 save

systemd

[Unit]
Description=uStore BackOffice MCP server
After=network-online.target

[Service]
Type=simple
User=tc
WorkingDirectory=/opt/mcp/ustore-backoffice-mcp
EnvironmentFile=/opt/mcp/ustore-backoffice-mcp/.env
ExecStart=/usr/bin/node index.js
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

Halten Sie .env bei chmod 600 – es enthält eine uStore-BackOffice-Anmeldeinformation, die eine administrative ist.

HAProxy

SSE benötigt deaktiviertes Buffering und ein langes Server-Timeout, sonst werden Sitzungen abgeschnitten:

backend be_mcp_ustore
    mode http
    option http-server-close
    timeout server 3600s
    timeout tunnel 3600s
    http-request set-header X-Accel-Buffering no
    server ustore1 127.0.0.1:8931 check

Beide Transporte werden bedient: POST /mcp (Streamable HTTP, aktuelle Spezifikation) und GET /sse + POST /messages (Legacy-SSE, passend zum bestehenden Stack). Setzen Sie MCP_BEARER_TOKEN, wenn der Server selbst ein gemeinsames Geheimnis prüfen soll, anstatt sich nur auf HAProxy-ACLs zu verlassen.

Client config

Lokales stdio (Claude Desktop auf derselben Maschine):

{
  "mcpServers": {
    "ustore-backoffice": {
      "command": "node",
      "args": ["/opt/mcp/ustore-backoffice-mcp/index.js"],
      "env": { "MCP_TRANSPORT": "stdio" }
    }
  }
}

Schreiben Sie die Konfigurationsdatei als UTF-8 ohne BOM.

In diesem env-Block sind keine Anmeldeinformationen erforderlich: Der Server liest die .env, die neben index.js liegt. Claude Desktop startet MCP-Server mit cwd=/ und einer nahezu leeren Umgebung, daher löst config.js .env relativ zu seinem eigenen Dateispeicherort auf, nicht zum Arbeitsverzeichnis. Alles, was Sie doch in env setzen, gewinnt weiterhin – echte Umgebungsvariablen haben Vorrang vor der Datei.

Nach dem Bearbeiten der Konfiguration beenden Sie Claude Desktop vollständig (Cmd-Q auf macOS, nicht nur das Fenster schließen), damit der Serverprozess neu gestartet wird.

Notes and gotchas

• Berechtigungsumfang. BackOffice-API-Konten sind in der Regel vollständige Administratoren. Wenn uStore eine eingeschränkte Operator-Rolle unterstützt, verwenden Sie eine – die Schreibschutz-Sperre in diesem Server schützt vor Unfällen, nicht vor einem kompromittierten Token.

• USTORE_ALLOW_PATHS ist eine Regex-Allowlist. Durch das Setzen wird der Server auf die Controller eingeschränkt, die Sie tatsächlich benötigen, was eine stärkere Kontrolle ist als das Schreib-Flag allein.

• Antwortkürzung standardmäßig auf 60k Zeichen. Wenn ein Auflistungs-Endpunkt überläuft, verwenden Sie seine Paginierungsparameter, anstatt die Obergrenze zu erhöhen – diese API nennt sie pageNumber (1-basiert) und pageSize (Standard 50).

• Spezifikations-Caching aktualisiert alle 15 Minuten. Nach einem uStore-Upgrade rufen Sie ustore_server_info mit refreshSpec: true auf, um Änderungen sofort zu übernehmen.

• Authentifizierungsfehler, die wie Verbindungsfehler aussehen. Der Server startet und listet seine Tools auch dann, wenn Anmeldeinformationen fehlen – die Anmeldung erfolgt erst beim ersten API-Aufruf. Wenn Tools erscheinen, aber jeder Aufruf Fehler meldet, führen Sie ustore_server_info aus und prüfen Sie hasToken.

• Dies ergänzt, nicht ersetzt, den SQL-MCP-Server. Die REST-API erzwingt die Geschäftslogik von uStore, daher ist sie der richtige Weg für alles, was den Zustand verändert. Direkte [PRODUPRODUCE].ustore-Abfragen bleiben besser für Reporting-Joins und Schema-Archäologie.