get_stamp
Retrieve detailed information about a specific Bitcoin stamp using its ID, including optional base64 image data for verification and display purposes.
Instructions
Retrieve detailed information about a specific Bitcoin stamp by its ID
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| stamp_id | Yes | The ID of the stamp to retrieve | |
| include_base64 | No | Whether to include base64 image data |
Implementation Reference
- src/tools/stamps.ts:33-115 (handler)The GetStampTool class implements the core handler logic for the 'get_stamp' MCP tool. It handles input validation, API calls to fetch stamp data, response formatting, and error handling.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 and TypeScript type for validating input parameters to the get_stamp tool (stamp_id required, include_base64 optional).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)Registration of the GetStampTool class under the tool name 'get_stamp' 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/api/stampchain-client.ts:341-344 (helper)StampchainClient.getStamp method called by the tool handler to fetch stamp data from the API endpoint `/stamps/${stampId}`.async getStamp(stampId: number): Promise<Stamp> { const response = await this.client.get<StampResponse>(`/stamps/${stampId}`); return response.data.data.stamp; }
- src/tools/stamps.ts:828-837 (registration)Factory function createStampTools that instantiates the GetStampTool for 'get_stamp' with optional API client.export function createStampTools(apiClient?: StampchainClient) { return { get_stamp: new GetStampTool(apiClient), search_stamps: new SearchStampsTool(apiClient), get_recent_stamps: new GetRecentStampsTool(apiClient), get_recent_sales: new GetRecentSalesTool(apiClient), get_market_data: new GetMarketDataTool(apiClient), get_stamp_market_data: new GetStampMarketDataTool(apiClient), }; }