search_collections
Query and filter stamp collections by name, creator, or sorting criteria to quickly find relevant results on the Stampchain MCP Server.
Instructions
Search for stamp collections with various filtering criteria
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| creator | No | Filter by creator address | |
| page | No | Page number | |
| page_size | No | Items per page | |
| query | No | Search query for collection name or description | |
| sort_by | No | Sort field | created_at |
| sort_order | No | Sort order | DESC |
Implementation Reference
- src/tools/collections.ts:252-351 (handler)The execute method in SearchCollectionsTool class that contains the core tool logic: input validation, constructing query params, calling the API's searchCollections method, handling response, formatting results as a table and detailed list 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 and validation rules for the search_collections tool.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)Registration of SearchCollectionsTool class in the collectionTools export object, making it available for tool registry.export const collectionTools = { get_collection: GetCollectionTool, search_collections: SearchCollectionsTool, };
- src/tools/collections.ts:365-370 (registration)Factory function that instantiates SearchCollectionsTool as part of createCollectionTools, used to create tool instances with shared API client.export function createCollectionTools(apiClient?: StampchainClient) { return { get_collection: new GetCollectionTool(apiClient), search_collections: new SearchCollectionsTool(apiClient), }; }
- src/tools/index.ts:47-70 (registration)Lists 'search_collections' in the getAvailableToolNames function, part of central tool registry in index.ts.export function getAvailableToolNames(): string[] { return [ // Stamp tools 'get_stamp', 'search_stamps', 'get_recent_stamps', 'get_recent_sales', 'get_market_data', 'get_stamp_market_data', // Collection tools 'get_collection', 'search_collections', // Token tools 'get_token_info', 'search_tokens', // Analysis tools 'analyze_stamp_code', 'get_stamp_dependencies', 'analyze_stamp_patterns', ]; }