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',