Stampchain MCP Server

Instructions

Implementation Reference

• src/tools/stamps.ts:682-811 (handler)

  GetStampMarketDataTool class: the core handler implementation for the 'get_stamp_market_data' tool. Validates params, calls StampchainClient.getStampMarketData(), formats and returns market data response.
  /** * Tool for retrieving market data for a specific stamp (v2.3 feature) */ export class GetStampMarketDataTool extends BaseTool< z.input<typeof GetStampMarketDataParamsSchema>, GetStampMarketDataParams > { public readonly name = 'get_stamp_market_data'; public readonly description = 'Retrieve detailed market data for a specific stamp (v2.3 feature)'; public readonly inputSchema: MCPTool['inputSchema'] = { type: 'object', properties: { stamp_id: { type: ['number', 'string'], description: 'The ID of the stamp to get market data for', }, }, required: ['stamp_id'], }; public readonly schema = GetStampMarketDataParamsSchema; public readonly metadata = { version: '1.0.0', tags: ['stamps', 'market', 'trading', 'v2.3'], requiresNetwork: true, apiDependencies: ['stampchain'], }; private apiClient: StampchainClient; constructor(apiClient?: StampchainClient) { super(); this.apiClient = apiClient || new StampchainClient(); } public async execute( params: GetStampMarketDataParams, context?: ToolContext ): Promise<ToolResponse> { try { context?.logger?.info('Executing get_stamp_market_data tool', { params }); // Validate parameters const validatedParams = this.validateParams(params); // Use API client from context if available, otherwise use instance client const client = context?.apiClient || this.apiClient; // Check if v2.3 features are available const features = client.getFeatureAvailability(); if (!features.marketData) { return textResponse( 'Market data is not available in the current API version. Please upgrade to v2.3 or later.' ); } // Get stamp market data const marketData: StampMarketData = await client.getStampMarketData(validatedParams.stamp_id); if (!marketData) { return textResponse(`No market data found for stamp ${validatedParams.stamp_id}`); } // Format the response const lines = [`Market Data for Stamp #${validatedParams.stamp_id}:`]; lines.push('---'); lines.push(`Floor Price: ${marketData.floorPriceBTC || 'N/A'} BTC`); if (marketData.floorPriceUSD) { lines.push(`Floor Price USD: $${marketData.floorPriceUSD.toFixed(2)}`); } // Note: marketCapUSD not available in v2.3 marketData object lines.push(`Activity Level: ${marketData.activityLevel}`); if (marketData.lastActivityTime) { lines.push(`Last Activity: ${new Date(marketData.lastActivityTime * 1000).toISOString()}`); } if (marketData.volume24hBTC) { lines.push(`24h Volume: ${marketData.volume24hBTC} BTC`); } if (marketData.volume7dBTC) { lines.push(`7d Volume: ${marketData.volume7dBTC} BTC`); } if (marketData.volume30dBTC) { lines.push(`30d Volume: ${marketData.volume30dBTC} BTC`); } if (marketData.lastSaleTxHash) { lines.push(''); lines.push('Last Sale Details:'); lines.push(`- Transaction: ${marketData.lastSaleTxHash}`); if (marketData.lastSaleBuyerAddress) { lines.push(`- Buyer: ${marketData.lastSaleBuyerAddress}`); } if (marketData.lastSaleDispenserAddress) { lines.push(`- Dispenser: ${marketData.lastSaleDispenserAddress}`); } if (marketData.lastSaleBtcAmount) { lines.push(`- Amount: ${marketData.lastSaleBtcAmount} BTC`); } if (marketData.lastSaleBlockIndex) { lines.push(`- Block: ${marketData.lastSaleBlockIndex}`); } } return textResponse(lines.join('\n')); } catch (error) { context?.logger?.error('Error executing get_stamp_market_data 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 market data', this.name, error); } } }
• src/schemas/stamps.ts:257-275 (schema)

  Zod input schema and TypeScript type for tool parameters (stamp_id). Used for validation in the tool handler.
  export const GetStampMarketDataParamsSchema = 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; }), }); export type GetStampMarketDataParams = z.infer<typeof GetStampMarketDataParamsSchema>;
• src/tools/stamps.ts:816-823 (registration)

  Registers GetStampMarketDataTool in the stampTools export object for aggregation.
  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:28-42 (registration)

  createAllTools function registers and instantiates all tools including get_stamp_market_data 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, }; }
• src/api/stampchain-client.ts:445-450 (helper)

  StampchainClient.getStampMarketData(): supporting API method called by the tool handler to fetch raw market data from the Stampchain API.
  async getStampMarketData(stampId: number): Promise<StampMarketData> { const response = await this.client.get<{ data: StampMarketData }>( `/stamps/${stampId}/marketData` ); return response.data.data; }