get_collection

Instructions

Implementation Reference

• src/tools/collections.ts:290-349 (handler)

  The main handler function for the 'get_collection' tool. It calls the GraphQL query, checks if the collection was found, formats the response with collection metadata and its products, and returns a text-based result.

  server.tool(
    "get_collection",
    "Fetch a single collection by GID with full details — title, handle, sort order, description, and the first N products inside it. Pass productsFirst=0 for metadata-only when you don't need the products array. Returns a friendly text view; pageInfo flags when more products exist beyond the requested page.",
    getCollectionSchema,
    async (args) => {
      const data = await client.graphql<{
        collection:
          | (Collection & {
              products: {
                edges: Array<{
                  node: {
                    id: string;
                    title: string;
                    handle: string;
                    status: string;
                    featuredImage?: { url: string } | null;
                  };
                }>;
                pageInfo: { hasNextPage: boolean };
              };
            })
          | null;
      }>(GET_COLLECTION_QUERY, {
        id: args.id,
        productsFirst: args.productsFirst,
      });
      if (!data.collection) {
        return {
          content: [
            { type: "text" as const, text: `Collection not found: ${args.id}` },
          ],
        };
      }
      const c = data.collection;
      const productLines = c.products.edges.map(
        ({ node }) => `    - ${node.title} [${node.status}] (${node.handle}) — ${node.id}`,
      );
      return {
        content: [
          {
            type: "text" as const,
            text: [
              `${c.title}`,
              `  ID: ${c.id}`,
              `  Handle: ${c.handle}`,
              `  Sort order: ${c.sortOrder ?? "(default)"}`,
              c.description ? `  Description: ${c.description}` : "",
              `  Products (${c.productsCount?.count ?? "?"}):`,
              ...productLines,
              c.products.pageInfo.hasNextPage
                ? "  (more products available; raise productsFirst to page further)"
                : "",
            ]
              .filter(Boolean)
              .join("\n"),
          },
        ],
      };
    },
  );

• src/tools/collections.ts:156-171 (schema)

  The Zod schema for the 'get_collection' tool, defining required 'id' (collection GID) and optional 'productsFirst' (number of products to include) parameters.

  const getCollectionSchema = {
    id: z
      .string()
      .describe(
        "Collection GID, e.g. 'gid://shopify/Collection/123456'. Get one from list_collections.",
      ),
    productsFirst: z
      .number()
      .int()
      .min(0)
      .max(100)
      .default(20)
      .describe(
        "How many products to include alongside the collection. Pass 0 to skip products entirely (faster for collection-only metadata).",
      ),
  };

• src/tools/collections.ts:36-61 (helper)

  The GET_COLLECTION_QUERY GraphQL query used by the handler to fetch collection details including products.

  const GET_COLLECTION_QUERY = /* GraphQL */ `
    query GetCollection($id: ID!, $productsFirst: Int!) {
      collection(id: $id) {
        id
        handle
        title
        description
        sortOrder
        updatedAt
        image { url altText }
        productsCount { count }
        products(first: $productsFirst) {
          edges {
            node {
              id
              title
              handle
              status
              featuredImage { url }
            }
          }
          pageInfo { hasNextPage endCursor }
        }
      }
    }
  `;

• src/tools/collections.ts:290-293 (registration)

  The registration of 'get_collection' with the MCP server via server.tool(), with its name, description, schema reference, and handler.

  server.tool(
    "get_collection",
    "Fetch a single collection by GID with full details — title, handle, sort order, description, and the first N products inside it. Pass productsFirst=0 for metadata-only when you don't need the products array. Returns a friendly text view; pageInfo flags when more products exist beyond the requested page.",
    getCollectionSchema,