list_metaobjects

Instructions

Implementation Reference

• src/tools/metaobjects.ts:308-343 (handler)

  Handler function for the list_metaobjects tool. Sends a GraphQL query (LIST_METAOBJECTS_QUERY) to fetch metaobjects of a given type, paginated, and returns formatted text with each metaobject's display name, status, handle, and GID.

  server.tool(
    "list_metaobjects",
    "List instances of a single metaobject type — e.g. all 'lookbook' or 'product_feature' entries. Returns each metaobject's display name, handle, GID, and (when the type is publishable) ACTIVE/DRAFT status. The type handle comes from list_metaobject_definitions. Cursor-paginated; pass `after` to advance pages. To inspect an individual metaobject's full field values, follow up with get_metaobject.",
    listMetaobjectsSchema,
    async (args) => {
      const data = await client.graphql<{
        metaobjects: Connection<MetaobjectNode>;
      }>(LIST_METAOBJECTS_QUERY, {
        type: args.type,
        first: args.first,
        after: args.after,
      });
      const edges = data.metaobjects.edges;
      if (edges.length === 0) {
        return {
          content: [
            {
              type: "text" as const,
              text: `No metaobjects of type "${args.type}".`,
            },
          ],
        };
      }
      const rows: string[] = [
        `Found ${edges.length} metaobject(s) of type "${args.type}":`,
      ];
      for (const { node } of edges) {
        const status = node.capabilities?.publishable?.status;
        const label = node.displayName ?? node.handle;
        rows.push(`  ${label}${status ? ` [${status}]` : ""} — ${node.handle} — ${node.id}`);
      }
      return {
        content: [{ type: "text" as const, text: rows.join("\n") }],
      };
    },
  );

• src/tools/metaobjects.ts:168-185 (schema)

  Zod schema defining the input parameters for list_metaobjects: type (string), first (page size, default 25), and after (optional pagination cursor).

  const listMetaobjectsSchema = {
    type: z
      .string()
      .describe(
        "Metaobject type handle (e.g. 'lookbook', 'product_feature', '$app:landing_page'). Get valid values from list_metaobject_definitions. Custom app namespaces use the '$app:' prefix.",
      ),
    first: z
      .number()
      .int()
      .min(1)
      .max(100)
      .default(25)
      .describe("Page size (1-100)."),
    after: z
      .string()
      .optional()
      .describe("Cursor from a prior page's pageInfo. Omit on the first call."),
  };

• src/server.ts:23-67 (registration)

  Registration point: the tool is registered via registerMetaobjectTools() called in buildContext().

  import { registerMetaobjectTools } from "./tools/metaobjects.js";
  import { registerAnalyticsTools } from "./tools/analytics.js";
  import { registerBridgeTools } from "./tools/bridge.js";
  
  export interface ServerConfig {
    host: string;
    port: number;
    shopifyStore: string;
    shopifyAccessToken: string;
    shopifyApiVersion?: string;
    comfyUIUrl?: string;
    comfyUIPublicUrl?: string;
    comfyUIDefaultCkpt: string;
  }
  
  interface Session {
    server: McpServer;
    transport: StreamableHTTPServerTransport;
  }
  
  function buildContext(config: ServerConfig) {
    const shopify = new ShopifyClient({
      store: config.shopifyStore,
      accessToken: config.shopifyAccessToken,
      apiVersion: config.shopifyApiVersion,
    });
    const comfyui = config.comfyUIUrl
      ? new ComfyUIClient({
          baseUrl: config.comfyUIUrl,
          publicUrl: config.comfyUIPublicUrl ?? config.comfyUIUrl,
        })
      : null;
    const buildServer = () => {
      const s = new McpServer({ name: "shopify-mcp", version: "0.1.0" });
      registerProductTools(s, shopify);
      registerOrderTools(s, shopify);
      registerInventoryTools(s, shopify);
      registerCustomerTools(s, shopify);
      registerMetafieldTools(s, shopify);
      registerDraftOrderTools(s, shopify);
      registerCollectionTools(s, shopify);
      registerVariantTools(s, shopify);
      registerFulfillmentTools(s, shopify);
      registerWebhookTools(s, shopify);
      registerMetaobjectTools(s, shopify);

• src/tools/metaobjects.ts:66-84 (helper)

  GraphQL query used by the list_metaobjects handler to fetch paginated metaobject instances of a given type.

  const LIST_METAOBJECTS_QUERY = /* GraphQL */ `
    query ListMetaobjects($type: String!, $first: Int!, $after: String) {
      metaobjects(type: $type, first: $first, after: $after) {
        edges {
          cursor
          node {
            id
            type
            handle
            displayName
            updatedAt
            capabilities { publishable { status } }
            fields { key type value }
          }
        }
        pageInfo { hasNextPage hasPreviousPage startCursor endCursor }
      }
    }
  `;