tavily_fastmcp¶

Top-level package for tavily_fastmcp.

Purpose:

Provide a typed, ergonomic FastMCP wrapper around Tavily search, extract, map, crawl, and research workflows.

Design:

Keep canonical request and response models in one place.
Expose a direct Python service API and a discoverable MCP server API.
Ship large packaged markdown prompts and reusable workflow profiles.

tavily_fastmcp.__all__[source]¶: Curated public API for settings, prompt loading, profile loading, server creation, and the direct Tavily service.

Examples

>>> from tavily_fastmcp import get_settings, load_profile
>>> settings = get_settings
>>> callable(settings)
True

Submodules¶

Classes¶

`LangChainTavilyService`	Production Tavily service backed by `langchain_tavily`.
`Settings`	Runtime settings for `tavily_fastmcp`.

Functions¶

`list_profiles`(→ list[tavily_fastmcp.models.ProfileSummary])	Return summary metadata for all packaged profiles.
`load_profile`(→ tavily_fastmcp.models.PromptProfile)	Load a full packaged prompt profile.
`profile_to_markdown`(→ str)	Render a profile to a human-readable markdown document.
`list_prompt_names`(→ list[str])	Return the packaged prompt names.
`load_prompt_text`(→ str)	Load a packaged markdown prompt.
`create_server`(→ Any)	Create a configured FastMCP server instance.
`get_settings`(→ Settings)	Return the cached package settings.

Package Contents¶

tavily_fastmcp.list_profiles() → list[tavily_fastmcp.models.ProfileSummary][source]¶

Return summary metadata for all packaged profiles.

Returns:: Sorted profile summaries.
Raises:: FileNotFoundError – If a packaged prompt file is missing.

Examples

>>> any(profile.slug == "router" for profile in list_profiles())
True

tavily_fastmcp.load_profile(slug: str) → tavily_fastmcp.models.PromptProfile[source]¶

Load a full packaged prompt profile.

Parameters:

slug – Stable profile slug.

Returns:

The full prompt profile.

Raises:

KeyError – If the profile slug is unknown.
FileNotFoundError – If the prompt markdown file is missing.

Examples

>>> load_profile("deep-research").title
'Deep Research'

tavily_fastmcp.profile_to_markdown(profile: tavily_fastmcp.models.PromptProfile) → str[source]¶

Render a profile to a human-readable markdown document.

Parameters:: profile – The profile to render.
Returns:: Markdown that combines metadata with prompt text.
Raises:: ValueError – If rendering fails.

Examples

>>> md = profile_to_markdown(load_profile("router"))
>>> md.startswith("# ")
True

tavily_fastmcp.list_prompt_names() → list[str][source]¶

Return the packaged prompt names.

Returns:: Sorted prompt names without file extensions.
Raises:: FileNotFoundError – If the prompts package is unavailable.

Examples

>>> isinstance(list_prompt_names(), list)
True

tavily_fastmcp.load_prompt_text(name: str) → str[source]¶

Load a packaged markdown prompt.

Parameters:: name – Prompt name without .md.
Returns:: The markdown contents of the prompt file.
Raises:: FileNotFoundError – If the prompt does not exist.

Examples

>>> text = load_prompt_text("router")
>>> text.startswith("# ")
True

tavily_fastmcp.create_server(*, settings: tavily_fastmcp.settings.Settings | None = None, service: tavily_fastmcp.service.TavilyServiceProtocol | None = None) → Any[source]¶

Create a configured FastMCP server instance.

Parameters:

settings – Optional validated settings object.
service – Optional Tavily service implementation for dependency injection in tests.

Returns:

A configured FastMCP server instance.

Raises:

RuntimeError – If FastMCP is not installed.

Examples

>>> callable(create_server)
True

class tavily_fastmcp.LangChainTavilyService(settings: tavily_fastmcp.settings.Settings)[source]¶

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[source]¶

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[source]¶: Execute an extract request.

map_from_model(request: tavily_fastmcp.models.MapRequest | None = None, **kwargs: Any) → tavily_fastmcp.models.MapResponse[source]¶: Execute a map request.

crawl_from_model(request: tavily_fastmcp.models.CrawlRequest | None = None, **kwargs: Any) → tavily_fastmcp.models.CrawlResponse[source]¶: Execute a crawl request.

research_from_model(request: tavily_fastmcp.models.ResearchRequest | None = None, **kwargs: Any) → tavily_fastmcp.models.ResearchResponse[source]¶: Execute a research request.

get_research_from_model(request: tavily_fastmcp.models.GetResearchRequest | None = None, **kwargs: Any) → tavily_fastmcp.models.ResearchResponse[source]¶: Retrieve a research task.

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

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

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

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

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

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

class tavily_fastmcp.Settings(_case_sensitive: bool | None = None, _nested_model_default_partial_update: bool | None = None, _env_prefix: str | None = None, _env_prefix_target: pydantic_settings.sources.EnvPrefixTarget | None = None, _env_file: pydantic_settings.sources.DotenvType | None = ENV_FILE_SENTINEL, _env_file_encoding: str | None = None, _env_ignore_empty: bool | None = None, _env_nested_delimiter: str | None = None, _env_nested_max_split: int | None = None, _env_parse_none_str: str | None = None, _env_parse_enums: bool | None = None, _cli_prog_name: str | None = None, _cli_parse_args: bool | list[str] | tuple[str, Ellipsis] | None = None, _cli_settings_source: pydantic_settings.sources.CliSettingsSource[Any] | None = None, _cli_parse_none_str: str | None = None, _cli_hide_none_type: bool | None = None, _cli_avoid_json: bool | None = None, _cli_enforce_required: bool | None = None, _cli_use_class_docs_for_groups: bool | None = None, _cli_exit_on_error: bool | None = None, _cli_prefix: str | None = None, _cli_flag_prefix_char: str | None = None, _cli_implicit_flags: bool | Literal['dual', 'toggle'] | None = None, _cli_ignore_unknown_args: bool | None = None, _cli_kebab_case: bool | Literal['all', 'no_enums'] | None = None, _cli_shortcuts: collections.abc.Mapping[str, str | list[str]] | None = None, _secrets_dir: pydantic_settings.sources.PathType | None = None, _build_sources: tuple[tuple[pydantic_settings.sources.PydanticBaseSettingsSource, Ellipsis], dict[str, Any]] | None = None, **values: Any)[source]¶

Bases: pydantic_settings.BaseSettings

Runtime settings for tavily_fastmcp.

Parameters:

tavily_api_key – Tavily API key read from TAVILY_API_KEY.
transport – MCP transport to run when using the CLI.
host – Hostname for streamable HTTP or SSE style transports.
port – TCP port for HTTP-based transports.
log_level – Logging verbosity.
default_search_topic – Default Tavily topic.
default_search_depth – Default Tavily search depth.
enable_live_tests – Whether live integration tests are enabled.

Returns:

A validated settings object.

Raises:

ValueError – If one or more settings values are invalid.

Examples

>>> settings = Settings.model_construct(
...     tavily_api_key="dummy",
...     transport="stdio",
... )
>>> settings.transport
'stdio'

model_config¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

tavily_api_key: pydantic.SecretStr = None¶

transport: Literal['stdio', 'http', 'sse'] = 'stdio'¶

host: str = '127.0.0.1'¶

port: int = 8001¶

log_level: Literal['DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'] = 'INFO'¶

default_search_topic: Literal['general', 'news', 'finance'] = 'general'¶

default_search_depth: Literal['basic', 'advanced'] = 'basic'¶

enable_live_tests: bool = False¶

tavily_fastmcp.get_settings() → Settings[source]¶

Return the cached package settings.

Returns:: The cached validated settings object.
Raises:: ValueError – If required environment variables are missing.

Examples

>>> from tavily_fastmcp.settings import get_settings
>>> callable(get_settings)
True