wormhole-metrics-mcp

Instructions

Fetch top symbols by volume from Wormholescan API.

Args:
    timeSpan: Time span for data (7d, 15d, 30d). Default: 7d

Returns:
    String representation of a pandas DataFrame containing top symbols by volume

Implementation Reference

• main.py:343-402 (handler)

  Handler function decorated with @mcp.tool() implementing the get_top_symbols_by_volume tool. Fetches data from Wormholescan API, validates input, processes into sorted DataFrame, returns markdown.

  # Define the get_top_symbols_by_volume tool
  @mcp.tool()
  async def get_top_symbols_by_volume(
      timeSpan: str = "7d"
  ) -> str:
      """
      Fetch top symbols by volume from Wormholescan API.
      
      Args:
          timeSpan: Time span for data (7d, 15d, 30d). Default: 7d
      
      Returns:
          String representation of a pandas DataFrame containing top symbols by volume
      """
      try:
          # Validate parameters
          valid_time_spans = {"7d", "15d", "30d"}
          
          if timeSpan not in valid_time_spans:
              raise ValueError(f"Invalid timeSpan. Must be one of {valid_time_spans}")
          
          # Construct query parameters
          params = {"timeSpan": timeSpan}
          
          # Make API request
          async with httpx.AsyncClient() as client:
              response = await client.get(
                  f"{API_BASE}/api/v1/top-symbols-by-volume",
                  params=params
              )
              response.raise_for_status()
              
              # Parse JSON response
              data = response.json()
              
              # Transform data for DataFrame
              rows = [
                  {
                      "symbol": item.get("symbol"),
                      "volume": item.get("volume"),
                      "txs": item.get("txs")
                  }
                  for item in data.get("symbols", [])
              ]
              
              # Create DataFrame
              df = pd.DataFrame(rows)
              
              # Convert numeric columns
              df["volume"] = pd.to_numeric(df["volume"], errors="coerce")
              df["txs"] = pd.to_numeric(df["txs"], errors="coerce")
              
              # Sort by volume descending for readability
              df = df.sort_values("volume", ascending=False)
              
              return df.to_markdown(index=False)
              
      except Exception as e:
          return str(e)        

• main.py:344-344 (registration)

  The @mcp.tool() decorator registers the get_top_symbols_by_volume function as an MCP tool.

  @mcp.tool()

• main.py:345-347 (schema)

  Function signature with type hints and docstring defining input schema (timeSpan: str) and output (str markdown table). Includes inline validation.

  async def get_top_symbols_by_volume(
      timeSpan: str = "7d"
  ) -> str: