list_metaobject_definitions

Instructions

Implementation Reference

• src/tools/metaobjects.ts:275-306 (handler)

  The tool handler registration for 'list_metaobject_definitions' — calls the GraphQL query LIST_METAOBJECT_DEFINITIONS_QUERY and formats the response as text.

  server.tool(
    "list_metaobject_definitions",
    "List the metaobject definitions (custom types/schemas) registered on this Shopify store, with their field definitions. Each definition declares a `type` handle, a set of typed fields, and which fields are required. Use this tool to discover what custom data shapes the store supports before calling list_metaobjects (which queries instances of one type) or create_metaobject (which creates a new instance). Cursor-paginated.",
    listDefinitionsSchema,
    async (args) => {
      const data = await client.graphql<{
        metaobjectDefinitions: Connection<MetaobjectDefinitionNode>;
      }>(LIST_METAOBJECT_DEFINITIONS_QUERY, {
        first: args.first,
        after: args.after,
      });
      const edges = data.metaobjectDefinitions.edges;
      if (edges.length === 0) {
        return {
          content: [
            { type: "text" as const, text: "No metaobject definitions on this store." },
          ],
        };
      }
      const rows: string[] = [`Found ${edges.length} definition(s):`];
      for (const { node } of edges) {
        rows.push(`  ${node.name} (${node.type}) — ${node.metaobjectsCount ?? "?"} objects — ${node.id}`);
        for (const f of node.fieldDefinitions) {
          const req = f.required ? "*" : "";
          rows.push(`    - ${f.key}${req}: ${f.type.name}`);
        }
      }
      return {
        content: [{ type: "text" as const, text: rows.join("\n") }],
      };
    },
  );

• src/tools/metaobjects.ts:154-166 (schema)

  Input schema (listDefinitionsSchema) for the tool: 'first' (page size, default 25, 1-100) and 'after' (optional cursor).

  const listDefinitionsSchema = {
    first: z
      .number()
      .int()
      .min(1)
      .max(100)
      .default(25)
      .describe("Page size (1-100). 25 is usually plenty — most stores have <50 metaobject types total."),
    after: z
      .string()
      .optional()
      .describe("Cursor from a prior page's pageInfo. Omit on the first call."),
  };

• src/tools/metaobjects.ts:275-306 (registration)

  Registration via server.tool('list_metaobject_definitions', ...) inside registerMetaobjectTools(), which is called from src/server.ts line 67.

  server.tool(
    "list_metaobject_definitions",
    "List the metaobject definitions (custom types/schemas) registered on this Shopify store, with their field definitions. Each definition declares a `type` handle, a set of typed fields, and which fields are required. Use this tool to discover what custom data shapes the store supports before calling list_metaobjects (which queries instances of one type) or create_metaobject (which creates a new instance). Cursor-paginated.",
    listDefinitionsSchema,
    async (args) => {
      const data = await client.graphql<{
        metaobjectDefinitions: Connection<MetaobjectDefinitionNode>;
      }>(LIST_METAOBJECT_DEFINITIONS_QUERY, {
        first: args.first,
        after: args.after,
      });
      const edges = data.metaobjectDefinitions.edges;
      if (edges.length === 0) {
        return {
          content: [
            { type: "text" as const, text: "No metaobject definitions on this store." },
          ],
        };
      }
      const rows: string[] = [`Found ${edges.length} definition(s):`];
      for (const { node } of edges) {
        rows.push(`  ${node.name} (${node.type}) — ${node.metaobjectsCount ?? "?"} objects — ${node.id}`);
        for (const f of node.fieldDefinitions) {
          const req = f.required ? "*" : "";
          rows.push(`    - ${f.key}${req}: ${f.type.name}`);
        }
      }
      return {
        content: [{ type: "text" as const, text: rows.join("\n") }],
      };
    },
  );

• src/tools/metaobjects.ts:41-64 (helper)

  The LIST_METAOBJECT_DEFINITIONS_QUERY GraphQL query used by the handler to fetch metaobject definitions from Shopify.

  const LIST_METAOBJECT_DEFINITIONS_QUERY = /* GraphQL */ `
    query ListMetaobjectDefinitions($first: Int!, $after: String) {
      metaobjectDefinitions(first: $first, after: $after) {
        edges {
          cursor
          node {
            id
            name
            type
            description
            metaobjectsCount
            fieldDefinitions {
              key
              name
              type { name }
              required
              description
            }
          }
        }
        pageInfo { hasNextPage hasPreviousPage startCursor endCursor }
      }
    }
  `;

• src/tools/metaobjects.ts:26-39 (helper)

  TypeScript interface MetaobjectDefinitionNode describing the shape of a metaobject definition returned by the GraphQL query.

  interface MetaobjectDefinitionNode {
    id: string;
    name: string;
    type: string;
    description?: string | null;
    metaobjectsCount?: number | null;
    fieldDefinitions: Array<{
      key: string;
      name: string;
      type: { name: string };
      required: boolean;
      description?: string | null;
    }>;
  }