tavus-cli 0.1.0__py3-none-any.whl

tavus_mcp/server.py

@@ -0,0 +1,877 @@
+from __future__ import annotations
+
+from typing import Any
+
+from fastmcp import FastMCP
+
+from tavus_mcp.sdk.client.http import TavusClient
+from tavus_mcp.sdk.recipes.build_and_verify import build_and_verify
+from tavus_mcp.sdk.recipes.options import describe_persona_options
+from tavus_mcp.sdk.recipes.quickstart import quickstart
+from tavus_mcp.sdk.recipes.scaffold_embed import EmbedTarget, scaffold_embed
+from tavus_mcp.sdk.recipes.templates import PersonaTemplate, persona_from_template
+from tavus_mcp.sdk.recipes.tool_reuse import (
+    build_inline_deprecation_notice,
+    build_library_match_advisory,
+    collect_inline_tools,
+)
+
+mcp = FastMCP(
+    "tavus",
+    instructions=(
+        "Persona tools are first-class objects, not inlined on the persona. "
+        "Before giving a persona a tool, check the saved library with "
+        "tavus_tool_list or tavus_describe_persona_options, then either ATTACH an "
+        "existing tool (tavus_persona_tools_attach) or CREATE a new one "
+        "(tavus_tool_create) and attach it. Writing tools inline via "
+        "tavus_patch_persona (layers.*.tools) is deprecated. Whenever you create a "
+        "new tool that overlaps an existing one, tell the user which existing tool "
+        "you saw and why its shape does not fit."
+    ),
+)
+
+
+def _list_data(value: Any) -> list[Any]:
+    if isinstance(value, dict) and isinstance(value.get("data"), list):
+        return value["data"]
+    if isinstance(value, list):
+        return value
+    return []
+
+
+@mcp.tool()
+async def tavus_persona_list(
+    limit: int = 25,
+    page: int = 0,
+    persona_type: str | None = None,
+) -> Any:
+    async with TavusClient.from_env() as client:
+        return await client.personas.list(limit=limit, page=page, persona_type=persona_type)
+
+
+@mcp.tool()
+async def tavus_persona_get(persona_id: str, include_settings: bool = False) -> Any:
+    async with TavusClient.from_env() as client:
+        return await client.personas.get(persona_id, include_settings=str(include_settings).lower())
+
+
+@mcp.tool()
+async def tavus_persona_create(
+    system_prompt: str | None = None,
+    persona_name: str = "Agentic Tavus Persona",
+    default_replica_id: str | None = None,
+    pipeline_mode: str = "full",
+    greeting: str | None = None,
+    context: str | None = None,
+    layers: dict[str, Any] | None = None,
+    memories: list[str] | None = None,
+    objectives_id: str | None = None,
+    guardrails_id: str | None = None,
+    guardrail_ids: list[str] | None = None,
+    guardrail_tags: list[str] | None = None,
+    document_ids: list[str] | None = None,
+    document_tags: list[str] | None = None,
+    is_template: bool | None = None,
+) -> Any:
+    """Create a persona. Beyond ``system_prompt``/``persona_name``, you can seed:
+      - ``pipeline_mode`` — ``"full"`` (default; LLM + TTS + STT + perception),
+        ``"speech-to-speech"`` (no LLM), or ``"echo"`` (TTS + transport only).
+        ``system_prompt`` is required for ``full`` and forbidden for the others.
+      - ``greeting`` — opening line the replica speaks.
+      - ``context`` — opaque text appended to the system prompt at runtime.
+      - ``layers`` — per-layer overrides (llm/tts/stt/perception/conversational_flow/
+        capabilities/knowledge_base). Same shape RQH stores; use
+        ``tavus_describe_persona_options`` to see valid paths.
+      - ``memories`` — initial seed lines for the persona's memory store.
+      - ``objectives_id`` — attach an existing objective set.
+      - ``guardrails_id`` (legacy set) or ``guardrail_ids`` / ``guardrail_tags``
+        (flat per-rule shape) — attach guardrails.
+      - ``document_ids`` / ``document_tags`` — RAG knowledge base.
+      - ``is_template`` — flag this persona as a template others can clone.
+
+    To attach **tools**, create the persona first then call
+    ``tavus_persona_tools_attach`` — tools live in a separate junction,
+    not at persona-create time."""
+    body: dict[str, Any] = {"persona_name": persona_name}
+    if pipeline_mode and pipeline_mode != "full":
+        body["pipeline_mode"] = pipeline_mode
+    if system_prompt is not None:
+        body["system_prompt"] = system_prompt
+    if default_replica_id:
+        body["default_replica_id"] = default_replica_id
+    if greeting is not None:
+        body["greeting"] = greeting
+    if context is not None:
+        body["context"] = context
+    if layers is not None:
+        body["layers"] = layers
+    if memories is not None:
+        body["memories"] = memories
+    if objectives_id:
+        body["objectives_id"] = objectives_id
+    if guardrails_id:
+        body["guardrails_id"] = guardrails_id
+    if guardrail_ids:
+        body["guardrail_ids"] = guardrail_ids
+    if guardrail_tags:
+        body["guardrail_tags"] = guardrail_tags
+    if document_ids:
+        body["document_ids"] = document_ids
+    if document_tags:
+        body["document_tags"] = document_tags
+    if is_template is not None:
+        body["is_template"] = is_template
+    async with TavusClient.from_env() as client:
+        return await client.personas.create(body)
+
+
+@mcp.tool()
+async def tavus_persona_delete(persona_id: str) -> Any:
+    async with TavusClient.from_env() as client:
+        return await client.personas.delete(persona_id)
+
+
+@mcp.tool()
+async def tavus_patch_persona(persona_id: str, ops: list[dict[str, Any]]) -> Any:
+    """Patch a persona with JSON Patch operations.
+
+    Tools are first-class now: prefer tavus_tool_create + tavus_persona_tools_attach
+    over writing tools inline here. If any op writes inline tools (layers.*.tools),
+    the result carries `_inline_tools_deprecated` steering you to that flow."""
+    inline = collect_inline_tools(ops)
+    async with TavusClient.from_env() as client:
+        result = await client.personas.patch(persona_id, ops)
+    if inline and isinstance(result, dict):
+        result["_inline_tools_deprecated"] = build_inline_deprecation_notice(inline)
+    return result
+
+
+@mcp.tool()
+async def tavus_describe_persona_options(persona_id: str) -> Any:
+    async with TavusClient.from_env() as client:
+        return await describe_persona_options(client, persona_id)
+
+
+@mcp.tool()
+async def tavus_replica_list(limit: int = 25, stock: bool = False) -> Any:
+    async with TavusClient.from_env() as client:
+        return await client.replicas.list(limit=limit, replica_type="system" if stock else None)
+
+
+@mcp.tool()
+async def tavus_conversation_create(
+    persona_id: str | None = None,
+    replica_id: str | None = None,
+    conversation_name: str | None = None,
+) -> Any:
+    body = {
+        "persona_id": persona_id,
+        "replica_id": replica_id,
+        "conversation_name": conversation_name,
+    }
+    async with TavusClient.from_env() as client:
+        return await client.conversations.create({k: v for k, v in body.items() if v})
+
+
+@mcp.tool()
+async def tavus_conversation_end(conversation_id: str) -> Any:
+    async with TavusClient.from_env() as client:
+        return await client.conversations.end(conversation_id)
+
+
+@mcp.tool()
+async def tavus_quickstart(
+    system_prompt: str,
+    persona_name: str = "Agentic Tavus Persona",
+    replica_id: str | None = None,
+) -> Any:
+    async with TavusClient.from_env() as client:
+        return await quickstart(
+            client,
+            system_prompt=system_prompt,
+            persona_name=persona_name,
+            replica_id=replica_id,
+        )
+
+
+@mcp.tool()
+async def tavus_persona_from_template(
+    template: PersonaTemplate,
+    persona_name: str | None = None,
+    business_context: str | None = None,
+    default_replica_id: str | None = None,
+    layers: dict[str, Any] | None = None,
+) -> Any:
+    async with TavusClient.from_env() as client:
+        return await persona_from_template(
+            client,
+            template=template,
+            persona_name=persona_name,
+            business_context=business_context,
+            default_replica_id=default_replica_id,
+            layers=layers,
+        )
+
+
+@mcp.tool()
+async def tavus_scaffold_embed(
+    conversation_url: str,
+    target: EmbedTarget = "iframe",
+    component_name: str = "TavusConversation",
+) -> Any:
+    return scaffold_embed(
+        conversation_url=conversation_url,
+        target=target,
+        component_name=component_name,
+    ).model_dump()
+
+
+@mcp.tool()
+async def tavus_resource_list(resource: str, limit: int = 25) -> Any:
+    async with TavusClient.from_env() as client:
+        return await _resource(client, resource).list(limit=limit)
+
+
+@mcp.tool()
+async def tavus_guardrail_list(
+    limit: int = 25,
+    page: int = 1,
+    type: str = "user",
+    name_or_uuid: str | None = None,
+    tags: str | None = None,
+    legacy: bool = False,
+    verbose: bool = False,
+) -> Any:
+    """List guardrails. `type` is "user" (account), "system", or "all";
+    `legacy=False` returns the flat, per-rule shape used by the new
+    persona-builder UI; `verbose=True` adds `persona_refs` and `guardrail_type`."""
+    params: dict[str, Any] = {
+        "limit": limit,
+        "page": page,
+        "type": type,
+        "legacy": "true" if legacy else "false",
+    }
+    if name_or_uuid:
+        params["name_or_uuid"] = name_or_uuid
+    if tags:
+        params["tags"] = tags
+    if verbose:
+        params["verbose"] = "true"
+    async with TavusClient.from_env() as client:
+        return await client.guardrails.list(**params)
+
+
+@mcp.tool()
+async def tavus_guardrail_get(
+    guardrail_id: str, verbose: bool = False, legacy: bool | None = None
+) -> Any:
+    """Get a single guardrail. `verbose=True` adds `persona_refs` and, for
+    individual items, `guardrail_type`."""
+    params: dict[str, Any] = {}
+    if verbose:
+        params["verbose"] = "true"
+    if legacy is not None:
+        params["legacy"] = "true" if legacy else "false"
+    async with TavusClient.from_env() as client:
+        return await client.guardrails.get(guardrail_id, **params)
+
+
+@mcp.tool()
+async def tavus_guardrail_create(
+    guardrail_name: str,
+    guardrail_prompt: str,
+    modality: str = "verbal",
+    callback_url: str = "",
+    tool_call: dict[str, Any] | None = None,
+    app_message: bool = True,
+    tags: list[str] | None = None,
+) -> Any:
+    """Create a flat (non-set) guardrail. `modality` is "verbal" / "visual" /
+    "audio". `tool_call` is optional structured payload sent when the
+    guardrail fires; `app_message=True` emits a data-channel message."""
+    body: dict[str, Any] = {
+        "guardrail_name": guardrail_name,
+        "guardrail_prompt": guardrail_prompt,
+        "modality": modality,
+        "callback_url": callback_url,
+        "app_message": app_message,
+        "tags": tags or [],
+    }
+    if tool_call is not None:
+        body["tool_call"] = tool_call
+    async with TavusClient.from_env() as client:
+        return await client.guardrails.create(body)
+
+
+@mcp.tool()
+async def tavus_guardrail_patch(
+    guardrail_id: str,
+    guardrail_name: str | None = None,
+    guardrail_prompt: str | None = None,
+    modality: str | None = None,
+    callback_url: str | None = None,
+    tool_call: dict[str, Any] | None = None,
+    app_message: bool | None = None,
+    tags: list[str] | None = None,
+) -> Any:
+    """Update a guardrail. Omit fields to leave them unchanged. RQH replaces
+    the whole field where supplied (no JSON-Patch semantics)."""
+    body: dict[str, Any] = {}
+    if guardrail_name is not None:
+        body["guardrail_name"] = guardrail_name
+    if guardrail_prompt is not None:
+        body["guardrail_prompt"] = guardrail_prompt
+    if modality is not None:
+        body["modality"] = modality
+    if callback_url is not None:
+        body["callback_url"] = callback_url
+    if tool_call is not None:
+        body["tool_call"] = tool_call
+    if app_message is not None:
+        body["app_message"] = app_message
+    if tags is not None:
+        body["tags"] = tags
+    async with TavusClient.from_env() as client:
+        return await client.guardrails.patch(guardrail_id, body)
+
+
+@mcp.tool()
+async def tavus_guardrail_delete(guardrail_id: str) -> Any:
+    async with TavusClient.from_env() as client:
+        return await client.guardrails.delete(guardrail_id)
+
+
+@mcp.tool()
+async def tavus_guardrail_tags(
+    search: str | None = None,
+    page: int | None = None,
+    limit: int | None = None,
+) -> Any:
+    """List tags applied to the account's guardrails. Mirrors the documents
+    `/tags` endpoint shape (`{tags, total_count}`)."""
+    async with TavusClient.from_env() as client:
+        return await client.guardrails.tags(search=search, page=page, limit=limit)
+
+
+@mcp.tool()
+async def tavus_objective_list(
+    limit: int = 25,
+    page: int = 1,
+    type: str = "user",
+    name_or_uuid: str | None = None,
+    sort: str = "ascending",
+) -> Any:
+    """List objective *sets*. Objectives still bundle into named sets that
+    personas reference by ``objectives_id`` — unlike guardrails, sets were
+    not flattened."""
+    params: dict[str, Any] = {
+        "limit": limit,
+        "page": page,
+        "type": type,
+        "sort": sort,
+    }
+    if name_or_uuid:
+        params["name_or_uuid"] = name_or_uuid
+    async with TavusClient.from_env() as client:
+        return await client.objectives.list(**params)
+
+
+@mcp.tool()
+async def tavus_objective_get(objectives_id: str) -> Any:
+    async with TavusClient.from_env() as client:
+        return await client.objectives.get(objectives_id)
+
+
+@mcp.tool()
+async def tavus_objective_create(
+    data: list[dict[str, Any]],
+    name: str = "",
+    allow_loops: bool = False,
+) -> Any:
+    """Create an objective set. ``data`` is a list of objective items —
+    each carries ``objective_name`` (letters/digits/underscores only),
+    ``objective_prompt``, optional ``confirmation_mode`` ("auto" | "manual"),
+    ``modality`` ("verbal" | "visual" | "audio"), ``output_variables``,
+    ``callback_url``, ``tool_call``, and chains either via
+    ``next_required_objective`` (linear) **or** ``next_conditional_objectives``
+    (branching) — not both. Exactly one item must be the root (not
+    referenced by any other) unless ``allow_loops=true``."""
+    body = {"name": name, "data": data, "allow_loops": allow_loops}
+    async with TavusClient.from_env() as client:
+        return await client.objectives.create(body)
+
+
+@mcp.tool()
+async def tavus_objective_patch(objectives_id: str, ops: list[dict[str, Any]]) -> Any:
+    """Patch an objective set with JSON Patch ops. RQH applies them to the
+    set document and re-runs cycle/single-root validation on the result.
+    Common ops:
+      - ``{"op": "replace", "path": "/data/0/objective_prompt", "value": "..."}``
+      - ``{"op": "add", "path": "/data/-", "value": {<new objective>}}``
+      - ``{"op": "remove", "path": "/data/2"}``"""
+    async with TavusClient.from_env() as client:
+        return await client.objectives.patch(objectives_id, ops)
+
+
+@mcp.tool()
+async def tavus_objective_delete(objectives_id: str) -> Any:
+    async with TavusClient.from_env() as client:
+        return await client.objectives.delete(objectives_id)
+
+
+@mcp.tool()
+async def tavus_objective_validate(
+    data: list[dict[str, Any]],
+    name: str = "",
+    allow_loops: bool = False,
+) -> Any:
+    """Validate an objective-set payload (cycles, single root, references)
+    without persisting. Useful before bulk-importing or after a manual edit."""
+    body = {"name": name, "data": data, "allow_loops": allow_loops}
+    async with TavusClient.from_env() as client:
+        return await client.objectives.validate(body)
+
+
+@mcp.tool()
+async def tavus_tool_list(
+    limit: int = 25,
+    page: int = 1,
+    type: str = "user",
+    name_or_uuid: str | None = None,
+    sort: str = "ascending",
+) -> Any:
+    """List tools. `type` is "user" / "system" / "all"."""
+    params: dict[str, Any] = {
+        "limit": limit,
+        "page": page,
+        "type": type,
+        "sort": sort,
+    }
+    if name_or_uuid:
+        params["name_or_uuid"] = name_or_uuid
+    async with TavusClient.from_env() as client:
+        return await client.tools.list(**params)
+
+
+@mcp.tool()
+async def tavus_tool_get(tool_id: str) -> Any:
+    async with TavusClient.from_env() as client:
+        return await client.tools.get(tool_id)
+
+
+@mcp.tool()
+async def tavus_tool_create(
+    name: str,
+    description: str,
+    parameters: dict[str, Any] | None = None,
+    delivery: dict[str, Any] | None = None,
+    origin: str = "llm",
+    on_call: str | None = None,
+    on_resolve: str | None = "fire_and_forget",
+    static_filler: str | None = None,
+    tags: list[str] | None = None,
+) -> Any:
+    """Create a tool.
+
+    `delivery` picks the channel: ``{"app_message": true}`` (Daily data
+    channel) or ``{"api": {"url": "https://...", "method": "POST", ...}}``
+    for direct third-party HTTPS calls. The HTTP form supports
+    ``headers``, ``query_params``, ``body_template``, ``content_type``,
+    ``timeout`` (default 10s, max 60), and ``auth`` with type ``none |
+    bearer | basic | api_key | hmac | oauth2_client_credentials``.
+    Placeholders ``{ident}`` in url/body/query must be declared in
+    ``parameters.properties``. Description + parameters JSON must total
+    ≤ 10,000 chars."""
+    body: dict[str, Any] = {
+        "name": name,
+        "description": description,
+        "parameters": parameters or {},
+        "delivery": delivery or {"app_message": True},
+        "origin": origin,
+    }
+    if on_call is not None:
+        body["on_call"] = on_call
+    if on_resolve is not None:
+        body["on_resolve"] = on_resolve
+    if static_filler is not None:
+        body["static_filler"] = static_filler
+    if tags is not None:
+        body["tags"] = tags
+    async with TavusClient.from_env() as client:
+        created = await client.tools.create(body)
+        # Surface same-origin saved tools so the agent reuses instead of
+        # duplicating. Injected as a namespaced key on the returned tool.
+        if isinstance(created, dict):
+            saved = _list_data(await client.tools.list(limit=100))
+            advisory = build_library_match_advisory(origin, name, saved)
+            if advisory:
+                created["_tool_reuse_advisory"] = advisory
+        return created
+
+
+@mcp.tool()
+async def tavus_tool_patch(
+    tool_id: str,
+    name: str | None = None,
+    description: str | None = None,
+    parameters: dict[str, Any] | None = None,
+    delivery: dict[str, Any] | None = None,
+    origin: str | None = None,
+    on_call: str | None = None,
+    on_resolve: str | None = None,
+    static_filler: str | None = None,
+    tags: list[str] | None = None,
+) -> Any:
+    """Update a tool. Omit fields to leave them unchanged. Secrets that came
+    back scrubbed (``********``) from a prior GET must be omitted, not
+    re-sent — RQH rejects the placeholder."""
+    body: dict[str, Any] = {}
+    if name is not None:
+        body["name"] = name
+    if description is not None:
+        body["description"] = description
+    if parameters is not None:
+        body["parameters"] = parameters
+    if delivery is not None:
+        body["delivery"] = delivery
+    if origin is not None:
+        body["origin"] = origin
+    if on_call is not None:
+        body["on_call"] = on_call
+    if on_resolve is not None:
+        body["on_resolve"] = on_resolve
+    if static_filler is not None:
+        body["static_filler"] = static_filler
+    if tags is not None:
+        body["tags"] = tags
+    async with TavusClient.from_env() as client:
+        return await client.tools.patch(tool_id, body)
+
+
+@mcp.tool()
+async def tavus_tool_delete(tool_id: str) -> Any:
+    async with TavusClient.from_env() as client:
+        return await client.tools.delete(tool_id)
+
+
+@mcp.tool()
+async def tavus_pronunciation_dictionary_list(
+    limit: int = 25,
+    page: int = 0,
+    sort: str = "desc",
+) -> Any:
+    """List pronunciation dictionaries — referenced from personas via
+    ``layers.tts.pronunciation_dictionary_id``."""
+    async with TavusClient.from_env() as client:
+        return await client.pronunciation_dictionaries.list(limit=limit, page=page, sort=sort)
+
+
+@mcp.tool()
+async def tavus_pronunciation_dictionary_get(dictionary_id: str) -> Any:
+    async with TavusClient.from_env() as client:
+        return await client.pronunciation_dictionaries.get(dictionary_id)
+
+
+@mcp.tool()
+async def tavus_pronunciation_dictionary_create(
+    name: str, rules: list[dict[str, Any]] | None = None
+) -> Any:
+    """Create a pronunciation dictionary. Each rule is
+    ``{text, pronunciation, type: "alias" | "ipa", alphabet?, case_sensitive?,
+    word_boundaries?}``. ``alias`` swaps the literal text for the
+    pronunciation string before TTS; ``ipa`` interprets the pronunciation
+    as IPA via SSML phoneme tags. ``text`` values must be unique within
+    the dictionary; max 10,000 rules per dictionary."""
+    body = {"name": name, "rules": rules or []}
+    async with TavusClient.from_env() as client:
+        return await client.pronunciation_dictionaries.create(body)
+
+
+@mcp.tool()
+async def tavus_pronunciation_dictionary_patch(
+    dictionary_id: str,
+    name: str | None = None,
+    rules: list[dict[str, Any]] | None = None,
+) -> Any:
+    """Patch a pronunciation dictionary. Supplying ``rules`` replaces the
+    full list (RQH does not merge rule arrays)."""
+    body: dict[str, Any] = {}
+    if name is not None:
+        body["name"] = name
+    if rules is not None:
+        body["rules"] = rules
+    async with TavusClient.from_env() as client:
+        return await client.pronunciation_dictionaries.patch(dictionary_id, body)
+
+
+@mcp.tool()
+async def tavus_pronunciation_dictionary_delete(dictionary_id: str) -> Any:
+    async with TavusClient.from_env() as client:
+        return await client.pronunciation_dictionaries.delete(dictionary_id)
+
+
+@mcp.tool()
+async def tavus_persona_tools_list(persona_id: str) -> Any:
+    """List the tools currently attached to a persona."""
+    async with TavusClient.from_env() as client:
+        return await client.personas.list_tools(persona_id)
+
+
+@mcp.tool()
+async def tavus_persona_tools_attach(persona_id: str, tool_ids: list[str]) -> Any:
+    """Attach one or more existing tools to a persona by ID. A persona can
+    hold up to 50 tools.
+
+    Vision/audio tools only fire when the persona runs Raven, so if any
+    attached tool is vision/audio this bumps the persona's perception_model to
+    raven-1 (response carries `_perception_model_bumped_to_raven_1`)."""
+    async with TavusClient.from_env() as client:
+        attached = await client.personas.attach_tools(persona_id, tool_ids)
+        tools_data = _list_data(attached)
+        origins = {t.get("origin") for t in tools_data if isinstance(t, dict)}
+        perception_bumped = False
+        if origins & {"vision", "audio"}:
+            persona = await client.personas.get(persona_id, include_settings="true")
+            layers = persona.get("layers") or {} if isinstance(persona, dict) else {}
+            perception = layers.get("perception")
+            if not isinstance(perception, dict):
+                op = {
+                    "op": "add",
+                    "path": "/layers/perception",
+                    "value": {"perception_model": "raven-1"},
+                }
+                needs_bump = True
+            elif perception.get("perception_model") not in {"raven-0", "raven-1"}:
+                op = {
+                    "op": "add",
+                    "path": "/layers/perception/perception_model",
+                    "value": "raven-1",
+                }
+                needs_bump = True
+            else:
+                needs_bump = False
+            if needs_bump:
+                await client.personas.patch(persona_id, [op])
+                perception_bumped = True
+        if isinstance(attached, dict):
+            attached["_perception_model_bumped_to_raven_1"] = perception_bumped
+        return attached
+
+
+@mcp.tool()
+async def tavus_persona_tools_detach(persona_id: str, tool_id: str) -> Any:
+    """Detach a tool from a persona."""
+    async with TavusClient.from_env() as client:
+        return await client.personas.detach_tool(persona_id, tool_id)
+
+
+@mcp.tool()
+async def tavus_builder_create(
+    name: str,
+    greeting: str | None = None,
+    persona_id: str | None = None,
+    model: str | None = None,
+) -> Any:
+    body: dict[str, Any] = {"name": name}
+    if greeting is not None:
+        body["greeting"] = greeting
+    if persona_id:
+        body["persona_id"] = persona_id
+    if model:
+        body["model"] = model
+    async with TavusClient.from_env() as client:
+        return await client.builders.create(body)
+
+
+@mcp.tool()
+async def tavus_builder_list(
+    limit: int | None = None,
+    page: int | None = None,
+    persona_id: str | None = None,
+    name: str | None = None,
+    status: str | None = None,
+) -> Any:
+    async with TavusClient.from_env() as client:
+        return await client.builders.list(
+            limit=limit, page=page, persona_id=persona_id, name=name, status=status
+        )
+
+
+@mcp.tool()
+async def tavus_builder_get(builder_id: str) -> Any:
+    async with TavusClient.from_env() as client:
+        return await client.builders.get(builder_id)
+
+
+@mcp.tool()
+async def tavus_builder_delete(builder_id: str) -> Any:
+    async with TavusClient.from_env() as client:
+        return await client.builders.delete(builder_id)
+
+
+@mcp.tool()
+async def tavus_builder_chat(builder_id: str, message: str) -> Any:
+    """Send a chat turn to the builder. Returns a structured response with
+    the assistant text, autocomplete suggestions, a `draft_ready` flag, and
+    the list of persona sections the builder LLM signaled as targets for
+    follow-up scoped updates (use ``tavus_builder_update_*`` to apply)."""
+    async with TavusClient.from_env() as client:
+        return await client.builders.chat(builder_id, message)
+
+
+@mcp.tool()
+async def tavus_builder_chat_history(builder_id: str, limit: int = 50) -> Any:
+    async with TavusClient.from_env() as client:
+        return await client.builders.chat_history(builder_id, limit=limit)
+
+
+@mcp.tool()
+async def tavus_builder_append_messages(builder_id: str, messages: list[dict[str, str]]) -> Any:
+    async with TavusClient.from_env() as client:
+        return await client.builders.append_messages(builder_id, messages)
+
+
+@mcp.tool()
+async def tavus_builder_update_objectives(builder_id: str, message: str) -> Any:
+    async with TavusClient.from_env() as client:
+        return await client.builders.update_objectives(builder_id, message)
+
+
+@mcp.tool()
+async def tavus_builder_update_guardrails(builder_id: str, message: str) -> Any:
+    async with TavusClient.from_env() as client:
+        return await client.builders.update_guardrails(builder_id, message)
+
+
+@mcp.tool()
+async def tavus_builder_update_greeting(builder_id: str, message: str) -> Any:
+    async with TavusClient.from_env() as client:
+        return await client.builders.update_greeting(builder_id, message)
+
+
+@mcp.tool()
+async def tavus_builder_update_personality(
+    builder_id: str,
+    message: str,
+    persona_name: bool = False,
+    system_prompt: bool = False,
+) -> Any:
+    async with TavusClient.from_env() as client:
+        return await client.builders.update_personality(
+            builder_id,
+            message,
+            persona_name=persona_name,
+            system_prompt=system_prompt,
+        )
+
+
+@mcp.tool()
+async def tavus_builder_publish(builder_id: str) -> Any:
+    async with TavusClient.from_env() as client:
+        return await client.builders.publish(builder_id)
+
+
+@mcp.tool()
+async def tavus_chat_start(
+    persona_id: str,
+    custom_greeting: str | None = None,
+    conversation_name: str | None = None,
+) -> Any:
+    """Start a text-only (chat-mode) conversation with a persona. Use this
+    to test a built persona by sending typed turns and reading replies; no
+    replica video is rendered."""
+    body: dict[str, Any] = {"persona_id": persona_id, "chat": True}
+    if custom_greeting:
+        body["custom_greeting"] = custom_greeting
+    if conversation_name:
+        body["conversation_name"] = conversation_name
+    async with TavusClient.from_env() as client:
+        return await client.conversations.create(body)
+
+
+@mcp.tool()
+async def tavus_chat_turn(
+    conversation_id: str,
+    text: str,
+    timeout_s: float = 20.0,
+) -> Any:
+    """Send one user turn to a chat-mode conversation and wait for the
+    persona's reply. Returns ``{text: <reply>}``."""
+    async with TavusClient.from_env() as client:
+        reply = await client.conversations.chat_turn(conversation_id, text, timeout_s=timeout_s)
+    return {"text": reply}
+
+
+@mcp.tool()
+async def tavus_chat_end(conversation_id: str) -> Any:
+    """End a chat-mode conversation. Same call as ``tavus_conversation_end``."""
+    async with TavusClient.from_env() as client:
+        return await client.conversations.end(conversation_id)
+
+
+@mcp.tool()
+async def tavus_persona_preview(
+    persona_id: str,
+    replica_id: str | None = None,
+    conversation_name: str | None = None,
+) -> Any:
+    """Start a full (audio/video) preview conversation against a persona and
+    return ``{conversation_id, conversation_url, ...}``. Hand the URL to a
+    human when you want them to visually verify the persona's behavior."""
+    body: dict[str, Any] = {"persona_id": persona_id}
+    if replica_id:
+        body["replica_id"] = replica_id
+    if conversation_name:
+        body["conversation_name"] = conversation_name
+    async with TavusClient.from_env() as client:
+        if not replica_id:
+            persona = await client.personas.get(persona_id)
+            default_replica = (
+                persona.get("default_replica_id") if isinstance(persona, dict) else None
+            )
+            if default_replica:
+                body["replica_id"] = default_replica
+        return await client.conversations.create(body)
+
+
+@mcp.tool()
+async def tavus_persona_build_and_verify(
+    prompt: str,
+    replica_id: str | None = None,
+    max_rounds: int = 4,
+    answers: list[str] | None = None,
+) -> Any:
+    """Build a persona from one creator prompt, optionally using supplied
+    creator answers for the builder's follow-up questions, then publish and
+    validate it through CVI chat mode. When ``replica_id`` is omitted, RQH
+    selects and attaches the default replica. Validation probes are generated
+    from the resulting persona spec."""
+    async with TavusClient.from_env() as client:
+        return await build_and_verify(
+            client,
+            prompt=prompt,
+            replica_id=replica_id,
+            max_rounds=max_rounds,
+            answers=answers,
+            auto_refine=True,
+            max_refine_rounds=1,
+        )
+
+
+def _resource(client: TavusClient, resource: str) -> Any:
+    normalized = resource.strip().lower().replace("-", "_")
+    aliases = {
+        "guardrail": "guardrails",
+        "objective": "objectives",
+        "document": "documents",
+        "voice": "voices",
+        "tool": "tools",
+    }
+    attr = aliases.get(normalized, normalized)
+    if attr not in {"guardrails", "objectives", "documents", "voices", "tools"}:
+        raise ValueError("resource must be guardrails, objectives, documents, voices, or tools")
+    return getattr(client, attr)
+
+
+def main() -> None:
+    mcp.run()