Stampchain MCP Server

Instructions

Implementation Reference

• src/tools/stamps.ts:315-375 (handler)

  Handler function implementing the get_recent_stamps tool logic. Validates input, calls searchStamps API with DESC sort order and specified limit, formats and returns list of recent stamps.

  public async execute(
    params: GetRecentStampsParams,
    context?: ToolContext
  ): Promise<ToolResponse> {
    try {
      context?.logger?.info('Executing get_recent_stamps tool', { params });
  
      // Validate parameters
      const validatedParams = this.validateParams(params);
  
      // Get recent stamps by searching with sort order DESC
      const queryParams = {
        sort_order: 'DESC' as const,
        page: 1,
        page_size: validatedParams.limit,
      };
  
      // Use API client from context if available, otherwise use instance client
      const client = context?.apiClient || this.apiClient;
  
      const stamps: Stamp[] = await client.searchStamps(queryParams);
  
      if (!stamps || stamps.length === 0) {
        return textResponse('No recent stamps found');
      }
  
      // Create a summary of recent stamps
      const lines = [`${stamps.length} Most Recent Stamps:`];
      lines.push('---');
  
      stamps.forEach((stamp, index) => {
        lines.push(`${index + 1}. Stamp #${stamp.stamp}`);
        lines.push(`   Block: ${stamp.block_index}`);
        lines.push(`   Creator: ${stamp.creator}`);
        lines.push(`   Type: ${stamp.ident}`);
        lines.push(`   CPID: ${stamp.cpid}`);
        if (stamp.floorPrice) {
          lines.push(`   Floor Price: ${stamp.floorPrice} BTC`);
        }
        lines.push('');
      });
  
      return textResponse(lines.join('\n'));
    } catch (error) {
      context?.logger?.error('Error executing get_recent_stamps 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 recent stamps', this.name, error);
    }

• src/schemas/stamps.ts:225-229 (schema)

  Zod schema for input parameters of get_recent_stamps tool, defining optional limit (1-100, default 20).

  export const GetRecentStampsParamsSchema = z.object({
    limit: z.number().int().min(1).max(100).optional().default(20),
  });
  
  export type GetRecentStampsParams = z.infer<typeof GetRecentStampsParamsSchema>;

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

  Registration of GetRecentStampsTool class 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/tools/stamps.ts:828-837 (registration)

  Factory function createStampTools instantiates GetRecentStampsTool and registers it in the tools map.

  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),
    };
  }

• src/tools/index.ts:52-82 (registration)

  Tool name listed in getAvailableToolNames() for discovery and in toolMetadata.

      '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',
    ];
  }
  
  /**
   * Tool metadata for discovery
   */
  export const toolMetadata = {
    stamps: {
      category: 'Bitcoin Stamps',
      description: 'Tools for querying and searching Bitcoin stamps',
      tools: [
        'get_stamp',
        'search_stamps',
        'get_recent_stamps',

• src/api/stampchain-client.ts:357-363 (helper)

  Supporting API client method getRecentStamps (though tool uses searchStamps directly).

  async getRecentStamps(limit: number = 20): Promise<Stamp[]> {
    const params: StampQueryParams = {
      limit,
    };
    const response = await this.client.get<StampListResponse>('/stamps', { params });
    return response.data.data;
  }