tavus-cli 0.9.1__tar.gz → 0.9.2__tar.gz

tavus_cli-0.9.2/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.9.2"
+}

{tavus_cli-0.9.1 → tavus_cli-0.9.2}/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.9.2](https://github.com/Tavus-Engineering/tavus-mcp/compare/v0.9.1...v0.9.2) (2026-10-10)
+
+
+### Bug Fixes
+
+* align MCP capability guidance with Charlie builder ([#68](https://github.com/Tavus-Engineering/tavus-mcp/issues/68)) ([c7a903d](https://github.com/Tavus-Engineering/tavus-mcp/commit/c7a903d08bc4f355a75d892924c1656e2c43caf4))
+
 ## [0.9.1](https://github.com/Tavus-Engineering/tavus-mcp/compare/v0.9.0...v0.9.1) (2026-10-09)
 
 

{tavus_cli-0.9.1 → tavus_cli-0.9.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: tavus-cli
-Version: 0.9.1
+Version: 0.9.2
 Summary: Tavus CLI and MCP server for agentic PAL creation and editing.
 Requires-Python: >=3.11
 Requires-Dist: fastmcp>=2.0.0
@@ -328,6 +328,13 @@ administration tools, and two tools that keep backward-compatible local names
 locally; `tavus_pal_capabilities_catalog` / `tavus_pal_knowledge_settings`
 hosted).
 
+Both servers load their builder instructions and capability-selection guidance
+from [builder_guidance.json](src/tavus_mcp/builder_guidance.json). These rules
+adapt Charlie's builder prompt to the MCP tools, including using Magic Canvas
+for on-screen scorecards instead of creating a saved tool. See
+[maintaining builder guidance](docs/builder-guidance.md) for the source and
+behavior checks.
+
 ### Deploys and releases
 
 Merges to `main` automatically build, test, deploy, and smoke-test the `stg`

{tavus_cli-0.9.1 → tavus_cli-0.9.2}/PROMPT.md

@@ -28,6 +28,8 @@ How the server works
 - Everything on a PAL is a resource with an id: faces, voices, guardrails, objectives, Knowledge documents, tools. Get ids from the matching list call (`tavus_face_list`, `tavus_voice_list`, `tavus_guardrail_list`, `tavus_objective_list`, `tavus_document_list`, `tavus_tool_list`) or from `tavus_describe_pal_options`, which returns one PAL with everything attachable to it.
 - Tools are first-class records. A tool is created once with `tavus_tool_create` and attached with `tavus_pal_tools_attach`. Writing tools inline under `layers.llm.tools` is rejected.
 - The five PAL Maker capabilities (Magic Canvas, Slide Presenter, Web Search, Perception, Memory) go through `tavus_pal_capability_attach`, `tavus_pal_capability_patch` and `tavus_pal_capability_detach`, not raw patches.
+- Choose built-ins by intent before creating tools. On-screen scorecards, quizzes, forms, charts, and links use Magic Canvas. Attach `magic_canvas` with the needed `magic_canvas_components` and `magic_canvas_usage_guidance` together. For a training scorecard, use `text` and/or `chart`; keep display choreography in the capability's usage guidance. A saved tool or API response cannot render the canvas. Saving results to a backend is a separate action and requires a real endpoint or implemented handler. Do not invent a delivery tool when only display or collection is needed. If I have not requested on-screen interaction, offer it once and wait for agreement.
+- Use Web Search for live weather, news, prices, and scores; Slide Presenter for an uploaded deck; Perception for screen and camera awareness; Memory for returning participants. Do not replace these with custom tools. After configuration, read `tavus_pal_capabilities_list` to verify the attachment. Successful saving or text testing does not prove that a card rendered; check the live display before claiming that.
 - Every conversation is billed like any other, including the build's own test turns, chat-mode tests and previews.
 
 How to do the common things properly

{tavus_cli-0.9.1 → tavus_cli-0.9.2}/README.md

@@ -306,6 +306,13 @@ administration tools, and two tools that keep backward-compatible local names
 locally; `tavus_pal_capabilities_catalog` / `tavus_pal_knowledge_settings`
 hosted).
 
+Both servers load their builder instructions and capability-selection guidance
+from [builder_guidance.json](src/tavus_mcp/builder_guidance.json). These rules
+adapt Charlie's builder prompt to the MCP tools, including using Magic Canvas
+for on-screen scorecards instead of creating a saved tool. See
+[maintaining builder guidance](docs/builder-guidance.md) for the source and
+behavior checks.
+
 ### Deploys and releases
 
 Merges to `main` automatically build, test, deploy, and smoke-test the `stg`

tavus_cli-0.9.2/docs/builder-guidance.md

@@ -0,0 +1,41 @@
+# Maintaining builder guidance
+
+Both MCP servers load `src/tavus_mcp/builder_guidance.json`. It supplies the
+instructions returned during MCP initialization, guidance on the create-tool
+and capability tools, and the Magic Canvas catalog description. The JSON ships
+inside the Python package and is bundled into the hosted Worker.
+
+The rules are adapted from `src/constants/builder.constants.ts` in
+`Tavus/developer-portal`, inspected at commit
+`dd5ad35b3` on October 9, 2026. The relevant sections are the on-screen
+interaction offer, built-in capabilities, saved tools, and the Magic Canvas
+capability catalog. When Charlie's rules change, review this shared file and
+the companion instructions in `PROMPT.md` and `skills/tavus-agentic-pals/SKILL.md`.
+
+Use MCP tool names and parameters when adapting Charlie's rules. Do not copy
+Portal-only tool names, UI instructions, or capabilities this server cannot
+configure. In particular, the hosted attach tool takes `capability`, while the
+local tool takes `capability_id`.
+
+## Behavior checks
+
+Use these prompts to evaluate capability selection with an MCP client:
+
+| Request | Expected behavior |
+| --- | --- |
+| Show a training scorecard after each exercise. | Attach Magic Canvas with `text` and/or `chart` and usage guidance in the same call. Do not create `record_training_scorecard`. |
+| Collect an email address on screen. We have no backend yet. | Attach Magic Canvas with `input`. Explain that delivery can be connected later. Do not invent an endpoint. |
+| Show the score and save it to our existing API. | Configure Magic Canvas for display and separately reuse or create a tool for the verified API. |
+| Ask quiz questions and keep a running score. | Use `question` plus `text` or `chart`; the model supplies questions and scores. |
+| Tell callers the current weather. | Attach Web Search and write location-first lookup instructions. Do not create `get_weather`. |
+| Walk through this uploaded slide deck automatically. | Attach Slide Presenter with the document IDs and `walk_the_deck`. |
+| Notice what I share on screen. | Configure Perception. Do not create `view_screen`. |
+| Remember returning visitors. | Attach Memory and add a first-visit fallback in the prompt and greeting. |
+| Do not show anything on screen. | Respect the decline; do not attach Magic Canvas. |
+
+The automated tests verify that clients receive the shared guidance and that
+the scorecard configuration travels through the MCP tools to the skills API and
+back, using a mocked API. They do not evaluate a model's tool choice or prove
+live rendering. For a live evaluation, record the model's tool calls, read back
+the saved capability, and inspect the canvas during a call before claiming the
+scorecard displayed.

{tavus_cli-0.9.1 → tavus_cli-0.9.2}/packages/tavus/pyproject.toml

@@ -1,11 +1,11 @@
 [project]
 name = "tavus"
-version = "0.9.1" # x-release-please-version
+version = "0.9.2" # x-release-please-version
 description = "Official alias for tavus-cli, the Tavus CLI and MCP server."
 readme = "README.md"
 requires-python = ">=3.11"
 dependencies = [
-  "tavus-cli==0.9.1", # x-release-please-version
+  "tavus-cli==0.9.2", # x-release-please-version
 ]
 
 [project.urls]

{tavus_cli-0.9.1 → tavus_cli-0.9.2}/packages/tavus-mcp/pyproject.toml

@@ -1,11 +1,11 @@
 [project]
 name = "tavus-mcp"
-version = "0.9.1" # x-release-please-version
+version = "0.9.2" # x-release-please-version
 description = "Official alias for tavus-cli, which provides the tavus-mcp MCP server."
 readme = "README.md"
 requires-python = ">=3.11"
 dependencies = [
-  "tavus-cli==0.9.1", # x-release-please-version
+  "tavus-cli==0.9.2", # x-release-please-version
 ]
 
 [project.urls]

{tavus_cli-0.9.1 → tavus_cli-0.9.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tavus-cli"
-version = "0.9.1"
+version = "0.9.2"
 description = "Tavus CLI and MCP server for agentic PAL creation and editing."
 readme = "README.md"
 requires-python = ">=3.11"

{tavus_cli-0.9.1 → tavus_cli-0.9.2}/skills/tavus-agentic-pals/SKILL.md

@@ -241,6 +241,21 @@ ids are `magic_canvas`, `slide_presenter`, `web_search`, `perception`, and
 Canvas, Slide Presenter, Web Search, and Memory persist through
 `/pals/{id}/skills`; Perception persists through `/layers/perception`.
 
+Choose built-ins by the requested behavior before creating a saved tool.
+On-screen scorecards, quizzes, forms, charts, and links use Magic Canvas.
+Attach `magic_canvas` with `magic_canvas_components` and
+`magic_canvas_usage_guidance` together. For a training scorecard, select `text`
+and/or `chart` and describe when to show it in the usage guidance. A saved tool
+or API response cannot render Magic Canvas. Recording results to a real backend
+is a separate action; do not create a placeholder tool for display or collection.
+Offer optional canvas interaction once and respect a decline.
+
+Use Web Search for live weather, news, prices, and scores; Slide Presenter for
+uploaded decks; Perception for camera and screen awareness; Memory for returning
+participants. Read `tavus_pal_capabilities_list` after configuring a capability.
+Saved settings and successful text tests do not prove visible rendering; verify
+the display in a live call before claiming it works.
+
 For PAL Knowledge, prefer `tavus_pal_knowledge_*` or
 `uv run tavus pal knowledge ...` over raw JSON Patch. The Knowledge section is
 `document_ids` plus `document_tags`, and RAG tuning lives under

{tavus_cli-0.9.1 → tavus_cli-0.9.2}/src/tavus_mcp/__init__.py

@@ -1,4 +1,4 @@
 """Tavus CLI and MCP server package."""
 
 __all__ = ["__version__"]
-__version__ = "0.9.1"  # x-release-please-version
+__version__ = "0.9.2"  # x-release-please-version

tavus_cli-0.9.2/src/tavus_mcp/builder_guidance.json

@@ -0,0 +1,21 @@
+{
+  "instructions": [
+    "Build PALs by the creator's intent. Check built-in capabilities before creating a saved tool. Read tavus_pal_capabilities_list for an existing PAL; preserve unrelated settings and attachments. Use tavus_pal_capability_attach, tavus_pal_capability_patch, and tavus_pal_capability_detach to configure built-ins.",
+    "Magic Canvas (magic_canvas) handles on-screen scorecards, running scores, charts, quizzes, forms, contact capture, text, and links during a call. A request to show a training scorecard means enabling Magic Canvas, not creating record_training_scorecard. The PAL's own model drives the canvas; a saved tool or API response cannot draw on it. Model-generated quiz questions, scores, dice rolls, and random picks do not need a custom tool. If the creator also wants to save results to a backend, configure that separately; recording data does not display it.",
+    "When the creator requests on-screen interaction, attach magic_canvas with the needed magic_canvas_components and magic_canvas_usage_guidance in the same call. For a scorecard use text and/or chart. For forms use input; for quizzes use question. Put one or two lines of when-to-show choreography in magic_canvas_usage_guidance, not in the PAL's system prompt. On attach, the component list selects what to enable and omitted components are disabled. For an existing canvas, read its config first. When patching config.components, send the full component map with your changes and preserve all unchanged settings, including any booking link. If the use case only suggests a canvas, offer it once and wait for agreement; a decline stays declined. Without a backend, explain that collection works on screen and delivery can be connected later. Do not create a placeholder delivery tool.",
+    "Magic Canvas calendar collects date/time preferences; it does not book appointments. Scheduling requires the creator's real HTTPS calendly.com booking link in scheduling_url, not a placeholder. Do not include scheduling_embed in magic_canvas_components to enable it; supply the booking link. Do not promise image or map output. Use only supported elements from the capability catalog.",
+    "Use slide_presenter for presenting an uploaded deck. Supply display-ready document_ids and slides_trigger=walk_the_deck for automatic narration and advancement, or on_demand when the PAL should wait. For a presentation or sales use case, offer a slide deck once; Magic Canvas does not replace Slide Presenter.",
+    "Use web_search for current information the finished PAL needs during calls, including weather, news, prices, and scores. Attach it and update the PAL's instructions with when to look up information; for weather ask for the location first. Do not create get_weather or invent an endpoint. Research needed only to build the PAL does not require attaching Web Search.",
+    "Use perception for camera and screen awareness, not an invented view_screen tool. Use memory for continuity with returning participants; update the prompt and greeting to use remembered information with a fallback for first-time visitors. Do not invent a custom tool for a missing integration or unsupported capability.",
+    "Create a saved tool only for a real external action, data lookup, or application event that built-ins do not provide. First inspect tavus_tool_list or tavus_describe_pal_options and reuse a matching tool. Use an endpoint supplied by the creator or verified in their code, or an app-message handler that the application implements. Never invent URLs or claim an unimplemented handler works. If a new tool overlaps an existing one, explain why the existing shape does not fit. Attach the returned tool_id with tavus_pal_tools_attach. Inline layers.*.tools writes through tavus_patch_pal are rejected.",
+    "Knowledge uses document_ids/document_tags and layers.knowledge_base settings. Use tavus_document_* for the library and tavus_pal_knowledge_* for attachments. Reading a document does not attach it.",
+    "After a capability write, read tavus_pal_capabilities_list to confirm the saved attachment and config. Report what the tools confirm. Saved config, successful backend delivery, and visible rendering are separate checks. Do not claim a canvas was displayed without a live visual check. A build or text-test verdict alone does not prove on-screen behavior."
+  ],
+  "tool_descriptions": {
+    "tavus_tool_create": "Create a saved tool for a real external action or application handler. Check built-in capabilities first: scorecards, quizzes, forms, charts, and on-screen text use tavus_pal_capability_attach with magic_canvas. A saved tool cannot render Magic Canvas. Backend recording is separate from on-screen display. Use web_search for weather or current information. Never invent an endpoint or placeholder handler.",
+    "tavus_pal_capability_attach": "Enable a built-in capability by intent. Use magic_canvas for scorecards, quizzes, forms, charts, and on-screen text; pass magic_canvas_components and magic_canvas_usage_guidance in this call. Use slide_presenter for decks, web_search for current information, perception for screen/camera awareness, and memory for returning participants. Read tavus_pal_capabilities_list afterward to verify the saved config.",
+    "tavus_pal_capability_patch": "Update an enabled built-in capability. For Magic Canvas, keep display choreography in magic_canvas_usage_guidance. The patch merges top-level config fields but replaces config.components when supplied. Read the saved config and preserve unchanged component settings, including any booking link, when changing components. Read tavus_pal_capabilities_list afterward to verify the saved config."
+  },
+  "magic_canvas_description": "Show scorecards, running scores, quizzes, forms, charts, text, and links during a call. The PAL's model drives the canvas; saved tools and API responses cannot render it. Use text or chart for a training scorecard, question for quizzes, and input for contact capture. Calendar collects preferences but books nothing. Scheduling needs a real HTTPS Calendly booking link. Image and map output are not available.",
+  "magic_canvas_usage_guidance": "One or two lines describing when to show each element, with one fixed variant per step. Keep this display choreography here rather than in the PAL's system prompt."
+}

tavus_cli-0.9.2/src/tavus_mcp/builder_guidance.py

@@ -0,0 +1,9 @@
+"""Builder guidance shared by the Python and hosted MCP servers."""
+
+import json
+from importlib.resources import files
+
+BUILDER_GUIDANCE = json.loads(
+    files("tavus_mcp").joinpath("builder_guidance.json").read_text(encoding="utf-8")
+)
+SERVER_INSTRUCTIONS = "\n\n".join(BUILDER_GUIDANCE["instructions"])

{tavus_cli-0.9.1 → tavus_cli-0.9.2}/src/tavus_mcp/sdk/recipes/capabilities.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 from typing import Any, Literal
 
+from tavus_mcp.builder_guidance import BUILDER_GUIDANCE
 from tavus_mcp.sdk.client.http import TavusClient
 
 CapabilityId = Literal[
@@ -29,7 +30,7 @@ MAGIC_CANVAS_COMPONENT_IDS = (
 CAPABILITY_CATALOG: dict[CapabilityId, dict[str, Any]] = {
     "magic_canvas": {
         "display_name": "Magic Canvas",
-        "description": "Show interactive on-screen elements during a call.",
+        "description": BUILDER_GUIDANCE["magic_canvas_description"],
         "portal_id": "builtin:magic_canvas",
         "rqh_skill_id": "magic_canvas",
         "config": {
@@ -37,7 +38,7 @@ CAPABILITY_CATALOG: dict[CapabilityId, dict[str, Any]] = {
                 "Sparse map of component id to config. Omitted components default on, "
                 "except scheduling_embed requires scheduling_url."
             ),
-            "usage_guidance": "Optional per-PAL guidance for when to use canvas elements.",
+            "usage_guidance": BUILDER_GUIDANCE["magic_canvas_usage_guidance"],
         },
     },
     "slide_presenter": {

{tavus_cli-0.9.1 → tavus_cli-0.9.2}/src/tavus_mcp/server.py

@@ -8,6 +8,7 @@ from typing import Annotated, Any, Literal
 from fastmcp import FastMCP
 from pydantic import Field
 
+from tavus_mcp.builder_guidance import BUILDER_GUIDANCE, SERVER_INSTRUCTIONS
 from tavus_mcp.sdk import daily_transport
 from tavus_mcp.sdk.auth.session import get_session
 from tavus_mcp.sdk.client.http import TavusClient, tool_call_context
@@ -164,6 +165,9 @@ class AnnotatedFastMCP(FastMCP):
         if name_or_fn is None:
             return lambda fn: self.tool(fn, **kwargs)
         name = kwargs.get("name") or name_or_fn.__name__
+        guidance = BUILDER_GUIDANCE["tool_descriptions"].get(name)
+        if guidance:
+            kwargs["description"] = guidance + "\n\n" + (inspect.getdoc(name_or_fn) or "")
         if kwargs.get("annotations") is None:
             kwargs["annotations"] = _annotations_for_tool(name)
         return super().tool(_with_intent(name_or_fn, name), **kwargs)
@@ -171,25 +175,7 @@ class AnnotatedFastMCP(FastMCP):
 
 mcp = AnnotatedFastMCP(
     "tavus",
-    instructions=(
-        "PAL tools are first-class objects, not inlined on the PAL. "
-        "Built-in PAL capabilities are backed by the PAL skills API: "
-        "Magic Canvas -> magic_canvas, Slide Presenter -> presentation, "
-        "Web Search -> internet_search, Memory -> memory; Perception is the "
-        "PAL's layers.perception config. Use tavus_pal_capabilities_list and "
-        "tavus_pal_capability_attach/detach/patch for those five PAL Maker "
-        "capabilities. "
-        "PAL Knowledge is backed by document_ids/document_tags plus "
-        "layers.knowledge_base RAG settings. Use tavus_document_* for the "
-        "document library and tavus_pal_knowledge_* for PAL attachments. "
-        "Before giving a PAL a tool, check the saved library with "
-        "tavus_tool_list or tavus_describe_pal_options, then either ATTACH an "
-        "existing tool (tavus_pal_tools_attach) or CREATE a new one "
-        "(tavus_tool_create) and attach it. Writing tools inline via "
-        "tavus_patch_pal (layers.*.tools) is rejected. 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."
-    ),
+    instructions=SERVER_INSTRUCTIONS,
 )
 
 

{tavus_cli-0.9.1 → tavus_cli-0.9.2}/tests/integration/test_mcp_server.py

@@ -10,6 +10,7 @@ from fastmcp import Client
 from httpx import Response
 from pydantic import ValidationError
 
+from tavus_mcp.builder_guidance import BUILDER_GUIDANCE, SERVER_INSTRUCTIONS
 from tavus_mcp.sdk.errors import TavusApiError
 from tavus_mcp.server import (
     mcp,
@@ -22,6 +23,57 @@ from tavus_mcp.server import (
 )
 
 
+@pytest.mark.asyncio
+async def test_builder_guidance_reaches_mcp_clients() -> None:
+    async with Client(mcp) as client:
+        assert client.initialize_result.instructions == SERVER_INSTRUCTIONS
+        tools = {tool.name: tool for tool in await client.list_tools()}
+        for name, guidance in BUILDER_GUIDANCE["tool_descriptions"].items():
+            assert tools[name].description.startswith(guidance)
+
+
+@pytest.mark.asyncio
+@respx.mock
+async def test_scorecard_attaches_canvas_through_mcp(clean_env: Path) -> None:
+    (clean_env / ".env").write_text(
+        "TAVUS_ENV=TEST\nTAVUS_API_KEY=test-key\n"
+        "TAVUS_PUBLIC_API_BASE_URL=https://api.example.test/v2\n"
+    )
+    saved = {}
+
+    def save_canvas(request):
+        saved.update(json.loads(request.content))
+        return Response(200, json={"skill_id": "magic_canvas", **saved})
+
+    route = respx.put("https://api.example.test/v2/pals/p-score/skills/magic_canvas").mock(
+        side_effect=save_canvas
+    )
+    respx.get("https://api.example.test/v2/pals/p-score").respond(200, json={"layers": {}})
+    respx.get("https://api.example.test/v2/pals/p-score/skills/").mock(
+        side_effect=lambda _: Response(
+            200, json={"data": {"magic_canvas": {"skill_id": "magic_canvas", **saved}}}
+        )
+    )
+    async with Client(mcp) as client:
+        await client.call_tool("tavus_pal_capability_attach", {
+            "pal_id": "p-score",
+            "capability_id": "magic_canvas",
+            "magic_canvas_components": ["text", "chart"],
+            "magic_canvas_usage_guidance": "Show the training scorecard after each exercise.",
+        })
+        result = await client.call_tool("tavus_pal_capabilities_list", {"pal_id": "p-score"})
+
+    assert route.call_count == 1
+    canvas = result.data["capabilities"]["magic_canvas"]
+    assert canvas["attached"] is True
+    assert canvas["attachment"]["config"] == saved["config"]
+    config = saved["config"]
+    assert config["usage_guidance"] == "Show the training scorecard after each exercise."
+    assert config["components"]["input"] == {"enabled": False}
+    assert "text" not in config["components"]  # Enabled by the skill's defaults.
+    assert "chart" not in config["components"]
+
+
 @pytest.mark.asyncio
 async def test_mcp_server_imports_and_registers_tools() -> None:
     tools = {tool.name: tool for tool in await mcp.list_tools()}

{tavus_cli-0.9.1 → tavus_cli-0.9.2}/uv.lock

@@ -1303,7 +1303,7 @@ wheels = [
 
 [[package]]
 name = "tavus-cli"
-version = "0.9.1"
+version = "0.9.2"
 source = { editable = "." }
 dependencies = [
     { name = "fastmcp" },

{tavus_cli-0.9.1 → tavus_cli-0.9.2}/workers/tavus-mcp/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@tavus/tavus-mcp-worker",
-  "version": "0.9.1",
+  "version": "0.9.2",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@tavus/tavus-mcp-worker",
-      "version": "0.9.1",
+      "version": "0.9.2",
       "dependencies": {
         "@modelcontextprotocol/sdk": "^1.29.0",
         "agents": "^0.12.2",

{tavus_cli-0.9.1 → tavus_cli-0.9.2}/workers/tavus-mcp/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tavus/tavus-mcp-worker",
-  "version": "0.9.1",
+  "version": "0.9.2",
   "private": true,
   "type": "module",
   "scripts": {

{tavus_cli-0.9.1 → tavus_cli-0.9.2}/workers/tavus-mcp/src/tavus.ts

@@ -5,6 +5,7 @@ import type { RegisteredTool } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
 import { z } from "zod";
 
+import builderGuidance from "../../../src/tavus_mcp/builder_guidance.json";
 import type { OAuthGrantKind } from "./oauth-grant";
 import { VERSION } from "./version";
 import type { OAuthSessionStoreBinding } from "./oauth-session";
@@ -275,13 +276,13 @@ export const CAPABILITY_CATALOG: Record<
 > = {
   magic_canvas: {
     display_name: "Magic Canvas",
-    description: "Show interactive on-screen elements during a call.",
+    description: builderGuidance.magic_canvas_description,
     portal_id: "builtin:magic_canvas",
     rqh_skill_id: "magic_canvas",
     config: {
       components:
         "Sparse map of component id to config. Omitted components default on, except scheduling_embed requires scheduling_url.",
-      usage_guidance: "Optional per-PAL guidance for when to use canvas elements.",
+      usage_guidance: builderGuidance.magic_canvas_usage_guidance,
     },
   },
   slide_presenter: {
@@ -533,7 +534,7 @@ export function createTavusMcpServer(
         theme: "dark",
       },
     ],
-  });
+  }, { instructions: builderGuidance.instructions.join("\n\n") });
   addToolIntent(server, authChallenge);
 
   server.tool(
@@ -1061,7 +1062,7 @@ export function createTavusMcpServer(
 
   server.tool(
     "tavus_tool_create",
-    "Create a first-class tool. Attach the returned tool_id to a PAL with tavus_pal_tools_attach or top-level tool_ids.",
+    builderGuidance.tool_descriptions.tavus_tool_create + " Attach the returned tool_id to a PAL with tavus_pal_tools_attach or top-level tool_ids.",
     toolWriteFields,
     writeAnnotations("Create tool"),
     async (body) => toolResult(await client.create("tools", clean(body))),
@@ -1301,7 +1302,7 @@ export function createTavusMcpServer(
 
   server.tool(
     "tavus_pal_capability_attach",
-    "Attach a PAL Maker capability by friendly id or portal id. Includes Magic Canvas, Slide Presenter, Web Search, Perception, and Memory.",
+    builderGuidance.tool_descriptions.tavus_pal_capability_attach,
     capabilityWriteSchema,
     {
       title: "Attach PAL capability",
@@ -1315,7 +1316,7 @@ export function createTavusMcpServer(
 
   server.tool(
     "tavus_pal_capability_patch",
-    "Patch an already-attached PAL Maker capability.",
+    builderGuidance.tool_descriptions.tavus_pal_capability_patch,
     capabilityWriteSchema,
     {
       title: "Patch PAL capability",

tavus_cli-0.9.2/workers/tavus-mcp/src/version.ts

@@ -0,0 +1 @@
+export const VERSION = "0.9.2"; // x-release-please-version

tavus_cli-0.9.2/workers/tavus-mcp/test/builder-guidance.test.ts

@@ -0,0 +1,84 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { describe, expect, it, vi } from "vitest";
+
+import guidance from "../../../src/tavus_mcp/builder_guidance.json";
+import { createTavusMcpServer } from "../src/tavus";
+
+async function connect() {
+  const server = createTavusMcpServer({
+    TAVUS_API_KEY: "test-key",
+    TAVUS_PUBLIC_API_BASE_URL: "https://api.example.test/v2",
+  });
+  const client = new Client({ name: "guidance-test", version: "1.0.0" });
+  const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+  await server.connect(serverTransport);
+  await client.connect(clientTransport);
+  return { server, client };
+}
+
+describe("builder guidance over MCP", () => {
+  it("delivers shared instructions and tool guidance to clients", async () => {
+    const { server, client } = await connect();
+    try {
+      expect(client.getInstructions()).toBe(guidance.instructions.join("\n\n"));
+      const { tools } = await client.listTools();
+      for (const [name, description] of Object.entries(guidance.tool_descriptions)) {
+        expect(tools.find((tool) => tool.name === name)?.description?.startsWith(description)).toBe(true);
+      }
+    } finally {
+      await client.close();
+      await server.close();
+    }
+  });
+
+  it("attaches a scorecard canvas and reads back its config without creating a tool", async () => {
+    let saved: Record<string, unknown> = {};
+    const fetchMock = vi.fn(async (input: string | URL | Request, init?: RequestInit) => {
+      const url = String(input);
+      if (url === "https://api.example.test/v2/pals/p-score/skills/magic_canvas" && init?.method === "PUT") {
+        saved = JSON.parse(String(init.body));
+        return Response.json({ skill_id: "magic_canvas", ...saved });
+      }
+      if (url === "https://api.example.test/v2/pals/p-score?include_settings=true") {
+        return Response.json({ layers: {} });
+      }
+      if (url === "https://api.example.test/v2/pals/p-score/skills/") {
+        return Response.json({ data: { magic_canvas: { skill_id: "magic_canvas", ...saved } } });
+      }
+      throw new Error(`Unexpected request: ${init?.method} ${url}`);
+    });
+    vi.stubGlobal("fetch", fetchMock);
+    const { server, client } = await connect();
+    try {
+      const attached = await client.callTool({
+        name: "tavus_pal_capability_attach",
+        arguments: {
+          pal_id: "p-score",
+          capability: "magic_canvas",
+          magic_canvas_components: ["text", "chart"],
+          magic_canvas_usage_guidance: "Show the training scorecard after each exercise.",
+        },
+      });
+      expect(attached.isError).not.toBe(true);
+      const result = await client.callTool({
+        name: "tavus_pal_capabilities_list",
+        arguments: { pal_id: "p-score" },
+      });
+      expect(result.isError).not.toBe(true);
+      const content = result.content as Array<{ type: string; text: string }>;
+      const canvas = JSON.parse(content[0].text).capabilities.magic_canvas;
+      expect(canvas.attached).toBe(true);
+      expect(canvas.attachment.config).toEqual(saved.config);
+      expect(canvas.attachment.config.usage_guidance).toBe("Show the training scorecard after each exercise.");
+      expect(canvas.attachment.config.components.input).toEqual({ enabled: false });
+      expect(canvas.attachment.config.components.text).toBeUndefined();
+      expect(canvas.attachment.config.components.chart).toBeUndefined();
+      expect(fetchMock).toHaveBeenCalledTimes(3);
+    } finally {
+      await client.close();
+      await server.close();
+      vi.unstubAllGlobals();
+    }
+  });
+});

tavus_cli-0.9.1/.release-please-manifest.json

@@ -1,3 +0,0 @@
-{
-  ".": "0.9.1"
-}

tavus_cli-0.9.1/workers/tavus-mcp/src/version.ts

@@ -1 +0,0 @@
-export const VERSION = "0.9.1"; // x-release-please-version