get_collection
Retrieve a single Shopify collection by GID, returning its title, handle, sort order, description, and the first N products. Set productsFirst to 0 for metadata-only. Indicates if more products exist.
Instructions
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.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Collection GID, e.g. 'gid://shopify/Collection/123456'. Get one from list_collections. | |
| productsFirst | No | How many products to include alongside the collection. Pass 0 to skip products entirely (faster for collection-only metadata). |
Implementation Reference
- src/tools/collections.ts:290-349 (handler)The main handler function for the 'get_collection' tool. It executes a GraphQL query to fetch a single collection by GID, including its products, and returns a formatted text view.
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)Input schema for get_collection: requires 'id' (collection GID string) and optional 'productsFirst' (number, 0-100, default 20).
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:290-349 (registration)Registration of the tool via server.tool() call with name 'get_collection', description, schema, and handler function. This is inside registerCollectionTools().
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:36-61 (helper)The GraphQL query used by the get_collection handler to fetch collection data and its 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/server.ts:63-63 (registration)Where registerCollectionTools is called to register all collection tools (including get_collection) on the MCP server.
registerCollectionTools(s, shopify);