search

Instructions

Args:
    search_request: The search request containing query, models, and options.

Returns:
    A formatted string containing the AI-generated response and source citations.

Implementation Reference

• src/application/api.py:8-38 (handler)

  The MCP tool handler named 'search'. It executes the search use case via get_search_use_case(), formats the AI-generated response with source citations, and handles SearchError and general exceptions.

  @mcp.tool()
  async def search(search_request: SearchRequestDTO) -> str:
      """Search the web using Perplexica and get AI-generated responses with sources.
  
      Args:
          search_request: The search request containing query, models, and options.
  
      Returns:
          A formatted string containing the AI-generated response and source citations.
      """
      use_case = get_search_use_case()
  
      try:
          result = await use_case.execute(search_request)
  
          response_parts = [result.message]
  
          if result.sources:
              response_parts.append("\n\n## Sources")
              for i, source in enumerate(result.sources, 1):
                  source_line = f"{i}. [{source.title}]({source.url})"
                  if source.snippet:
                      source_line += f"\n   > {source.snippet}"
                  response_parts.append(source_line)
  
          return "\n".join(response_parts)
  
      except SearchError as e:
          return f"Search failed: {e.message}"
      except Exception as e:
          return f"Unexpected error: {e}"

• src/application/requests.py:48-109 (schema)

  Pydantic BaseModel defining the input schema for the 'search' tool, including nested ChatModelRequest and EmbeddingModelRequest, with validation, examples, and descriptions.

  class SearchRequestDTO(BaseModel):
      """Request DTO for search operations.
  
      Attributes:
          query: The search query string.
          chat_model: Configuration for the chat model.
          embedding_model: Configuration for the embedding model.
          focus_mode: The search focus mode.
          optimization_mode: The optimization mode for search.
          history: Conversation history as list of [role, content] tuples.
          system_instructions: Optional custom system instructions.
          stream: Whether to stream the response.
      """
  
      model_config = ConfigDict(
          json_schema_extra={
              "example": {
                  "query": "What is the capital of France?",
                  "chatModel": {
                      "providerId": "a1850332-621f-4960-b005-b005b8680328",
                      "key": "anthropic/claude-sonnet-4.5",
                  },
                  "embeddingModel": {
                      "providerId": "a1850332-621f-4960-b005-b005b8680328",
                      "key": "openai/text-embedding-3-small",
                  },
                  "focusMode": "webSearch",
                  "optimizationMode": "balanced",
                  "history": [
                      ["human", "Hi, how are you?"],
                      ["assistant", "I am doing well, how can I help you today?"],
                  ],
                  "systemInstructions": "Focus on providing accurate information",
                  "stream": False,
              }
          }
      )
  
      query: str = Field(..., min_length=1, description="The search query string")
      chat_model: ChatModelRequest = Field(..., alias="chatModel")
      embedding_model: EmbeddingModelRequest = Field(..., alias="embeddingModel")
      focus_mode: str = Field(
          default="webSearch",
          alias="focusMode",
          description="Search focus mode",
      )
      optimization_mode: str = Field(
          default="balanced",
          alias="optimizationMode",
          description="Optimization mode for search",
      )
      history: list[list[str]] = Field(
          default_factory=list,
          description="Conversation history as list of [role, content] pairs",
      )
      system_instructions: str | None = Field(
          default=None,
          alias="systemInstructions",
          description="Custom system instructions",
      )
      stream: bool = Field(default=False, description="Whether to stream the response")

• src/main.py:6-7 (registration)

  Import statement in main.py that triggers registration of the 'search' MCP tool (and others) via @mcp.tool() decorators in api.py.

  # Import api module to register MCP tools via decorators
  import application.api  # noqa: F401

• src/dependencies.py:11-25 (registration)

  Creation of the FastMCP server instance with instructions documenting the 'search' tool.

  mcp = FastMCP(
      name="mcp-perplexica",
      instructions="""
      MCP server for Perplexica search API.
      
      This server provides web search capabilities through Perplexica,
      allowing you to search the web and get AI-generated responses
      with source citations.
      
      Available tools:
      - search: Perform a web search using Perplexica
      """,
      host=settings.host,
      port=settings.port
  )

• src/dependencies.py:43-54 (helper)

  Dependency injection factory function that provides the SearchUseCase instance (wired with PerplexicaAdapter) to the tool handler.

  def get_search_use_case() -> SearchUseCase:
      """Create SearchUseCase instance with dependencies.
  
      Args:
          settings: Optional settings instance. If not provided, loads from environment.
  
      Returns:
          Configured SearchUseCase instance.
      """
      adapter = get_perplexica_adapter()
      return SearchUseCase(search_port=adapter)