list_metaobject_definitions

Instructions

Implementation Reference

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

  The tool handler function for 'list_metaobject_definitions'. It executes the GraphQL query, formats results (definition name, type, object count, field definitions), and returns a text response.

  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 (handler)

  The GraphQL query (ListMetaobjectDefinitions) that fetches metaobject definitions from Shopify with pagination support.

  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:154-166 (schema)

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

  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/server.ts:67-67 (registration)

  Registration call: registerMetaobjectTools(s, shopify) is invoked in buildContext to register all metaobject tools including 'list_metaobject_definitions'.

  registerMetaobjectTools(s, shopify);

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

  The export function registerMetaobjectTools that uses server.tool() to register the tool with the MCP server.

  export function registerMetaobjectTools(
    server: McpServer,
    client: ShopifyClient,
  ): void {