Stampchain MCP Server

Instructions

Implementation Reference

• src/tools/tokens.ts:230-353 (handler)

  Core handler function that executes the search_tokens tool: validates input, builds API query params, calls stampchain API searchTokens, processes and formats results as text table and metadata JSON.

  public async execute(params: SearchTokensParams, context?: ToolContext): Promise<ToolResponse> {
    try {
      context?.logger?.info('Executing search_tokens tool', { params });
  
      // Validate parameters
      const validatedParams = this.validateParams(params);
  
      // Build query parameters
      const queryParams = {
        query: validatedParams.query,
        deployer: validatedParams.deployer,
        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 tokens
      const searchResponse = await this.apiClient.searchTokens(queryParams);
  
      if (!searchResponse || searchResponse.length === 0) {
        return textResponse('No tokens found matching the search criteria');
      }
  
      // Note: searchTokens returns TokenResponse[] directly
      const tokens = searchResponse;
  
      // Note: Client-side filtering for unsupported API fields
      let filteredTokens = tokens;
      if (
        validatedParams.min_holders !== undefined ||
        validatedParams.min_percent_minted !== undefined
      ) {
        // These fields are not available in the current API response
        // Filtering will be skipped and a note will be added to the output
        filteredTokens = tokens;
      }
  
      // Create summary
      const lines = [`Found ${filteredTokens.length} tokens`];
      lines.push('---');
  
      // Create table view
      const tokenTable = createTable(filteredTokens, [
        { key: 'tick', label: 'Ticker' },
        { key: 'max', label: 'Max Supply' },
        { key: 'lim', label: 'Mint Limit' },
        { key: 'deci', label: 'Decimals' },
        {
          key: 'creator',
          label: 'Creator',
          format: (v: unknown) => (typeof v === 'string' ? v.substring(0, 8) + '...' : String(v)),
        },
      ]);
  
      lines.push(tokenTable);
  
      // Add detailed view for top tokens
      lines.push('\n\nDetailed View (Top 5):');
      lines.push('---');
  
      filteredTokens.slice(0, 5).forEach((token, index) => {
        lines.push(`\n${index + 1}. ${token.tick}`);
        lines.push(`   Protocol: ${token.p} | Operation: ${token.op}`);
        lines.push(`   Max Supply: ${token.max}`);
        if (token.lim) {
          lines.push(`   Mint Limit: ${token.lim}`);
        }
        if (token.deci !== undefined) {
          lines.push(`   Decimals: ${token.deci}`);
        }
        lines.push(`   Creator: ${token.creator}`);
        lines.push(`   Block Index: ${token.block_index}`);
        lines.push(`   Block Time: ${new Date(token.block_time).toLocaleString()}`);
        if (token.creator_name) {
          lines.push(`   Creator Name: ${token.creator_name}`);
        }
        if (token.destination_name) {
          lines.push(`   Destination: ${token.destination_name}`);
        }
      });
  
      // Include metadata
      const metadata = {
        results_count: filteredTokens.length,
        query_params: queryParams,
        note: 'Pagination and holder/minting statistics are not available in the current API response',
        additional_filters: {
          min_holders: validatedParams.min_holders,
          min_percent_minted: validatedParams.min_percent_minted,
        },
      };
  
      // Add note about unsupported filters
      if (
        validatedParams.min_holders !== undefined ||
        validatedParams.min_percent_minted !== undefined
      ) {
        lines.push(
          '\n⚠️  Note: Holder and minting percentage filters are not supported by the current API and have been ignored.'
        );
      }
  
      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_tokens tool', { error });
  
      if (error instanceof ValidationError) {
        throw error;
      }
  
      throw new ToolExecutionError('Failed to search tokens', this.name, error);
    }
  }

• src/schemas/tokens.ts:122-135 (schema)

  Zod schema defining the input parameters and validation for the search_tokens tool.

  export const SearchTokensParamsSchema = z.object({
    query: z.string().optional().describe('Search query for token ticker'),
    deployer: z.string().optional().describe('Filter by deployer address'),
    min_holders: z.number().int().nonnegative().optional().describe('Minimum number of holders'),
    min_percent_minted: z.number().min(0).max(100).optional().describe('Minimum percent minted'),
    sort_by: z
      .enum(['deploy_timestamp', 'holders', 'percent_minted'])
      .optional()
      .default('deploy_timestamp')
      .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/tokens.ts:359-372 (registration)

  Registration of SearchTokensTool class and factory function to instantiate search_tokens tool with API client.

  export const tokenTools = {
    get_token_info: GetTokenInfoTool,
    search_tokens: SearchTokensTool,
  };
  
  /**
   * Factory function to create all token tool instances
   */
  export function createTokenTools(apiClient?: StampchainClient) {
    return {
      get_token_info: new GetTokenInfoTool(apiClient),
      search_tokens: new SearchTokensTool(apiClient),
    };
  }

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

  Central factory function that creates all tools including search_tokens via createTokenTools and aggregates them.

  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:477-482 (helper)

  Underlying API client method called by the tool handler to perform the actual token search via Stampchain API.

   * Search SRC-20 tokens with query parameters
   */
  async searchTokens(params: TokenQueryParams = {}): Promise<TokenResponse[]> {
    const response = await this.client.get<TokenListResponse>('/src20', { params });
    return response.data.data;
  }