SODAX Builders MCP

Instructions

Implementation Reference

• src/tools/sodaxApi.ts:429-445 (handler)

  Main MCP tool handler for sodax_refresh_cache. Registers the tool with the server and implements the handler that gets cache stats, clears the cache, and returns a confirmation message.

  // Bonus Tool: Refresh Cache
  server.tool(
    "sodax_refresh_cache",
    "Clear the cached API data to force fresh fetches on next requests",
    {},
    { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
    async () => {
      const statsBefore = getCacheStats();
      clearCache();
      return {
        content: [{
          type: "text",
          text: `Cache cleared. ${statsBefore.size} cached entries removed.`
        }]
      };
    }
  );

• src/services/sodaxApi.ts:300-315 (helper)

  Service layer functions that implement the actual cache operations: clearCache() clears all cached entries, and getCacheStats() returns the size and keys of the cache.

  /**
   * Clear all cached data
   */
  export function clearCache(): void {
    cache.clear();
  }
  
  /**
   * Get cache statistics
   */
  export function getCacheStats(): { size: number; keys: string[] } {
    return {
      size: cache.size,
      keys: Array.from(cache.keys())
    };
  }

• src/services/sodaxApi.ts:22-42 (schema)

  Cache data structure and helper functions - defines CacheEntry interface, cache Map instance, getCached(), and setCache() functions used for caching API responses.

  // Cache for API responses
  interface CacheEntry<T> {
    data: T;
    timestamp: number;
  }
  
  const cache = new Map<string, CacheEntry<unknown>>();
  
  function getCached<T>(key: string): T | null {
    const entry = cache.get(key) as CacheEntry<T> | undefined;
    if (!entry) return null;
    if (Date.now() - entry.timestamp > CACHE_DURATION_MS) {
      cache.delete(key);
      return null;
    }
    return entry.data;
  }
  
  function setCache<T>(key: string, data: T): void {
    cache.set(key, { data, timestamp: Date.now() });
  }

• src/index.ts:19-45 (registration)

  Server setup and tool registration - imports registerSodaxApiTools and calls it to register all SODAX API tools including sodax_refresh_cache on the MCP server.

  import { registerSodaxApiTools } from "./tools/sodaxApi.js";
  import { registerGitBookProxyTools, getGitBookToolNames } from "./tools/gitbookProxy.js";
  import { checkGitBookHealth, fetchGitBookTools } from "./services/gitbookProxy.js";
  import { withAnalytics, shutdownAnalytics } from "./services/analytics.js";
  
  const __filename = fileURLToPath(import.meta.url);
  const __dirname = dirname(__filename);
  
  /**
   * Creates a fully configured McpServer instance.
   * Used per-request in HTTP mode to avoid transport conflicts
   * when handling parallel requests.
   */
  async function createServer(): Promise<McpServer> {
    const server = new McpServer({
      name: "builders-sodax-mcp-server",
      version: "1.0.0"
    });
  
    // Wrap server.tool() so every tool call is tracked in PostHog
    // ⚠️  Must be called BEFORE registering any tools
    withAnalytics(server);
  
    registerSodaxApiTools(server);
    await registerGitBookProxyTools(server);
  
    return server;

• src/index.ts:192-205 (registration)

  API endpoint documentation - lists sodax_refresh_cache in the available API tools array returned by the /api endpoint.

  tools: {
    api: [
      "sodax_get_supported_chains",
      "sodax_get_swap_tokens",
      "sodax_get_transaction",
      "sodax_get_user_transactions",
      "sodax_get_volume",
      "sodax_get_orderbook",
      "sodax_get_money_market_assets",
      "sodax_get_user_position",
      "sodax_get_partners",
      "sodax_get_token_supply",
      "sodax_refresh_cache"
    ],