W3Ship MCP Server

Instructions

Implementation Reference

• src/index.ts:605-645 (handler)

  The handler implementation for the `track_shipment` tool, located in the `src/index.ts` file as part of the main `CallToolRequestSchema` request handler switch case.

  case 'track_shipment': {
      const { shipmentService } = await import('./shipment/service.js');
      const shipmentId = args?.shipmentId as string;
      const orderId = args?.orderId as string;
  
      let shipment;
      if (shipmentId) {
          shipment = await shipmentService.getShipment(shipmentId);
      } else if (orderId) {
          shipment = await shipmentService.getShipmentByOrderId(orderId);
      } else {
          return { content: [{ type: 'text', text: `Error: Must provide shipmentId or orderId.` }], isError: true };
      }
  
      if (!shipment) {
          return { content: [{ type: 'text', text: `Error: Shipment not found.` }], isError: true };
      }
  
      // Simulate status update based on time elapsed
      const createdTime = new Date(shipment.events[0].timestamp).getTime();
      const now = Date.now();
      const minutesElapsed = (now - createdTime) / 60000;
  
      let newStatus = shipment.status;
      if (minutesElapsed > 5 && shipment.status === 'Label Created') newStatus = 'Picked Up';
      else if (minutesElapsed > 10 && shipment.status === 'Picked Up') newStatus = 'In Transit';
      else if (minutesElapsed > 20 && shipment.status === 'In Transit') newStatus = 'Out for Delivery';
      else if (minutesElapsed > 30 && shipment.status === 'Out for Delivery') newStatus = 'Delivered';
  
      if (newStatus !== shipment.status) {
          shipment.status = newStatus as any;
          shipment.events.push({
              timestamp: new Date().toISOString(),
              status: newStatus,
              description: `Status updated to ${newStatus}`
          });
          await shipmentService.updateShipment(shipment);
      }
  
      return { content: [{ type: 'text', text: JSON.stringify(shipment, null, 2) }] };
  }

• src/index.ts:157-166 (schema)

  The tool definition and input schema for `track_shipment` in the `ListToolsRequestSchema` handler.

      name: 'track_shipment',
      description: 'Track the delivery status of a shipment (TMF621).',
      inputSchema: {
          type: 'object',
          properties: {
              shipmentId: { type: 'string', description: 'The unique Shipment ID' },
              orderId: { type: 'string', description: 'The Order ID (optional, to lookup shipment)' },
          },
      },
  },