ShipBob API MCP Server

Implementation Reference

• src/tools/return-tools.js:78-93 (handler)

  The handler function implementing the 'create_return' MCP tool logic. It calls the ShipBob API client to create the return and formats a text response with the result or error.

  handler: async (returnData) => {
    try {
      const newReturn = await shipbobClient.createReturn(returnData);
      return {
        content: [{ 
          type: "text", 
          text: `Return created successfully: ${JSON.stringify(newReturn, null, 2)}`
        }]
      };
    } catch (error) {
      return {
        content: [{ type: "text", text: `Error creating return: ${error.message}` }],
        isError: true
      };
    }
  }

• src/tools/return-tools.js:59-77 (schema)

  Zod schema defining the input parameters for the 'create_return' tool: orderId, items (array of orderItemId, quantity, optional reason), and optional returnAddress object.

  schema: {
    orderId: z.string().describe("The ID of the order to create a return for"),
    items: z.array(
      z.object({
        orderItemId: z.string().describe("Order item ID to return"),
        quantity: z.number().describe("Quantity to return"),
        reason: z.string().optional().describe("Reason for return")
      })
    ).describe("Items to return"),
    returnAddress: z.object({
      name: z.string().describe("Return address name"),
      address1: z.string().describe("Address line 1"),
      address2: z.string().optional().describe("Address line 2"),
      city: z.string().describe("City"),
      state: z.string().describe("State/Province"),
      zipCode: z.string().describe("Zip/Postal code"),
      country: z.string().describe("Country code (e.g., US)")
    }).optional().describe("Return address information")
  },

• src/server.js:55-55 (registration)

  Registers the returnTools array (which includes the 'create_return' tool) with the MCP server using the generic registerTools function.

  registerTools(returnTools);

• src/api-client.js:140-142 (helper)

  ShipBobClient helper method that makes the POST request to '/returns' endpoint, invoked by the tool handler.

  async createReturn(returnData) {
    return this.request('POST', '/returns', returnData);
  }

• src/tools/return-tools.js:56-94 (registration)

  The tool specification object for 'create_return' defined in the returnTools array, which is later registered with the MCP server.

  {
    name: "create_return",
    description: "Create a new return in ShipBob",
    schema: {
      orderId: z.string().describe("The ID of the order to create a return for"),
      items: z.array(
        z.object({
          orderItemId: z.string().describe("Order item ID to return"),
          quantity: z.number().describe("Quantity to return"),
          reason: z.string().optional().describe("Reason for return")
        })
      ).describe("Items to return"),
      returnAddress: z.object({
        name: z.string().describe("Return address name"),
        address1: z.string().describe("Address line 1"),
        address2: z.string().optional().describe("Address line 2"),
        city: z.string().describe("City"),
        state: z.string().describe("State/Province"),
        zipCode: z.string().describe("Zip/Postal code"),
        country: z.string().describe("Country code (e.g., US)")
      }).optional().describe("Return address information")
    },
    handler: async (returnData) => {
      try {
        const newReturn = await shipbobClient.createReturn(returnData);
        return {
          content: [{ 
            type: "text", 
            text: `Return created successfully: ${JSON.stringify(newReturn, null, 2)}`
          }]
        };
      } catch (error) {
        return {
          content: [{ type: "text", text: `Error creating return: ${error.message}` }],
          isError: true
        };
      }
    }
  }