Stampchain MCP Server

Instructions

Implementation Reference

• src/tools/stamps.ts:195-271 (handler)

  The main handler function for the 'search_stamps' tool. It validates input parameters, constructs query params, calls the StampchainClient.searchStamps API, formats the results, and returns a multi-response with text summary and metadata.

  public async execute(params: SearchStampsParams, context?: ToolContext): Promise<ToolResponse> {
    try {
      context?.logger?.info('Executing search_stamps tool', { params });
  
      // Validate parameters
      const validatedParams = this.validateParams(params);
  
      // Build query parameters
      const queryParams = {
        query: validatedParams.query,
        creator: validatedParams.creator,
        collection_id: validatedParams.collection_id,
        cpid: validatedParams.cpid,
        is_btc_stamp: validatedParams.is_btc_stamp,
        is_cursed: validatedParams.is_cursed,
        sort_order: validatedParams.sort_order,
        page: validatedParams.page,
        page_size: validatedParams.page_size,
      };
  
      // Remove undefined values
      Object.keys(queryParams).forEach((key) => {
        if (queryParams[key as keyof typeof queryParams] === undefined) {
          delete queryParams[key as keyof typeof queryParams];
        }
      });
  
      // Use API client from context if available, otherwise use instance client
      const client = context?.apiClient || this.apiClient;
  
      // Search stamps
      const stamps: Stamp[] = await client.searchStamps(queryParams);
  
      if (!stamps || stamps.length === 0) {
        return textResponse('No stamps found matching the search criteria');
      }
  
      // Since the API returns an array, we need to handle pagination info differently
      const total = stamps.length;
      const page = validatedParams.page || 1;
      const limit = validatedParams.page_size || 20;
  
      // Format the response
      const formattedList = formatStampList(stamps, total, page, limit);
  
      // Include metadata about the search
      const metadata = {
        total_results: total,
        current_page: page,
        page_size: limit,
        total_pages: Math.ceil(total / limit),
        query_params: queryParams,
      };
  
      return multiResponse(
        { type: 'text', text: formattedList },
        { type: 'text', text: `\nSearch Metadata:\n${JSON.stringify(metadata, null, 2)}` }
      );
    } catch (error) {
      context?.logger?.error('Error executing search_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 search stamps', this.name, error);
    }
  }

• src/schemas/stamps.ts:199-218 (schema)

  Zod schema defining the input parameters and validation rules for the search_stamps tool.

  export const SearchStampsParamsSchema = z.object({
    query: z.string().optional(),
    creator: z.string().optional(),
    collection_id: z.string().optional(),
    cpid: z.string().optional(),
    is_btc_stamp: z.boolean().optional(),
    is_cursed: z.boolean().optional(),
    sort_order: z.enum(['ASC', 'DESC']).optional().default('DESC'),
    page: z.number().int().min(1).optional().default(1),
    page_size: z.number().int().min(1).max(100).optional().default(20),
    limit: z.number().int().min(1).max(1000).optional(),
    // v2.3: New filtering parameters
    from_timestamp: z.number().int().positive().optional(),
    to_timestamp: z.number().int().positive().optional(),
    min_floor_price: z.number().positive().optional(),
    max_floor_price: z.number().positive().optional(),
    activity_level: z.enum(['HOT', 'WARM', 'COOL', 'DORMANT', 'COLD']).optional(),
    include_market_data: z.boolean().optional().default(false),
    include_dispenser_info: z.boolean().optional().default(false),
  });

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

  Registration of the SearchStampsTool class in the stampTools object, which aggregates all stamp-related tools for export.

  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)

  Central factory function that creates all tool instances, including search_stamps from createStampTools, for use in the MCP server.

  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/tools/stamps.ts:828-837 (helper)

  Factory function that instantiates the SearchStampsTool instance, which can then be registered in the ToolRegistry.

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