@mastra/mcp-docs-server 0.13.24 → 0.13.25-alpha.1

package/.docs/organized/changelogs/mastra.md

@@ -1,5 +1,68 @@
 # mastra
 
+## 0.13.3-alpha.1
+
+### Patch Changes
+
+- Update peer deps ([#8154](https://github.com/mastra-ai/mastra/pull/8154))
+
+- Fixed an issue in playground where text-start/end parts were ignored in handleStreamChunk and tool ordering vs text wasn't retained ([#8234](https://github.com/mastra-ai/mastra/pull/8234))
+
+- Add conditional chaining to scorer.agentNames return ([#8199](https://github.com/mastra-ai/mastra/pull/8199))
+
+- Show model that worked when there are model fallbacks ([#8167](https://github.com/mastra-ai/mastra/pull/8167))
+
+- Updated dependencies [[`5089c84`](https://github.com/mastra-ai/mastra/commit/5089c84a2f535ad12e79b5aa524ad7d8ca5e2b4c), [`5f4e677`](https://github.com/mastra-ai/mastra/commit/5f4e67757bc23f2694d83af10f88cfccdc6013ff), [`5c98f03`](https://github.com/mastra-ai/mastra/commit/5c98f03ae76d9a93cd6be206b4abb7bf186b3163), [`57b75b0`](https://github.com/mastra-ai/mastra/commit/57b75b01c0c64d91c50d7384c700afda89456fe8), [`4c5e65d`](https://github.com/mastra-ai/mastra/commit/4c5e65de746fbdab23eb6072cb999f4c7aeef9f3), [`504438b`](https://github.com/mastra-ai/mastra/commit/504438b961bde211071186bba63a842c4e3db879), [`57b6dd5`](https://github.com/mastra-ai/mastra/commit/57b6dd50f9e6d92c0ed3e7199e6a92752025e3a1), [`a7243e2`](https://github.com/mastra-ai/mastra/commit/a7243e2e58762667a6e3921e755e89d6bb0a3282), [`504438b`](https://github.com/mastra-ai/mastra/commit/504438b961bde211071186bba63a842c4e3db879), [`7fceb0a`](https://github.com/mastra-ai/mastra/commit/7fceb0a327d678e812f90f5387c5bc4f38bd039e), [`df64f9e`](https://github.com/mastra-ai/mastra/commit/df64f9ef814916fff9baedd861c988084e7c41de), [`809eea0`](https://github.com/mastra-ai/mastra/commit/809eea092fa80c3f69b9eaf078d843b57fd2a88e), [`683e5a1`](https://github.com/mastra-ai/mastra/commit/683e5a1466e48b686825b2c11f84680f296138e4), [`3679378`](https://github.com/mastra-ai/mastra/commit/3679378673350aa314741dc826f837b1984149bc), [`7775bc2`](https://github.com/mastra-ai/mastra/commit/7775bc20bb1ad1ab24797fb420e4f96c65b0d8ec), [`db1891a`](https://github.com/mastra-ai/mastra/commit/db1891a4707443720b7cd8a260dc7e1d49b3609c), [`e8f379d`](https://github.com/mastra-ai/mastra/commit/e8f379d390efa264c4e0874f9ac0cf8839b07777), [`652066b`](https://github.com/mastra-ai/mastra/commit/652066bd1efc6bb6813ba950ed1d7573e8b7d9d4), [`ea8d386`](https://github.com/mastra-ai/mastra/commit/ea8d386cd8c5593664515fd5770c06bf2aa980ef), [`c2a4919`](https://github.com/mastra-ai/mastra/commit/c2a4919ba6797d8bdb1509e02287496eef69303e), [`6f67656`](https://github.com/mastra-ai/mastra/commit/6f676562276926e2982401574d1e07157579be30), [`0130986`](https://github.com/mastra-ai/mastra/commit/0130986fc62d0edcc626dd593282661dbb9af141), [`5dc8e9a`](https://github.com/mastra-ai/mastra/commit/5dc8e9a7f8472298cd3d4e8a0cf6d265529f287d)]:
+  - @mastra/deployer@0.19.0-alpha.1
+  - @mastra/mcp@0.13.2-alpha.0
+  - @mastra/core@0.19.0-alpha.1
+  - @mastra/loggers@0.10.14-alpha.0
+
+## 0.13.3-alpha.0
+
+### Patch Changes
+
+- Remove legacy helpers ([#8017](https://github.com/mastra-ai/mastra/pull/8017))
+
+- add a way to hide the deploy mastra cloud button ([#8137](https://github.com/mastra-ai/mastra/pull/8137))
+
+- Add types in the streamVNext codepath, fixes for various issues across multiple packages surfaced from type issues, align return types. ([#8010](https://github.com/mastra-ai/mastra/pull/8010))
+
+- Add model fallbacks to playground ([#7427](https://github.com/mastra-ai/mastra/pull/7427))
+
+- Updated dependencies [[`dc099b4`](https://github.com/mastra-ai/mastra/commit/dc099b40fb31147ba3f362f98d991892033c4c67), [`b342a68`](https://github.com/mastra-ai/mastra/commit/b342a68e1399cf1ece9ba11bda112db89d21118c), [`303a9c0`](https://github.com/mastra-ai/mastra/commit/303a9c0d7dd58795915979f06a0512359e4532fb), [`370f8a6`](https://github.com/mastra-ai/mastra/commit/370f8a6480faec70fef18d72e5f7538f27004301), [`623ffaf`](https://github.com/mastra-ai/mastra/commit/623ffaf2d969e11e99a0224633cf7b5a0815c857), [`9fc1613`](https://github.com/mastra-ai/mastra/commit/9fc16136400186648880fd990119ac15f7c02ee4), [`61f62aa`](https://github.com/mastra-ai/mastra/commit/61f62aa31bc88fe4ddf8da6240dbcfbeb07358bd), [`3e292ba`](https://github.com/mastra-ai/mastra/commit/3e292ba00837886d5d68a34cbc0d9b703c991883), [`418c136`](https://github.com/mastra-ai/mastra/commit/418c1366843d88e491bca3f87763899ce855ca29), [`c84b7d0`](https://github.com/mastra-ai/mastra/commit/c84b7d093c4657772140cbfd2b15ef72f3315ed5)]:
+  - @mastra/core@0.18.1-alpha.0
+  - @mastra/deployer@0.18.1-alpha.0
+
+## 0.13.2
+
+### Patch Changes
+
+- feat: implement trace scoring with batch processing capabilities ([#8033](https://github.com/mastra-ai/mastra/pull/8033))
+
+- Add model fallback handlers and apis ([#7378](https://github.com/mastra-ai/mastra/pull/7378))
+
+- dependencies updates: ([#8007](https://github.com/mastra-ai/mastra/pull/8007))
+  - Updated dependency [`fs-extra@^11.3.2` ↗︎](https://www.npmjs.com/package/fs-extra/v/11.3.2) (from `^11.3.1`, in `dependencies`)
+
+- show the tool-output stream in the playground for streamVNext ([#7983](https://github.com/mastra-ai/mastra/pull/7983))
+
+- Get rid off swr one for all ([#7931](https://github.com/mastra-ai/mastra/pull/7931))
+
+- Fix DateTimePicker style issue ([#8106](https://github.com/mastra-ai/mastra/pull/8106))
+
+- Fix navigating between scores and entity types ([#8129](https://github.com/mastra-ai/mastra/pull/8129))
+
+- Fix getting tool link path from agent in playground ui tools page ([#8135](https://github.com/mastra-ai/mastra/pull/8135))
+
+- Update Peerdeps for packages based on core minor bump ([#8025](https://github.com/mastra-ai/mastra/pull/8025))
+
+- Updated dependencies [[`288745a`](https://github.com/mastra-ai/mastra/commit/288745a19aa9557db3ab3c877d667ff59f14d79c), [`cf34503`](https://github.com/mastra-ai/mastra/commit/cf345031de4e157f29087946449e60b965e9c8a9), [`6b4b1e4`](https://github.com/mastra-ai/mastra/commit/6b4b1e4235428d39e51cbda9832704c0ba70ab32), [`3469fca`](https://github.com/mastra-ai/mastra/commit/3469fca7bb7e5e19369ff9f7044716a5e4b02585), [`a61f23f`](https://github.com/mastra-ai/mastra/commit/a61f23fbbca4b88b763d94f1d784c47895ed72d7), [`4b339b8`](https://github.com/mastra-ai/mastra/commit/4b339b8141c20d6a6d80583c7e8c5c05d8c19492), [`8f56160`](https://github.com/mastra-ai/mastra/commit/8f56160fd45c740076529148b9c225f6842d43b0), [`d1dc606`](https://github.com/mastra-ai/mastra/commit/d1dc6067b0557a71190b68d56ee15b48c26d2411), [`2d29ad9`](https://github.com/mastra-ai/mastra/commit/2d29ad92763cac02fc1d80c221ac93c39c0c5caf), [`c45298a`](https://github.com/mastra-ai/mastra/commit/c45298a0a0791db35cf79f1199d77004da0704cb), [`c4a8204`](https://github.com/mastra-ai/mastra/commit/c4a82046bfd241d6044e234bc5917d5a01fe6b55), [`d3bd4d4`](https://github.com/mastra-ai/mastra/commit/d3bd4d482a685bbb67bfa89be91c90dca3fa71ad), [`c591dfc`](https://github.com/mastra-ai/mastra/commit/c591dfc1e600fae1dedffe239357d250e146378f), [`1920c5c`](https://github.com/mastra-ai/mastra/commit/1920c5c6d666f687785c73021196aa551e579e0d), [`b6a3b65`](https://github.com/mastra-ai/mastra/commit/b6a3b65d830fa0ca7754ad6481661d1f2c878f21), [`af3abb6`](https://github.com/mastra-ai/mastra/commit/af3abb6f7c7585d856e22d27f4e7d2ece2186b9a), [`5b1ee71`](https://github.com/mastra-ai/mastra/commit/5b1ee71dc3ac92383226dc1e375642ca5f9b4224), [`282379f`](https://github.com/mastra-ai/mastra/commit/282379fafed80c6417fe1e791087110decd481ca)]:
+  - @mastra/deployer@0.18.0
+  - @mastra/core@0.18.0
+  - @mastra/loggers@0.10.13
+  - @mastra/mcp@0.13.1
+
 ## 0.13.2-alpha.4
 
 ### Patch Changes
@@ -236,67 +299,4 @@
 
 ## 0.12.4-alpha.0
 
-### Patch Changes
-
-- fix minor playground stuff for observability ([#7765](https://github.com/mastra-ai/mastra/pull/7765))
-
-- Handle zod intersections in dynamic form ([#7768](https://github.com/mastra-ai/mastra/pull/7768))
-
-- Playground ui -pass runtimeContext to client SDK get methods ([#7767](https://github.com/mastra-ai/mastra/pull/7767))
-
-- Updated dependencies [[`5802bf5`](https://github.com/mastra-ai/mastra/commit/5802bf57f6182e4b67c28d7d91abed349a8d14f3), [`5bda53a`](https://github.com/mastra-ai/mastra/commit/5bda53a9747bfa7d876d754fc92c83a06e503f62), [`f26a8fd`](https://github.com/mastra-ai/mastra/commit/f26a8fd99fcb0497a5d86c28324430d7f6a5fb83), [`f0ab020`](https://github.com/mastra-ai/mastra/commit/f0ab02034532a4afb71a1ef4fe243f9a8dffde84), [`1a1fbe6`](https://github.com/mastra-ai/mastra/commit/1a1fbe66efb7d94abc373ed0dd9676adb8122454), [`36f39c0`](https://github.com/mastra-ai/mastra/commit/36f39c00dc794952dc3c11aab91c2fa8bca74b11)]:
-  - @mastra/core@0.16.4-alpha.0
-  - @mastra/deployer@0.16.4-alpha.0
-
-## 0.12.3
-
-### Patch Changes
-
-- Client SDK Agents, Mastra server - support runtimeContext with GET requests ([#7734](https://github.com/mastra-ai/mastra/pull/7734))
-
-- Add new scorers to list ([#7614](https://github.com/mastra-ai/mastra/pull/7614))
-
-- fix playground UI issue about dynmic workflow exec in agent thread ([#7665](https://github.com/mastra-ai/mastra/pull/7665))
-
-- Updated dependencies [[`b4379f7`](https://github.com/mastra-ai/mastra/commit/b4379f703fd74474f253420e8c3a684f2c4b2f8e), [`b4379f7`](https://github.com/mastra-ai/mastra/commit/b4379f703fd74474f253420e8c3a684f2c4b2f8e), [`2a6585f`](https://github.com/mastra-ai/mastra/commit/2a6585f7cb71f023f805d521d1c3c95fb9a3aa59), [`3d26e83`](https://github.com/mastra-ai/mastra/commit/3d26e8353a945719028f087cc6ac4b06f0ce27d2), [`dd9119b`](https://github.com/mastra-ai/mastra/commit/dd9119b175a8f389082f75c12750e51f96d65dca), [`d34aaa1`](https://github.com/mastra-ai/mastra/commit/d34aaa1da5d3c5f991740f59e2fe6d28d3e2dd91), [`56e55d1`](https://github.com/mastra-ai/mastra/commit/56e55d1e9eb63e7d9e41aa46e012aae471256812), [`ce1e580`](https://github.com/mastra-ai/mastra/commit/ce1e580f6391e94a0c6816a9c5db0a21566a262f), [`b2babfa`](https://github.com/mastra-ai/mastra/commit/b2babfa9e75b22f2759179e71d8473f6dc5421ed), [`d8c3ba5`](https://github.com/mastra-ai/mastra/commit/d8c3ba516f4173282d293f7e64769cfc8738d360), [`a566c4e`](https://github.com/mastra-ai/mastra/commit/a566c4e92d86c1671707c54359b1d33934f7cc13), [`0666082`](https://github.com/mastra-ai/mastra/commit/06660820230dcb1fa7c1d51c8254107afd68cd67), [`af333aa`](https://github.com/mastra-ai/mastra/commit/af333aa30fe6d1b127024b03a64736c46eddeca2), [`4c81b65`](https://github.com/mastra-ai/mastra/commit/4c81b65a28d128560bdf63bc9b8a1bddd4884812), [`3863c52`](https://github.com/mastra-ai/mastra/commit/3863c52d44b4e5779968b802d977e87adf939d8e), [`6424c7e`](https://github.com/mastra-ai/mastra/commit/6424c7ec38b6921d66212431db1e0958f441b2a7), [`db94750`](https://github.com/mastra-ai/mastra/commit/db94750a41fd29b43eb1f7ce8e97ba8b9978c91b), [`a66a371`](https://github.com/mastra-ai/mastra/commit/a66a3716b00553d7f01842be9deb34f720b10fab), [`69fc3cd`](https://github.com/mastra-ai/mastra/commit/69fc3cd0fd814901785bdcf49bf536ab1e7fd975)]:
-  - @mastra/core@0.16.3
-  - @mastra/deployer@0.16.3
-
-## 0.12.3-alpha.1
-
-### Patch Changes
-
-- Client SDK Agents, Mastra server - support runtimeContext with GET requests ([#7734](https://github.com/mastra-ai/mastra/pull/7734))
-
-- Updated dependencies [[`2a6585f`](https://github.com/mastra-ai/mastra/commit/2a6585f7cb71f023f805d521d1c3c95fb9a3aa59), [`3d26e83`](https://github.com/mastra-ai/mastra/commit/3d26e8353a945719028f087cc6ac4b06f0ce27d2), [`56e55d1`](https://github.com/mastra-ai/mastra/commit/56e55d1e9eb63e7d9e41aa46e012aae471256812), [`4c81b65`](https://github.com/mastra-ai/mastra/commit/4c81b65a28d128560bdf63bc9b8a1bddd4884812)]:
-  - @mastra/core@0.16.3-alpha.1
-  - @mastra/deployer@0.16.3-alpha.1
-
-## 0.12.3-alpha.0
-
-### Patch Changes
-
-- Add new scorers to list ([#7614](https://github.com/mastra-ai/mastra/pull/7614))
-
-- fix playground UI issue about dynmic workflow exec in agent thread ([#7665](https://github.com/mastra-ai/mastra/pull/7665))
-
-- Updated dependencies [[`b4379f7`](https://github.com/mastra-ai/mastra/commit/b4379f703fd74474f253420e8c3a684f2c4b2f8e), [`b4379f7`](https://github.com/mastra-ai/mastra/commit/b4379f703fd74474f253420e8c3a684f2c4b2f8e), [`dd9119b`](https://github.com/mastra-ai/mastra/commit/dd9119b175a8f389082f75c12750e51f96d65dca), [`d34aaa1`](https://github.com/mastra-ai/mastra/commit/d34aaa1da5d3c5f991740f59e2fe6d28d3e2dd91), [`ce1e580`](https://github.com/mastra-ai/mastra/commit/ce1e580f6391e94a0c6816a9c5db0a21566a262f), [`b2babfa`](https://github.com/mastra-ai/mastra/commit/b2babfa9e75b22f2759179e71d8473f6dc5421ed), [`d8c3ba5`](https://github.com/mastra-ai/mastra/commit/d8c3ba516f4173282d293f7e64769cfc8738d360), [`a566c4e`](https://github.com/mastra-ai/mastra/commit/a566c4e92d86c1671707c54359b1d33934f7cc13), [`0666082`](https://github.com/mastra-ai/mastra/commit/06660820230dcb1fa7c1d51c8254107afd68cd67), [`af333aa`](https://github.com/mastra-ai/mastra/commit/af333aa30fe6d1b127024b03a64736c46eddeca2), [`3863c52`](https://github.com/mastra-ai/mastra/commit/3863c52d44b4e5779968b802d977e87adf939d8e), [`6424c7e`](https://github.com/mastra-ai/mastra/commit/6424c7ec38b6921d66212431db1e0958f441b2a7), [`db94750`](https://github.com/mastra-ai/mastra/commit/db94750a41fd29b43eb1f7ce8e97ba8b9978c91b), [`a66a371`](https://github.com/mastra-ai/mastra/commit/a66a3716b00553d7f01842be9deb34f720b10fab), [`69fc3cd`](https://github.com/mastra-ai/mastra/commit/69fc3cd0fd814901785bdcf49bf536ab1e7fd975)]:
-  - @mastra/core@0.16.3-alpha.0
-  - @mastra/deployer@0.16.3-alpha.0
-
-## 0.12.2
-
-### Patch Changes
-
-- Updated dependencies [[`61926ef`](https://github.com/mastra-ai/mastra/commit/61926ef40d415b805a63527cffe27a50542e15e5)]:
-  - @mastra/core@0.16.2
-  - @mastra/deployer@0.16.2
-
-## 0.12.2-alpha.0
-
-### Patch Changes
-
-- Updated dependencies [[`61926ef`](https://github.com/mastra-ai/mastra/commit/61926ef40d415b805a63527cffe27a50542e15e5)]:
-  - @mastra/core@0.16.2-alpha.0
-
-... 5720 more lines hidden. See full changelog in package directory.
+... 5783 more lines hidden. See full changelog in package directory.

package/.docs/organized/code-examples/agent.md

@@ -762,7 +762,6 @@ const weatherAgent = new Agent({
   instructions: `You are a weather agent that can help you get weather information for a given city`,
   description: `An agent that can help you get weather information for a given city`,
   model: openai_v5('gpt-4o-mini'),
-  tools: { weatherInfo },
   workflows: {
     myWorkflow,
   },
@@ -774,9 +773,6 @@ export const networkAgent = new Agent({
     'A chef agent that can help you cook great meals with whatever ingredients you have available based on your location and current weather.',
   instructions: `You are a the manager of several agent, tools, and workflows. Use the best primitives based on what the user wants to accomplish your task.`,
   model: openai_v5('gpt-4o-mini'),
-  workflows: {
-    myWorkflow,
-  },
   agents: {
     weatherAgent,
   },

package/.docs/organized/code-examples/ai-elements.md

@@ -0,0 +1,47 @@
+### package.json
+```json
+{
+  "name": "ai-elements",
+  "dependencies": {
+    "@mastra/playground-ui": "file:../../packages/playground-ui",
+    "@mastra/react": "file:../../client-sdks/react",
+    "@radix-ui/react-avatar": "^1.1.10",
+    "@radix-ui/react-collapsible": "^1.1.12",
+    "@radix-ui/react-dropdown-menu": "^2.1.16",
+    "@radix-ui/react-hover-card": "^1.1.15",
+    "@radix-ui/react-progress": "^1.1.7",
+    "@radix-ui/react-scroll-area": "^1.2.10",
+    "@radix-ui/react-select": "^2.2.6",
+    "@radix-ui/react-slot": "^1.2.3",
+    "@radix-ui/react-tooltip": "^1.2.8",
+    "@radix-ui/react-use-controllable-state": "^1.2.2",
+    "ai": "^5.0.57",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "embla-carousel-react": "^8.6.0",
+    "lucide-react": "^0.544.0",
+    "nanoid": "^5.1.6",
+    "next": "15.5.4",
+    "react": "19.1.0",
+    "react-dom": "19.1.0",
+    "react-syntax-highlighter": "^15.6.6",
+    "streamdown": "^1.3.0",
+    "tailwind-merge": "^3.3.1",
+    "tokenlens": "^1.3.1",
+    "use-stick-to-bottom": "^1.1.1"
+  },
+  "devDependencies": {
+    "@eslint/eslintrc": "^3",
+    "@tailwindcss/postcss": "^4",
+    "@types/node": "^20",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "@types/react-syntax-highlighter": "^15.5.13",
+    "eslint": "^9",
+    "eslint-config-next": "15.5.4",
+    "tailwindcss": "^4",
+    "tw-animate-css": "^1.4.0",
+    "typescript": "^5"
+  }
+}
+```

package/.docs/organized/code-examples/heads-up-game.md

@@ -7,15 +7,15 @@
   },
   "dependencies": {
     "@ai-sdk/openai": "^1.3.23",
-    "@mastra/core": "^0.16.3",
-    "@mastra/libsql": "^0.14.1",
-    "@mastra/loggers": "^0.10.11",
-    "@mastra/memory": "^0.15.1",
+    "@mastra/core": "^0.18.0",
+    "@mastra/libsql": "^0.14.3",
+    "@mastra/loggers": "^0.10.13",
+    "@mastra/memory": "^0.15.3",
     "zod": "^3.25.76"
   },
   "devDependencies": {
     "@types/node": "^24.3.0",
-    "mastra": "^0.12.3",
+    "mastra": "^0.13.2",
     "typescript": "^5.9.2"
   }
 }

package/.docs/raw/auth/clerk.mdx

@@ -23,17 +23,17 @@ CLERK_JWKS_URI=https://your-clerk-domain.clerk.accounts.dev/.well-known/jwks.jso
 
 ## Installation
 
-Before you can use the `MastraAuthClerk` class you have to install the `@mastra/clerk-auth` package.
+Before you can use the `MastraAuthClerk` class you have to install the `@mastra/auth-clerk` package.
 
 ```bash copy
-npm install @mastra/clerk-auth@latest
+npm install @mastra/auth-clerk@latest
 ```
 
 ## Usage example
 
 ```typescript {2,7-11} filename="src/mastra/index.ts" showLineNumbers copy
 import { Mastra } from "@mastra/core/mastra";
-import { MastraAuthClerk } from '@mastra/clerk-auth';
+import { MastraAuthClerk } from '@mastra/auth-clerk';
 
 export const mastra = new Mastra({
   // ..

package/.docs/raw/index.mdx

@@ -20,3 +20,4 @@ The main features include:
 - **[Retrieval-augmented generation (RAG)](/docs/rag/overview.mdx)**: Mastra gives you APIs to process documents (text, HTML, Markdown, JSON) into chunks, create embeddings, and store them in a vector database. At query time, it retrieves relevant chunks to ground LLM responses in your data, with a unified API on top of multiple vector stores (Pinecone, pgvector, etc) and embedding providers (OpenAI, Cohere, etc).
 - **[Deployment](/docs/deployment/deployment.mdx)**: Mastra supports bundling your agents and workflows within an existing React, Next.js, or Node.js application, or into standalone endpoints. The Mastra deploy helper lets you easily bundle agents and workflows into a Node.js server using Hono, or deploy it onto a serverless platform like Vercel, Cloudflare Workers, or Netlify.
 - **[Evals](/docs/evals/overview.mdx)**: Mastra provides automated evaluation metrics that use model-graded, rule-based, and statistical methods to assess LLM outputs, with built-in metrics for toxicity, bias, relevance, and factual accuracy. You can also define your own evals.
+- **[Observability](/docs/observability/overview.mdx)**: Mastra provides specialized AI tracing to monitor LLM operations, agent decisions, and tool executions. Track token usage, latency, and conversation flows with native exporters for Langfuse, Braintrust, and Mastra Cloud. Structured logging provides additional debugging capabilities for comprehensive monitoring.

package/.docs/raw/observability/ai-tracing/exporters/braintrust.mdx

@@ -0,0 +1,81 @@
+---
+title: "Braintrust Exporter | AI Tracing | Observability | Mastra Docs"
+description: "Send AI traces to Braintrust for evaluation and monitoring"
+---
+
+import { Callout } from "nextra/components";
+
+# Braintrust Exporter
+
+[Braintrust](https://www.braintrust.dev/) is an evaluation and monitoring platform that helps you measure and improve LLM application quality. The Braintrust exporter sends your AI traces to Braintrust, enabling systematic evaluation, scoring, and experimentation.
+
+## When to Use Braintrust
+
+Braintrust excels at:
+- **Evaluation workflows** - Systematic quality measurement
+- **Experiment tracking** - Compare model versions and prompts
+- **Dataset management** - Curate test cases and golden datasets
+- **Regression testing** - Ensure improvements don't break existing functionality
+- **Team collaboration** - Share experiments and insights
+
+## Installation
+
+```bash npm2yarn
+npm install @mastra/braintrust
+```
+
+## Configuration
+
+### Prerequisites
+
+1. **Braintrust Account**: Sign up at [braintrust.dev](https://www.braintrust.dev/)
+2. **Project**: Create or select a project for your traces
+3. **API Key**: Generate in Braintrust Settings → API Keys
+4. **Environment Variables**: Set your credentials:
+
+```bash filename=".env"
+BRAINTRUST_API_KEY=sk-xxxxxxxxxxxxxxxx
+BRAINTRUST_PROJECT_NAME=my-project  # Optional, defaults to 'mastra-tracing'
+```
+
+### Basic Setup
+
+```typescript filename="src/mastra/index.ts"
+import { Mastra } from "@mastra/core";
+import { BraintrustExporter } from "@mastra/braintrust";
+
+export const mastra = new Mastra({
+  observability: {
+    configs: {
+      braintrust: {
+        serviceName: 'my-service',
+        exporters: [
+          new BraintrustExporter({
+            apiKey: process.env.BRAINTRUST_API_KEY,
+            projectName: process.env.BRAINTRUST_PROJECT_NAME,
+          }),
+        ],
+      },
+    },
+  },
+});
+```
+
+### Complete Configuration
+
+```typescript
+new BraintrustExporter({
+  // Required
+  apiKey: process.env.BRAINTRUST_API_KEY!,
+
+  // Optional settings
+  projectName: 'my-project',          // Default: 'mastra-tracing'
+  endpoint: 'https://api.braintrust.dev',  // Custom endpoint if needed
+  logLevel: 'info',                   // Diagnostic logging: debug | info | warn | error
+})
+```
+
+## Related
+
+- [AI Tracing Overview](/docs/observability/ai-tracing/overview)
+- [Braintrust Documentation](https://www.braintrust.dev/docs)

package/.docs/raw/observability/ai-tracing/exporters/cloud.mdx

@@ -0,0 +1,120 @@
+---
+title: "Cloud Exporter | AI Tracing | Observability | Mastra Docs"
+description: "Send traces to Mastra Cloud for production monitoring"
+---
+
+import { Callout } from "nextra/components";
+
+# Cloud Exporter
+
+The `CloudExporter` sends traces to Mastra Cloud for centralized monitoring and team collaboration. It's automatically enabled when using the default observability configuration with a valid access token.
+
+## When to Use CloudExporter
+
+CloudExporter is ideal for:
+- **Production monitoring** - Centralized trace visualization
+- **Team collaboration** - Share traces across your organization
+- **Advanced analytics** - Insights and performance metrics
+- **Zero maintenance** - No infrastructure to manage
+
+## Configuration
+
+### Prerequisites
+
+1. **Mastra Cloud Account**: Sign up at [cloud.mastra.ai](https://cloud.mastra.ai)
+2. **Access Token**: Generate in Mastra Cloud → Settings → API Tokens
+3. **Environment Variables**: Set your credentials:
+
+```bash filename=".env"
+MASTRA_CLOUD_ACCESS_TOKEN=mst_xxxxxxxxxxxxxxxx
+```
+
+### Basic Setup
+
+```typescript filename="src/mastra/index.ts"
+import { Mastra } from "@mastra/core";
+import { CloudExporter } from "@mastra/core/ai-tracing";
+
+export const mastra = new Mastra({
+  observability: {
+    configs: {
+      production: {
+        serviceName: 'my-service',
+        exporters: [
+          new CloudExporter(),  // Uses MASTRA_CLOUD_ACCESS_TOKEN env var
+        ],
+      },
+    },
+  },
+});
+```
+
+### Automatic Configuration
+
+When using the default observability configuration, CloudExporter is automatically included if the access token is set:
+
+```typescript
+export const mastra = new Mastra({
+  observability: {
+    default: { enabled: true },  // Automatically includes CloudExporter if token exists
+  },
+});
+```
+
+### Complete Configuration
+
+```typescript
+new CloudExporter({
+  // Optional - defaults to env var
+  accessToken: process.env.MASTRA_CLOUD_ACCESS_TOKEN,
+
+  // Optional - for self-hosted Mastra Cloud
+  endpoint: 'https://cloud.your-domain.com',
+
+  // Batching configuration
+  maxBatchSize: 1000,     // Max spans per batch
+  maxBatchWaitMs: 5000,   // Max wait before sending batch
+
+  // Diagnostic logging
+  logLevel: 'info',  // debug | info | warn | error
+})
+```
+
+## Viewing Traces
+
+### Mastra Cloud Dashboard
+
+1. Navigate to [cloud.mastra.ai](https://cloud.mastra.ai)
+2. Select your project
+3. Go to Observability → Traces
+4. Use filters to find specific traces:
+   - Service name
+   - Time range
+   - Trace ID
+   - Error status
+
+### Features
+
+- **Trace Timeline** - Visual execution flow
+- **Span Details** - Inputs, outputs, metadata
+- **Performance Metrics** - Latency, token usage
+- **Team Collaboration** - Share trace links
+
+## Performance
+
+<Callout type="info">
+  CloudExporter uses intelligent batching to optimize network usage. Traces are buffered and sent in batches, reducing overhead while maintaining near real-time visibility.
+</Callout>
+
+### Batching Behavior
+
+- Traces are batched up to `maxBatchSize` (default: 1000)
+- Batches are sent when full or after `maxBatchWaitMs` (default: 5 seconds)
+- Failed batches are retried with exponential backoff
+- Graceful degradation if Mastra Cloud is unreachable
+
+## Related
+
+- [AI Tracing Overview](/docs/observability/ai-tracing/overview)
+- [DefaultExporter](/docs/observability/ai-tracing/exporters/default)
+- [Mastra Cloud Documentation](https://cloud.mastra.ai/docs)

package/.docs/raw/observability/ai-tracing/exporters/default.mdx

@@ -0,0 +1,168 @@
+---
+title: "Default Exporter | AI Tracing | Observability | Mastra Docs"
+description: "Store traces locally for development and debugging"
+---
+
+# Default Exporter
+
+The `DefaultExporter` persists traces to your configured storage backend, making them accessible through the Mastra Playground. It's automatically enabled when using the default observability configuration and requires no external services.
+
+## When to Use DefaultExporter
+
+DefaultExporter is ideal for:
+- **Local development** - Debug and analyze traces offline
+- **Data ownership** - Complete control over your trace data
+- **Zero dependencies** - No external services required
+- **Playground integration** - View traces in Mastra Playground UI
+
+## Configuration
+
+### Prerequisites
+
+1. **Storage Backend**: Configure a storage provider (LibSQL, PostgreSQL, etc.)
+2. **Mastra Playground**: Install for viewing traces locally
+
+### Basic Setup
+
+```typescript filename="src/mastra/index.ts"
+import { Mastra } from "@mastra/core";
+import { DefaultExporter } from "@mastra/core/ai-tracing";
+import { LibSQLStore } from "@mastra/libsql";
+
+export const mastra = new Mastra({
+  storage: new LibSQLStore({
+    url: "file:./mastra.db",  // Required for trace persistence
+  }),
+  observability: {
+    configs: {
+      local: {
+        serviceName: 'my-service',
+        exporters: [
+          new DefaultExporter(),
+        ],
+      },
+    },
+  },
+});
+```
+
+### Automatic Configuration
+
+When using the default observability configuration, DefaultExporter is automatically included:
+
+```typescript
+export const mastra = new Mastra({
+  storage: new LibSQLStore({
+    url: "file:./mastra.db",
+  }),
+  observability: {
+    default: { enabled: true },  // Automatically includes DefaultExporter
+  },
+});
+```
+
+## Viewing Traces
+
+### Mastra Playground
+
+Access your traces through the local Playground:
+
+1. Start the Playground
+2. Navigate to Observability
+3. Filter and search your local traces
+4. Inspect detailed span information
+
+## Tracing Strategies
+
+DefaultExporter automatically selects the optimal tracing strategy based on your storage provider. You can also override this selection if needed.
+
+### Available Strategies
+
+| Strategy | Description | Use Case |
+|----------|-------------|----------|
+| **realtime** | Process each event immediately | Development, debugging, low traffic |
+| **batch-with-updates** | Buffer events and batch write with full lifecycle support | Low volume Production |
+| **insert-only** | Only process completed spans, ignore updates | High volume Production |
+
+### Strategy Configuration
+
+```typescript
+new DefaultExporter({
+  strategy: 'auto',  // Default - let storage provider decide
+  // or explicitly set:
+  // strategy: 'realtime' | 'batch-with-updates' | 'insert-only'
+
+  // Batching configuration (applies to both batch-with-updates and insert-only)
+  maxBatchSize: 1000,      // Max spans per batch
+  maxBatchWaitMs: 5000,    // Max wait before flushing
+  maxBufferSize: 10000,    // Max spans to buffer
+})
+```
+
+## Storage Provider Support
+
+Different storage providers support different tracing strategies.
+
+If you set the strategy to `'auto'`, the `DefaultExporter` automatically selects the optimal strategy for the storage provider. If you set the strategy to a mode that the storage provider doesn't support, you will get an error message.
+
+| Storage Provider | Preferred Strategy | Supported Strategies | Notes |
+|-----------------|-------------------|---------------------|--------|
+| **[LibSQL](/reference/storage/libsql)** | batch-with-updates | realtime, batch-with-updates, insert-only | Default storage, good for development |
+| **[PostgreSQL](/reference/storage/postgresql)** | batch-with-updates | batch-with-updates, insert-only | Recommended for production |
+
+### Strategy Benefits
+
+- **realtime**: Immediate visibility, best for debugging
+- **batch-with-updates**: 10-100x throughput improvement, full span lifecycle
+- **insert-only**: Additional 70% reduction in database operations, perfect for analytics
+
+## Batching Behavior
+
+### Flush Triggers
+
+For both batch strategies (`batch-with-updates` and `insert-only`), traces are flushed to storage when any of these conditions are met:
+
+1. **Size trigger**: Buffer reaches `maxBatchSize` spans
+2. **Time trigger**: `maxBatchWaitMs` elapsed since first event
+3. **Emergency flush**: Buffer approaches `maxBufferSize` limit
+4. **Shutdown**: Force flush all pending events
+
+### Error Handling
+
+The DefaultExporter includes robust error handling for production use:
+
+- **Retry Logic**: Exponential backoff (500ms, 1s, 2s, 4s)
+- **Transient Failures**: Automatic retry with backoff
+- **Persistent Failures**: Drop batch after 4 failed attempts
+- **Buffer Overflow**: Prevent memory issues during storage outages
+
+### Configuration Examples
+
+```typescript
+// Zero config - recommended for most users
+new DefaultExporter()
+
+// Development override
+new DefaultExporter({
+  strategy: 'realtime',  // Immediate visibility for debugging
+})
+
+// High-throughput production
+new DefaultExporter({
+  maxBatchSize: 2000,      // Larger batches
+  maxBatchWaitMs: 10000,   // Wait longer to fill batches
+  maxBufferSize: 50000,    // Handle longer outages
+})
+
+// Low-latency production
+new DefaultExporter({
+  maxBatchSize: 100,       // Smaller batches
+  maxBatchWaitMs: 1000,    // Flush quickly
+})
+```
+
+## Related
+
+- [AI Tracing Overview](/docs/observability/ai-tracing/overview)
+- [CloudExporter](/docs/observability/ai-tracing/exporters/cloud)
+- [Storage Configuration](/docs/storage/overview)