create_fulfillment

Instructions

Implementation Reference

• src/tools/fulfillment.ts:381-427 (handler)

  The handler for the create_fulfillment tool. It constructs the fulfillment input, calls the FulfillmentCreate GraphQL mutation, checks for user errors, and returns the created fulfillment details (name, status, id, order, tracking).

  server.tool(
  "create_fulfillment",
  "Mark items as shipped — creates a fulfillment record covering one or more fulfillment orders. For each fulfillment order in the request, you can either fulfill everything still remaining (omit `fulfillmentOrderLineItems`) or specify per-line {id, quantity} pairs for partial shipments. Optionally attach tracking info (carrier + number; URL is auto-derived for major carriers like USPS/UPS/FedEx/DHL) and set notifyCustomer=true to send the shipment-confirmation email. The fulfillmentOrderLineItem IDs come from list_fulfillment_orders. Side effects: customer-facing email if notifyCustomer is true; webhook fires; remaining quantities decrement.",
  createFulfillmentSchema,
  async (args) => {
    const fulfillment: Record<string, unknown> = {
      lineItemsByFulfillmentOrder: args.lineItemsByFulfillmentOrder,
    };
    if (args.trackingInfo) fulfillment.trackingInfo = args.trackingInfo;
    if (args.notifyCustomer !== undefined) {
      fulfillment.notifyCustomer = args.notifyCustomer;
    }
  
    const data = await client.graphql<{
      fulfillmentCreate: {
        fulfillment: FulfillmentNode | null;
        userErrors: ShopifyUserError[];
      };
    }>(FULFILLMENT_CREATE_MUTATION, { fulfillment });
    throwIfUserErrors(data.fulfillmentCreate.userErrors, "fulfillmentCreate");
    const f = data.fulfillmentCreate.fulfillment;
    if (!f) {
      return {
        content: [
          { type: "text" as const, text: "fulfillmentCreate returned no fulfillment." },
        ],
      };
    }
    const tracking = f.trackingInfo
      .map((t) => [t.company, t.number, t.url].filter(Boolean).join(" | "))
      .filter(Boolean)
      .join("; ");
    return {
      content: [
        {
          type: "text" as const,
          text: [
            `Created fulfillment ${f.name} [${f.status}] — ${f.id}`,
            f.order ? `  Order: ${f.order.name} (${f.order.id})` : "",
            tracking ? `  Tracking: ${tracking}` : "",
          ]
            .filter(Boolean)
            .join("\n"),
        },
      ],
    };
  },

• src/tools/fulfillment.ts:212-222 (schema)

  Schema definition for create_fulfillment tool inputs: lineItemsByFulfillmentOrder (array of fulfillment order + line item selections), optional trackingInfo, optional notifyCustomer.

  const createFulfillmentSchema = {
    lineItemsByFulfillmentOrder: z
      .array(lineItemByFulfillmentOrderSchema)
      .min(1)
      .describe("One entry per fulfillment order being fulfilled in this shipment."),
    trackingInfo: trackingInfoSchema.optional(),
    notifyCustomer: z
      .boolean()
      .optional()
      .describe("Send the customer a shipment notification email."),
  };

• src/tools/fulfillment.ts:258-502 (registration)

  The registerFulfillmentTools function registers all fulfillment tools (including create_fulfillment) on the MCP server using server.tool().

  export function registerFulfillmentTools(
    server: McpServer,
    client: ShopifyClient,
  ): void {
    server.tool(
      "list_fulfillment_orders",
      "List the fulfillment orders attached to a Shopify order. A fulfillment order groups line items by the location that will ship them — a single order can have multiple fulfillment orders if items split across warehouses. Each one tracks per-line remaining quantity (totalQuantity minus what's already shipped/cancelled). Returns the assigned location, destination address, and line-item progress for each. This is the primary read tool you'll call before create_fulfillment to figure out which fulfillmentOrderLineItem IDs and quantities to mark as shipped.",
      listFulfillmentOrdersSchema,
      async (args) => {
        const data = await client.graphql<{
          order:
            | {
                id: string;
                name: string;
                fulfillmentOrders: {
                  edges: Array<{ node: FulfillmentOrderNode }>;
                };
              }
            | null;
        }>(LIST_FULFILLMENT_ORDERS_QUERY, { orderId: args.orderId });
        if (!data.order) {
          return {
            content: [
              { type: "text" as const, text: `Order not found: ${args.orderId}` },
            ],
          };
        }
        const fos = data.order.fulfillmentOrders.edges;
        if (fos.length === 0) {
          return {
            content: [
              {
                type: "text" as const,
                text: `Order ${data.order.name} has no fulfillment orders.`,
              },
            ],
          };
        }
        const lines: string[] = [
          `Order ${data.order.name} has ${fos.length} fulfillment order(s):`,
        ];
        for (const { node } of fos) {
          lines.push(...summarizeFulfillmentOrder(node));
        }
        return {
          content: [{ type: "text" as const, text: lines.join("\n") }],
        };
      },
    );
  
    server.tool(
      "get_fulfillment_order",
      "Fetch a single fulfillment order by GID with its full line-item set and remaining quantities. Use this when you have the FulfillmentOrder ID directly (e.g. from a webhook payload) and want detail without having to look up its parent order first. Returns the same shape as list_fulfillment_orders for one record.",
      getFulfillmentOrderSchema,
      async (args) => {
        const data = await client.graphql<{
          fulfillmentOrder: FulfillmentOrderNode | null;
        }>(GET_FULFILLMENT_ORDER_QUERY, { id: args.id });
        if (!data.fulfillmentOrder) {
          return {
            content: [
              { type: "text" as const, text: `Fulfillment order not found: ${args.id}` },
            ],
          };
        }
        return {
          content: [
            {
              type: "text" as const,
              text: summarizeFulfillmentOrder(data.fulfillmentOrder).join("\n"),
            },
          ],
        };
      },
    );
  
    server.tool(
      "get_fulfillment",
      "Fetch a single fulfillment (a shipment record produced by create_fulfillment) by GID. Returns its status (SUCCESS/CANCELLED/etc.), tracking entries (carrier, number, URL), the parent order, and timestamps. Use after create_fulfillment to confirm the shipment took, or when a webhook delivers a fulfillment GID and you need the details.",
      getFulfillmentSchema,
      async (args) => {
        const data = await client.graphql<{ fulfillment: FulfillmentNode | null }>(
          GET_FULFILLMENT_QUERY,
          { id: args.id },
        );
        if (!data.fulfillment) {
          return {
            content: [
              { type: "text" as const, text: `Fulfillment not found: ${args.id}` },
            ],
          };
        }
        const f = data.fulfillment;
        const tracking = f.trackingInfo
          .map((t) => {
            const parts = [t.company, t.number, t.url].filter(Boolean);
            return parts.length > 0 ? `    - ${parts.join(" | ")}` : "    - (empty)";
          })
          .join("\n");
        return {
          content: [
            {
              type: "text" as const,
              text: [
                `${f.name} [${f.status}]`,
                `  ID: ${f.id}`,
                f.order ? `  Order: ${f.order.name} (${f.order.id})` : "",
                f.totalQuantity !== null && f.totalQuantity !== undefined
                  ? `  Total quantity: ${f.totalQuantity}`
                  : "",
                "  Tracking:",
                tracking || "    (none)",
                `  Created: ${f.createdAt}`,
                `  Updated: ${f.updatedAt}`,
              ]
                .filter(Boolean)
                .join("\n"),
            },
          ],
        };
      },
    );
  
      server.tool(
      "create_fulfillment",
      "Mark items as shipped — creates a fulfillment record covering one or more fulfillment orders. For each fulfillment order in the request, you can either fulfill everything still remaining (omit `fulfillmentOrderLineItems`) or specify per-line {id, quantity} pairs for partial shipments. Optionally attach tracking info (carrier + number; URL is auto-derived for major carriers like USPS/UPS/FedEx/DHL) and set notifyCustomer=true to send the shipment-confirmation email. The fulfillmentOrderLineItem IDs come from list_fulfillment_orders. Side effects: customer-facing email if notifyCustomer is true; webhook fires; remaining quantities decrement.",
      createFulfillmentSchema,
      async (args) => {
        const fulfillment: Record<string, unknown> = {
          lineItemsByFulfillmentOrder: args.lineItemsByFulfillmentOrder,
        };
        if (args.trackingInfo) fulfillment.trackingInfo = args.trackingInfo;
        if (args.notifyCustomer !== undefined) {
          fulfillment.notifyCustomer = args.notifyCustomer;
        }
  
        const data = await client.graphql<{
          fulfillmentCreate: {
            fulfillment: FulfillmentNode | null;
            userErrors: ShopifyUserError[];
          };
        }>(FULFILLMENT_CREATE_MUTATION, { fulfillment });
        throwIfUserErrors(data.fulfillmentCreate.userErrors, "fulfillmentCreate");
        const f = data.fulfillmentCreate.fulfillment;
        if (!f) {
          return {
            content: [
              { type: "text" as const, text: "fulfillmentCreate returned no fulfillment." },
            ],
          };
        }
        const tracking = f.trackingInfo
          .map((t) => [t.company, t.number, t.url].filter(Boolean).join(" | "))
          .filter(Boolean)
          .join("; ");
        return {
          content: [
            {
              type: "text" as const,
              text: [
                `Created fulfillment ${f.name} [${f.status}] — ${f.id}`,
                f.order ? `  Order: ${f.order.name} (${f.order.id})` : "",
                tracking ? `  Tracking: ${tracking}` : "",
              ]
                .filter(Boolean)
                .join("\n"),
            },
          ],
        };
      },
    );
  
    server.tool(
      "update_fulfillment_tracking",
      "Update or add tracking info on an existing fulfillment after the fact. Use this when you've already called create_fulfillment but didn't have the carrier/tracking number yet, or when a tracking number was wrong and needs fixing. company+number is enough; Shopify auto-derives the URL for known carriers (USPS, UPS, FedEx, DHL, etc.). Set notifyCustomer=true to re-send the shipping email with the updated tracking. Omitted fields are left unchanged.",
      updateTrackingSchema,
      async (args) => {
        const trackingInfoInput: Record<string, unknown> = {};
        if (args.company !== undefined) trackingInfoInput.company = args.company;
        if (args.number !== undefined) trackingInfoInput.number = args.number;
        if (args.url !== undefined) trackingInfoInput.url = args.url;
  
        const data = await client.graphql<{
          fulfillmentTrackingInfoUpdate: {
            fulfillment: FulfillmentNode | null;
            userErrors: ShopifyUserError[];
          };
        }>(FULFILLMENT_TRACKING_UPDATE_MUTATION, {
          fulfillmentId: args.fulfillmentId,
          trackingInfoInput,
          notifyCustomer: args.notifyCustomer,
        });
        throwIfUserErrors(
          data.fulfillmentTrackingInfoUpdate.userErrors,
          "fulfillmentTrackingInfoUpdate",
        );
        const f = data.fulfillmentTrackingInfoUpdate.fulfillment;
        if (!f) {
          return {
            content: [
              { type: "text" as const, text: "fulfillmentTrackingInfoUpdate returned no fulfillment." },
            ],
          };
        }
        const tracking = f.trackingInfo
          .map((t) => [t.company, t.number, t.url].filter(Boolean).join(" | "))
          .filter(Boolean)
          .join("; ");
        return {
          content: [
            {
              type: "text" as const,
              text: `Updated tracking on ${f.id} [${f.status}]${tracking ? `: ${tracking}` : ""}.`,
            },
          ],
        };
      },
    );
  
    server.tool(
      "cancel_fulfillment",
      "Cancel an existing fulfillment — use when an item that was marked shipped won't actually ship (lost in warehouse, address bounced, customer cancelled). Restores remaining quantity on the underlying fulfillment order so the items can be re-fulfilled later. Does NOT issue a refund — combine with order-level refund tools if money needs to come back to the customer. Returns the new fulfillment status (typically CANCELLED).",
      cancelFulfillmentSchema,
      async (args) => {
        const data = await client.graphql<{
          fulfillmentCancel: {
            fulfillment: FulfillmentNode | null;
            userErrors: ShopifyUserError[];
          };
        }>(FULFILLMENT_CANCEL_MUTATION, { id: args.id });
        throwIfUserErrors(data.fulfillmentCancel.userErrors, "fulfillmentCancel");
        const f = data.fulfillmentCancel.fulfillment;
        return {
          content: [
            {
              type: "text" as const,
              text: f
                ? `Cancelled fulfillment ${f.id} — new status: ${f.status}`
                : `Cancelled fulfillment ${args.id}.`,
            },
          ],
        };
      },
    );
  }

• src/server.ts:21-65 (registration)

  Import and invocation of registerFulfillmentTools to register all fulfillment tools on the MCP server during initialization.

  import { registerFulfillmentTools } from "./tools/fulfillment.js";
  import { registerWebhookTools } from "./tools/webhooks.js";
  import { registerMetaobjectTools } from "./tools/metaobjects.js";
  import { registerAnalyticsTools } from "./tools/analytics.js";
  import { registerBridgeTools } from "./tools/bridge.js";
  
  export interface ServerConfig {
    host: string;
    port: number;
    shopifyStore: string;
    shopifyAccessToken: string;
    shopifyApiVersion?: string;
    comfyUIUrl?: string;
    comfyUIPublicUrl?: string;
    comfyUIDefaultCkpt: string;
  }
  
  interface Session {
    server: McpServer;
    transport: StreamableHTTPServerTransport;
  }
  
  function buildContext(config: ServerConfig) {
    const shopify = new ShopifyClient({
      store: config.shopifyStore,
      accessToken: config.shopifyAccessToken,
      apiVersion: config.shopifyApiVersion,
    });
    const comfyui = config.comfyUIUrl
      ? new ComfyUIClient({
          baseUrl: config.comfyUIUrl,
          publicUrl: config.comfyUIPublicUrl ?? config.comfyUIUrl,
        })
      : null;
    const buildServer = () => {
      const s = new McpServer({ name: "shopify-mcp", version: "0.1.0" });
      registerProductTools(s, shopify);
      registerOrderTools(s, shopify);
      registerInventoryTools(s, shopify);
      registerCustomerTools(s, shopify);
      registerMetafieldTools(s, shopify);
      registerDraftOrderTools(s, shopify);
      registerCollectionTools(s, shopify);
      registerVariantTools(s, shopify);
      registerFulfillmentTools(s, shopify);

• src/shopify/client.ts:65-75 (helper)

  throwIfUserErrors helper used by the handler to check and throw on Shopify API user errors.

  export function throwIfUserErrors(
    errors: ShopifyUserError[] | undefined,
    operation: string,
  ): void {
    if (!errors || errors.length === 0) return;
    const messages = errors
      .map((e) => (e.field ? `${e.field.join(".")}: ${e.message}` : e.message))
      .join("; ");
    throw new Error(`Shopify ${operation} userErrors: ${messages}`);
  }