tavily_fastmcp.service

Direct Tavily service layer.

Purpose:

Offer a typed Python API that wraps langchain-tavily while keeping optional third-party imports out of package import time.

Design:

• Define a protocol so tests can swap in a fake service.

• Normalize upstream payloads into stable local models.

• Keep network calls explicit and easy to mock.

Examples

>>> from tavily_fastmcp.models import SearchRequest
>>> callable(SearchRequest)
True

Attributes

_SEARCH_CONSTRUCTOR_FIELDS

Classes

TavilyServiceProtocol	Protocol for Tavily operations used by the MCP server.
LangChainTavilyService	Production Tavily service backed by langchain_tavily.

Module Contents

tavily_fastmcp.service._SEARCH_CONSTRUCTOR_FIELDS

class tavily_fastmcp.service.TavilyServiceProtocol

Bases: Protocol

Protocol for Tavily operations used by the MCP server.

Examples

>>> hasattr(TavilyServiceProtocol, '__class__')
True

search_from_model(request: tavily_fastmcp.models.SearchRequest | None = None, **kwargs: Any) → tavily_fastmcp.models.SearchResponse

Execute a Tavily search request.

extract_from_model(request: tavily_fastmcp.models.ExtractRequest | None = None, **kwargs: Any) → tavily_fastmcp.models.ExtractResponse

Execute a Tavily extract request.

map_from_model(request: tavily_fastmcp.models.MapRequest | None = None, **kwargs: Any) → tavily_fastmcp.models.MapResponse

Execute a Tavily map request.

crawl_from_model(request: tavily_fastmcp.models.CrawlRequest | None = None, **kwargs: Any) → tavily_fastmcp.models.CrawlResponse

Execute a Tavily crawl request.

research_from_model(request: tavily_fastmcp.models.ResearchRequest | None = None, **kwargs: Any) → tavily_fastmcp.models.ResearchResponse

Execute a Tavily research request.

get_research_from_model(request: tavily_fastmcp.models.GetResearchRequest | None = None, **kwargs: Any) → tavily_fastmcp.models.ResearchResponse

Retrieve a Tavily research task.

class tavily_fastmcp.service.LangChainTavilyService(settings: tavily_fastmcp.settings.Settings)

Production Tavily service backed by langchain_tavily.

Parameters:

settings – Package settings containing the Tavily API key and defaults for topic and depth.

Returns:

A service object able to execute Tavily operations.

Raises:

RuntimeError – If langchain_tavily is not installed.

Examples

>>> service = LangChainTavilyService.__new__(LangChainTavilyService)
>>> service is not None
True

settings

_search_tool_cls

_search_tool

_extract_tool

_map_tool

_crawl_tool

_research_tool

_get_research_tool

search_from_model(request: tavily_fastmcp.models.SearchRequest | None = None, **kwargs: Any) → tavily_fastmcp.models.SearchResponse

Execute a search request.

Parameters:

• request – Optional typed request.

• **kwargs – Alternative field values when no request is supplied.

Returns:

A normalized search response.

Raises:

RuntimeError – If the underlying tool call fails.

Examples

>>> callable(LangChainTavilyService.search_from_model)
True

extract_from_model(request: tavily_fastmcp.models.ExtractRequest | None = None, **kwargs: Any) → tavily_fastmcp.models.ExtractResponse

Execute an extract request.

map_from_model(request: tavily_fastmcp.models.MapRequest | None = None, **kwargs: Any) → tavily_fastmcp.models.MapResponse

Execute a map request.

crawl_from_model(request: tavily_fastmcp.models.CrawlRequest | None = None, **kwargs: Any) → tavily_fastmcp.models.CrawlResponse

Execute a crawl request.

research_from_model(request: tavily_fastmcp.models.ResearchRequest | None = None, **kwargs: Any) → tavily_fastmcp.models.ResearchResponse

Execute a research request.

get_research_from_model(request: tavily_fastmcp.models.GetResearchRequest | None = None, **kwargs: Any) → tavily_fastmcp.models.ResearchResponse

Retrieve a research task.

static _raise_if_error(raw: dict[str, Any]) → None

static _normalize_search_response(raw: dict[str, Any]) → tavily_fastmcp.models.SearchResponse

static _normalize_extract_response(raw: dict[str, Any]) → tavily_fastmcp.models.ExtractResponse

static _normalize_map_response(raw: dict[str, Any]) → tavily_fastmcp.models.MapResponse

static _normalize_crawl_response(raw: dict[str, Any]) → tavily_fastmcp.models.CrawlResponse

static _normalize_research_response(raw: dict[str, Any]) → tavily_fastmcp.models.ResearchResponse