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);