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",