Documentation Search MCP Server

Instructions

Search with advanced filtering options.

Args:
    query: The search query
    library: The library to search in
    content_type: Filter by content type ("tutorial", "reference", "example", "guide")
    difficulty_level: Filter by difficulty ("beginner", "intermediate", "advanced")
    has_code_examples: Filter for content with code examples (true/false)
    version: Library version to search (e.g., "4.2", "stable", "latest"). Default: "latest"
    auto_detect_version: Automatically detect installed package version. Default: False

Returns:
    Filtered search results matching specified criteria

Implementation Reference

• src/documentation_search_enhanced/main.py:970-1037 (handler)

  The main handler function for the 'filtered_search' MCP tool. It constructs SearchFilters from parameters and delegates to the FilteredSearch instance's search_with_filters method. Includes the @mcp.tool() registration decorator.

  @mcp.tool()
  async def filtered_search(
      query: str,
      library: str,
      content_type: Optional[str] = None,
      difficulty_level: Optional[str] = None,
      has_code_examples: Optional[bool] = None,
      version: str = "latest",
      auto_detect_version: bool = False,
  ):
      """
      Search with advanced filtering options.
  
      Args:
          query: The search query
          library: The library to search in
          content_type: Filter by content type ("tutorial", "reference", "example", "guide")
          difficulty_level: Filter by difficulty ("beginner", "intermediate", "advanced")
          has_code_examples: Filter for content with code examples (true/false)
          version: Library version to search (e.g., "4.2", "stable", "latest"). Default: "latest"
          auto_detect_version: Automatically detect installed package version. Default: False
  
      Returns:
          Filtered search results matching specified criteria
      """
      from .smart_search import filtered_search, SearchFilters
  
      await enforce_rate_limit("filtered_search")
  
      filters = SearchFilters(
          content_type=content_type,
          difficulty_level=difficulty_level,
          has_code_examples=has_code_examples,
      )
  
      try:
          results = await filtered_search.search_with_filters(query, library, filters)
  
          return {
              "query": query,
              "library": library,
              "filters_applied": {
                  "content_type": content_type,
                  "difficulty_level": difficulty_level,
                  "has_code_examples": has_code_examples,
              },
              "total_results": len(results),
              "results": [
                  {
                      "title": result.title,
                      "url": result.url,
                      "snippet": (
                          result.snippet[:200] + "..."
                          if len(result.snippet) > 200
                          else result.snippet
                      ),
                      "relevance_score": result.relevance_score,
                      "content_type": result.content_type,
                      "difficulty_level": result.difficulty_level,
                      "estimated_read_time": f"{result.estimated_read_time} min",
                  }
                  for result in results[:10]
              ],
          }
      except Exception as e:
          return {"error": f"Filtered search failed: {str(e)}", "results": []}

• src/documentation_search_enhanced/smart_search.py:420-469 (helper)

  FilteredSearch class that wraps SmartSearch and applies post-search filtering based on content_type, difficulty_level, and has_code_examples.

  class FilteredSearch:
      """Search with advanced filtering capabilities"""
  
      def __init__(self, smart_search: SmartSearch):
          self.smart_search = smart_search
  
      async def search_with_filters(
          self, query: str, library: str, filters: SearchFilters
      ) -> List[SearchResult]:
          """Perform search with applied filters"""
  
          # Get base search results
          results = await self.smart_search.semantic_search(query, library)
  
          # Apply filters
          filtered_results = []
          for result in results:
              if self.passes_filters(result, filters):
                  filtered_results.append(result)
  
          return filtered_results
  
      def passes_filters(self, result: SearchResult, filters: SearchFilters) -> bool:
          """Check if a result passes all filters"""
  
          if filters.content_type and result.content_type != filters.content_type:
              return False
  
          if (
              filters.difficulty_level
              and result.difficulty_level != filters.difficulty_level
          ):
              return False
  
          if filters.has_code_examples is not None:
              has_code = result.code_snippets_count > 0
              if filters.has_code_examples != has_code:
                  return False
  
          if (
              filters.max_reading_time
              and result.estimated_read_time > filters.max_reading_time
          ):
              return False
  
          # Language filter would need more sophisticated detection
          # For now, skip language filtering
  
          return True

• src/documentation_search_enhanced/smart_search.py:409-418 (schema)

  Dataclass defining the filter parameters used by FilteredSearch.

  @dataclass
  class SearchFilters:
      """Filters for refining search results"""
  
      content_type: Optional[str] = None  # "tutorial", "reference", "example"
      difficulty_level: Optional[str] = None  # "beginner", "intermediate", "advanced"
      has_code_examples: Optional[bool] = None
      max_reading_time: Optional[int] = None  # in minutes
      language: Optional[str] = None  # programming language

• src/documentation_search_enhanced/smart_search.py:472-474 (helper)

  Global instance of FilteredSearch used by the tool handler.

  smart_search = SmartSearch()
  filtered_search = FilteredSearch(smart_search)