Stampchain MCP Server

Instructions

Implementation Reference

• src/tools/stamps.ts:601-678 (handler)

  The execute method of GetMarketDataTool class implements the core tool logic: validates parameters, checks API feature availability, fetches market data via StampchainClient.getMarketData(), formats the response as text, and handles errors.

  public async execute(params: GetMarketDataParams, context?: ToolContext): Promise<ToolResponse> {
    try {
      context?.logger?.info('Executing get_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 market data
      const marketData = await client.getMarketData(validatedParams);
  
      if (!marketData.data || marketData.data.length === 0) {
        return textResponse('No market data found for the specified criteria');
      }
  
      // Format the response
      const lines = [`Market Data (${marketData.data.length} results):`];
      lines.push('---');
  
      marketData.data.forEach((data: StampMarketData, index: number) => {
        lines.push(`${index + 1}. Market Data Entry`);
        lines.push(`   Floor Price: ${data.floorPriceBTC || 'N/A'} BTC`);
        if (data.floorPriceUSD) {
          lines.push(`   Floor Price USD: $${data.floorPriceUSD.toFixed(2)}`);
        }
        // Note: marketCapUSD not available in v2.3 marketData object
        lines.push(`   Activity Level: ${data.activityLevel}`);
        if (data.lastActivityTime) {
          lines.push(`   Last Activity: ${new Date(data.lastActivityTime * 1000).toISOString()}`);
        }
        if (data.volume24hBTC) {
          lines.push(`   24h Volume: ${data.volume24hBTC} BTC`);
        }
        if (data.lastSaleTxHash) {
          lines.push(`   Last Sale TX: ${data.lastSaleTxHash}`);
        }
        if (data.lastSaleBuyerAddress) {
          lines.push(`   Last Buyer: ${data.lastSaleBuyerAddress}`);
        }
        lines.push('');
      });
  
      // Add metadata
      lines.push('Metadata:');
      lines.push(`- Total Results: ${marketData.total}`);
      lines.push(`- Page: ${marketData.page}`);
      lines.push(`- Page Size: ${marketData.limit}`);
      lines.push(`- Last Block: ${marketData.last_block}`);
  
      return textResponse(lines.join('\n'));
    } catch (error) {
      context?.logger?.error('Error executing get_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 market data', this.name, error);
    }

• src/schemas/stamps.ts:244-254 (schema)

  Zod schema GetMarketDataParamsSchema defining input validation and TypeScript types for the get_market_data tool parameters.

  export const GetMarketDataParamsSchema = z.object({
    stamp_id: z.number().int().positive().optional(),
    activity_level: z.enum(['HOT', 'WARM', 'COOL', 'DORMANT', 'COLD']).optional(),
    min_floor_price: z.number().positive().optional(),
    max_floor_price: z.number().positive().optional(),
    include_volume_data: z.boolean().optional().default(true),
    page: z.number().int().min(1).optional().default(1),
    page_size: z.number().int().min(1).max(100).optional().default(20),
  });
  
  export type GetMarketDataParams = z.infer<typeof GetMarketDataParamsSchema>;

• src/tools/stamps.ts:816-823 (registration)

  Registration of GetMarketDataTool in the stampTools export object, making it available for tool aggregation and server registration.

  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)

  Central list of all available tool names including 'get_market_data' for MCP tool discovery.

  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/api/stampchain-client.ts:431-440 (helper)

  StampchainClient.getMarketData method that performs the HTTP request to the Stampchain API endpoint for market data, used by the tool handler.

  async getMarketData(params: MarketDataQueryParams = {}): Promise<{
    data: StampMarketData[];
    last_block: number;
    page: number;
    limit: number;
    total: number;
  }> {
    const response = await this.client.get('/stamps/marketData', { params });
    return response.data;
  }