Stampchain MCP Server

Instructions

Implementation Reference

• src/tools/stamps.ts:33-115 (handler)

  The GetStampTool class implements the core handler logic for the 'get_stamp' MCP tool. It handles input validation, API calls to fetch stamp data, response formatting, and error handling.

  export class GetStampTool extends BaseTool<z.input<typeof GetStampParamsSchema>, GetStampParams> {
    public readonly name = 'get_stamp';
  
    public readonly description =
      'Retrieve detailed information about a specific Bitcoin stamp by its ID';
  
    public readonly inputSchema: MCPTool['inputSchema'] = {
      type: 'object',
      properties: {
        stamp_id: {
          type: ['number', 'string'],
          description: 'The ID of the stamp to retrieve',
        },
        include_base64: {
          type: 'boolean',
          description: 'Whether to include base64 image data',
          default: false,
        },
      },
      required: ['stamp_id'],
    };
  
    public readonly schema = GetStampParamsSchema;
  
    public readonly metadata = {
      version: '1.0.0',
      tags: ['stamps', 'query'],
      requiresNetwork: true,
      apiDependencies: ['stampchain'],
    };
  
    private apiClient: StampchainClient;
  
    constructor(apiClient?: StampchainClient) {
      super();
      this.apiClient = apiClient || new StampchainClient();
    }
  
    public async execute(params: GetStampParams, context?: ToolContext): Promise<ToolResponse> {
      try {
        context?.logger?.info('Executing get_stamp tool', { params });
  
        // Validate parameters
        const validatedParams = this.validateParams(params);
        const stampId = parseStampId(validatedParams.stamp_id);
  
        // Use API client from context if available, otherwise use instance client
        const client = context?.apiClient || this.apiClient;
  
        // Fetch stamp data
        const stamp: Stamp = await client.getStamp(stampId);
  
        if (!stamp) {
          throw new ToolExecutionError(`Stamp with ID ${stampId} not found`, this.name, { stampId });
        }
  
        // Format the response
        const formattedStamp = formatStamp(stamp, {
          includeBase64: validatedParams.include_base64,
        });
  
        // Return both formatted text and JSON data
        return multiResponse({ type: 'text', text: formattedStamp }, stampToJSON(stamp));
      } catch (error) {
        context?.logger?.error('Error executing get_stamp 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 information', this.name, error);
      }
    }
  }

• src/schemas/stamps.ts:175-194 (schema)

  Zod schema and TypeScript type for validating input parameters to the get_stamp tool (stamp_id required, include_base64 optional).

  export const GetStampParamsSchema = 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;
      }),
    include_base64: z.boolean().optional().default(false),
  });
  
  export type GetStampParams = z.infer<typeof GetStampParamsSchema>;

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

  Registration of the GetStampTool class under the tool name 'get_stamp' 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/api/stampchain-client.ts:341-344 (helper)

  StampchainClient.getStamp method called by the tool handler to fetch stamp data from the API endpoint `/stamps/${stampId}`.

  async getStamp(stampId: number): Promise<Stamp> {
    const response = await this.client.get<StampResponse>(`/stamps/${stampId}`);
    return response.data.data.stamp;
  }

• src/tools/stamps.ts:828-837 (registration)

  Factory function createStampTools that instantiates the GetStampTool for 'get_stamp' with optional API client.

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