sap-wm-mcp 0.2.4 → 0.2.6

package/README.md

@@ -13,7 +13,7 @@ Connect AI agents — Claude, Copilot, or any MCP-compatible client — directly
 >
 > This project ships a custom RAP OData V4 service that exposes classic WM operations as a proper API — and wraps it in an MCP server so AI agents can drive it. Large portions of the SAP install base are still on classic WM. This fills the gap.
 
-The **npm package** ships 18 tools covering core operations, analytics, shift management, and anomaly detection. This repository contains the 9 open-sourced tool implementations — the ABAP RAP service source and additional tool source are available separately (see [ABAP Service Installation](#abap-service-installation)).
+The **npm package** ships 21 tools covering core operations, analytics, shift management, anomaly detection, audit history, and proactive replenishment. This repository contains the 9 open-sourced tool implementations — the ABAP RAP service source and additional tool source are available separately (see [ABAP Service Installation](#abap-service-installation)).
 
 ---
 
@@ -56,7 +56,7 @@ AI Agent (Claude / Copilot / any MCP client)
         ├── LTAP   (Transfer Order Items)
         ├── LTBK   (Transfer Requirement Header)
         ├── MARD   (IM Stock per Storage Location)
-        └── FMs    L_TO_CREATE_SINGLE · L_TO_CONFIRM · L_TO_CONFIRM_SU
+        └── FMs    L_TO_CREATE_SINGLE · L_TO_CONFIRM · L_TO_CONFIRM_SU · L_TO_CANCEL
 ```
 
 Unlike EWM, classic WM has no standard OData APIs. This package requires a **custom RAP OData V4 service** (`ZSD_WMMCPSERVICE`) installed in your SAP system. The MCP server calls that service. See [ABAP Service Installation](#abap-service-installation).
@@ -362,11 +362,19 @@ For write operations:
 "Are there any fragmented quants that need consolidation TOs?"
 ```
 
+**Audit and history**
+```
+"Show me all transfer orders created in warehouse 102 this month"
+"Which TOs did NOMANH create last week?"
+"Show me all open TOs created more than 3 days ago — something is stuck"
+"Give me a history of movement type 999 TOs for material TG0001"
+```
+
 ---
 
 ## Tools Reference
 
-The npm package ships **18 tools** across four capability areas. The 9 tools below are open-sourced in this repository. Analytics, shift management, and anomaly detection tools are available in the published package.
+The npm package ships **21 tools** across five capability areas. The 9 tools below are open-sourced in this repository. Analytics, shift management, anomaly detection, and operations tools are available in the published package.
 
 ---
 
@@ -496,6 +504,21 @@ Confirm all open Transfer Orders on a storage unit in one call — useful for SU
 
 ---
 
+#### `cancel_transfer_order`
+
+Cancel an open Transfer Order — removes it from the active TO queue. Equivalent to transaction **LT15**.
+
+Internally calls `L_TO_CANCEL`. Returns a clear error message for each SAP exception (already confirmed, locked, partially confirmed, etc.).
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `warehouse` | string | ✅ | Warehouse number |
+| `transferOrderNumber` | string | ✅ | Transfer order number — e.g. `0000000652` |
+
+> **Note:** Only open (unconfirmed) TOs can be cancelled. Confirmed TOs, partially confirmed TOs, and TOs locked by another user will return a descriptive error.
+
+---
+
 ### Additional Tools (npm package)
 
 The following tools are available in the published npm package and fully functional via `npx sap-wm-mcp`:
@@ -511,6 +534,8 @@ The following tools are available in the published npm package and fully functio
 | `get_quant_fragmentation` | Bin+material combinations with excessive quant count — consolidation candidates |
 | `get_unresolved_su_negatives` | Persistent negative quants in SU zones older than a configurable age |
 | `get_inventory_anomalies` | Bins stuck in mid-inventory state — empty bins with locks, open count docs, orphaned lock codes |
+| `get_transfer_order_history` | Full TO history with creation date, creator, confirmation date, executor, duration, and item detail — filterable by date range, status, movement type, material, or user |
+| `get_replenishment_needs` | Find forward-pick bins at or below a stock threshold — flags bins with an open replenishment TO already in progress to avoid duplicate moves |
 
 ---
 
@@ -586,6 +611,7 @@ Classic WM has no standard OData APIs. This project builds one using **ABAP REST
 | `CreateTransferOrder` | `L_TO_CREATE_SINGLE` | Called via RFC wrapper `ZWM_TO_CREATE` with `DESTINATION 'NONE'` |
 | `ConfirmTransferOrder` | `L_TO_CONFIRM` | Called directly — no COMMIT needed |
 | `ConfirmTransferOrderSU` | `L_TO_CONFIRM_SU` | Called directly — no COMMIT needed |
+| `CancelTransferOrder` | `L_TO_CANCEL` | Called directly — no COMMIT needed |
 
 ### Why the RFC wrapper?
 
@@ -648,7 +674,9 @@ sap-wm-mcp/
 │   ├── openTransferOrders.js         ← get_open_transfer_orders
 │   ├── createTransferOrder.js        ← create_transfer_order
 │   ├── confirmTransferOrder.js       ← confirm_transfer_order
-│   └── confirmTransferOrderSU.js     ← confirm_transfer_order_su
+│   ├── confirmTransferOrderSU.js     ← confirm_transfer_order_su
+│   ├── cancelTransferOrder.js        ← cancel_transfer_order
+│   └── transferOrderHistory.js       ← get_transfer_order_history
 ├── .env.example
 └── package.json
 ```
@@ -673,7 +701,7 @@ Running both side-by-side shows the contrast directly: same tools, same question
 | Phase | Status | Description |
 |---|---|---|
 | Phase 0 — RAP Service | ✅ Complete | Custom OData V4 service with 7 entity sets over classic WM tables |
-| Phase 1 — Local MCP | ✅ Complete | 18 tools working, security hardened, published to npm |
+| Phase 1 — Local MCP | ✅ Complete | 21 tools working, security hardened, published to npm |
 | Phase 2 — BTP CF | 🔜 Planned | Deploy to SAP BTP Cloud Foundry with SSE transport + XSUAA + Cloud Connector |
 | Phase 3 — Joule Agent | 💡 Future | Native Joule Studio agent using the same RAP service |
 

package/index.js

@@ -25,8 +25,11 @@ import { getGoodsReceiptMonitor } from './tools/goodsReceiptMonitor.js';
 import { getQuantFragmentation } from './tools/quantFragmentation.js';
 import { getUnresolvedSuNegatives } from './tools/unresolvedSuNegatives.js';
 import { getInventoryAnomalies } from './tools/inventoryAnomalies.js';
+import { getTransferOrderHistory } from './tools/transferOrderHistory.js';
+import { cancelTransferOrder } from './tools/cancelTransferOrder.js';
+import { getReplenishmentNeeds } from './tools/replenishmentNeeds.js';
 
-const server = new McpServer({ name: 'sap-wm-mcp', version: '0.2.0' });
+const server = new McpServer({ name: 'sap-wm-mcp', version: '0.2.6' });
 
 // Tool 1 — get_bin_status
 server.tool(
@@ -388,6 +391,71 @@ server.tool(
   }
 );
 
+// Tool 19 — get_transfer_order_history
+server.tool(
+  'get_transfer_order_history',
+  'Get the full history of classic WM Transfer Orders in S/4HANA — when they were created, by whom, when confirmed, who executed them, and how long they took. Filter by date range, status (open/confirmed/all), movement type, material, creator, or executor.',
+  {
+    warehouse:    z.string().describe('Warehouse number e.g. 102'),
+    dateFrom:     z.string().optional().describe('Filter TOs created from this date (YYYY-MM-DD) e.g. 2026-01-01'),
+    dateTo:       z.string().optional().describe('Filter TOs created up to this date (YYYY-MM-DD) e.g. 2026-03-31'),
+    status:       z.enum(['open', 'confirmed', 'all']).optional().default('all').describe('Filter by confirmation status — open, confirmed, or all (default: all)'),
+    movementType: z.string().optional().describe('Filter by WM movement type e.g. 999'),
+    createdBy:    z.string().optional().describe('Filter by the SAP user who created the TO e.g. NOMANH'),
+    executedBy:   z.string().optional().describe('Filter by the SAP user who executed/confirmed the TO'),
+    material:     z.string().optional().describe('Filter by material number e.g. TG0001'),
+    top:          z.number().optional().default(50).describe('Max number of TOs to return (default 50)')
+  },
+  async (params) => {
+    try {
+      const result = await getTransferOrderHistory(params);
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    } catch (err) {
+      return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
+    }
+  }
+);
+
+// Tool 20 — cancel_transfer_order
+server.tool(
+  'cancel_transfer_order',
+  'Cancel an open classic WM Transfer Order — releases the source quant lock and removes the destination bin reservation. Only works on TOs not yet confirmed. Use to recover from a wrong bin or quantity before retrying with corrected parameters.',
+  {
+    warehouse:           z.string().describe('Warehouse number e.g. 102'),
+    transferOrderNumber: z.string().describe('Transfer order number to cancel e.g. 0000000730')
+  },
+  async (params) => {
+    try {
+      const result = await cancelTransferOrder(params);
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    } catch (err) {
+      return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
+    }
+  }
+);
+
+// Tool 21 — get_replenishment_needs
+server.tool(
+  'get_replenishment_needs',
+  'Find forward pick and fixed storage bins that are at or below their minimum stock threshold and need replenishment. Returns urgency level (critical = empty or negative, low = below minimum) and flags bins where an open replenishment TO already exists. Run at shift start and before peak picking periods.',
+  {
+    warehouse:       z.string().describe('Warehouse number e.g. 102'),
+    storageType:     z.string().optional().default('P01').describe('Forward pick storage type to check (default P01)'),
+    material:        z.string().optional().describe('Narrow to a specific material e.g. TG0001'),
+    minimumQuantity: z.number().optional().default(0).describe('Flag bins with stock at or below this level. Default 0 = empty or negative only.'),
+    targetQuantity:  z.number().optional().describe('Fill-to target quantity — used to calculate replenishmentQty in the response. Leave unset if unknown.'),
+    top:             z.number().optional().default(50).describe('Max records to return')
+  },
+  async (params) => {
+    try {
+      const result = await getReplenishmentNeeds(params);
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    } catch (err) {
+      return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
+    }
+  }
+);
+
 const transport = new StdioServerTransport();
 await server.connect(transport);
 console.error('SAP WM MCP Server running (stdio)...');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sap-wm-mcp",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "description": "MCP server for SAP Classic Warehouse Management — connects AI agents to S/4HANA WM via a custom RAP OData V4 service. For systems where EWM is not active.",
   "type": "module",
   "main": "index.js",

package/tools/cancelTransferOrder.js

@@ -0,0 +1,20 @@
+import { s4hPost } from '../lib/s4hClient.js';
+import { esc } from '../lib/sanitize.js';
+
+const BASE = `/sap/opu/odata4/iwbep/all/srvd/sap/zsd_wmmcpservice/0001`;
+const NS   = `com.sap.gateway.srvd.zsd_wmmcpservice.v0001`;
+
+export async function cancelTransferOrder({ warehouse, transferOrderNumber }) {
+  // Instance action — key goes in the URL path, not the body
+  const path = `${BASE}/WMTransferOrder(WarehouseNumber='${encodeURIComponent(esc(warehouse))}',TransferOrderNumber='${encodeURIComponent(esc(transferOrderNumber))}')/${NS}.CancelTransferOrder`;
+
+  await s4hPost(path, {});
+
+  return {
+    success:        true,
+    toNumber:       transferOrderNumber,
+    message:        'Transfer order cancelled successfully',
+    previousStatus: 'open',
+    newStatus:      'cancelled'
+  };
+}

package/tools/replenishmentNeeds.js

@@ -0,0 +1,140 @@
+import { s4hGet } from '../lib/s4hClient.js';
+import { esc } from '../lib/sanitize.js';
+
+const BASE_STOCK  = `/sap/opu/odata4/iwbep/all/srvd/sap/zsd_wmmcpservice/0001/WMWarehouseStock`;
+const BASE_HEADER = `/sap/opu/odata4/iwbep/all/srvd/sap/zsd_wmmcpservice/0001/WMTransferOrder`;
+const BASE_ITEM   = `/sap/opu/odata4/iwbep/all/srvd/sap/zsd_wmmcpservice/0001/WMTransferOrderItem`;
+
+export async function getReplenishmentNeeds({
+  warehouse,
+  storageType = 'P01',
+  material,
+  minimumQuantity = 0,
+  targetQuantity,
+  top = 50
+}) {
+  // Step 1 + 2 in parallel: stock per bin + open TO headers
+  const stockFilters = [
+    `WarehouseNumber eq '${esc(warehouse)}'`,
+    `StorageType eq '${esc(storageType)}'`
+  ];
+  if (material) stockFilters.push(`Material eq '${esc(material)}'`);
+
+  const stockPath = `${BASE_STOCK}?$filter=${encodeURIComponent(stockFilters.join(' and '))}`
+    + `&$top=${top * 10}`
+    + `&$select=StorageType,StorageBin,Material,Plant,TotalStock,AvailableStock,PickQuantity,UnitOfMeasure`;
+
+  const headerPath = `${BASE_HEADER}?$filter=${encodeURIComponent(
+    `WarehouseNumber eq '${esc(warehouse)}' and IsConfirmed ne true`
+  )}&$top=500&$select=TransferOrderNumber`;
+
+  const [stockData, headerData] = await Promise.all([
+    s4hGet(stockPath),
+    s4hGet(headerPath)
+  ]);
+
+  const allStock    = stockData.value  ?? [];
+  const openHeaders = headerData.value ?? [];
+
+  // Aggregate stock by bin+material (multiple quants per bin collapse to one row)
+  const stockMap = new Map();
+  for (const row of allStock) {
+    const mat = row.Material?.trimStart?.() ?? row.Material;
+    const key = `${row.StorageBin}::${mat}`;
+    if (!stockMap.has(key)) {
+      stockMap.set(key, {
+        storageType:    row.StorageType,
+        bin:            row.StorageBin,
+        material:       mat,
+        plant:          row.Plant,
+        totalStock:     0,
+        availableStock: 0,
+        pickQty:        0,
+        uom:            row.UnitOfMeasure
+      });
+    }
+    const e = stockMap.get(key);
+    e.totalStock     += parseFloat(row.TotalStock     ?? 0);
+    e.availableStock += parseFloat(row.AvailableStock ?? 0);
+    e.pickQty        += parseFloat(row.PickQuantity   ?? 0);
+  }
+
+  // Filter: bins at or below the minimum threshold
+  const lowBins = [...stockMap.values()].filter(e => e.totalStock <= minimumQuantity);
+
+  if (lowBins.length === 0) {
+    return {
+      count:     0,
+      truncated: false,
+      warehouse,
+      storageType,
+      filters:   { material: material ?? 'all', minimumQuantity, targetQuantity: targetQuantity ?? null },
+      summary:   { critical: 0, low: 0 },
+      bins:      [],
+      note:      `All bins in storage type ${storageType} are above minimum quantity (${minimumQuantity})`
+    };
+  }
+
+  // Fetch open TO items targeting this type as destination (replenishment TOs in progress)
+  const replenTOMap = new Map(); // 'bin::material' → TO number
+  if (openHeaders.length > 0) {
+    const toFilter = openHeaders
+      .map(h => `TransferOrderNumber eq '${esc(h.TransferOrderNumber)}'`)
+      .join(' or ');
+    const itemFilters = [
+      `WarehouseNumber eq '${esc(warehouse)}'`,
+      `DestStorageType eq '${esc(storageType)}'`,
+      `(${toFilter})`
+    ];
+    if (material) itemFilters.push(`Material eq '${esc(material)}'`);
+
+    const itemPath = `${BASE_ITEM}?$filter=${encodeURIComponent(itemFilters.join(' and '))}`
+      + `&$top=500&$select=TransferOrderNumber,DestBin,Material`;
+    const itemData = await s4hGet(itemPath);
+
+    for (const item of (itemData.value ?? [])) {
+      const mat = item.Material?.trimStart?.() ?? item.Material;
+      const key = `${item.DestBin}::${mat}`;
+      if (!replenTOMap.has(key)) replenTOMap.set(key, item.TransferOrderNumber);
+    }
+  }
+
+  // Build response — sorted critical first (most negative / lowest stock first)
+  const bins = lowBins
+    .sort((a, b) => a.totalStock - b.totalStock)
+    .map(e => {
+      const key          = `${e.bin}::${e.material}`;
+      const urgency      = e.totalStock <= 0 ? 'critical' : 'low';
+      const openTONumber = replenTOMap.get(key) ?? null;
+      const replenishmentQty = targetQuantity != null
+        ? Math.max(0, targetQuantity - e.totalStock)
+        : null;
+      return {
+        storageType:      e.storageType,
+        bin:              e.bin,
+        material:         e.material,
+        plant:            e.plant,
+        currentStock:     e.totalStock,
+        availableStock:   e.availableStock,
+        pickQty:          e.pickQty,
+        replenishmentQty,
+        uom:              e.uom,
+        urgency,
+        openReplenTO:     openTONumber !== null,
+        openTONumber
+      };
+    });
+
+  return {
+    count:     bins.length,
+    truncated: allStock.length >= top * 10,
+    warehouse,
+    storageType,
+    filters:   { material: material ?? 'all', minimumQuantity, targetQuantity: targetQuantity ?? null },
+    summary: {
+      critical: bins.filter(b => b.urgency === 'critical').length,
+      low:      bins.filter(b => b.urgency === 'low').length
+    },
+    bins
+  };
+}

package/tools/transferOrderHistory.js

@@ -0,0 +1,146 @@
+import { s4hGet } from '../lib/s4hClient.js';
+import { esc } from '../lib/sanitize.js';
+
+const BASE_HEADER = `/sap/opu/odata4/iwbep/all/srvd/sap/zsd_wmmcpservice/0001/WMTransferOrder`;
+const BASE_ITEM   = `/sap/opu/odata4/iwbep/all/srvd/sap/zsd_wmmcpservice/0001/WMTransferOrderItem`;
+
+export async function getTransferOrderHistory({
+  warehouse,
+  dateFrom,
+  dateTo,
+  status = 'all',
+  movementType,
+  createdBy,
+  executedBy,
+  material,
+  top = 50
+}) {
+
+  // Step 1 — Build header filters
+  const headerFilters = [`WarehouseNumber eq '${esc(warehouse)}'`];
+
+  if (status === 'confirmed') headerFilters.push(`IsConfirmed eq true`);
+  if (status === 'open')      headerFilters.push(`IsConfirmed ne true`);
+
+  if (dateFrom)      headerFilters.push(`CreatedDate ge ${esc(dateFrom)}`);
+  if (dateTo)        headerFilters.push(`CreatedDate le ${esc(dateTo)}`);
+  if (movementType)  headerFilters.push(`MovementType eq '${esc(movementType)}'`);
+  if (createdBy)     headerFilters.push(`CreatedBy eq '${esc(createdBy)}'`);
+  if (executedBy)    headerFilters.push(`ExecutedBy eq '${esc(executedBy)}'`);
+
+  const headerSelect = [
+    'WarehouseNumber','TransferOrderNumber','MovementType','IsConfirmed',
+    'CreatedDate','CreatedTime','CreatedBy',
+    'ConfirmedDate','ExecutedBy','StartDate','StartTime','EndDate','EndTime',
+    'TransferReqNumber','NumberOfItems'
+  ].join(',');
+
+  const headerPath = `${BASE_HEADER}?$filter=${encodeURIComponent(headerFilters.join(' and '))}&$orderby=CreatedDate desc,CreatedTime desc&$top=${top}&$select=${headerSelect}`;
+  const headerData = await s4hGet(headerPath);
+  const headers    = headerData.value ?? [];
+
+  if (headers.length === 0) {
+    return {
+      count: 0,
+      truncated: false,
+      warehouse,
+      filters: { dateFrom: dateFrom ?? 'all', dateTo: dateTo ?? 'all', status, movementType: movementType ?? 'all' },
+      orders: []
+    };
+  }
+
+  // Step 2 — Fetch items for the returned TOs
+  const toNumbers = [...new Set(headers.map(h => h.TransferOrderNumber))];
+  const toFilter  = toNumbers.map(n => `TransferOrderNumber eq '${esc(n)}'`).join(' or ');
+
+  const itemFilters = [`WarehouseNumber eq '${esc(warehouse)}'`, `(${toFilter})`];
+  if (material) itemFilters.push(`Material eq '${esc(material)}'`);
+
+  const itemPath = `${BASE_ITEM}?$filter=${encodeURIComponent(itemFilters.join(' and '))}&$top=${top * 10}`;
+  const itemData = await s4hGet(itemPath);
+  const allItems = itemData.value ?? [];
+
+  // Step 3 — Group items by TO number
+  const itemsByTo = {};
+  for (const item of allItems) {
+    const key = item.TransferOrderNumber;
+    if (!itemsByTo[key]) itemsByTo[key] = [];
+    itemsByTo[key].push({
+      item:         item.TransferOrderItem,
+      material:     item.Material?.trimStart?.() ?? item.Material,
+      plant:        item.Plant,
+      sourceType:   item.SourceStorageType,
+      sourceBin:    item.SourceBin,
+      destType:     item.DestStorageType,
+      destBin:      item.DestBin,
+      requiredQty:  parseFloat(item.RequiredQuantity)  || 0,
+      confirmedQty: parseFloat(item.ConfirmedQuantity) || 0,
+      uom:          item.UnitOfMeasure
+    });
+  }
+
+  // Step 4 — If material filter active, drop TOs that have no matching items
+  const filteredHeaders = material
+    ? headers.filter(h => itemsByTo[h.TransferOrderNumber]?.length > 0)
+    : headers;
+
+  // Step 5 — Build response
+  const today = new Date();
+
+  const orders = filteredHeaders.map(h => {
+    const items          = itemsByTo[h.TransferOrderNumber] ?? [];
+    const createdAt      = h.CreatedDate ? new Date(h.CreatedDate) : null;
+    const daysSince      = createdAt ? Math.floor((today - createdAt) / 86400000) : null;
+    const isConfirmed    = h.IsConfirmed === true || h.IsConfirmed === 'X';
+
+    // Duration: minutes between StartDate/Time and EndDate/Time
+    let durationMinutes = null;
+    if (h.StartDate && h.EndDate && h.StartTime && h.EndTime) {
+      const start = new Date(`${h.StartDate}T${h.StartTime}`);
+      const end   = new Date(`${h.EndDate}T${h.EndTime}`);
+      if (!isNaN(start) && !isNaN(end)) {
+        durationMinutes = Math.round((end - start) / 60000);
+      }
+    }
+
+    return {
+      toNumber:           h.TransferOrderNumber,
+      status:             isConfirmed ? 'confirmed' : 'open',
+      movementType:       h.MovementType,
+      transferReqNumber:  h.TransferReqNumber || null,
+      numberOfItems:      parseInt(h.NumberOfItems) || items.length,
+      created: {
+        date:   h.CreatedDate,
+        time:   h.CreatedTime,
+        by:     h.CreatedBy,
+        daysAgo: daysSince
+      },
+      execution: isConfirmed ? {
+        confirmedDate: h.ConfirmedDate  || null,
+        executedBy:    h.ExecutedBy     || null,
+        startDate:     h.StartDate      || null,
+        startTime:     h.StartTime      || null,
+        endDate:       h.EndDate        || null,
+        endTime:       h.EndTime        || null,
+        durationMinutes
+      } : null,
+      items
+    };
+  });
+
+  return {
+    count:    orders.length,
+    truncated: headers.length === top,
+    warehouse,
+    filters: {
+      dateFrom:     dateFrom     ?? 'all',
+      dateTo:       dateTo       ?? 'all',
+      status,
+      movementType: movementType ?? 'all',
+      createdBy:    createdBy    ?? 'all',
+      executedBy:   executedBy   ?? 'all',
+      material:     material     ?? 'all'
+    },
+    orders
+  };
+}