Stampchain MCP Server

Instructions

Implementation Reference

• src/tools/collections.ts:252-351 (handler)

  The execute method of the SearchCollectionsTool class, which validates input parameters, constructs query params, calls the Stampchain API's searchCollections method, formats the results into a table and detailed view, and returns a multi-response with metadata.

  public async execute(
    params: SearchCollectionsParams,
    context?: ToolContext
  ): Promise<ToolResponse> {
    try {
      context?.logger?.info('Executing search_collections tool', { params });
  
      // Validate parameters
      const validatedParams = this.validateParams(params);
  
      // Build query parameters
      const queryParams = {
        query: validatedParams.query,
        creator: validatedParams.creator,
        sort_by: validatedParams.sort_by,
        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];
        }
      });
  
      // Search collections
      const searchResponse = await this.apiClient.searchCollections(queryParams);
  
      if (!searchResponse || searchResponse.length === 0) {
        return textResponse('No collections found matching the search criteria');
      }
  
      // Note: searchCollections returns CollectionResponse[] directly
      const collections = searchResponse;
  
      // Create summary
      const lines = [`Found ${collections.length} collections`];
      lines.push('---');
  
      // Create table view
      const collectionTable = createTable(collections, [
        { key: 'collection_name', label: 'Name' },
        {
          key: 'collection_id',
          label: 'ID',
          format: (v: unknown) => (typeof v === 'string' ? v.substring(0, 8) + '...' : String(v)),
        },
        {
          key: 'creators',
          label: 'Creators',
          format: (v: unknown) =>
            Array.isArray(v)
              ? v.join(', ').substring(0, 20) + (v.join(', ').length > 20 ? '...' : '')
              : String(v),
        },
        { key: 'stamp_count', label: 'Stamps' },
        { key: 'total_editions', label: 'Editions' },
      ]);
  
      lines.push(collectionTable);
  
      // Add detailed view for each collection
      lines.push('\n\nDetailed View:');
      lines.push('---');
  
      collections.forEach((collection, index) => {
        lines.push(`\n${index + 1}. ${collection.collection_name}`);
        lines.push(`   ID: ${collection.collection_id}`);
        lines.push(`   Creators: ${collection.creators.join(', ')}`);
        lines.push(`   Stamps: ${collection.stamp_count}`);
        lines.push(`   Total Editions: ${collection.total_editions}`);
        if (collection.collection_description) {
          lines.push(
            `   Description: ${collection.collection_description.substring(0, 100)}${collection.collection_description.length > 100 ? '...' : ''}`
          );
        }
      });
  
      // Include metadata
      const metadata = {
        results_count: collections.length,
        query_params: queryParams,
      };
  
      return multiResponse(
        { type: 'text', text: lines.join('\n') },
        { type: 'text', text: `\n\nSearch Metadata:\n${JSON.stringify(metadata, null, 2)}` }
      );
    } catch (error) {
      context?.logger?.error('Error executing search_collections tool', { error });
  
      if (error instanceof ValidationError) {
        throw error;
      }
  
      throw new ToolExecutionError('Failed to search collections', this.name, error);
    }
  }

• src/schemas/collections.ts:85-96 (schema)

  Zod schema defining the input parameters for the search_collections tool, including optional query, creator filter, sorting options, and pagination.

  export const SearchCollectionsParamsSchema = z.object({
    query: z.string().optional().describe('Search query for collection name or description'),
    creator: z.string().optional().describe('Filter by creator address'),
    sort_by: z
      .enum(['created_at', 'stamp_count', 'name'])
      .optional()
      .default('created_at')
      .describe('Sort field'),
    sort_order: z.enum(['ASC', 'DESC']).optional().default('DESC').describe('Sort order'),
    page: z.number().int().positive().optional().default(1).describe('Page number'),
    page_size: z.number().int().positive().max(100).optional().default(20).describe('Items per page'),
  });

• src/tools/collections.ts:357-360 (registration)

  Export of the collectionTools object that registers the SearchCollectionsTool class under the 'search_collections' key.

  export const collectionTools = {
    get_collection: GetCollectionTool,
    search_collections: SearchCollectionsTool,
  };

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

  The createAllTools function in the central tools index that instantiates and includes the search_collections tool via createCollectionTools(client) in the spread of all tools.

  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/collections.ts:365-369 (helper)

  Factory function that creates instances of SearchCollectionsTool for use in the tools registry.

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