CoinStats MCP Server

Instructions

Implementation Reference

• src/tools/toolConfigs.ts:7-77 (schema)

  Defines the schema, description, endpoint, method, and Zod parameter schemas for the 'get-coins' tool.

  {
      name: 'get-coins',
      description:
          'Get comprehensive data about all cryptocurrencies: Price, market cap, and volume. Price changes (1h, 24h, 7d). Supply information. Trading metrics. Social links and metadata.',
      endpoint: '/coins',
      method: 'GET',
      parameters: {
          name: z.string().optional().describe('Search coins by name'),
          page: z.number().optional().describe('Page number').default(1),
          limit: z.number().optional().describe('Number of results per page').default(20),
          currency: z.string().optional().describe('Currency for price data').default('USD'),
          symbol: z.string().optional().describe('Get coins by symbol'),
          blockchains: z.string().optional().describe('Blockchain filters, separated by commas (e.g., ethereum,solana)'),
          includeRiskScore: z.string().optional().describe('Include risk score: true or false. Default - false'),
          categories: z.string().optional().describe('Category filters, separated by commas (e.g., memecoins,sports)'),
          sortBy: z.string().optional().describe('Field to sort by'),
          sortDir: z.enum(['asc', 'desc']).optional().describe('Sort direction'),
  
          // Market Cap filters
          'marketCap-greaterThan': z.number().optional().describe('Marketcap Greater Than'),
          'marketCap-equals': z.number().optional().describe('Marketcap Equals'),
          'marketCap-lessThan': z.number().optional().describe('Marketcap Less Than'),
  
          // Fully Diluted Valuation filters
          'fullyDilutedValuation-greaterThan': z.number().optional().describe('Fully Diluted Valuation Greater Than'),
          'fullyDilutedValuation-equals': z.number().optional().describe('Fully Diluted Valuation Equals'),
          'fullyDilutedValuation-lessThan': z.number().optional().describe('Fully Diluted Valuation Less Than'),
  
          // Volume filters
          'volume-greaterThan': z.number().optional().describe('Volume Greater Than'),
          'volume-equals': z.number().optional().describe('Volume Equals'),
          'volume-lessThan': z.number().optional().describe('Volume Less Than'),
  
          // Price Change filters
          'priceChange1h-greaterThan': z.number().optional().describe('Price Change 1h Greater Than'),
          'priceChange1h-equals': z.number().optional().describe('Price Change 1h Equals'),
          'priceChange1h-lessThan': z.number().optional().describe('Price Change 1h Less Than'),
  
          'priceChange1d-greaterThan': z.number().optional().describe('Price Change 1d Greater Than'),
          'priceChange1d-equals': z.number().optional().describe('Price Change 1d Equals'),
          'priceChange1d-lessThan': z.number().optional().describe('Price Change 1d Less Than'),
  
          'priceChange7d-greaterThan': z.number().optional().describe('Price Change 7d Greater Than'),
          'priceChange7d-equals': z.number().optional().describe('Price Change 7d Equals'),
          'priceChange7d-lessThan': z.number().optional().describe('Price Change 7d Less Than'),
  
          // Supply filters
          'availableSupply-greaterThan': z.number().optional().describe('Available Supply Greater Than'),
          'availableSupply-equals': z.number().optional().describe('Available Supply Equals'),
          'availableSupply-lessThan': z.number().optional().describe('Available Supply Less Than'),
  
          'totalSupply-greaterThan': z.number().optional().describe('Total Supply Greater Than'),
          'totalSupply-equals': z.number().optional().describe('Total Supply Equals'),
          'totalSupply-lessThan': z.number().optional().describe('Total Supply Less Than'),
  
          // Rank filters
          'rank-greaterThan': z.number().optional().describe('Rank Greater Than'),
          'rank-equals': z.number().optional().describe('Rank Equals'),
          'rank-lessThan': z.number().optional().describe('Rank Less Than'),
  
          // Price filters
          'price-greaterThan': z.number().optional().describe('Price Greater Than'),
          'price-equals': z.number().optional().describe('Price Equals'),
          'price-lessThan': z.number().optional().describe('Price Less Than'),
  
          // Risk Score filters
          'riskScore-greaterThan': z.number().optional().describe('Risk Score Greater Than (Only if includeRiskScore=true)'),
          'riskScore-equals': z.number().optional().describe('Risk Score Equals (Only if includeRiskScore=true)'),
          'riskScore-lessThan': z.number().optional().describe('Risk Score Less Than (Only if includeRiskScore=true)'),
      },
  },

• src/services/request.ts:35-97 (handler)

  Implements the execution logic for API tools like 'get-coins'. Handles path params, special param key replacement for '/coins' endpoint (MCP compatibility), API request via fetch, error handling, and MCP response formatting.

  export async function universalApiHandler<T>(
      basePath: string,
      endpoint: string,
      method: string = 'GET',
      params: Record<string, any> = {},
      body?: any
  ): Promise<{
      content: Array<{ type: 'text'; text: string; isError?: boolean }>;
  }> {
      try {
          // Handle path parameters - replace {paramName} in endpoint with actual values
          let processedEndpoint = endpoint;
          let processedParams = { ...params };
  
          // Find all path parameters in the endpoint (e.g., {coinId}, {id}, {type})
          const pathParamMatches = endpoint.match(/\{([^}]+)\}/g);
  
          if (pathParamMatches) {
              for (const match of pathParamMatches) {
                  const paramName = match.slice(1, -1); // Remove { and }
  
                  if (processedParams[paramName] !== undefined) {
                      // Replace the placeholder with the actual value
                      processedEndpoint = processedEndpoint.replace(match, processedParams[paramName]);
                      // Remove the parameter from query params since it's now part of the path
                      delete processedParams[paramName];
                  } else {
                      throw new Error(`Required path parameter '${paramName}' is missing`);
                  }
              }
          }
  
          // MCP clients might not support '~' in parameter names, so we replace '-' with '~' specifically for the /coins endpoint before making the request.
          if (endpoint === '/coins') {
              processedParams = Object.entries(processedParams).reduce((acc, [key, value]) => {
                  acc[key.replace(/-/g, '~')] = value;
                  return acc;
              }, {} as Record<string, any>);
          }
  
          const url = `${basePath}${processedEndpoint}`;
          const data = await makeRequestCsApi<T>(url, method, processedParams, body);
  
          if (!data) {
              return {
                  content: [{ type: 'text', text: 'Something went wrong', isError: true }],
              };
          }
  
          return {
              content: [
                  {
                      type: 'text',
                      text: JSON.stringify(data),
                  },
              ],
          };
      } catch (error) {
          return {
              content: [{ type: 'text', text: `Error: ${error}`, isError: true }],
          };
      }
  }

• src/tools/toolFactory.ts:19-79 (registration)

  Registers the 'get-coins' tool (and others) with the MCP server by calling server.tool with name, description, schema, and generic handler function.

  export function registerTools(server: McpServer, toolConfigs: ToolConfig<any>[]) {
      toolConfigs.forEach((config) => {
          server.tool(config.name, config.description, config.parameters, async (params: Record<string, any>) => {
              // Handle local operations
              if (config.isLocal) {
                  // Handle specific local tools
                  if (config.name === 'save-share-token') {
                      await saveToCache('shareToken', params.shareToken);
                      return {
                          content: [
                              {
                                  type: 'text',
                                  text: 'Share token saved successfully',
                              },
                          ],
                      };
                  }
  
                  if (config.name === 'get-share-token') {
                      const shareToken = await getFromCache('shareToken');
  
                      return {
                          content: [
                              {
                                  type: 'text',
                                  text: shareToken ? shareToken : 'No share token found in cache',
                                  isError: !shareToken,
                              },
                          ],
                      };
                  }
                  // Future local tools can be added here
  
                  // Default response for unhandled local tools
                  return {
                      content: [
                          {
                              type: 'text',
                              text: 'Operation completed',
                          },
                      ],
                  };
              }
  
              // Handle API operations
              const basePath = config.basePath || COINSTATS_API_BASE;
              const method = config.method || 'GET';
  
              // Methods that typically have a request body
              const bodyMethods = ['POST', 'PUT', 'PATCH', 'DELETE'];
  
              // For GET/DELETE requests, all params go in the URL
              // For POST/PUT/PATCH, send params as the body
              if (bodyMethods.includes(method.toUpperCase())) {
                  return universalApiHandler(basePath, config.endpoint, method, {}, params);
              } else {
                  return universalApiHandler(basePath, config.endpoint, method, params);
              }
          });
      });
  }

• src/index.ts:17-18 (registration)

  Calls registerTools to register all tools including 'get-coins' on the MCP server instance.

  // Register all tools from configurations
  registerTools(server, allToolConfigs);