create_collection

Instructions

Implementation Reference

• src/tools/collections.ts:355-384 (handler)

  The handler function for the create_collection tool. It builds the GraphQL input from args (title required; optional descriptionHtml, handle, products), executes CREATE_COLLECTION_MUTATION via the Shopify client, checks for user errors, and returns the created collection's title/handle/id.

  async (args) => {
    const input: Record<string, unknown> = { title: args.title };
    if (args.description) input.descriptionHtml = args.description;
    if (args.handle) input.handle = args.handle;
    if (args.productIds) input.products = args.productIds;
  
    const data = await client.graphql<{
      collectionCreate: {
        collection: Collection | null;
        userErrors: ShopifyUserError[];
      };
    }>(CREATE_COLLECTION_MUTATION, { input });
    throwIfUserErrors(data.collectionCreate.userErrors, "collectionCreate");
    const c = data.collectionCreate.collection;
    if (!c) {
      return {
        content: [
          { type: "text" as const, text: "collectionCreate returned no collection." },
        ],
      };
    }
    return {
      content: [
        {
          type: "text" as const,
          text: `Created collection "${c.title}" — ${c.handle} — ${c.id}`,
        },
      ],
    };
  },

• src/tools/collections.ts:173-196 (schema)

  The Zod-based input schema for create_collection. Defines title (required, min 1), description (optional HTML), handle (optional URL slug), and productIds (optional array of product GIDs).

  const createCollectionSchema = {
    title: z
      .string()
      .min(1)
      .describe("Display title shown to shoppers. Required."),
    description: z
      .string()
      .optional()
      .describe(
        "HTML body for the collection page. Plain text works; HTML tags render.",
      ),
    handle: z
      .string()
      .optional()
      .describe(
        "URL slug (e.g. 'summer-sale'). Defaults to a slugified title. Must be unique per shop.",
      ),
    productIds: z
      .array(z.string())
      .optional()
      .describe(
        "Product GIDs to seed into the new (manual) collection. Smart collections built from rules aren't supported by this tool — use the Shopify admin UI for those.",
      ),
  };

• src/tools/collections.ts:351-385 (registration)

  Registration of the 'create_collection' tool on the MCP server via server.tool(), including its description string and schema reference.

  server.tool(
    "create_collection",
    "Create a new manual collection (rule-based 'smart' collections aren't supported here — use the Shopify admin for those). Title is required; description, handle, and an initial product list are optional. Returns the new collection's GID, which you'll need for subsequent add_products_to_collection or update_collection calls. Side effect: collection becomes immediately visible in the storefront unless you've configured publication channels separately.",
    createCollectionSchema,
    async (args) => {
      const input: Record<string, unknown> = { title: args.title };
      if (args.description) input.descriptionHtml = args.description;
      if (args.handle) input.handle = args.handle;
      if (args.productIds) input.products = args.productIds;
  
      const data = await client.graphql<{
        collectionCreate: {
          collection: Collection | null;
          userErrors: ShopifyUserError[];
        };
      }>(CREATE_COLLECTION_MUTATION, { input });
      throwIfUserErrors(data.collectionCreate.userErrors, "collectionCreate");
      const c = data.collectionCreate.collection;
      if (!c) {
        return {
          content: [
            { type: "text" as const, text: "collectionCreate returned no collection." },
          ],
        };
      }
      return {
        content: [
          {
            type: "text" as const,
            text: `Created collection "${c.title}" — ${c.handle} — ${c.id}`,
          },
        ],
      };
    },
  );

• src/tools/collections.ts:63-73 (helper)

  The GraphQL mutation (CREATE_COLLECTION_MUTATION) that creates a collection via Shopify's CollectionCreate mutation.

  const CREATE_COLLECTION_MUTATION = /* GraphQL */ `
    mutation CollectionCreate($input: CollectionInput!) {
      collectionCreate(input: $input) {
        collection {
          id
          handle
          title
        }
        userErrors { field message }
      }
    }

• src/server.ts:63-63 (registration)

  The call to registerCollectionTools(s, shopify) in server.ts that wires all collection tools (including create_collection) into the MCP server.

  registerCollectionTools(s, shopify);