search_collections
Find stamp collections by name, description, or creator address with sorting and pagination options for Bitcoin Stamps data.
Instructions
Search for stamp collections with various filtering criteria
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | Search query for collection name or description | |
| creator | No | Filter by creator address | |
| sort_by | No | Sort field | created_at |
| sort_order | No | Sort order | DESC |
| page | No | Page number | |
| page_size | No | Items per page |
Implementation Reference
- src/tools/collections.ts:252-351 (handler)The execute method of the SearchCollectionsTool class, which validates input parameters, constructs query params, calls the Stampchain API's searchCollections method, formats the results into a table and detailed view, and returns a multi-response with metadata.public async execute( params: SearchCollectionsParams, context?: ToolContext ): Promise<ToolResponse> { try { context?.logger?.info('Executing search_collections tool', { params }); // Validate parameters const validatedParams = this.validateParams(params); // Build query parameters const queryParams = { query: validatedParams.query, creator: validatedParams.creator, sort_by: validatedParams.sort_by, sort_order: validatedParams.sort_order, page: validatedParams.page, page_size: validatedParams.page_size, }; // Remove undefined values Object.keys(queryParams).forEach((key) => { if (queryParams[key as keyof typeof queryParams] === undefined) { delete queryParams[key as keyof typeof queryParams]; } }); // Search collections const searchResponse = await this.apiClient.searchCollections(queryParams); if (!searchResponse || searchResponse.length === 0) { return textResponse('No collections found matching the search criteria'); } // Note: searchCollections returns CollectionResponse[] directly const collections = searchResponse; // Create summary const lines = [`Found ${collections.length} collections`]; lines.push('---'); // Create table view const collectionTable = createTable(collections, [ { key: 'collection_name', label: 'Name' }, { key: 'collection_id', label: 'ID', format: (v: unknown) => (typeof v === 'string' ? v.substring(0, 8) + '...' : String(v)), }, { key: 'creators', label: 'Creators', format: (v: unknown) => Array.isArray(v) ? v.join(', ').substring(0, 20) + (v.join(', ').length > 20 ? '...' : '') : String(v), }, { key: 'stamp_count', label: 'Stamps' }, { key: 'total_editions', label: 'Editions' }, ]); lines.push(collectionTable); // Add detailed view for each collection lines.push('\n\nDetailed View:'); lines.push('---'); collections.forEach((collection, index) => { lines.push(`\n${index + 1}. ${collection.collection_name}`); lines.push(` ID: ${collection.collection_id}`); lines.push(` Creators: ${collection.creators.join(', ')}`); lines.push(` Stamps: ${collection.stamp_count}`); lines.push(` Total Editions: ${collection.total_editions}`); if (collection.collection_description) { lines.push( ` Description: ${collection.collection_description.substring(0, 100)}${collection.collection_description.length > 100 ? '...' : ''}` ); } }); // Include metadata const metadata = { results_count: collections.length, query_params: queryParams, }; return multiResponse( { type: 'text', text: lines.join('\n') }, { type: 'text', text: `\n\nSearch Metadata:\n${JSON.stringify(metadata, null, 2)}` } ); } catch (error) { context?.logger?.error('Error executing search_collections tool', { error }); if (error instanceof ValidationError) { throw error; } throw new ToolExecutionError('Failed to search collections', this.name, error); } }
- src/schemas/collections.ts:85-96 (schema)Zod schema defining the input parameters for the search_collections tool, including optional query, creator filter, sorting options, and pagination.export const SearchCollectionsParamsSchema = z.object({ query: z.string().optional().describe('Search query for collection name or description'), creator: z.string().optional().describe('Filter by creator address'), sort_by: z .enum(['created_at', 'stamp_count', 'name']) .optional() .default('created_at') .describe('Sort field'), sort_order: z.enum(['ASC', 'DESC']).optional().default('DESC').describe('Sort order'), page: z.number().int().positive().optional().default(1).describe('Page number'), page_size: z.number().int().positive().max(100).optional().default(20).describe('Items per page'), });
- src/tools/collections.ts:357-360 (registration)Export of the collectionTools object that registers the SearchCollectionsTool class under the 'search_collections' key.export const collectionTools = { get_collection: GetCollectionTool, search_collections: SearchCollectionsTool, };
- src/tools/index.ts:28-42 (registration)The createAllTools function in the central tools index that instantiates and includes the search_collections tool via createCollectionTools(client) in the spread of all tools.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, }; }
- src/tools/collections.ts:365-369 (helper)Factory function that creates instances of SearchCollectionsTool for use in the tools registry.export function createCollectionTools(apiClient?: StampchainClient) { return { get_collection: new GetCollectionTool(apiClient), search_collections: new SearchCollectionsTool(apiClient), };