set_metafield

Instructions

Implementation Reference

• src/tools/metafields.ts:121-161 (handler)

  Handler function for the set_metafield tool. Receives ownerId, namespace, key, type, and value, calls the Shopify GraphQL MetafieldsSet mutation, throws on user errors, and returns a success message with the saved metafield details.

  async (args) => {
    const data = await client.graphql<{
      metafieldsSet: {
        metafields: Metafield[];
        userErrors: ShopifyUserError[];
      };
    }>(METAFIELDS_SET_MUTATION, {
      metafields: [
        {
          ownerId: args.ownerId,
          namespace: args.namespace,
          key: args.key,
          type: args.type,
          value: args.value,
        },
      ],
    });
    throwIfUserErrors(data.metafieldsSet.userErrors, "metafieldsSet");
    const mf = data.metafieldsSet.metafields[0];
    if (!mf) {
      return {
        content: [
          { type: "text" as const, text: "metafieldsSet returned no metafield." },
        ],
      };
    }
    return {
      content: [
        {
          type: "text" as const,
          text: [
            "Metafield saved:",
            `  ${mf.namespace}.${mf.key} (${mf.type})`,
            `  = ${mf.value}`,
            `  ID: ${mf.id}`,
            `  Owner: ${mf.ownerType}`,
          ].join("\n"),
        },
      ],
    };
  },

• src/tools/metafields.ts:70-96 (schema)

  Zod schema defining the input parameters for set_metafield: ownerId (GID string), namespace (2-255 chars), key (1-64 chars), type (Shopify metafield type enum), and value (serialized string per type).

  const setMetafieldSchema = {
    ownerId: z
      .string()
      .describe(
        "GID of the resource to attach the metafield to (e.g. gid://shopify/Product/123, gid://shopify/Collection/456, gid://shopify/Customer/789, gid://shopify/Order/...)",
      ),
    namespace: z
      .string()
      .min(2)
      .max(255)
      .describe("Metafield namespace (2-255 chars). Convention: app-specific prefix."),
    key: z
      .string()
      .min(1)
      .max(64)
      .describe("Metafield key within the namespace (1-64 chars)."),
    type: z
      .string()
      .describe(
        "Metafield type: 'single_line_text_field', 'multi_line_text_field', 'number_integer', 'number_decimal', 'boolean', 'json', 'url', 'date', 'date_time', 'rating', 'color', 'weight', 'volume', 'dimension', 'money', 'rich_text_field', or reference types like 'product_reference', 'collection_reference', 'file_reference'.",
      ),
    value: z
      .string()
      .describe(
        "Metafield value, serialized per the type. JSON/reference types take a JSON string; primitives take the literal string.",
      ),
  };

• src/tools/metafields.ts:117-162 (registration)

  Registration of the "set_metafield" tool on the MCP server with its description, schema, and handler.

  server.tool(
    "set_metafield",
    "Create or update (upsert) a single metafield on any supported Shopify resource — product, variant, collection, customer, order, draft order, shop, or shop policies. The (ownerId, namespace, key) triple is the unique identifier; calling this tool with an existing triple replaces the value, otherwise creates a new metafield. The `type` must be a Shopify-supported metafield type and the `value` must serialize per that type — e.g. JSON types take a JSON string, references take a target GID, primitives take literal text. Errors come back as MCP tool errors with the validation messages from Shopify.",
    setMetafieldSchema,
    async (args) => {
      const data = await client.graphql<{
        metafieldsSet: {
          metafields: Metafield[];
          userErrors: ShopifyUserError[];
        };
      }>(METAFIELDS_SET_MUTATION, {
        metafields: [
          {
            ownerId: args.ownerId,
            namespace: args.namespace,
            key: args.key,
            type: args.type,
            value: args.value,
          },
        ],
      });
      throwIfUserErrors(data.metafieldsSet.userErrors, "metafieldsSet");
      const mf = data.metafieldsSet.metafields[0];
      if (!mf) {
        return {
          content: [
            { type: "text" as const, text: "metafieldsSet returned no metafield." },
          ],
        };
      }
      return {
        content: [
          {
            type: "text" as const,
            text: [
              "Metafield saved:",
              `  ${mf.namespace}.${mf.key} (${mf.type})`,
              `  = ${mf.value}`,
              `  ID: ${mf.id}`,
              `  Owner: ${mf.ownerType}`,
            ].join("\n"),
          },
        ],
      };
    },
  );

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

  Call-site where the metafield tools are registered on the MCP server during server initialization.

  registerMetafieldTools(s, shopify);

• src/tools/metafields.ts:19-35 (helper)

  GraphQL mutation string used by set_metafield to send the MetafieldsSet mutation to the Shopify Admin API.

  const METAFIELDS_SET_MUTATION = /* GraphQL */ `
    mutation MetafieldsSet($metafields: [MetafieldsSetInput!]!) {
      metafieldsSet(metafields: $metafields) {
        metafields {
          id
          namespace
          key
          type
          value
          ownerType
          createdAt
          updatedAt
        }
        userErrors { field message code }
      }
    }
  `;