Web Research Assistant

Instructions

Search for packages by keywords or description across registries.

Use this to find packages that solve a specific problem or provide certain functionality.
Perfect for discovering libraries when you know what you need but not the package name.

Examples:
- package_search("web framework", reasoning="Need backend framework", registry="npm")
- package_search("json parsing", reasoning="Data processing", registry="pypi")

Implementation Reference

• src/searxng_mcp/server.py:566-621 (handler)

  MCP tool handler for 'package_search'. Calls PackageRegistryClient.search_packages, formats results with _format_package_search_results, handles errors and tracks usage.

  @mcp.tool()
  async def package_search(
      query: Annotated[
          str,
          "Search keywords (e.g., 'web framework', 'json parser', 'machine learning')",
      ],
      reasoning: Annotated[str, "Why you're searching for packages (required for analytics)"],
      registry: Annotated[
          Literal["npm", "pypi", "crates", "go"],
          "Package registry to search (npm, pypi, crates, go)",
      ] = "npm",
      max_results: Annotated[int, "Maximum number of results to return (1-10)"] = 5,
  ) -> str:
      """
      Search for packages by keywords or description across registries.
  
      Use this to find packages that solve a specific problem or provide certain functionality.
      Perfect for discovering libraries when you know what you need but not the package name.
  
      Examples:
      - package_search("web framework", reasoning="Need backend framework", registry="npm")
      - package_search("json parsing", reasoning="Data processing", registry="pypi")
      """
      start_time = time.time()
      success = False
      error_msg = None
      result = ""
  
      try:
          max_results = max(1, min(max_results, 10))  # Clamp to 1-10
  
          packages = await registry_client.search_packages(query, registry, max_results)
          result = _format_package_search_results(packages, query, registry)
          result = clamp_text(result, MAX_RESPONSE_CHARS)
          success = True
      except Exception as exc:  # noqa: BLE001
          error_msg = str(exc)
          result = f"Search failed for '{query}' on {registry}: {exc}"
      finally:
          # Track usage
          response_time = (time.time() - start_time) * 1000
          tracker.track_usage(
              tool_name="package_search",
              reasoning=reasoning,
              parameters={
                  "query": query,
                  "registry": registry,
                  "max_results": max_results,
              },
              response_time_ms=response_time,
              success=success,
              error_message=error_msg,
              response_size=len(result.encode("utf-8")),
          )
  
      return result

• src/searxng_mcp/server.py:540-564 (helper)

  Helper function to format the list of PackageInfo objects into a human-readable string for the tool response.

  def _format_package_search_results(packages: list[PackageInfo], query: str, registry: str) -> str:
      """Format package search results into readable text."""
  
      if not packages:
          return f"No packages found for '{query}' on {registry}.\n\nTry different keywords or check another registry."
  
      lines = [
          f"Search Results for '{query}' on {registry}:",
          "─" * 50,
      ]
  
      for i, pkg in enumerate(packages, 1):
          lines.append(f"{i}. {pkg.name}")
          if pkg.version != "unknown":
              lines.append(f"   Version: {pkg.version}")
          if pkg.downloads:
              lines.append(f"   Downloads: {pkg.downloads}")
          if pkg.description:
              # Truncate long descriptions
              desc = pkg.description[:100] + "..." if len(pkg.description) > 100 else pkg.description
              lines.append(f"   Description: {desc}")
          lines.append("")  # blank line between results
  
      return "\n".join(lines)

• src/searxng_mcp/registry.py:36-49 (helper)

  Core helper method in PackageRegistryClient that dispatches to registry-specific search functions (_search_npm, etc.) based on the registry parameter.

  async def search_packages(
      self, query: str, registry: str, max_results: int = 5
  ) -> list[PackageInfo]:
      """Search for packages by description/keywords."""
  
      if registry == "npm":
          return await self._search_npm(query, max_results)
      elif registry == "pypi":
          return await self._search_pypi(query, max_results)
      elif registry == "crates":
          return await self._search_crates(query, max_results)
      else:  # go
          return await self._search_go(query, max_results)

• src/searxng_mcp/registry.py:12-27 (schema)

  Dataclass schema defining the structure of package information used throughout the package search functionality.

  @dataclass(slots=True)
  class PackageInfo:
      """Structured package metadata from various registries."""
  
      name: str
      registry: str
      version: str
      description: str
      license: str | None
      downloads: str | None
      last_updated: str
      repository: str | None
      homepage: str | None
      dependencies_count: int | None
      security_issues: int

• src/searxng_mcp/server.py:26-34 (registration)

  Import and instantiation of PackageRegistryClient used by the package_search tool.

  from .registry import PackageInfo, PackageRegistryClient
  from .search import SearxSearcher
  from .service_health import ServiceHealthChecker
  from .tracking import get_tracker
  
  mcp = FastMCP("web-research-assistant")
  searcher = SearxSearcher()
  crawler_client = CrawlerClient()
  registry_client = PackageRegistryClient()