crypto-sentiment-mcp

Instructions

Implementation Reference

• main.py:151-190 (handler)

  The main handler function for the 'get_trending_words' MCP tool, including decorator, type hints, docstring, and execution logic that aggregates trending words from Santiment API data.

  @mcp.tool()
  def get_trending_words(days: int = 7, top_n: int = 5) -> str:
      """
      Retrieve the top trending words in the crypto space over a specified period, aggregated and ranked by score.
      
      Parameters:
      - days (int): Number of days to analyze trending words, defaults to 7.
      - top_n (int): Number of top trending words to return, defaults to 5.
      
      Usage:
      - Call this tool to get a list of the most popular words trending in cryptocurrency discussions, ranked across the entire period.
      
      Returns:
      - A string listing the top trending words (e.g., "Top 5 trending words over the past 7 days: 'halving', 'bullrun', 'defi', 'nft', 'pump'").
      """
      try:
          data = fetch_trending_words(days)
          trends = data.get("data", {}).get("getTrendingWords", [])
          if not trends:
              return "Unable to fetch trending words. Check API subscription limits or connectivity."
          
          word_scores = {}
          for day in trends:
              for word_data in day["topWords"]:
                  word = word_data["word"]
                  score = word_data["score"]
                  if word in word_scores:
                      word_scores[word] += score
                  else:
                      word_scores[word] = score
          
          if not word_scores:
              return "No trending words data available for the specified period."
          
          top_words = sorted(word_scores.items(), key=lambda x: x[1], reverse=True)[:top_n]
          top_words_list = [word for word, _ in top_words]
          
          return f"Top {top_n} trending words over the past {days} days: {', '.join(top_words_list)}."
      except Exception as e:
          return f"Error fetching trending words: {str(e)}"

• main.py:43-64 (helper)

  Helper function that queries the Santiment GraphQL API to fetch raw trending words data (getTrendingWords), used by the main handler.

  def fetch_trending_words(days: int = 7) -> dict:
      now = datetime.now(UTC)
      
      to_date = now
      from_date = to_date - timedelta(days=days)
      
      query = f"""
      {{
        getTrendingWords(size: 10, from: "{from_date.isoformat()}", to: "{to_date.isoformat()}", interval: "1d") {{
          datetime
          topWords {{
            word
            score
          }}
        }}
      }}
      """
      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:152-165 (schema)

  Function signature with type annotations and docstring defining input schema (days: int=7, top_n: int=5) and output (str) for the tool.

  def get_trending_words(days: int = 7, top_n: int = 5) -> str:
      """
      Retrieve the top trending words in the crypto space over a specified period, aggregated and ranked by score.
      
      Parameters:
      - days (int): Number of days to analyze trending words, defaults to 7.
      - top_n (int): Number of top trending words to return, defaults to 5.
      
      Usage:
      - Call this tool to get a list of the most popular words trending in cryptocurrency discussions, ranked across the entire period.
      
      Returns:
      - A string listing the top trending words (e.g., "Top 5 trending words over the past 7 days: 'halving', 'bullrun', 'defi', 'nft', 'pump'").
      """

• main.py:151-151 (registration)

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

  @mcp.tool()