Stampchain MCP Server

Instructions

Implementation Reference

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

  The GetStampMarketDataTool class implements the core handler logic for the 'get_stamp_market_data' tool. It validates input, checks API feature availability, calls the StampchainClient.getStampMarketData method, formats the market data response, and handles errors.
  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 schema and TypeScript type definition for the input parameters of the get_stamp_market_data tool, validating the stamp_id parameter.
  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)

  Registration of the GetStampMarketDataTool class in the stampTools object, making it available for export and use in tool registries.
  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:445-450 (helper)

  API client helper method that fetches market data for a specific stamp from the Stampchain API endpoint /stamps/{stampId}/marketData, used by the tool handler.
  async getStampMarketData(stampId: number): Promise<StampMarketData> { const response = await this.client.get<{ data: StampMarketData }>( `/stamps/${stampId}/marketData` ); return response.data.data; }
• src/tools/index.ts:55-56 (registration)

  The tool name 'get_stamp_market_data' is listed in the getAvailableToolNames() function for tool discovery.
  'get_stamp_market_data',