ustore-backoffice-mcp

Un servidor MCP para la API REST de XMPie uStore BackOffice en https://produproduce.mysite.com/ustorebackofficerestapi.

Estado: funcionando, verificado de extremo a extremo contra la API en vivo. La especificación se carga (52 rutas / 63 operaciones en 15 grupos de etiquetas), el inicio de sesión tiene éxito, y ustore_call_endpoint GET /v1/admin/stores devuelve HTTP 200. El guard de solo lectura rechaza correctamente DELETE.

Diseño

El servidor no codifica endpoints de forma fija. En el primer uso, obtiene el documento OpenAPI 3.0 de la propia API y expone cinco herramientas sobre él:

Esta es la misma forma que los servidores MCP de MSSQL (list_databases → list_tables → describe_table → query), y mantiene el número de herramientas bajo sin importar cuántos endpoints exponga la API. También sobrevive a las actualizaciones de uStore: los nuevos endpoints aparecen automáticamente en la siguiente actualización de la especificación.

Las escrituras están deshabilitadas por defecto. Los métodos que no sean GET se rechazan hasta que se establezca USTORE_ALLOW_WRITES=true en el proceso del servidor.

Related MCP server: mcp-db-server

Configuración

Debe ejecutarse en un host con acceso a la red interna de produproduce.

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

El handshake de autenticación está confirmado contra la API en vivo y ya es el predeterminado:

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

Authorization: uStoreBackoffice <token>     # on every subsequent request

Ten en cuenta que el cuerpo de inicio de sesión usa email, no username, y el campo de token es Token con mayúscula. El esquema es literalmente uStoreBackoffice: la API rechaza cualquier otro prefijo con {"Errors":[{"Message":"Invalid security token."}]}.

La URL de la especificación también está confirmada y preestablecida:

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

Debe establecerse explícitamente: este despliegue sirve OAS3 en /ustore-oas3, y las rutas que loadSpec() probaría de otro modo devuelven 404.

Luego:

npm run http          # or: npm run stdio

Verificar:

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

/healthz solo demuestra que el proceso está activo. Para confirmar que la parte de la API funciona, llama a ustore_server_info desde un cliente: informa el esquema de autenticación resuelto y el recuento de operaciones, y falla de forma ruidosa si el inicio de sesión está roto.

Despliegue

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

Mantén .env con chmod 600: contiene una credencial de uStore BackOffice, que es administrativa.

HAProxy

SSE necesita el buffering desactivado y un timeout de servidor largo, o las sesiones se cortan:

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

Se sirven ambos transportes: POST /mcp (HTTP Streamable, especificación actual) y GET /sse + POST /messages (SSE heredado, que coincide con la pila existente). Establece MCP_BEARER_TOKEN si quieres que el servidor verifique un secreto compartido en lugar de depender solo de las ACL de HAProxy.

Configuración del cliente

stdio local (Claude Desktop en la misma máquina):

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

Escribe el archivo de configuración como UTF-8 sin BOM.

No se necesitan credenciales en ese bloque env: el servidor lee el .env que se encuentra junto a index.js. Claude Desktop lanza los servidores MCP con cwd=/ y un entorno casi vacío, por lo que config.js resuelve .env contra su propia ubicación de archivo en lugar del directorio de trabajo. Cualquier cosa que sí pongas en env sigue ganando: las variables de entorno reales tienen prioridad sobre el archivo.

Después de editar la configuración, sal por completo de Claude Desktop (Cmd-Q en macOS, no solo cerrar la ventana) para que el proceso del servidor se reinicie.

Notas y advertencias

• Alcance de credenciales. Las cuentas de API de BackOffice suelen ser administrador completo. Si uStore admite un rol de operador limitado, usa uno: el guard de solo lectura en este servidor protege contra accidentes, no contra un token comprometido.

• USTORE_ALLOW_PATHS es una lista blanca de expresiones regulares. Configurarlo reduce el servidor a los controladores que realmente necesitas, lo cual es un control más fuerte que el flag de escritura solo.

• Truncamiento de respuestas tiene un valor predeterminado de 60k caracteres. Si un endpoint de listado se desborda, usa sus parámetros de paginación en lugar de aumentar el límite: esta API los escribe como pageNumber (basado en 1) y pageSize (predeterminado 50).

• Caché de especificación se actualiza cada 15 minutos. Después de una actualización de uStore, llama a ustore_server_info con refreshSpec: true para recoger los cambios de inmediato.

• Fallos de autenticación que parecen fallos de conexión. El servidor se inicia y lista sus herramientas incluso cuando faltan credenciales: el inicio de sesión solo ocurre en la primera llamada a la API. Si las herramientas aparecen pero cada llamada da error, ejecuta ustore_server_info y verifica hasToken.

• Esto complementa, no reemplaza, el servidor MCP de SQL. La API REST aplica la lógica de negocio de uStore, por lo que es la ruta correcta para cualquier cosa que mute el estado. Las consultas directas a [PRODUPRODUCE].ustore siguen siendo mejores para uniones de informes y arqueología de esquemas.