Stampchain MCP Server

Instructions

Implementation Reference

• src/tools/tokens.ts:69-149 (handler)

  The execute method implementing the core logic of the 'get_token_info' tool, which fetches and formats token information using the Stampchain API.

  public async execute(params: GetTokenInfoParams, context?: ToolContext): Promise<ToolResponse> {
    try {
      context?.logger?.info('Executing get_token_info tool', { params });
  
      // Validate parameters
      const validatedParams = this.validateParams(params);
  
      // Search for the specific token
      const tokenResponse = await this.apiClient.searchTokens({
        query: validatedParams.tick,
        page: 1,
        page_size: 1,
      });
  
      if (!tokenResponse || !tokenResponse || tokenResponse.length === 0) {
        throw new ToolExecutionError(
          `Token with ticker ${validatedParams.tick} not found`,
          this.name,
          { tick: validatedParams.tick }
        );
      }
  
      const token = tokenResponse[0];
  
      // Verify exact match (case-insensitive)
      if (token.tick.toLowerCase() !== validatedParams.tick.toLowerCase()) {
        throw new ToolExecutionError(
          `Token with ticker ${validatedParams.tick} not found (found ${token.tick} instead)`,
          this.name,
          { requestedTick: validatedParams.tick, foundTick: token.tick }
        );
      }
  
      const contents = [];
  
      // Add formatted token info
      contents.push({ type: 'text' as const, text: formatToken(token) });
  
      // Add deployment information
      const stats = [
        '\nDeployment Information:',
        '---',
        `Block Index: ${token.block_index}`,
        `Block Time: ${new Date(token.block_time).toLocaleString()}`,
        `Transaction Hash: ${token.tx_hash}`,
      ];
  
      if (token.creator_name) {
        stats.push(`Creator: ${token.creator_name} (${token.creator})`);
      } else {
        stats.push(`Creator: ${token.creator}`);
      }
  
      contents.push({ type: 'text' as const, text: stats.join('\n') });
  
      // Note about additional data
      if (validatedParams.include_holders || validatedParams.include_transfers) {
        contents.push({
          type: 'text' as const,
          text: '\nNote: Detailed holder and transfer data requires additional API endpoints that may not be available in the current implementation.',
        });
      }
  
      // Add JSON representation
      contents.push(tokenToJSON(token));
  
      return multiResponse(...contents);
    } catch (error) {
      context?.logger?.error('Error executing get_token_info tool', { error });
  
      if (error instanceof ValidationError) {
        throw error;
      }
  
      if (error instanceof ToolExecutionError) {
        throw error;
      }
  
      throw new ToolExecutionError('Failed to retrieve token information', this.name, error);
    }
  }

• src/schemas/tokens.ts:105-117 (schema)

  Zod schema defining the input parameters for the 'get_token_info' tool, including ticker and optional flags for additional data.

  export const GetTokenInfoParamsSchema = z.object({
    tick: TokenTickerSchema.describe('The ticker symbol of the SRC-20 token'),
    include_holders: z
      .boolean()
      .optional()
      .default(false)
      .describe('Whether to include holder statistics'),
    include_transfers: z
      .boolean()
      .optional()
      .default(false)
      .describe('Whether to include recent transfer data'),
  });

• src/tools/tokens.ts:359-362 (registration)

  Registration of the GetTokenInfoTool constructor under the 'get_token_info' key in the tokenTools export.

  export const tokenTools = {
    get_token_info: GetTokenInfoTool,
    search_tokens: SearchTokensTool,
  };

• src/tools/index.ts:47-70 (registration)

  The get_token_info tool is listed in the central getAvailableToolNames function that returns all available tool names.

  export function getAvailableToolNames(): string[] {
    return [
      // Stamp tools
      'get_stamp',
      'search_stamps',
      'get_recent_stamps',
      'get_recent_sales',
      'get_market_data',
      'get_stamp_market_data',
  
      // Collection tools
      'get_collection',
      'search_collections',
  
      // Token tools
      'get_token_info',
      'search_tokens',
  
      // Analysis tools
      'analyze_stamp_code',
      'get_stamp_dependencies',
      'analyze_stamp_patterns',
    ];
  }

• src/tools/tokens.ts:53-53 (schema)

  Assignment of the GetTokenInfoParamsSchema to the tool's schema property.

  public readonly schema = GetTokenInfoParamsSchema;