get_top_topics
Retrieve top-performing forum topics within specified time periods to identify valuable discussions, research important threads, and discover popular content based on engagement scores.
Instructions
Fetch top-performing topics for a specific time period.
Args:
period: Time window for ranking. Must be one of:
- "daily": Top topics from today
- "weekly": Top topics this week
- "monthly": Top topics this month (default)
- "quarterly": Top topics this quarter
- "yearly": Top topics this year
page: Page number for pagination (0-indexed). Use page=1 to get more topics.
Use this to:
- Find the most valuable discussions in a time range
- Research historically important threads
- Identify evergreen popular content
Returns TopicSummary objects sorted by engagement score.
Example: Use "yearly" to find the most impactful discussions,
or "daily" to see what's trending today.Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| period | No | Time window for ranking: 'daily', 'weekly', 'monthly' (default), 'quarterly', or 'yearly' | monthly |
| page | No | Page number for pagination (0-indexed, default: 0) |
Implementation Reference
- The primary MCP tool handler for 'get_top_topics', decorated with @mcp.tool(). Defines the input schema using Pydantic's Annotated and Field for parameters 'period' and 'page'. Includes comprehensive docstring. Delegates execution to the underlying DiscourseClient instance via get_client().
@mcp.tool() def get_top_topics( period: Annotated[ str, Field( default="monthly", description="Time window for ranking: 'daily', 'weekly', 'monthly' (default), 'quarterly', or 'yearly'", ), ] = "monthly", page: Annotated[ int | None, Field(default=None, description="Page number for pagination (0-indexed, default: 0)"), ] = None, ) -> list[TopicSummary]: """ Fetch top-performing topics for a specific time period. Args: period: Time window for ranking. Must be one of: - "daily": Top topics from today - "weekly": Top topics this week - "monthly": Top topics this month (default) - "quarterly": Top topics this quarter - "yearly": Top topics this year page: Page number for pagination (0-indexed). Use page=1 to get more topics. Use this to: - Find the most valuable discussions in a time range - Research historically important threads - Identify evergreen popular content Returns TopicSummary objects sorted by engagement score. Example: Use "yearly" to find the most impactful discussions, or "daily" to see what's trending today. """ return get_client().get_top_topics(period=period, page=page) - src/uscardforum/client.py:185-198 (helper)DiscourseClient wrapper method for get_top_topics. Calls the TopicsAPI implementation and enriches the TopicSummary objects with category names using _enrich_with_categories.
def get_top_topics( self, period: str = "monthly", *, page: int | None = None ) -> list[TopicSummary]: """Fetch top topics for a time period. Args: period: One of 'daily', 'weekly', 'monthly', 'quarterly', 'yearly' page: Page number for pagination (0-indexed, default: 0) Returns: List of top topic summaries """ topics = self._topics.get_top_topics(period=period, page=page) return self._enrich_with_categories(topics) - src/uscardforum/api/topics.py:66-92 (helper)Low-level TopicsAPI.get_top_topics implementation. Performs HTTP GET to '/top.json' with 'period' and 'page' parameters, validates period, parses JSON response from Discourse API, and constructs list of TopicSummary Pydantic models.
def get_top_topics( self, period: str = "monthly", *, page: int | None = None ) -> list[TopicSummary]: """Fetch top topics for a time period. Args: period: One of 'daily', 'weekly', 'monthly', 'quarterly', 'yearly' page: Page number for pagination (0-indexed, default: 0) Returns: List of top topic summaries """ allowed = {"daily", "weekly", "monthly", "quarterly", "yearly"} if period not in allowed: raise ValueError(f"period must be one of {sorted(list(allowed))}") params: dict[str, Any] = {"period": period} if page is not None: params["page"] = int(page) payload = self._get( "/top.json", params=params, headers={"Accept": "application/json, text/plain, */*"}, ) topics = payload.get("topic_list", {}).get("topics", []) return [TopicSummary(**t) for t in topics] - src/uscardforum/server_tools/__init__.py:25-71 (registration)Import of get_top_topics from .topics module in server_tools __init__.py, making it available for import from the package.
from .topics import get_hot_topics, get_new_topics, get_top_topics from .search import search_forum from .categories import get_categories # ============================================================================= # 📖 Reading — Access topic content # ============================================================================= from .topics import get_topic_info, get_topic_posts, get_all_topic_posts # ============================================================================= # 👤 Users — Profile & activity research # ============================================================================= from .users import ( get_user_summary, get_user_topics, get_user_replies, get_user_actions, get_user_badges, get_user_following, get_user_followers, get_user_reactions, list_users_with_badge, ) # ============================================================================= # 🔐 Auth — Authenticated actions (requires login) # ============================================================================= from .auth import ( login, get_current_session, get_notifications, bookmark_post, subscribe_topic, ) # ============================================================================= # Prompts & Resources # ============================================================================= from .prompts import analyze_user, compare_cards, find_data_points, research_topic from .resources import resource_categories, resource_hot_topics, resource_new_topics __all__ = [ # 📰 Discovery "get_hot_topics", "get_new_topics", "get_top_topics", - src/uscardforum/server.py:26-26 (registration)Import of get_top_topics in server.py entrypoint, exposing the tool for MCP server startup.
get_top_topics,