search_subreddits

Instructions

Search for subreddits using either name-based or description-based search.

Args:
    by: Search parameters, either SearchByName or SearchByDescription

Returns:
    List of matching subreddits with their details

Implementation Reference

• src/reddit_mcp/tools/search_subreddits.py:52-85 (handler)

  The core handler function that implements the search_subreddits tool logic. It uses the RedditClient to search subreddits by name or description based on input parameters and maps results to SubredditResult models.

  def search_subreddits(by: SearchParams) -> List[SubredditResult]:
      """
      Search for subreddits using either name-based or description-based search.
  
      Args:
          by: Search parameters, either SearchByName or SearchByDescription
  
      Returns:
          List of matching subreddits with their details
      """
      client = RedditClient.get_instance()
  
      if by.type == "name":
          subreddits = client.reddit.subreddits.search_by_name(
              by.query, exact=by.exact_match, include_nsfw=by.include_nsfw
          )
      else:  # by.type == "description"
          subreddits = client.reddit.subreddits.search(by.query)
  
      return [
          SubredditResult(
              name=subreddit.display_name,
              public_description=subreddit.public_description,
              description=(
                  subreddit.description
                  if (by.type == "description" and by.include_full_description)
                  else None
              ),
              url=subreddit.url,
              subscribers=subreddit.subscribers,
              created_utc=format_utc_timestamp(subreddit.created_utc),
          )
          for subreddit in subreddits
      ]

• src/reddit_mcp/tools/search_subreddits.py:23-48 (schema)

  Input schema definitions for the tool, discriminating union between SearchByName and SearchByDescription parameters.

  class SearchByName(BaseModel):
      """Parameters for searching subreddits by name"""
  
      type: Literal["name"]
      query: str
      include_nsfw: bool = Field(
          default=False,
          description="Whether to include NSFW subreddits in search results",
      )
      exact_match: bool = Field(
          default=False, description="If True, only return exact name matches"
      )
  
  
  class SearchByDescription(BaseModel):
      """Parameters for searching subreddits by description"""
  
      type: Literal["description"]
      query: str
      include_full_description: bool = Field(
          default=False,
          description="Whether to include the full subreddit description (aka sidebar description) in results -- can be very long and contain markdown formatting",
      )
  
  
  SearchParams = Union[SearchByName, SearchByDescription]

• src/reddit_mcp/tools/search_subreddits.py:9-21 (schema)

  Output schema model defining the structure of each subreddit result returned by the tool.

  class SubredditResult(BaseModel):
      """Subreddit search result"""
  
      name: str = Field(description="Display name of the subreddit")
      public_description: str = Field(description="Short description shown publicly")
      url: str = Field(description="URL of the subreddit")
      subscribers: int | None = Field(default=None, description="Number of subscribers")
      created_utc: str = Field(description="UTC date when subreddit was created")
      description: str | None = Field(
          default=None,
          description="Full subreddit description with markdown formatting",
      )

• src/reddit_mcp/tools/__init__.py:17-24 (registration)

  The search_subreddits tool function is included in the central tools registry list, which is imported and used by the MCP server for registration.

  tools = [
      get_submission,
      get_subreddit,
      get_comments_by_submission,
      get_comment_by_id,
      search_posts,
      search_subreddits,
  ]

• src/reddit_mcp/server.py:10-13 (registration)

  Generic registration loop in the MCP server that applies mcp.tool() decorator to each function in the tools list, including search_subreddits.

  for tool in tools:
      logger.info(f"Registering tool: {tool.__name__}")
      mcp.tool()(tool)