update_metaobject

Instructions

Implementation Reference

• src/tools/metaobjects.ts:422-462 (registration)

  Registration of the update_metaobject tool using server.tool(), registering the tool name, description, schema, and handler on the MCP server.

  server.tool(
    "update_metaobject",
    "Update an existing metaobject's handle, field values, or publishable status. Fields are upserted by key — pass only the fields you want to change; omitted fields keep their current values. To clear a field, pass an empty string or null-ish value matching the field type. If you change the handle, set redirectNewHandle=true to have Shopify redirect from the old handle on the storefront. The `type` cannot be changed by this tool — delete and recreate to change type.",
    updateMetaobjectSchema,
    async (args) => {
      const metaobject: Record<string, unknown> = {};
      if (args.handle !== undefined) metaobject.handle = args.handle;
      if (args.fields) metaobject.fields = args.fields;
      if (args.redirectNewHandle !== undefined) {
        metaobject.redirectNewHandle = args.redirectNewHandle;
      }
      if (args.status) {
        metaobject.capabilities = {
          publishable: { status: args.status },
        };
      }
      const data = await client.graphql<{
        metaobjectUpdate: {
          metaobject: MetaobjectNode | null;
          userErrors: ShopifyUserError[];
        };
      }>(METAOBJECT_UPDATE_MUTATION, { id: args.id, metaobject });
      throwIfUserErrors(data.metaobjectUpdate.userErrors, "metaobjectUpdate");
      const m = data.metaobjectUpdate.metaobject;
      if (!m) {
        return {
          content: [
            { type: "text" as const, text: "metaobjectUpdate returned no metaobject." },
          ],
        };
      }
      return {
        content: [
          {
            type: "text" as const,
            text: `Updated metaobject ${m.displayName ?? m.handle} (${m.type}) — ${m.id}`,
          },
        ],
      };
    },
  );

• src/tools/metaobjects.ts:426-461 (handler)

  Handler function for the update_metaobject tool. Builds the metaobject payload from args (handle, fields, redirectNewHandle, status), calls the Shopify GraphQL API with METAOBJECT_UPDATE_MUTATION, throws on user errors, and returns a success message with the updated metaobject's display name, type, and GID.

  async (args) => {
    const metaobject: Record<string, unknown> = {};
    if (args.handle !== undefined) metaobject.handle = args.handle;
    if (args.fields) metaobject.fields = args.fields;
    if (args.redirectNewHandle !== undefined) {
      metaobject.redirectNewHandle = args.redirectNewHandle;
    }
    if (args.status) {
      metaobject.capabilities = {
        publishable: { status: args.status },
      };
    }
    const data = await client.graphql<{
      metaobjectUpdate: {
        metaobject: MetaobjectNode | null;
        userErrors: ShopifyUserError[];
      };
    }>(METAOBJECT_UPDATE_MUTATION, { id: args.id, metaobject });
    throwIfUserErrors(data.metaobjectUpdate.userErrors, "metaobjectUpdate");
    const m = data.metaobjectUpdate.metaobject;
    if (!m) {
      return {
        content: [
          { type: "text" as const, text: "metaobjectUpdate returned no metaobject." },
        ],
      };
    }
    return {
      content: [
        {
          type: "text" as const,
          text: `Updated metaobject ${m.displayName ?? m.handle} (${m.type}) — ${m.id}`,
        },
      ],
    };
  },

• src/tools/metaobjects.ts:221-249 (schema)

  Input schema for update_metaobject using Zod. Defines the 'id' (required), 'handle', 'fields', 'status', and 'redirectNewHandle' (all optional) parameters with descriptions.

  const updateMetaobjectSchema = {
    id: z
      .string()
      .describe("GID of the metaobject to update."),
    handle: z
      .string()
      .optional()
      .describe(
        "New handle. Changes the storefront URL slug. Pair with redirectNewHandle=true to keep old links working.",
      ),
    fields: z
      .array(fieldInputSchema)
      .optional()
      .describe(
        "Field-level upserts: only the keys present here are written; other fields keep their current values. Pass empty string to clear a field.",
      ),
    status: z
      .enum(["ACTIVE", "DRAFT"])
      .optional()
      .describe(
        "New publishable status (only for publishable types). Omit to leave unchanged.",
      ),
    redirectNewHandle: z
      .boolean()
      .optional()
      .describe(
        "If true and `handle` is being changed, Shopify creates a 301 redirect from the old handle to the new one on the storefront.",
      ),
  };

• src/tools/metaobjects.ts:116-130 (helper)

  GraphQL mutation used by the update_metaobject handler. Sends 'id' and 'metaobject' (MetaobjectUpdateInput) to Shopify's metaobjectUpdate endpoint and returns the updated metaobject with fields and capabilities.

  const METAOBJECT_UPDATE_MUTATION = /* GraphQL */ `
    mutation MetaobjectUpdate($id: ID!, $metaobject: MetaobjectUpdateInput!) {
      metaobjectUpdate(id: $id, metaobject: $metaobject) {
        metaobject {
          id
          type
          handle
          displayName
          fields { key type value }
          capabilities { publishable { status } }
        }
        userErrors { field message code }
      }
    }
  `;

• src/tools/metaobjects.ts:271-273 (registration)

  The exported registration function that wires all metaobject tools (including update_metaobject) into the MCP server instance.

  export function registerMetaobjectTools(
    server: McpServer,
    client: ShopifyClient,