DevLens MCP

Instructions

Implementation Reference

• src/devlens/server.py:40-51 (registration)

  The tool `tool_search_web` is defined and registered here using the `@mcp.tool()` decorator. It delegates to the `search_web` helper function.

  @mcp.tool()
  async def tool_search_web(query: str, limit: int = 5) -> list[dict]:
      """Search the web using DuckDuckGo.
  
      Args:
          query: Search query string.
          limit: Maximum results (1-20, default 5).
  
      Returns:
          List of results with title, url, snippet.
      """
      return await search_web(query, limit)

• src/devlens/tools/search.py:20-74 (handler)

  The implementation of the web search logic, using `DDGAdapter` to perform the actual search.

  async def search_web(
      query: str,
      limit: int = 5,
      *,
      region: str | None = None,
      safe_search: bool = True,
  ) -> list[dict]:
      """Search the web using DuckDuckGo.
  
      Args:
          query: Search query string. Supports operators like:
              - site:domain.com to search specific domain
              - "exact phrase" for exact matches
              - -word to exclude terms
          limit: Maximum number of results (1-20).
          region: Optional region code (e.g., 'us-en', 'uk-en').
          safe_search: Enable safe search filtering.
  
      Returns:
          List of search results with title, url, and snippet.
  
      Raises:
          SearchError: If search fails or query is invalid.
  
      Example:
          >>> results = await search_web("Python asyncio tutorial", limit=5)
          >>> results = await search_web('site:docs.python.org async', limit=3)
      """
      if not query or not query.strip():
          raise SearchError(query, "Query cannot be empty")
  
      # Normalize query
      normalized = _normalize_query(query)
  
      # Clamp limit
      limit = min(max(limit, 1), 20)
  
      try:
          results = await _adapter.search(
              normalized,
              limit=limit,
              region=region,
              safe_search=safe_search,
          )
  
          # Filter out low-quality results
          filtered = [r for r in results if r.title and r.url and len(r.snippet) > 20]
  
          return [r.model_dump() for r in filtered]
  
      except SearchError:
          raise
      except Exception as e:
          raise SearchError(query, f"Unexpected error: {e}") from e