Stampchain MCP Server

Instructions

Implementation Reference

• src/tools/collections.ts:24-183 (handler)

  The GetCollectionTool class implements the core logic for the 'get_collection' tool. It validates input, calls the Stampchain API (using searchCollections as fallback), formats collection information and optional stamps into a table, and returns a multi-part response including text summary and JSON data.

  export class GetCollectionTool extends BaseTool<
    z.input<typeof GetCollectionParamsSchema>,
    GetCollectionParams
  > {
    public readonly name = 'get_collection';
  
    public readonly description =
      'Retrieve detailed information about a specific stamp collection by its ID';
  
    public readonly inputSchema: MCPTool['inputSchema'] = {
      type: 'object',
      properties: {
        collection_id: {
          type: 'string',
          description: 'The ID of the collection to retrieve',
        },
        include_stamps: {
          type: 'boolean',
          description: 'Whether to include stamps in the collection',
          default: false,
        },
        stamps_page: {
          type: 'number',
          description: 'Page number for stamps if included',
          minimum: 1,
          default: 1,
        },
        stamps_limit: {
          type: 'number',
          description: 'Number of stamps per page',
          minimum: 1,
          maximum: 100,
          default: 20,
        },
      },
      required: ['collection_id'],
    };
  
    public readonly schema = GetCollectionParamsSchema;
  
    public readonly metadata = {
      version: '1.0.0',
      tags: ['collections', 'query'],
      requiresNetwork: true,
      apiDependencies: ['stampchain'],
    };
  
    private apiClient: StampchainClient;
  
    constructor(apiClient?: StampchainClient) {
      super();
      this.apiClient = apiClient || new StampchainClient();
    }
  
    public async execute(params: GetCollectionParams, context?: ToolContext): Promise<ToolResponse> {
      try {
        context?.logger?.info('Executing get_collection tool', { params });
  
        // Validate parameters
        const validatedParams = this.validateParams(params);
  
        // Since the API doesn't have a direct getCollection method,
        // we'll search for collections with the specific ID
        const collectionResponse = await this.apiClient.searchCollections({
          query: validatedParams.collection_id,
          page: 1,
          page_size: 1,
        });
  
        if (!collectionResponse || collectionResponse.length === 0) {
          throw new ToolExecutionError(
            `Collection with ID ${validatedParams.collection_id} not found`,
            this.name,
            { collectionId: validatedParams.collection_id }
          );
        }
  
        const collection = collectionResponse[0];
        const contents = [];
  
        // Add formatted collection info
        const collectionInfo = [
          `Collection: ${collection.collection_name}`,
          `ID: ${collection.collection_id}`,
          `Description: ${collection.collection_description}`,
          `Creators: ${collection.creators.join(', ')}`,
          `Stamps: ${collection.stamp_count}`,
          `Total Editions: ${collection.total_editions}`,
        ].join('\n');
        contents.push({ type: 'text' as const, text: collectionInfo });
  
        // If stamps are requested, fetch them
        if (validatedParams.include_stamps) {
          try {
            const stampsResponse = await this.apiClient.searchStamps({
              collection_id: validatedParams.collection_id,
              page: validatedParams.stamps_page,
              page_size: validatedParams.stamps_limit,
            });
  
            if (stampsResponse && stampsResponse.length > 0) {
              contents.push({
                type: 'text' as const,
                text: `\n\nStamps in Collection (Page ${validatedParams.stamps_page}):\n`,
              });
  
              const stampTable = createTable(stampsResponse, [
                { key: 'stamp', label: 'ID' },
                { key: 'cpid', label: 'CPID' },
                {
                  key: 'creator',
                  label: 'Creator',
                  format: (v: unknown) =>
                    typeof v === 'string' ? v.substring(0, 12) + '...' : String(v),
                },
                { key: 'supply', label: 'Supply' },
                {
                  key: 'floorPrice',
                  label: 'Floor Price',
                  format: (v: unknown) => (v ? `${String(v)} BTC` : 'N/A'),
                },
              ]);
  
              contents.push({ type: 'text' as const, text: stampTable });
              contents.push({
                type: 'text' as const,
                text: `\nTotal stamps in collection: ${stampsResponse.length}`,
              });
            }
          } catch (error) {
            context?.logger?.warn('Failed to fetch stamps for collection', { error });
            contents.push({
              type: 'text' as const,
              text: '\n\nNote: Unable to fetch stamps for this collection',
            });
          }
        }
  
        // Add JSON representation
        contents.push({
          type: 'text' as const,
          text: JSON.stringify(collection, null, 2),
        });
  
        return multiResponse(...contents);
      } catch (error) {
        context?.logger?.error('Error executing get_collection tool', { error });
  
        if (error instanceof ValidationError) {
          throw error;
        }
  
        if (error instanceof ToolExecutionError) {
          throw error;
        }
  
        throw new ToolExecutionError('Failed to retrieve collection information', this.name, error);
      }
    }
  }

• src/schemas/collections.ts:58-80 (schema)

  Zod schema defining the input parameters for the get_collection tool, including collection_id (required), and optional flags for including stamps with pagination.

  export const GetCollectionParamsSchema = z.object({
    collection_id: z.string().describe('The ID of the collection to retrieve'),
    include_stamps: z
      .boolean()
      .optional()
      .default(false)
      .describe('Whether to include stamps in the collection'),
    stamps_page: z
      .number()
      .int()
      .positive()
      .optional()
      .default(1)
      .describe('Page number for stamps if included'),
    stamps_limit: z
      .number()
      .int()
      .positive()
      .max(100)
      .optional()
      .default(20)
      .describe('Number of stamps per page'),
  });

• src/tools/collections.ts:365-370 (registration)

  Factory function that instantiates the GetCollectionTool (as 'get_collection') with optional API client, used for tool registration.

  export function createCollectionTools(apiClient?: StampchainClient) {
    return {
      get_collection: new GetCollectionTool(apiClient),
      search_collections: new SearchCollectionsTool(apiClient),
    };
  }

• src/tools/index.ts:28-42 (registration)

  Central factory that creates all tool instances including 'get_collection' from createCollectionTools, spreading them into the main tools registry.

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

  API client method to fetch a specific collection by ID, though the tool uses searchCollections instead (noted in tool comments).

  async getCollection(collectionId: string): Promise<CollectionResponse> {
    const response = await this.client.get<CollectionResponse>(`/collections/${collectionId}`);
    return response.data;
  }