search_stamps
Use this tool to search Bitcoin stamps by creator, collection, or type, with options to filter results and sort by stamp ID. Query Stampchain MCP Server for detailed Bitcoin Stamps data.
Instructions
Search for Bitcoin stamps with various filtering criteria including creator, collection, and stamp type
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| collection_id | No | Filter by collection ID | |
| cpid | No | Filter by CPID | |
| creator | No | Filter by creator address | |
| is_btc_stamp | No | Filter for BTC stamps only | |
| is_cursed | No | Filter for cursed stamps only | |
| page | No | Page number | |
| page_size | No | Items per page | |
| query | No | Search query string | |
| sort_order | No | Sort order by stamp ID | DESC |
Implementation Reference
- src/tools/stamps.ts:120-271 (handler)The SearchStampsTool class implements the 'search_stamps' tool handler, including the execute method that validates params, calls the Stampchain API, formats results, and handles errors.export class SearchStampsTool extends BaseTool< z.input<typeof SearchStampsParamsSchema>, SearchStampsParams > { public readonly name = 'search_stamps'; public readonly description = 'Search for Bitcoin stamps with various filtering criteria including creator, collection, and stamp type'; public readonly inputSchema: MCPTool['inputSchema'] = { type: 'object', properties: { query: { type: 'string', description: 'Search query string', }, creator: { type: 'string', description: 'Filter by creator address', }, collection_id: { type: 'string', description: 'Filter by collection ID', }, cpid: { type: 'string', description: 'Filter by CPID', }, is_btc_stamp: { type: 'boolean', description: 'Filter for BTC stamps only', }, is_cursed: { type: 'boolean', description: 'Filter for cursed stamps only', }, sort_order: { type: 'string', enum: ['ASC', 'DESC'], description: 'Sort order by stamp ID', default: 'DESC', }, page: { type: 'number', description: 'Page number', minimum: 1, default: 1, }, page_size: { type: 'number', description: 'Items per page', minimum: 1, maximum: 100, default: 20, }, }, required: [], }; public readonly schema = SearchStampsParamsSchema; public readonly metadata = { version: '1.0.0', tags: ['stamps', 'search', 'query'], requiresNetwork: true, apiDependencies: ['stampchain'], }; private apiClient: StampchainClient; constructor(apiClient?: StampchainClient) { super(); this.apiClient = apiClient || new StampchainClient(); } public async execute(params: SearchStampsParams, context?: ToolContext): Promise<ToolResponse> { try { context?.logger?.info('Executing search_stamps tool', { params }); // Validate parameters const validatedParams = this.validateParams(params); // Build query parameters const queryParams = { query: validatedParams.query, creator: validatedParams.creator, collection_id: validatedParams.collection_id, cpid: validatedParams.cpid, is_btc_stamp: validatedParams.is_btc_stamp, is_cursed: validatedParams.is_cursed, 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]; } }); // Use API client from context if available, otherwise use instance client const client = context?.apiClient || this.apiClient; // Search stamps const stamps: Stamp[] = await client.searchStamps(queryParams); if (!stamps || stamps.length === 0) { return textResponse('No stamps found matching the search criteria'); } // Since the API returns an array, we need to handle pagination info differently const total = stamps.length; const page = validatedParams.page || 1; const limit = validatedParams.page_size || 20; // Format the response const formattedList = formatStampList(stamps, total, page, limit); // Include metadata about the search const metadata = { total_results: total, current_page: page, page_size: limit, total_pages: Math.ceil(total / limit), query_params: queryParams, }; return multiResponse( { type: 'text', text: formattedList }, { type: 'text', text: `\nSearch Metadata:\n${JSON.stringify(metadata, null, 2)}` } ); } catch (error) { context?.logger?.error('Error executing search_stamps tool', { error }); if (error instanceof ValidationError) { throw error; } if (error instanceof ToolExecutionError) { throw error; } // Pass through the original error message for API errors if (error instanceof Error) { throw new ToolExecutionError(error.message, this.name, error); } throw new ToolExecutionError('Failed to search stamps', this.name, error); } }
- src/schemas/stamps.ts:199-220 (schema)Zod schema definition for SearchStampsParams used for input validation in the search_stamps tool.export const SearchStampsParamsSchema = z.object({ query: z.string().optional(), creator: z.string().optional(), collection_id: z.string().optional(), cpid: z.string().optional(), is_btc_stamp: z.boolean().optional(), is_cursed: z.boolean().optional(), sort_order: z.enum(['ASC', 'DESC']).optional().default('DESC'), page: z.number().int().min(1).optional().default(1), page_size: z.number().int().min(1).max(100).optional().default(20), limit: z.number().int().min(1).max(1000).optional(), // v2.3: New filtering parameters from_timestamp: z.number().int().positive().optional(), to_timestamp: z.number().int().positive().optional(), min_floor_price: z.number().positive().optional(), max_floor_price: z.number().positive().optional(), activity_level: z.enum(['HOT', 'WARM', 'COOL', 'DORMANT', 'COLD']).optional(), include_market_data: z.boolean().optional().default(false), include_dispenser_info: z.boolean().optional().default(false), }); export type SearchStampsParams = z.infer<typeof SearchStampsParamsSchema>;
- src/tools/stamps.ts:816-823 (registration)Registration of the SearchStampsTool class in the stampTools export object.export const stampTools = { get_stamp: GetStampTool, search_stamps: SearchStampsTool, get_recent_stamps: GetRecentStampsTool, get_recent_sales: GetRecentSalesTool, get_market_data: GetMarketDataTool, get_stamp_market_data: GetStampMarketDataTool, };
- src/tools/index.ts:47-70 (registration)The search_stamps tool is listed in the getAvailableToolNames function, indicating its registration in the overall toolset.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', ]; }
- src/tools/index.ts:75-104 (registration)Metadata registration including search_stamps in the stamps category tools list.export const toolMetadata = { stamps: { category: 'Bitcoin Stamps', description: 'Tools for querying and searching Bitcoin stamps', tools: [ 'get_stamp', 'search_stamps', 'get_recent_stamps', 'get_recent_sales', 'get_market_data', 'get_stamp_market_data', ], }, collections: { category: 'Stamp Collections', description: 'Tools for exploring stamp collections', tools: ['get_collection', 'search_collections'], }, tokens: { category: 'SRC-20 Tokens', description: 'Tools for SRC-20 token information', tools: ['get_token_info', 'search_tokens'], }, analysis: { category: 'Recursive Stamp Analysis', description: 'Tools for analyzing recursive stamp code structure and dependencies', tools: ['analyze_stamp_code', 'get_stamp_dependencies', 'analyze_stamp_patterns'], }, };