SODAX Builders MCP

Instructions

Implementation Reference

• src/tools/sodaxApi.ts:119-148 (handler)

  MCP tool registration for sodax_get_swap_tokens - defines tool metadata, input schema (chainId, format), and the handler that calls getSwapTokens service and formats the response
  server.tool( "sodax_get_swap_tokens", "Get available tokens for swapping on SODAX, optionally filtered by chain", { chainId: z.string().optional() .describe("Filter tokens by chain ID (e.g., 'base', 'ethereum', 'icon')"), format: z.nativeEnum(ResponseFormat).optional().default(ResponseFormat.MARKDOWN) .describe("Response format: 'json' for raw data or 'markdown' for formatted text") }, READ_ONLY, async ({ chainId, format }) => { try { const tokens = await getSwapTokens(chainId); const summary = chainId ? `## Swap Tokens on ${chainId}\n\n${tokens.length} tokens available\n\n` : `## All Swap Tokens\n\n${tokens.length} tokens available across all chains\n\n`; return { content: [{ type: "text", text: summary + formatResponse(tokens, format) }] }; } catch (error) { return { content: [{ type: "text", text: `Error: ${error instanceof Error ? error.message : "Unknown error"}` }], isError: true }; } } );
• src/services/sodaxApi.ts:77-107 (handler)

  Service layer implementation of getSwapTokens - handles caching, makes HTTP GET requests to SODAX API endpoints (/config/swap/tokens or /config/swap/{chainId}/tokens), and returns array of SwapToken objects
  export async function getSwapTokens(chainId?: string): Promise<SwapToken[]> { const cacheKey = `tokens-${chainId || "all"}`; const cached = getCached<SwapToken[]>(cacheKey); if (cached) return cached; try { const endpoint = chainId ? `/config/swap/${chainId}/tokens` : "/config/swap/tokens"; const response = await apiClient.get(endpoint); // API returns object keyed by chain ID, flatten if getting all const data = response.data; let tokens: SwapToken[] = []; if (chainId && Array.isArray(data)) { tokens = data; } else if (typeof data === "object" && !Array.isArray(data)) { // Flatten all chain tokens into single array for (const chain of Object.keys(data)) { const chainTokens = data[chain]; if (Array.isArray(chainTokens)) { tokens.push(...chainTokens.map(t => ({ ...t, chainId: chain }))); } } } else { tokens = data?.data || []; } setCache(cacheKey, tokens); return tokens; } catch (error) { console.error("Error fetching swap tokens:", error); throw new Error("Failed to fetch swap tokens from SODAX API"); } }
• src/types.ts:31-39 (schema)

  Type definition for SwapToken interface - defines the structure of token data including address, chainId, symbol, name, decimals, logoUrl, and priceUsd
  export interface SwapToken { address: string; chainId: string; symbol: string; name: string; decimals: number; logoUrl?: string; priceUsd?: number; }
• src/tools/sodaxApi.ts:119-148 (registration)

  Tool registration with MCP server using server.tool() - registers sodax_get_swap_tokens with proper annotations and handler function
  server.tool( "sodax_get_swap_tokens", "Get available tokens for swapping on SODAX, optionally filtered by chain", { chainId: z.string().optional() .describe("Filter tokens by chain ID (e.g., 'base', 'ethereum', 'icon')"), format: z.nativeEnum(ResponseFormat).optional().default(ResponseFormat.MARKDOWN) .describe("Response format: 'json' for raw data or 'markdown' for formatted text") }, READ_ONLY, async ({ chainId, format }) => { try { const tokens = await getSwapTokens(chainId); const summary = chainId ? `## Swap Tokens on ${chainId}\n\n${tokens.length} tokens available\n\n` : `## All Swap Tokens\n\n${tokens.length} tokens available across all chains\n\n`; return { content: [{ type: "text", text: summary + formatResponse(tokens, format) }] }; } catch (error) { return { content: [{ type: "text", text: `Error: ${error instanceof Error ? error.message : "Unknown error"}` }], isError: true }; } } );
• src/services/analytics.ts:29-29 (helper)

  Analytics mapping - maps sodax_get_swap_tokens to the 'api' group for PostHog tracking of tool usage
  sodax_get_swap_tokens: "api",