get_stamp
Retrieve detailed information about a specific Bitcoin stamp, including optional base64 image data, using its unique ID from the Stampchain MCP Server’s Bitcoin Stamps API, enabling efficient data queries without authentication.
Instructions
Retrieve detailed information about a specific Bitcoin stamp by its ID
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| include_base64 | No | Whether to include base64 image data | |
| stamp_id | Yes | The ID of the stamp to retrieve |
Implementation Reference
- src/tools/stamps.ts:71-114 (handler)Execute method of GetStampTool class - core handler logic that validates input, fetches stamp data from StampchainClient, formats and returns response.public async execute(params: GetStampParams, context?: ToolContext): Promise<ToolResponse> { try { context?.logger?.info('Executing get_stamp tool', { params }); // Validate parameters const validatedParams = this.validateParams(params); const stampId = parseStampId(validatedParams.stamp_id); // Use API client from context if available, otherwise use instance client const client = context?.apiClient || this.apiClient; // Fetch stamp data const stamp: Stamp = await client.getStamp(stampId); if (!stamp) { throw new ToolExecutionError(`Stamp with ID ${stampId} not found`, this.name, { stampId }); } // Format the response const formattedStamp = formatStamp(stamp, { includeBase64: validatedParams.include_base64, }); // Return both formatted text and JSON data return multiResponse({ type: 'text', text: formattedStamp }, stampToJSON(stamp)); } catch (error) { context?.logger?.error('Error executing get_stamp 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 retrieve stamp information', this.name, error); } }
- src/tools/stamps.ts:33-115 (handler)Full GetStampTool class definition including name 'get_stamp', schema, metadata, constructor, and execute handler.export class GetStampTool extends BaseTool<z.input<typeof GetStampParamsSchema>, GetStampParams> { public readonly name = 'get_stamp'; public readonly description = 'Retrieve detailed information about a specific Bitcoin stamp by its ID'; public readonly inputSchema: MCPTool['inputSchema'] = { type: 'object', properties: { stamp_id: { type: ['number', 'string'], description: 'The ID of the stamp to retrieve', }, include_base64: { type: 'boolean', description: 'Whether to include base64 image data', default: false, }, }, required: ['stamp_id'], }; public readonly schema = GetStampParamsSchema; public readonly metadata = { version: '1.0.0', tags: ['stamps', 'query'], requiresNetwork: true, apiDependencies: ['stampchain'], }; private apiClient: StampchainClient; constructor(apiClient?: StampchainClient) { super(); this.apiClient = apiClient || new StampchainClient(); } public async execute(params: GetStampParams, context?: ToolContext): Promise<ToolResponse> { try { context?.logger?.info('Executing get_stamp tool', { params }); // Validate parameters const validatedParams = this.validateParams(params); const stampId = parseStampId(validatedParams.stamp_id); // Use API client from context if available, otherwise use instance client const client = context?.apiClient || this.apiClient; // Fetch stamp data const stamp: Stamp = await client.getStamp(stampId); if (!stamp) { throw new ToolExecutionError(`Stamp with ID ${stampId} not found`, this.name, { stampId }); } // Format the response const formattedStamp = formatStamp(stamp, { includeBase64: validatedParams.include_base64, }); // Return both formatted text and JSON data return multiResponse({ type: 'text', text: formattedStamp }, stampToJSON(stamp)); } catch (error) { context?.logger?.error('Error executing get_stamp 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 retrieve stamp information', this.name, error); } } }
- src/schemas/stamps.ts:175-194 (schema)Zod schema for get_stamp tool input parameters: stamp_id (number/string) and optional include_base64.export const GetStampParamsSchema = z.object({ stamp_id: z .union([z.number(), z.string()]) .refine( (val) => { const num = typeof val === 'string' ? parseInt(val, 10) : val; return !isNaN(num) && num > 0; }, { message: 'stamp_id must be a positive number', } ) .transform((val) => { const num = typeof val === 'string' ? parseInt(val, 10) : val; return num; }), include_base64: z.boolean().optional().default(false), }); export type GetStampParams = z.infer<typeof GetStampParamsSchema>;
- src/tools/stamps.ts:816-823 (registration)Export of stampTools object registering GetStampTool as 'get_stamp' for aggregation in index.tsexport 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:28-42 (registration)createAllTools function that instantiates and registers all tools including get_stamp via createStampTools.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, }; }