crypto-sentiment-mcp

Instructions

Implementation Reference

• main.py:116-149 (handler)

  The handler function for 'alert_social_shift' tool. It fetches social volume data from Santiment API, computes the percentage change of the latest day compared to the average of previous days, and alerts if it exceeds the threshold. Registered via @mcp.tool() decorator.
  @mcp.tool() def alert_social_shift(asset: str, threshold: float = 50.0, days: int = 7) -> str: """ Detect significant shifts (spikes or drops) in social volume (social_volume_total) for a given asset. Parameters: - asset (str): The cryptocurrency slug (e.g., "bitcoin", "ethereum"). Required. - threshold (float): Minimum percentage change (absolute value) to trigger an alert, defaults to 50.0 (i.e., 50%). - days (int): Number of days to analyze for baseline volume, defaults to 7. Usage: - Call this tool to check if the latest social volume has significantly spiked or dropped compared to the previous average. Returns: - A string indicating if a shift occurred (e.g., "Bitcoin's social volume spiked by 75.0% in the last 24 hours" or "Bitcoin's social volume dropped by 60.0% in the last 24 hours"). """ try: data = fetch_santiment_data("social_volume_total", asset, days) timeseries = data.get("data", {}).get("getMetric", {}).get("timeseriesData", []) if not timeseries or len(timeseries) < 2: return f"Unable to detect social volume shift for {asset}, insufficient data." latest_volume = int(timeseries[-1]["value"]) # Latest day's volume prev_avg_volume = sum(int(d["value"]) for d in timeseries[:-1]) / (len(timeseries) - 1) # Average of previous days change_percent = ((latest_volume - prev_avg_volume) / prev_avg_volume) * 100 abs_change = abs(change_percent) if abs_change >= threshold: direction = "spiked" if change_percent > 0 else "dropped" return f"{asset.capitalize()}'s social volume {direction} by {abs_change:.1f}% in the last 24 hours, from an average of {prev_avg_volume:,.0f} to {latest_volume:,}." return f"No significant shift detected for {asset.capitalize()}, change is {change_percent:.1f}%." except Exception as e: return f"Error detecting social volume shift for {asset}: {str(e)}"
• main.py:16-42 (helper)

  Helper function used by alert_social_shift to fetch timeseries data from Santiment GraphQL API for a given metric and asset over specified days.
  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
• main.py:116-116 (registration)

  The @mcp.tool() decorator registers the alert_social_shift function as an MCP tool.
  @mcp.tool()
• main.py:118-131 (schema)

  Docstring providing schema description, parameters, usage, and return format for the tool.
  """ Detect significant shifts (spikes or drops) in social volume (social_volume_total) for a given asset. Parameters: - asset (str): The cryptocurrency slug (e.g., "bitcoin", "ethereum"). Required. - threshold (float): Minimum percentage change (absolute value) to trigger an alert, defaults to 50.0 (i.e., 50%). - days (int): Number of days to analyze for baseline volume, defaults to 7. Usage: - Call this tool to check if the latest social volume has significantly spiked or dropped compared to the previous average. Returns: - A string indicating if a shift occurred (e.g., "Bitcoin's social volume spiked by 75.0% in the last 24 hours" or "Bitcoin's social volume dropped by 60.0% in the last 24 hours"). """