@mastra/mcp-docs-server 1.0.0-beta.10 → 1.0.0-beta.13

package/.docs/raw/guides/getting-started/vite-react.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Integrate Mastra in your React + Vite project | Frameworks"
+title: "React + Vite | Frameworks"
 description: A step-by-step guide to integrating Mastra with React and Vite.
 ---
 
@@ -8,248 +8,418 @@ import TabItem from "@theme/TabItem";
 
 # Integrate Mastra in your React + Vite project
 
-Mastra integrates with Vite, making it easy to:
+In this guide, you'll build a tool-calling AI agent using Mastra, then connect it to React by calling the agent directly from Mastra's standalone server.
 
-- Build flexible APIs to serve AI-powered features
-- Simplify deployment with a unified codebase for frontend and backend
-- Take advantage of Mastra's Client SDK
+You'll use [AI SDK UI](https://ai-sdk.dev/docs/ai-sdk-ui/overview) and [AI Elements](https://ai-sdk.dev/elements) to create a beautiful, interactive chat experience.
 
-Use this guide to scaffold and integrate Mastra with your React + Vite project.
+## Before you begin
 
-:::warning
+- You'll need an API key from a supported [model provider](/models/v1). If you don't have a preference, use [OpenAI](/models/v1/providers/openai).
+- Install Node.js `v22.13.0` or later
 
-This guide assumes you're using React + Vite with React Router v7 at the root of your project, e.g., `app`.
+## Create a new React + Vite app (optional)
 
-:::
+If you already have a React + Vite app using Tailwind, skip to the next step.
 
-## Install Mastra
+### Project scaffold
 
-Install the required Mastra packages:
+Run the following command to [create a new React + Vite app](https://vite.dev/guide/#scaffolding-your-first-vite-project):
 
-<Tabs>
+<Tabs groupId="pm">
 <TabItem value="npm" label="npm">
-
 ```bash copy
-npm install mastra@beta @mastra/core@beta @mastra/libsql@beta @mastra/client-js@beta
+npm create vite@latest mastra-react -- --template react-ts
+cd mastra-react
 ```
-
 </TabItem>
-<TabItem value="yarn" label="yarn">
-
+<TabItem value="pnpm" label="pnpm">
 ```bash copy
-yarn add mastra@beta @mastra/core@beta @mastra/libsql@beta @mastra/client-js@beta
+pnpm create vite mastra-react --template react-ts
+cd mastra-react
 ```
-
 </TabItem>
-<TabItem value="pnpm" label="pnpm">
-
+<TabItem value="yarn" label="yarn">
 ```bash copy
-pnpm add mastra@beta @mastra/core@beta @mastra/libsql@beta @mastra/client-js@beta
+yarn create vite mastra-react --template react-ts
+cd mastra-react
 ```
-
 </TabItem>
 <TabItem value="bun" label="bun">
-
 ```bash copy
-bun add mastra@beta @mastra/core@beta @mastra/libsql@beta @mastra/client-js@beta
+bun create vite mastra-react --template react-ts
+cd mastra-react
 ```
-
 </TabItem>
 </Tabs>
 
-## Integrate Mastra
+This creates a project called `mastra-react`, but you can replace it with any name you want.
 
-To integrate Mastra into your project, you have two options:
+### Tailwind
 
-### 1. Use the One-Liner
-
-Run the following command to quickly scaffold the default Weather agent with sensible defaults:
+Next, install Tailwind: 
 
+<Tabs groupId="pm">
+<TabItem value="npm" label="npm">
 ```bash copy
-npx mastra@beta init --dir . --components agents,tools --example --llm openai
+npm install tailwindcss @tailwindcss/vite
 ```
-
-> See [mastra init](/reference/v1/cli/create-mastra) for more information.
-
-### 2. Use the Interactive CLI
-
-If you prefer to customize the setup, run the `init` command and choose from the options when prompted:
-
+</TabItem>
+<TabItem value="pnpm" label="pnpm">
 ```bash copy
-npx mastra@latest init
+pnpm add tailwindcss @tailwindcss/vite
 ```
+</TabItem>
+<TabItem value="yarn" label="yarn">
+```bash copy
+yarn add tailwindcss @tailwindcss/vite
+```
+</TabItem>
+<TabItem value="bun" label="bun">
+```bash copy
+bun add tailwindcss @tailwindcss/vite
+```
+</TabItem>
+</Tabs>
 
-:::warning
-
-By default, `mastra init` suggests `src` as the install location. If you're using React + Vite at the root of your project (e.g., `app`, not `src/app`), enter `.` when prompted:
+Configure the Vite plugins:
+
+```typescript title="vite.config.ts" {3-4,7-12}
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import path from "path"
+import tailwindcss from '@tailwindcss/vite'
+
+export default defineConfig({
+  plugins: [react(), tailwindcss()],
+  resolve: {
+    alias: {
+      "@": path.resolve(__dirname, "./src"),
+    },
+  },
+})
+```
 
-:::
+Replace everything in `src/index.css` with the following:
 
-Add the `dev` and `build` scripts to `package.json`:
+```css title="src/index.css"
+@import "tailwindcss";
+```
 
-<Tabs>
-<TabItem value="app" label="app">
+Add these `compilerOptions` to `tsconfig.json`:
 
-```json title="package.json"
+```ts title="tsconfig.json"
 {
-  "scripts": {
-    ...
-    "dev:mastra": "mastra dev --dir mastra",
-    "build:mastra": "mastra build --dir mastra"
+  // ...
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./src/*"]
+    }
   }
 }
 ```
 
-</TabItem>
-<TabItem value="src-app" label="src/app">
+Edit `tsconfig.app.json` to resolve paths:
 
-```json title="package.json"
+```ts title="tsconfig.app.json"
 {
-  "scripts": {
-    ...
-    "dev:mastra": "mastra dev --dir src/mastra",
-    "build:mastra": "mastra build --dir src/mastra"
+  "compilerOptions": {
+    // ...
+    "baseUrl": ".",
+    "paths": {
+      "@/*": [
+        "./src/*"
+      ]
+    }
+    // ...
   }
 }
 ```
 
-</TabItem>
-</Tabs>
+## Initialize Mastra
 
-## Configure TypeScript
+Run [`mastra init`](/reference/v1/cli/create-mastra). When prompted, choose a provider (e.g. OpenAI) and enter your key:
 
-Modify the `tsconfig.json` file in your project root:
+<Tabs groupId="pm">
+<TabItem value="npm" label="npm">
 
-```json title="tsconfig.json"
-{
-  ...
-  "exclude": ["dist", ".mastra"]
-}
+```bash copy
+cd mastra-react
+npx mastra@beta init
 ```
 
-## Set Up API Keys
+</TabItem>
+<TabItem value="pnpm" label="pnpm">
 
-```bash title=".env" copy
-OPENAI_API_KEY=<your-api-key>
+```bash copy
+cd mastra-react
+pnpm dlx mastra@beta init
 ```
 
-> Each LLM provider uses a different env var. See [Model Capabilities](https://sdk.vercel.ai/providers) for more information.
+</TabItem>
+<TabItem value="yarn" label="yarn">
 
-## Update .gitignore
+```bash copy
+cd mastra-react
+yarn dlx mastra@beta init
+```
 
-Add `.mastra` to your `.gitignore` file:
+</TabItem>
+<TabItem value="bun" label="bun">
 
-```bash title=".gitignore" copy
-.mastra
+```bash copy
+cd mastra-react
+bunx mastra@beta init
 ```
 
-## Start the Mastra Dev Server
+</TabItem>
+</Tabs>
+
+This creates a `src/mastra` folder with an example weather agent and the following files:
+
+-	`index.ts` - Mastra config, including memory
+- `tools/weather-tool.ts` - a tool to fetch weather for a given location
+-	`agents/weather-agent.ts`- a weather agent with a prompt that uses the tool
 
-Start the Mastra Dev Server to expose your agents as REST endpoints:
+You'll call `weather-agent.ts` from your chat UI in the next steps.
 
-<Tabs>
+## Install AI SDK UI & AI Elements
+
+Install AI SDK UI along with the Mastra adapter:
+
+<Tabs groupId="pm">
 <TabItem value="npm" label="npm">
 
 ```bash copy
-npm run dev:mastra
+npm install @mastra/ai-sdk@beta @ai-sdk/react ai
 ```
 
 </TabItem>
-<TabItem value="cli" label="CLI">
+<TabItem value="pnpm" label="pnpm">
 
 ```bash copy
-mastra dev:mastra
+pnpm add @mastra/ai-sdk@beta @ai-sdk/react ai
 ```
 
 </TabItem>
-</Tabs>
+<TabItem value="yarn" label="yarn">
+
+```bash copy
+yarn add @mastra/ai-sdk@beta @ai-sdk/react ai
+```
 
-> Once running, your agents are available locally. See [Local Development Environment](/docs/v1/getting-started/studio) for more information.
+</TabItem>
+<TabItem value="bun" label="bun">
 
-## Start Vite Dev Server
+```bash copy
+bun add @mastra/ai-sdk@beta @ai-sdk/react ai
+```
 
-With the Mastra Dev Server running, you can start your Vite app in the usual way.
+</TabItem>
+</Tabs>
 
-## Create Mastra Client
+Next, initialize AI Elements. When prompted, choose the default options:
 
-Create a new directory and file. Then add the example code:
+<Tabs groupId="pm">
+<TabItem value="npm" label="npm">
 
 ```bash copy
-mkdir lib
-touch lib/mastra.ts
+npx ai-elements@latest
 ```
 
-```typescript title="lib/mastra.ts" showLineNumbers copy
-import { MastraClient } from "@mastra/client-js";
+</TabItem>
+<TabItem value="pnpm" label="pnpm">
 
-export const mastraClient = new MastraClient({
-  baseUrl: import.meta.env.VITE_MASTRA_API_URL || "http://localhost:4111",
-});
+```bash copy
+pnpm dlx ai-elements@latest
 ```
 
-## Create Test Route Config
-
-Add new `route` to the config:
-
-```typescript title="app/routes.ts" showLineNumbers copy
-import { type RouteConfig, index, route } from "@react-router/dev/routes";
+</TabItem>
+<TabItem value="yarn" label="yarn">
 
-export default [
-  index("routes/home.tsx"),
-  route("test", "routes/test.tsx"),
-] satisfies RouteConfig;
+```bash copy
+yarn dlx ai-elements@latest
 ```
 
-## Create Test Route
-
-Create a new Route, and add the example code:
+</TabItem>
+<TabItem value="bun" label="bun">
 
 ```bash copy
-touch app/routes/test.tsx
+bunx ai-elements@latest
 ```
 
-```typescript title="app/routes/test.tsx" showLineNumbers copy
-import { useState } from "react";
-import { mastraClient } from "../../lib/mastra";
+</TabItem>
+</Tabs>
 
-export default function Test() {
-  const [result, setResult] = useState<string | null>(null);
+This downloads the entire AI Elements UI component library into a `@/components/ai-elements` folder.
 
-  async function handleSubmit(event: React.FormEvent<HTMLFormElement>) {
-    event.preventDefault();
+## Create a chat route
 
-    const formData = new FormData(event.currentTarget);
-    const city = formData.get("city")?.toString();
-    const agent = mastraClient.getAgent("weatherAgent");
+Open ⁠`src/mastra/index.ts` and add a [⁠chatRoute()](https://github.com/reference/v1/ai-sdk/chat-route) to your config. This creates an API route your React frontend can call for AI SDK-compatible chat responses, which you’ll use with ⁠useChat() next.
 
-    const response = await agent.generate({
-      messages: [{ role: "user", content: `What's the weather like in ${city}?` }]
-    });
+```ts title="src/mastra/index.ts"
+import { Mastra } from '@mastra/core/mastra';
+// Existing imports...
+import { chatRoute } from "@mastra/ai-sdk"
 
-    setResult(response.text);
+export const mastra = new Mastra({
+  // Existing config...
+  server: {
+    apiRoutes: [
+      chatRoute({
+        path: '/chat/:agentId'
+      })
+    ]
   }
+});
+```
+
+## Add the chat UI
+
+Replace the `src/App.tsx` file to create a chat interface:
+
+```tsx title="src/App.tsx"
+import * as React from 'react';
+import { DefaultChatTransport, type ToolUIPart } from 'ai';
+import { useChat } from '@ai-sdk/react';
+
+import {
+  PromptInput,
+  PromptInputBody,
+  PromptInputTextarea,
+} from '@/components/ai-elements/prompt-input';
+
+import {
+  Conversation,
+  ConversationContent,
+  ConversationScrollButton,
+} from '@/components/ai-elements/conversation';
+
+import {
+  Message,
+  MessageContent,
+  MessageResponse
+} from '@/components/ai-elements/message';
+
+import {
+  Tool,
+  ToolHeader,
+  ToolContent,
+  ToolInput,
+  ToolOutput,
+} from '@/components/ai-elements/tool';
+
+export default function App() {
+  const [input, setInput] = React.useState<string>('');
+
+  const { messages, sendMessage, status } = useChat({
+    transport: new DefaultChatTransport({
+      api: 'http://localhost:4111/chat/weather-agent',
+    }),
+  });
+
+  const handleSubmit = async () => {
+    if (!input.trim()) return;
+
+    sendMessage({ text: input });
+    setInput('');
+  };
 
   return (
-    <>
-      <h1>Test</h1>
-      <form onSubmit={handleSubmit}>
-        <input name="city" placeholder="Enter city" required />
-        <button type="submit">Get Weather</button>
-      </form>
-      {result && <pre>{result}</pre>}
-    </>
+    <div className="max-w-4xl mx-auto p-6 relative size-full h-screen">
+      <div className="flex flex-col h-full">
+        <Conversation className="h-full">
+          <ConversationContent>
+            {messages.map((message) => (
+              <div key={message.id}>
+                {message.parts?.map((part, i) => {
+                  if (part.type === 'text') {
+                    return (
+                      <Message
+                        key={`${message.id}-${i}`}
+                        from={message.role}>
+                          <MessageContent>
+                            <MessageResponse>{part.text}</MessageResponse>
+                          </MessageContent>
+                      </Message>
+                    );
+                  }
+
+                  if (part.type?.startsWith('tool-')) {
+                    return (
+                      <Tool key={`${message.id}-${i}`}>
+                        <ToolHeader
+                          type={(part as ToolUIPart).type}
+                          state={(part as ToolUIPart).state || 'output-available'}
+                          className="cursor-pointer"
+                        />
+                        <ToolContent>
+                          <ToolInput input={(part as ToolUIPart).input || {}} />
+                          <ToolOutput
+                            output={(part as ToolUIPart).output}
+                            errorText={(part as ToolUIPart).errorText}
+                          />
+                        </ToolContent>
+                      </Tool>
+                    );
+                  }
+
+                  return null;
+                })}
+              </div>
+            ))}
+            <ConversationScrollButton />
+          </ConversationContent>
+        </Conversation>
+        <PromptInput onSubmit={handleSubmit} className="mt-20">
+          <PromptInputBody>
+            <PromptInputTextarea
+              onChange={(e) => setInput(e.target.value)}
+              className="md:leading-10"
+              value={input}
+              placeholder="Ask about the weather..."
+              disabled={status !== 'ready'}
+            />
+          </PromptInputBody>
+        </PromptInput>
+      </div>
+    </div>
   );
 }
 ```
 
-> You can now navigate to `/test` in your browser to try it out.
+This component connects [`useChat()`](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-chat) to the `chat/weather-agent` endpoint, sending prompts there and streaming the response back in chunks.
 
-Submitting **London** as the city would return a result similar to:
+It renders the response text using the [`<MessageResponse>`](https://ai-sdk.dev/elements/components/message#messageresponse-) component, and shows any tool invocations with the [`<Tool>`](https://ai-sdk.dev/elements/components/tool) component.
 
-```plaintext
-The current weather in London is partly cloudy with a temperature of 19.3°C, feeling like 17.4°C. The humidity is at 53%, and there is a wind speed of 15.9 km/h, with gusts up to 38.5 km/h.
-```
+## Test your agent
+
+In order to test your agent with the chat interface, you need to run both the Mastra server and the Vite development server.
+
+1. Start the Mastra development server:
+
+    ```bash copy
+    npx mastra dev
+    ```
+1. In a separate terminal window, start the Vite development server:
+
+    ```bash copy
+    npm run dev
+    ```
+1. Open your application at http://localhost:5173
+1. Try asking about the weather. If your API key is set up correctly, you'll get a response
 
 ## Next steps
 
-- [Monorepo Deployment](/docs/v1/deployment/monorepo)
+Congratulations on building your Mastra agent with React! 🎉
+
+From here, you can extend the project with your own tools and logic:
+
+- Learn more about [agents](/docs/v1/agents/overview)
+- Give your agent its own [tools](/docs/v1/agents/using-tools)
+- Add human-like [memory](/docs/v1/agents/agent-memory) to your agent
+
+When you're ready, read more about how Mastra integrates with AI SDK UI and React, and how to deploy your agent anywhere:
+
+- Integrate Mastra with [AI SDK UI](/guides/v1/build-your-ui/ai-sdk-ui)
+- Deploy your agent [anywhere](/docs/v1/deployment/overview)

package/.docs/raw/guides/guide/research-assistant.mdx

@@ -373,7 +373,7 @@ curl -X POST http://localhost:4111/api/agents/researchAgent/generate \
 
 Explore these examples for more advanced RAG techniques:
 
-- [Filter RAG](/examples/v1/rag/usage/filter-rag) for filtering results using metadata
-- [Cleanup RAG](/examples/v1/rag/usage/cleanup-rag) for optimizing information density
-- [Chain of Thought RAG](/examples/v1/rag/usage/cot-rag) for complex reasoning queries using workflows
-- [Rerank RAG](/examples/v1/rag/usage/cleanup-rag) for improved result relevance
+- [Filter RAG](https://github.com/mastra-ai/mastra/tree/main/examples/basics/rag/filter-rag) for filtering results using metadata
+- [Cleanup RAG](https://github.com/mastra-ai/mastra/tree/main/examples/basics/rag/cleanup-rag) for optimizing information density
+- [Chain of Thought RAG](https://github.com/mastra-ai/mastra/tree/main/examples/basics/rag/cot-rag) for complex reasoning queries using workflows
+- [Rerank RAG](https://github.com/mastra-ai/mastra/tree/main/examples/basics/rag/rerank-rag) for improved result relevance

package/.docs/raw/guides/migrations/upgrade-to-v1/agent.mdx

@@ -313,3 +313,73 @@ To migrate, remove the `TMetrics` generic parameter and configure scorers using
     // ...
   });
 ```
+
+### Tripwire response format changed
+
+The tripwire response format has changed from separate `tripwire` and `tripwireReason` fields to a single `tripwire` object containing all related data.
+
+To migrate, update your code to access tripwire data from the new object structure.
+
+```diff
+  const result = await agent.generate('Hello');
+
+- if (result.tripwire) {
+-   console.log(result.tripwireReason);
+- }
++ if (result.tripwire) {
++   console.log(result.tripwire.reason);
++   // New fields available:
++   // result.tripwire.retry - whether this step should be retried
++   // result.tripwire.metadata - additional metadata from the processor
++   // result.tripwire.processorId - which processor triggered the tripwire
++ }
+```
+
+For streaming responses:
+
+```diff
+  for await (const chunk of stream.fullStream) {
+    if (chunk.type === 'tripwire') {
+-     console.log(chunk.payload.tripwireReason);
++     console.log(chunk.payload.reason);
++     // New fields available:
++     // chunk.payload.retry
++     // chunk.payload.metadata
++     // chunk.payload.processorId
+    }
+  }
+```
+
+The step results now also include tripwire information:
+
+```diff
+  const result = await agent.generate('Hello');
+
+  for (const step of result.steps) {
+-   // No tripwire info on steps
++   if (step.tripwire) {
++     console.log('Step was blocked:', step.tripwire.reason);
++   }
+  }
+```
+
+### `prepareStep` messages format
+
+The `prepareStep` callback now receives messages in `MastraDBMessage` format instead of AI SDK v5 model message format. This change unifies `prepareStep` with the new `processInputStep` processor method, which runs at each step of the agentic loop.
+
+If you need the old AI SDK v5 format, use `messageList.get.all.aiV5.model()`:
+
+```diff
+  agent.generate({
+    prompt: 'Hello',
+    prepareStep: async ({ messages, messageList }) => {
+-     // messages was AI SDK v5 ModelMessage format
+-     console.log(messages[0].content);
++     // messages is now MastraDBMessage format
++     // Use messageList to get AI SDK v5 format if needed:
++     const aiSdkMessages = messageList.get.all.aiV5.model();
+
+      return { toolChoice: 'auto' };
+    },
+  });
+```

package/.docs/raw/guides/migrations/upgrade-to-v1/client.mdx

@@ -155,6 +155,23 @@ To migrate, use workflow streaming APIs instead of watch.
 + }
 ```
 
+### Run-related methods cannot be called directly on workflow instance
+
+Run-related methods cannot be called directly on workflow instance. You need to create a run instance first using `createRun()` method.
+
+
+```diff
+- const result = await workflow.start({ runId: '123', inputData: { ... } });
++ const run = await workflow.createRun({ runId: '123' });
++ const result = await run.start({ inputData: { ... } });
+```
+
+```diff
+- const result = await workflow.stream({ runId: '123', inputData: { ... } });
++ const run = await workflow.createRun({ runId: '123' });
++ const stream = await run.stream({ inputData: { ... } });
+```
+
 ### Deprecated stream endpoints
 
 Some stream endpoints are deprecated and will be removed. The `/api/agents/:agentId/stream/vnext` endpoint returns 410 Gone, and `/api/agents/:agentId/stream/ui` is deprecated. This change consolidates on standard streaming endpoints.