AlphaVantage-MCP

Instructions

Implementation Reference

• src/alpha_vantage_mcp/server.py:418-444 (handler)

  The main handler function that implements the core logic for the 'get-crypto-exchange-rate' tool. It validates input parameters, makes an asynchronous HTTP request to the Alpha Vantage CURRENCY_EXCHANGE_RATE API using the make_alpha_request helper, handles errors, formats the response using format_crypto_rate, and returns a formatted text content response.

  elif name == "get-crypto-exchange-rate":
      crypto_symbol = arguments.get("crypto_symbol")
      if not crypto_symbol:
          return [types.TextContent(type="text", text="Missing crypto_symbol parameter")]
  
      market = arguments.get("market", "USD")
      crypto_symbol = crypto_symbol.upper()
      market = market.upper()
  
      async with httpx.AsyncClient() as client:
          crypto_data = await make_alpha_request(
              client,
              "CURRENCY_EXCHANGE_RATE",
              None,
              {
                  "from_currency": crypto_symbol,
                  "to_currency": market
              }
          )
  
          if isinstance(crypto_data, str):
              return [types.TextContent(type="text", text=f"Error: {crypto_data}")]
  
          formatted_rate = format_crypto_rate(crypto_data)
          rate_text = f"Cryptocurrency exchange rate for {crypto_symbol}/{market}:\n\n{formatted_rate}"
  
          return [types.TextContent(type="text", text=rate_text)]

• src/alpha_vantage_mcp/server.py:67-85 (registration)

  Tool registration in the list_tools handler, defining the tool name, description, and JSON schema for input validation (crypto_symbol required, market optional with USD default).

  types.Tool(
      name="get-crypto-exchange-rate",
      description="Get current cryptocurrency exchange rate",
      inputSchema={
          "type": "object",
          "properties": {
              "crypto_symbol": {
                  "type": "string",
                  "description": "Cryptocurrency symbol (e.g., BTC, ETH)",
              },
              "market": {
                  "type": "string",
                  "description": "Market currency (e.g., USD, EUR)",
                  "default": "USD"
              }
          },
          "required": ["crypto_symbol"],
      },
  ),

• src/alpha_vantage_mcp/server.py:70-84 (schema)

  JSON schema defining the input parameters for the tool: crypto_symbol (string, required) and market (string, optional default 'USD').

  inputSchema={
      "type": "object",
      "properties": {
          "crypto_symbol": {
              "type": "string",
              "description": "Cryptocurrency symbol (e.g., BTC, ETH)",
          },
          "market": {
              "type": "string",
              "description": "Market currency (e.g., USD, EUR)",
              "default": "USD"
          }
      },
      "required": ["crypto_symbol"],
  },

• src/alpha_vantage_mcp/tools.py:147-172 (helper)

  Supporting helper function that takes the raw API response from Alpha Vantage CURRENCY_EXCHANGE_RATE and formats it into a readable multi-line string with currency details, exchange rate, bid/ask prices, and metadata.

  def format_crypto_rate(crypto_data: Dict[str, Any]) -> str:
      """Format cryptocurrency exchange rate data into a concise string.
      
      Args:
          crypto_data: The response data from the Alpha Vantage CURRENCY_EXCHANGE_RATE endpoint
          
      Returns:
          A formatted string containing the cryptocurrency exchange rate information
      """
      try:
          realtime_data = crypto_data.get("Realtime Currency Exchange Rate", {})
          if not realtime_data:
              return "No exchange rate data available in the response"
  
          return (
              f"From: {realtime_data.get('2. From_Currency Name', 'N/A')} ({realtime_data.get('1. From_Currency Code', 'N/A')})\n"
              f"To: {realtime_data.get('4. To_Currency Name', 'N/A')} ({realtime_data.get('3. To_Currency Code', 'N/A')})\n"
              f"Exchange Rate: {realtime_data.get('5. Exchange Rate', 'N/A')}\n"
              f"Last Updated: {realtime_data.get('6. Last Refreshed', 'N/A')} {realtime_data.get('7. Time Zone', 'N/A')}\n"
              f"Bid Price: {realtime_data.get('8. Bid Price', 'N/A')}\n"
              f"Ask Price: {realtime_data.get('9. Ask Price', 'N/A')}\n"
              "---"
          )
      except Exception as e:
          return f"Error formatting cryptocurrency data: {str(e)}"