DeFi Trading Agent MCP Server

Instructions

Implementation Reference

• src/toolService.js:40-70 (handler)

  Main handler function for get_swap_quote tool. Validates parameters, adds user address as taker if missing, delegates to AgService.getSwapQuote, enhances result with chainId, and returns formatted response with next steps.

  async getSwapQuote(params) {
    // Validate required parameters
    const { chainId, buyToken, sellToken, sellAmount } = params;
  
    if (!chainId || !buyToken || !sellToken || !sellAmount) {
      throw new Error(
        "Missing required parameters: chainId, buyToken, sellToken, sellAmount"
      );
    }
  
    // Add taker address if not provided
    const quoteParams = {
      ...params,
      taker: params.taker || this.userAddress,
    };
  
    const result = await this.agg.getSwapQuote(quoteParams);
  
    // Add chainId to the result for executeSwap to use
    result.chainId = chainId;
  
    return {
      message: "Swap quote retrieved successfully",
      data: result,
      nextSteps: [
        "1. Review the quote details including fees and gas estimates",
        "2. Use execute_swap tool to execute this swap",
        "3. The permit2 signature will be handled automatically",
      ],
    };
  }

• src/index.js:120-156 (schema)

  Input schema definition for the get_swap_quote tool, specifying parameters like chainId, buyToken, sellToken, sellAmount, with optional taker and slippageBps.

  {
    name: TOOL_NAMES.GET_SWAP_QUOTE,
    description:
      "Get executable quote with transaction data for a token swap",
    inputSchema: {
      type: "object",
      properties: {
        chainId: {
          type: "integer",
          description: "Blockchain ID (e.g., 1 for Ethereum)",
        },
        buyToken: {
          type: "string",
          description: "Contract address of token to buy",
        },
        sellToken: {
          type: "string",
          description: "Contract address of token to sell",
        },
        sellAmount: {
          type: "string",
          description: "Amount of sellToken in base units",
        },
        taker: {
          type: "string",
          description:
            "Address executing the trade (optional, uses USER_ADDRESS from env)",
        },
        slippageBps: {
          type: "integer",
          description:
            "Maximum acceptable slippage in basis points (optional, default: 100)",
        },
      },
      required: ["chainId", "buyToken", "sellToken", "sellAmount"],
    },
  },

• src/index.js:988-990 (registration)

  Registration of the get_swap_quote tool in the MCP CallToolRequestSchema handler switch statement, dispatching to toolService.getSwapQuote.

  case TOOL_NAMES.GET_SWAP_QUOTE:
    result = await toolService.getSwapQuote(args);
    break;

• src/services/agService.js:30-49 (helper)

  Helper function in AgService that performs the actual HTTP request to the aggregator API endpoint /api/swap/quote to fetch the swap quote data.

  async getSwapQuote(params) {
    try {
      const queryParams = new URLSearchParams(params);
      const response = await fetch(`${this.baseUrl}/api/swap/quote?${queryParams}`);
      
      if (!response.ok) {
        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
      }
      
      const data = await response.json();
      
      if (!data.success) {
        throw new Error(data.error || 'API request failed');
      }
      
      return data.data;
    } catch (error) {
      throw new Error(`Failed to get swap quote: ${error.message}`);
    }
  }

• src/constants.js:5-6 (registration)

  Constant definition mapping GET_SWAP_QUOTE to the tool name string 'get_swap_quote' used in schema and registration.

  GET_SWAP_QUOTE: "get_swap_quote",
  EXECUTE_SWAP: "execute_swap",