crypto-sentiment-mcp

Instructions

Implementation Reference

• main.py:66-89 (handler)

  The handler function for the 'get_sentiment_balance' tool, registered via @mcp.tool() decorator. It fetches sentiment_balance_total data from Santiment API using the helper function, computes the average over the specified days, and returns a formatted string.

  @mcp.tool()
  def get_sentiment_balance(asset: str, days: int = 7) -> str:
      """
      Retrieve the sentiment balance (sentiment_balance_total) for a given asset.
      
      Parameters:
      - asset (str): The cryptocurrency slug (e.g., "bitcoin", "ethereum"). Required.
      - days (int): Number of days to calculate the average sentiment balance, defaults to 7.
      
      Usage:
      - Use this tool to get the average sentiment balance (positive minus negative sentiment) over a period.
      
      Returns:
      - A string with the average sentiment balance (e.g., "Bitcoin's sentiment balance over the past 7 days is 12.5").
      """
      try:
          data = fetch_santiment_data("sentiment_balance_total", asset, days)
          timeseries = data.get("data", {}).get("getMetric", {}).get("timeseriesData", [])
          if not timeseries:
              return f"Unable to fetch sentiment data for {asset}. Check subscription limits or asset availability."
          avg_balance = sum(float(d["value"]) for d in timeseries) / len(timeseries)
          return f"{asset.capitalize()}'s sentiment balance over the past {days} days is {avg_balance:.1f}."
      except Exception as e:
          return f"Error fetching sentiment balance for {asset}: {str(e)}"

• main.py:16-42 (helper)

  Helper utility function to query Santiment GraphQL API for timeseries data of a specific metric (e.g., sentiment_balance_total) for an asset over a number of days. Used by get_sentiment_balance and other tools.

  def fetch_santiment_data(metric: str, asset: str, days: int) -> dict:
      now = datetime.now(UTC)
      
      to_date = now
      from_date = to_date - timedelta(days=days)
      
      query = f"""
      {{
        getMetric(metric: "{metric}") {{
          timeseriesData(
            slug: "{asset}"
            from: "{from_date.isoformat()}"
            to: "{to_date.isoformat()}"
            interval: "1d"
          ) {{
            datetime
            value
          }}
        }}
      }}
      """
      response = requests.post(SANTIMENT_API_URL, json={"query": query}, headers=HEADERS)
      result = response.json()
      if result.get("errors"):
          raise Exception(f"API error: {result.get('errors')}")
      return result