Europarcel MCP Server

Instructions

Implementation Reference

• src/tools/orders/cancelOrder.ts:26-129 (handler)

  The main handler function for the 'cancelOrder' tool. It validates input parameters (order_id and refund_channel), retrieves the API key, creates an API client, calls the cancelOrder API method, formats the success/error response, and returns it as MCP tool content.

  async (args: any) => {
    // Get API key from async context
    const apiKey = apiKeyStorage.getStore();
  
    if (!apiKey) {
      return {
        content: [
          {
            type: "text",
            text: "Error: X-API-KEY header is required",
          },
        ],
      };
    }
  
    // Create API client with customer's API key
    const client = new EuroparcelApiClient(apiKey);
  
    try {
      if (!args.order_id) {
        return {
          content: [
            {
              type: "text",
              text: "Error: order_id parameter is required",
            },
          ],
        };
      }
  
      const orderId = Number(args.order_id);
      if (!Number.isInteger(orderId) || orderId <= 0) {
        return {
          content: [
            {
              type: "text",
              text: "Error: order_id must be a positive integer",
            },
          ],
        };
      }
  
      if (
        !args.refund_channel ||
        !["wallet", "card"].includes(args.refund_channel)
      ) {
        return {
          content: [
            {
              type: "text",
              text: "Error: refund_channel parameter is required and must be 'wallet' or 'card'",
            },
          ],
        };
      }
  
      logger.info("Cancelling order", {
        order_id: orderId,
        refund_channel: args.refund_channel,
      });
  
      const result = await client.cancelOrder(orderId, args.refund_channel);
  
      logger.info("Order cancellation result", result);
  
      let formattedResponse = result.success ? "✅ " : "❌ ";
      formattedResponse += result.message + "\n\n";
  
      if (result.success) {
        formattedResponse += `Order #${result.order_id} has been cancelled.\n`;
        if (result.status) {
          formattedResponse += `Status: ${result.status}\n`;
        }
        formattedResponse += `Refund will be processed to: ${args.refund_channel}\n`;
  
        if (result.details) {
          formattedResponse += "\nAdditional Details:\n";
          Object.entries(result.details).forEach(([key, value]) => {
            formattedResponse += `   ${key}: ${value}\n`;
          });
        }
      }
  
      return {
        content: [
          {
            type: "text",
            text: formattedResponse,
          },
        ],
      };
    } catch (error: any) {
      logger.error("Failed to cancel order", error);
  
      return {
        content: [
          {
            type: "text",
            text: `Error cancelling order: ${error.message || "Unknown error"}`,
          },
        ],
      };
    }
  },

• src/tools/orders/cancelOrder.ts:7-133 (registration)

  Registers the 'cancelOrder' MCP tool on the server, including title, description, input schema using Zod, and the handler function.

  export function registerCancelOrderTool(server: McpServer): void {
    // Create API client instance
  
    // Register cancelOrder tool
    server.registerTool(
      "cancelOrder",
      {
        title: "Cancel Order",
        description:
          "Cancel an existing order. Parameters: order_id (required - accepts numbers like 6505 and strings like '6505'), refund_channel ('wallet' or 'card', required)",
        inputSchema: {
          order_id: z
            .union([z.string(), z.number()])
            .describe("The order ID to cancel"),
          refund_channel: z
            .enum(["wallet", "card"])
            .describe("Where to process the refund: 'wallet' or 'card'"),
        },
      },
      async (args: any) => {
        // Get API key from async context
        const apiKey = apiKeyStorage.getStore();
  
        if (!apiKey) {
          return {
            content: [
              {
                type: "text",
                text: "Error: X-API-KEY header is required",
              },
            ],
          };
        }
  
        // Create API client with customer's API key
        const client = new EuroparcelApiClient(apiKey);
  
        try {
          if (!args.order_id) {
            return {
              content: [
                {
                  type: "text",
                  text: "Error: order_id parameter is required",
                },
              ],
            };
          }
  
          const orderId = Number(args.order_id);
          if (!Number.isInteger(orderId) || orderId <= 0) {
            return {
              content: [
                {
                  type: "text",
                  text: "Error: order_id must be a positive integer",
                },
              ],
            };
          }
  
          if (
            !args.refund_channel ||
            !["wallet", "card"].includes(args.refund_channel)
          ) {
            return {
              content: [
                {
                  type: "text",
                  text: "Error: refund_channel parameter is required and must be 'wallet' or 'card'",
                },
              ],
            };
          }
  
          logger.info("Cancelling order", {
            order_id: orderId,
            refund_channel: args.refund_channel,
          });
  
          const result = await client.cancelOrder(orderId, args.refund_channel);
  
          logger.info("Order cancellation result", result);
  
          let formattedResponse = result.success ? "✅ " : "❌ ";
          formattedResponse += result.message + "\n\n";
  
          if (result.success) {
            formattedResponse += `Order #${result.order_id} has been cancelled.\n`;
            if (result.status) {
              formattedResponse += `Status: ${result.status}\n`;
            }
            formattedResponse += `Refund will be processed to: ${args.refund_channel}\n`;
  
            if (result.details) {
              formattedResponse += "\nAdditional Details:\n";
              Object.entries(result.details).forEach(([key, value]) => {
                formattedResponse += `   ${key}: ${value}\n`;
              });
            }
          }
  
          return {
            content: [
              {
                type: "text",
                text: formattedResponse,
              },
            ],
          };
        } catch (error: any) {
          logger.error("Failed to cancel order", error);
  
          return {
            content: [
              {
                type: "text",
                text: `Error cancelling order: ${error.message || "Unknown error"}`,
              },
            ],
          };
        }
      },
    );
  
    logger.info("cancelOrder tool registered successfully");
  }

• src/tools/orders/cancelOrder.ts:17-24 (schema)

  Input schema for the cancelOrder tool using Zod validation for order_id (string or number) and refund_channel (enum: wallet or card).

  inputSchema: {
    order_id: z
      .union([z.string(), z.number()])
      .describe("The order ID to cancel"),
    refund_channel: z
      .enum(["wallet", "card"])
      .describe("Where to process the refund: 'wallet' or 'card'"),
  },

• src/tools/orders/index.ts:18-18 (registration)

  Top-level registration call for the cancelOrder tool as part of registering all order-related tools.

  registerCancelOrderTool(server);

• src/api/client.ts:351-364 (helper)

  EuroparcelApiClient.cancelOrder method called by the tool handler to perform the actual API DELETE request to cancel the order.

  async cancelOrder(
    orderId: number,
    refundChannel: "wallet" | "card",
  ): Promise<CancelOrderResponse> {
    const response = await this.client.delete<CancelOrderResponse>(
      `/orders/${orderId}`,
      {
        params: {
          refund_channel: refundChannel,
        },
      },
    );
    return response.data;
  }

• src/types/index.ts:286-292 (schema)

  TypeScript interface defining the response structure from the cancelOrder API endpoint.

  export interface CancelOrderResponse {
    success: boolean;
    order_id: number;
    status?: string;
    message: string;
    details?: any;
  }