@mastra/mcp-docs-server 1.0.0-beta.11 → 1.0.0-beta.14

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
+```bash
+npm create vite@latest mastra-react -- --template react-ts
+cd mastra-react
 ```
-
 </TabItem>
-<TabItem value="yarn" label="yarn">
-
-```bash copy
-yarn add mastra@beta @mastra/core@beta @mastra/libsql@beta @mastra/client-js@beta
+<TabItem value="pnpm" label="pnpm">
+```bash
+pnpm create vite mastra-react --template react-ts
+cd mastra-react
 ```
-
 </TabItem>
-<TabItem value="pnpm" label="pnpm">
-
-```bash copy
-pnpm add mastra@beta @mastra/core@beta @mastra/libsql@beta @mastra/client-js@beta
+<TabItem value="yarn" label="yarn">
+```bash
+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
+```bash
+bun create vite mastra-react --template react-ts
+cd mastra-react
 ```
-
 </TabItem>
 </Tabs>
 
-## Integrate Mastra
-
-To integrate Mastra into your project, you have two options:
+This creates a project called `mastra-react`, but you can replace it with any name you want.
 
-### 1. Use the One-Liner
+### Tailwind
 
-Run the following command to quickly scaffold the default Weather agent with sensible defaults:
+Next, install Tailwind: 
 
-```bash copy
-npx mastra@beta init --dir . --components agents,tools --example --llm openai
+<Tabs groupId="pm">
+<TabItem value="npm" label="npm">
+```bash
+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:
-
-```bash copy
-npx mastra@latest init
+</TabItem>
+<TabItem value="pnpm" label="pnpm">
+```bash
+pnpm add tailwindcss @tailwindcss/vite
 ```
+</TabItem>
+<TabItem value="yarn" label="yarn">
+```bash
+yarn add tailwindcss @tailwindcss/vite
+```
+</TabItem>
+<TabItem value="bun" label="bun">
+```bash
+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/mastra#mastra-init). 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
+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
+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
+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
+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
+
+You'll call `weather-agent.ts` from your chat UI in the next steps.
 
-Start the Mastra Dev Server to expose your agents as REST endpoints:
+## Install AI SDK UI & AI Elements
 
-<Tabs>
+Install AI SDK UI along with the Mastra adapter:
+
+<Tabs groupId="pm">
 <TabItem value="npm" label="npm">
 
-```bash copy
-npm run dev:mastra
+```bash
+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
+```bash
+pnpm add @mastra/ai-sdk@beta @ai-sdk/react ai
 ```
 
 </TabItem>
-</Tabs>
-
-> Once running, your agents are available locally. See [Local Development Environment](/docs/v1/getting-started/studio) for more information.
+<TabItem value="yarn" label="yarn">
 
-## Start Vite Dev Server
+```bash
+yarn 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>
+<TabItem value="bun" label="bun">
 
-## Create Mastra Client
+```bash
+bun add @mastra/ai-sdk@beta @ai-sdk/react ai
+```
 
-Create a new directory and file. Then add the example code:
+</TabItem>
+</Tabs>
 
-```bash copy
-mkdir lib
-touch lib/mastra.ts
-```
+Next, initialize AI Elements. When prompted, choose the default options:
 
-```typescript title="lib/mastra.ts" showLineNumbers copy
-import { MastraClient } from "@mastra/client-js";
+<Tabs groupId="pm">
+<TabItem value="npm" label="npm">
 
-export const mastraClient = new MastraClient({
-  baseUrl: import.meta.env.VITE_MASTRA_API_URL || "http://localhost:4111",
-});
+```bash
+npx ai-elements@latest
 ```
 
-## Create Test Route Config
+</TabItem>
+<TabItem value="pnpm" label="pnpm">
 
-Add new `route` to the config:
+```bash
+pnpm dlx ai-elements@latest
+```
 
-```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
+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
+```bash
+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/ai-recruiter.mdx

@@ -28,7 +28,7 @@ Set up the Workflow, define steps to extract and classify candidate data, and th
 
 Create a new file `src/mastra/workflows/candidate-workflow.ts` and define your workflow:
 
-```ts copy title="src/mastra/workflows/candidate-workflow.ts"
+```ts title="src/mastra/workflows/candidate-workflow.ts"
 import { createWorkflow, createStep } from "@mastra/core/workflows";
 import { z } from "zod";
 
@@ -56,7 +56,7 @@ You want to extract candidate details from the resume text and classify the pers
 
 To the existing `src/mastra/workflows/candidate-workflow.ts` file add the following:
 
-```ts copy title="src/mastra/workflows/candidate-workflow.ts"
+```ts title="src/mastra/workflows/candidate-workflow.ts"
 import { Agent } from "@mastra/core/agent";
 
 const recruiter = new Agent({
@@ -109,7 +109,7 @@ This step prompts a candidate who is identified as "technical" for more informat
 
 To the existing `src/mastra/workflows/candidate-workflow.ts` file add the following:
 
-```ts copy title="src/mastra/workflows/candidate-workflow.ts"
+```ts title="src/mastra/workflows/candidate-workflow.ts"
 const askAboutSpecialty = createStep({
   id: "askAboutSpecialty",
   inputSchema: z.object({
@@ -140,7 +140,7 @@ If the candidate is "non-technical", you want a different follow-up question. Th
 
 To the existing `src/mastra/workflows/candidate-workflow.ts` file add the following:
 
-```ts title="src/mastra/workflows/candidate-workflow.ts" copy
+```ts title="src/mastra/workflows/candidate-workflow.ts"
 const askAboutRole = createStep({
   id: "askAboutRole",
   inputSchema: z.object({
@@ -170,7 +170,7 @@ You now combine the steps to implement branching logic based on the candidate's
 
 To the existing `src/mastra/workflows/candidate-workflow.ts` file change the `candidateWorkflow` like so:
 
-```ts title="src/mastra/workflows/candidate-workflow.ts" copy {10-14}
+```ts title="src/mastra/workflows/candidate-workflow.ts" {10-14}
 export const candidateWorkflow = createWorkflow({
   id: "candidate-workflow",
   inputSchema: z.object({
@@ -199,7 +199,7 @@ export const candidateWorkflow = createWorkflow({
 
 In your `src/mastra/index.ts` file, register the workflow:
 
-```ts copy title="src/mastra/index.ts" {2, 5}
+```ts title="src/mastra/index.ts" {2, 5}
 import { Mastra } from "@mastra/core";
 import { candidateWorkflow } from "./workflows/candidate-workflow";
 
@@ -216,13 +216,13 @@ export const mastra = new Mastra({
 
 You can test your workflow inside [Studio](/docs/v1/getting-started/studio) by starting the development server:
 
-```bash copy
+```bash
 mastra dev
 ```
 
 In the sidebar, navigate to **Workflows** and select **candidate-workflow**. In the middle you'll see a graph view of your workflow and on the right sidebar the **Run** tab is selected by default. Inside this tab you can enter a resume text, for example:
 
-```text copy
+```text
 Knowledgeable Software Engineer with more than 10 years of experience in software development. Proven expertise in the design and development of software databases and optimization of user interfaces.
 ```
 
@@ -230,7 +230,7 @@ After entering the resume text, press the **Run** button. You should now see two
 
 You can also test the workflow programmatically by calling [`.createRun()`](/reference/v1/workflows/workflow-methods/create-run) and [`.start()`](/reference/v1/workflows/run-methods/start). Create a new file `src/test-workflow.ts` and add the following:
 
-```ts copy title="src/test-workflow.ts"
+```ts title="src/test-workflow.ts"
 import { mastra } from "./mastra";
 
 const run = await mastra.getWorkflow("candidateWorkflow").createRun();
@@ -256,7 +256,7 @@ if (res.status === "success") {
 
 Now, run the workflow and get output in your terminal:
 
-```bash copy
+```bash
 npx tsx src/test-workflow.ts
 ```