sap-wm-mcp 0.2.3 → 0.2.5

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 19 tools covering core operations, analytics, shift management, anomaly detection, and audit history. 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)).
 
 ---
 
@@ -26,6 +26,7 @@ The **npm package** ships 18 tools covering core operations, analytics, shift ma
 - [MCP Client Setup](#mcp-client-setup)
   - [Option A — npx (Claude Desktop, Claude Code, Cursor)](#option-a--npx-recommended)
   - [Option B — Clone locally](#option-b--clone-locally-for-developers)
+  - [Windows troubleshooting (Claude Code)](#windows-claude-code)
   - [Verify it's working](#verify-its-working)
   - [Example conversations](#example-conversations)
 - [Tools Reference](#tools-reference)
@@ -194,6 +195,75 @@ The sap-wm-mcp tools appear automatically in the tools panel. You'll see a hamme
 
 > **`.mcp.json` is project-scoped.** Add it to `.gitignore` — it contains credentials.
 
+> **Windows users:** If the server doesn't appear after restart, see [Windows troubleshooting](#windows-claude-code) below.
+
+---
+
+#### Claude Code — Windows
+
+On Windows, Claude Code may silently fail to launch `npx` or `node` directly (known issue with process spawning). If the server doesn't appear in `/mcp`, use this pattern instead.
+
+**Step 1 — Create a wrapper script** (requires [Git for Windows](https://gitforwindows.org)):
+
+Save as `scripts/run-sap-wm-mcp.sh` in your project:
+
+```bash
+#!/bin/bash
+SCRIPT_DIR="$(cd "${BASH_SOURCE[0]%/*}" && pwd)"
+ROOT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+exec npx --prefix "$ROOT_DIR" sap-wm-mcp
+```
+
+Or to load credentials from a `.env` file instead of inline in `.mcp.json`:
+
+```bash
+#!/bin/bash
+SCRIPT_DIR="$(cd "${BASH_SOURCE[0]%/*}" && pwd)"
+ENV_FILE="$(cd "$SCRIPT_DIR/.." && pwd)/.env"
+
+if [ -f "$ENV_FILE" ]; then
+  set -a; source "$ENV_FILE"; set +a
+else
+  echo "ERROR: .env not found" >&2; exit 1
+fi
+
+exec npx sap-wm-mcp
+```
+
+**Step 2 — Update `.mcp.json`** to use `bash.exe` as the command:
+
+```json
+{
+  "mcpServers": {
+    "sap-wm-mcp": {
+      "command": "C:/Program Files/Git/usr/bin/bash.exe",
+      "args": [
+        "C:/absolute/path/to/your/project/scripts/run-sap-wm-mcp.sh"
+      ]
+    }
+  }
+}
+```
+
+Use an absolute path with forward slashes. No `env` block needed if credentials are in `.env`.
+
+**Step 3 — Skip the approval dialog** (optional but recommended):
+
+Create `.claude/settings.local.json` in your project root:
+
+```json
+{
+  "enableAllProjectMcpServers": true
+}
+```
+
+This prevents a silently-dismissed approval prompt from blocking the server on every restart.
+
+**Step 4 — Restart Claude Code.** Run `/mcp` to verify the tools are loaded.
+
+> **Note:** If the server was previously rejected in the approval dialog, run `claude mcp reset-project-choices` before restarting.
+
 ---
 
 #### Cursor, Windsurf, and other MCP clients
@@ -232,7 +302,7 @@ node index.js
 
 Then point your MCP client at the local file:
 
-**Claude Desktop:**
+**Claude Desktop / macOS / Linux:**
 ```json
 {
   "mcpServers": {
@@ -244,6 +314,8 @@ Then point your MCP client at the local file:
 }
 ```
 
+**Claude Code on Windows** — use the bash wrapper pattern (see [Windows troubleshooting](#windows-claude-code)) with `exec node "$ROOT_DIR/index.js"` in the script instead of `npx`.
+
 ---
 
 ### Verify it's working
@@ -290,6 +362,14 @@ 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
@@ -439,6 +519,7 @@ 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 |
 
 ---
 
@@ -577,6 +658,7 @@ sap-wm-mcp/
 │   ├── createTransferOrder.js        ← create_transfer_order
 │   ├── confirmTransferOrder.js       ← confirm_transfer_order
 │   └── confirmTransferOrderSU.js     ← confirm_transfer_order_su
+│   └── transferOrderHistory.js       ← get_transfer_order_history
 ├── .env.example
 └── package.json
 ```
@@ -601,7 +683,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 | 19 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,9 @@ 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';
 
-const server = new McpServer({ name: 'sap-wm-mcp', version: '0.2.0' });
+const server = new McpServer({ name: 'sap-wm-mcp', version: '0.2.5' });
 
 // Tool 1 — get_bin_status
 server.tool(
@@ -388,6 +389,31 @@ 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 };
+    }
+  }
+);
+
 const transport = new StdioServerTransport();
 await server.connect(transport);
 console.error('SAP WM MCP Server running (stdio)...');

package/lib/s4hClient.js

@@ -130,8 +130,25 @@ export async function s4hPost(path, body) {
 
   if (!response.ok) {
     const text = await response.text();
-    log('error', 'odata_post_http_error', { url, status: response.status, ms: Date.now() - start });
-    throw new Error(`OData POST failed [${response.status}] — see server log for details`);
+    log('error', 'odata_post_http_error', { url, status: response.status, body: text, ms: Date.now() - start });
+
+    // Extract the SAP business error message from the OData V4 error body.
+    // RAP surfaces reported[] messages in error.innererror.errordetails[].
+    // Only the message string is returned — the raw body stays in the log.
+    let sapMessage = null;
+    try {
+      const errJson = JSON.parse(text);
+      const details = errJson?.error?.innererror?.errordetails;
+      if (Array.isArray(details) && details.length > 0) {
+        sapMessage = details.find(d => d.severity === 'error')?.message ?? details[0]?.message;
+      }
+      sapMessage = sapMessage ?? errJson?.error?.message ?? null;
+    } catch { /* non-JSON body — fall through to generic message */ }
+
+    const msg = sapMessage
+      ? `OData POST failed [${response.status}]: ${sapMessage}`
+      : `OData POST failed [${response.status}] — see server log for details`;
+    throw new Error(msg);
   }
 
   log('debug', 'odata_post_ok', { url, ms: Date.now() - start });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sap-wm-mcp",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "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/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
+  };
+}