CoinStats MCP Server

Instructions

Implementation Reference

• src/tools/toolFactory.ts:21-77 (handler)

  Handler function registered for the 'get-wallet-balances' tool. Since not local, calls universalApiHandler(COINSTATS_API_BASE, '/wallet/balances', 'GET', params) to execute the API request.

  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/tools/toolConfigs.ts:177-190 (schema)

  Zod schema definition for input parameters of the 'get-wallet-balances' tool: address (required), networks (optional, default 'all'). Also defines description, endpoint, and method.

  {
      name: 'get-wallet-balances',
      description: 'Get the balance data for a provided wallet address on all CoinStats supported networks.',
      endpoint: '/wallet/balances',
      method: 'GET',
      parameters: {
          address: z.string().describe('The wallet address for which the balance is being queried'),
          networks: z
              .string()
              .optional()
              .describe('Blockchain networks to query, comma-separated (e.g., "ethereum,polygon,binance")')
              .default('all'),
      },
  },

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

  Registration of all tools, including 'get-wallet-balances', by calling registerTools(server, allToolConfigs) in the main MCP server setup.

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

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

  Core universalApiHandler invoked by the tool handler; constructs the full URL (COINSTATS_API_BASE + '/wallet/balances'), handles query/path params, calls makeRequestCsApi to fetch data from CoinStats API, and formats response as MCP content.

  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/services/request.ts:4-32 (helper)

  Low-level HTTP request maker using fetch to CoinStats API with API key; appends params as query string, handles JSON response.

  export async function makeRequestCsApi<T>(url: string, method: string = 'GET', params: Record<string, any> = {}, body?: any): Promise<T | null> {
      const headers = {
          'X-API-KEY': COINSTATS_API_KEY,
          'Content-Type': 'application/json',
      };
  
      try {
          // Build request options
          const options: RequestInit = { method, headers };
  
          // Add body for non-GET requests if provided
          if (method !== 'GET' && body) {
              options.body = JSON.stringify(body);
          }
  
          // Add query params for all requests
          const queryParams = new URLSearchParams(params);
          const queryString = queryParams.toString();
          const urlWithParams = queryString ? `${url}?${queryString}` : url;
  
          const response = await fetch(urlWithParams, options);
          if (!response.ok) {
              throw new Error(`HTTP error! status: ${response.status}`);
          }
          return (await response.json()) as T;
      } catch (error) {
          return null;
      }
  }