get_collection
Retrieve detailed information about a stamp collection using its ID, optionally including stamps with pagination. Works with Stampchain MCP Server for querying Bitcoin Stamps data without authentication.
Instructions
Retrieve detailed information about a specific stamp collection by its ID
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| collection_id | Yes | The ID of the collection to retrieve | |
| include_stamps | No | Whether to include stamps in the collection | |
| stamps_limit | No | Number of stamps per page | |
| stamps_page | No | Page number for stamps if included |
Implementation Reference
- src/tools/collections.ts:78-182 (handler)The `execute` method in `GetCollectionTool` class implements the core handler logic for the 'get_collection' tool. It validates params, searches for the collection using Stampchain API, formats the response with collection details and optional stamps table, and returns a multi-response.public async execute(params: GetCollectionParams, context?: ToolContext): Promise<ToolResponse> { try { context?.logger?.info('Executing get_collection tool', { params }); // Validate parameters const validatedParams = this.validateParams(params); // Since the API doesn't have a direct getCollection method, // we'll search for collections with the specific ID const collectionResponse = await this.apiClient.searchCollections({ query: validatedParams.collection_id, page: 1, page_size: 1, }); if (!collectionResponse || collectionResponse.length === 0) { throw new ToolExecutionError( `Collection with ID ${validatedParams.collection_id} not found`, this.name, { collectionId: validatedParams.collection_id } ); } const collection = collectionResponse[0]; const contents = []; // Add formatted collection info const collectionInfo = [ `Collection: ${collection.collection_name}`, `ID: ${collection.collection_id}`, `Description: ${collection.collection_description}`, `Creators: ${collection.creators.join(', ')}`, `Stamps: ${collection.stamp_count}`, `Total Editions: ${collection.total_editions}`, ].join('\n'); contents.push({ type: 'text' as const, text: collectionInfo }); // If stamps are requested, fetch them if (validatedParams.include_stamps) { try { const stampsResponse = await this.apiClient.searchStamps({ collection_id: validatedParams.collection_id, page: validatedParams.stamps_page, page_size: validatedParams.stamps_limit, }); if (stampsResponse && stampsResponse.length > 0) { contents.push({ type: 'text' as const, text: `\n\nStamps in Collection (Page ${validatedParams.stamps_page}):\n`, }); const stampTable = createTable(stampsResponse, [ { key: 'stamp', label: 'ID' }, { key: 'cpid', label: 'CPID' }, { key: 'creator', label: 'Creator', format: (v: unknown) => typeof v === 'string' ? v.substring(0, 12) + '...' : String(v), }, { key: 'supply', label: 'Supply' }, { key: 'floorPrice', label: 'Floor Price', format: (v: unknown) => (v ? `${String(v)} BTC` : 'N/A'), }, ]); contents.push({ type: 'text' as const, text: stampTable }); contents.push({ type: 'text' as const, text: `\nTotal stamps in collection: ${stampsResponse.length}`, }); } } catch (error) { context?.logger?.warn('Failed to fetch stamps for collection', { error }); contents.push({ type: 'text' as const, text: '\n\nNote: Unable to fetch stamps for this collection', }); } } // Add JSON representation contents.push({ type: 'text' as const, text: JSON.stringify(collection, null, 2), }); return multiResponse(...contents); } catch (error) { context?.logger?.error('Error executing get_collection tool', { error }); if (error instanceof ValidationError) { throw error; } if (error instanceof ToolExecutionError) { throw error; } throw new ToolExecutionError('Failed to retrieve collection information', this.name, error); } }
- src/schemas/collections.ts:58-80 (schema)Zod schema `GetCollectionParamsSchema` defining the input parameters and validation for the get_collection tool.export const GetCollectionParamsSchema = z.object({ collection_id: z.string().describe('The ID of the collection to retrieve'), include_stamps: z .boolean() .optional() .default(false) .describe('Whether to include stamps in the collection'), stamps_page: z .number() .int() .positive() .optional() .default(1) .describe('Page number for stamps if included'), stamps_limit: z .number() .int() .positive() .max(100) .optional() .default(20) .describe('Number of stamps per page'), });
- src/tools/collections.ts:357-360 (registration)Registration of GetCollectionTool under the key 'get_collection' in the collectionTools export object.export const collectionTools = { get_collection: GetCollectionTool, search_collections: SearchCollectionsTool, };
- src/tools/collections.ts:365-370 (registration)Factory function `createCollectionTools` that instantiates and registers the get_collection tool instance.export function createCollectionTools(apiClient?: StampchainClient) { return { get_collection: new GetCollectionTool(apiClient), search_collections: new SearchCollectionsTool(apiClient), }; }
- src/tools/index.ts:28-42 (registration)Global factory `createAllTools` that includes the collection tools (thus get_collection) by spreading createCollectionTools result.export function createAllTools(apiClient?: StampchainClient): Record<string, ITool> { const client = apiClient || new StampchainClient(); const stamps = createStampTools(client); const collections = createCollectionTools(client); const tokens = createTokenTools(client); const analysis = createStampAnalysisTools(client); return { ...stamps, ...collections, ...tokens, ...analysis, }; }