@mastra/mcp-docs-server 1.1.5 → 1.1.6-alpha.0

package/.docs/guides/getting-started/sveltekit.md

@@ -0,0 +1,296 @@
+# Integrate Mastra in your SvelteKit project
+
+In this guide, you'll build a tool-calling AI agent using Mastra, then connect it to SvelteKit by importing and calling the agent directly from your routes.
+
+You'll use [AI SDK UI](https://ai-sdk.dev/docs/ai-sdk-ui/overview) to create a beautiful, interactive chat experience.
+
+## Before you begin
+
+- You'll need an API key from a supported [model provider](https://mastra.ai/models). If you don't have a preference, use [OpenAI](https://mastra.ai/models/providers/openai).
+- Install Node.js `v22.13.0` or later
+
+## Create a new SvelteKit app (optional)
+
+If you already have a SvelteKit app using Tailwind, skip to the next step.
+
+Run the following command to [create a new SvelteKit app](https://svelte.dev/docs/kit/creating-a-project):
+
+**npm**:
+
+```bash
+npx sv create mastra-svelte --template minimal --types ts --add tailwindcss="plugins:forms" --install npm
+```
+
+**pnpm**:
+
+```bash
+pnpm dlx sv create mastra-svelte --template minimal --types ts --add tailwindcss="plugins:forms" --install npm
+```
+
+**Yarn**:
+
+```bash
+yarn dlx sv create mastra-svelte --template minimal --types ts --add tailwindcss="plugins:forms" --install npm
+```
+
+**Bun**:
+
+```bash
+bun x sv create mastra-svelte --template minimal --types ts --add tailwindcss="plugins:forms" --install npm
+```
+
+This creates a project called `mastra-svelte`, but you can replace it with any name you want. Tailwind was added for styling purposes later on.
+
+## Initialize Mastra
+
+Navigate to your SvelteKit project:
+
+```bash
+cd mastra-svelte
+```
+
+Run [`mastra init`](https://mastra.ai/reference/cli/mastra). When prompted, choose a provider (e.g. OpenAI) and enter your key:
+
+**npm**:
+
+```bash
+npx mastra@latest init
+```
+
+**pnpm**:
+
+```bash
+pnpm dlx mastra@latest init
+```
+
+**Yarn**:
+
+```bash
+yarn dlx mastra@latest init
+```
+
+**Bun**:
+
+```bash
+bun x mastra@latest init
+```
+
+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 SvelteKit routes in the next steps.
+
+## Install AI SDK UI
+
+Install AI SDK UI along with the Mastra adapter:
+
+**npm**:
+
+```bash
+npm install @mastra/ai-sdk@latest @ai-sdk/svelte ai
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/ai-sdk@latest @ai-sdk/svelte ai
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/ai-sdk@latest @ai-sdk/svelte ai
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/ai-sdk@latest @ai-sdk/svelte ai
+```
+
+## Create a chat route
+
+Create `src/routes/api/chat/+server.ts`:
+
+```ts
+import type { RequestHandler } from './$types'
+import { handleChatStream } from '@mastra/ai-sdk'
+import { toAISdkV5Messages } from '@mastra/ai-sdk/ui'
+import { createUIMessageStreamResponse } from 'ai'
+import { mastra } from '../../../mastra'
+
+const THREAD_ID = 'example-user-id'
+const RESOURCE_ID = 'weather-chat'
+
+export const POST: RequestHandler = async ({ request }) => {
+  const params = await request.json()
+  const stream = await handleChatStream({
+    mastra,
+    agentId: 'weather-agent',
+    params: {
+      ...params,
+      memory: {
+        ...params.memory,
+        thread: THREAD_ID,
+        resource: RESOURCE_ID,
+      },
+    },
+  })
+
+  return createUIMessageStreamResponse({ stream })
+}
+
+export const GET: RequestHandler = async () => {
+  const memory = await mastra.getAgentById('weather-agent').getMemory()
+  let response = null
+
+  try {
+    response = await memory?.recall({
+      threadId: THREAD_ID,
+      resourceId: RESOURCE_ID,
+    })
+  } catch {
+    console.log('No previous messages found.')
+  }
+
+  const uiMessages = toAISdkV5Messages(response?.messages || [])
+
+  return Response.json(uiMessages)
+}
+```
+
+The `POST` route accepts a prompt and streams the agent's response back in AI SDK format, while the `GET` route fetches message history from memory so the UI can be hydrated when the client reloads.
+
+In order for the `GET` handler to be called, you need to create a `src/routes/+page.ts` file. Its `load()` function runs alongside `+page.svelte`.
+
+```ts
+import type { UIDataTypes, UIMessage, UITools } from 'ai'
+import type { PageLoad } from './$types'
+
+export const load: PageLoad = async ({ fetch }) => {
+  const response = await fetch('/api/chat')
+  const initialMessages = (await response.json()) as UIMessage<unknown, UIDataTypes, UITools>[]
+  return { initialMessages }
+}
+```
+
+## Add the chat UI
+
+Replace `src/routes/+page.svelte` with the following.
+
+```svelte
+<script lang="ts">
+  import { Chat } from '@ai-sdk/svelte';
+  import { DefaultChatTransport, type ToolUIPart } from 'ai';
+
+  let input = $state('');
+  const { data } = $props();
+  let messages = $derived(data.initialMessages)
+
+  const chat = new Chat({
+    transport: new DefaultChatTransport({
+      api: '/api/chat'
+    }),
+    get messages() {
+      return messages;
+    }
+  });
+
+  function handleSubmit(event: SubmitEvent) {
+    event.preventDefault();
+    chat.sendMessage({ text: input });
+    input = '';
+  }
+
+  const STATE_TO_LABEL_MAP: Record<ToolUIPart["state"], string> = {
+    "input-streaming": "Pending",
+    "input-available": "Running",
+    // @ts-expect-error - Only available in AI SDK v6
+    "approval-requested": "Awaiting Approval",
+    "approval-responded": "Responded",
+    "output-available": "Completed",
+    "output-error": "Error",
+    "output-denied": "Denied",
+  };
+</script>
+
+<main class="max-w-3xl mx-auto p-6 size-full h-screen">
+  <div class="flex flex-col h-full">
+    <div class="flex-1 min-h-0 overflow-y-auto" data-name="conversation">
+      <div data-name="conversation-content" class="flex flex-col gap-8">
+        {#each chat.messages as message, messageIndex (messageIndex)}
+          <div>
+            {#each message.parts as part, partIndex (partIndex)}
+              {#if part.type === 'text'}
+                <div data-name="message" class={[message.role === 'user' && 'ml-auto justify-end', 'group flex w-full max-w-[95%] flex-col gap-2', message.role === 'user' ? 'is-user' : 'is-assistant']}>
+                  <div data-name="message-content" class={["is-user:dark flex w-fit max-w-full min-w-0 flex-col gap-2 overflow-hidden text-sm",
+      "group-[.is-user]:ml-auto group-[.is-user]:rounded-lg group-[.is-user]:bg-blue-100 group-[.is-user]:px-4 group-[.is-user]:py-3 group-[.is-user]:text-foreground",
+      "group-[.is-assistant]:text-foreground"]}>
+                    <div data-name="message-response" class="size-full [&>*:first-child]:mt-0 [&>*:last-child]:mb-0">
+                      {part.text}
+                    </div>
+                  </div>
+                </div>
+              {:else if part.type.startsWith('tool-')}
+                <div data-name="tool" class="not-prose mb-6 w-full rounded-lg border border-gray-300 shadow">
+                  <details data-name="tool-header" class="w-full p-3 hover:cursor-pointer">
+                    <summary class="font-medium text-sm">{(part as ToolUIPart).type.split("-").slice(1).join("-")} - {STATE_TO_LABEL_MAP[(part as ToolUIPart).state ?? 'output-available']}</summary>
+                    <div data-name="tool-content" class="">
+                      <div data-name="tool-input" class="space-y-2 overflow-hidden py-4">
+                        <div class="font-medium text-muted-foreground text-xs uppercase tracking-wide">Parameters</div>
+                        <pre class="w-full overflow-x-auto rounded-md border border-gray-300 bg-gray-50 p-3 text-sm"><code>{JSON.stringify((part as ToolUIPart).input, null, 2)}</code></pre>
+                      </div>
+                      <div data-name="tool-output" class="space-y-2 overflow-hidden py-4">
+                        <div class="font-medium text-muted-foreground text-xs uppercase tracking-wide">{(part as ToolUIPart).errorText ? 'Error' : 'Result'}</div>
+                        <pre class="w-full overflow-x-auto rounded-md border border-gray-300 bg-gray-50 p-3 text-sm"><code>{JSON.stringify((part as ToolUIPart).output, null, 2)}</code></pre>
+                        {#if (part as ToolUIPart).errorText}
+                          <div data-name="tool-error" class="text-red-600">
+                            {(part as ToolUIPart).errorText}
+                          </div>
+                        {/if}
+                      </div>
+                    </div>
+                  </details>
+                </div>
+              {/if}
+            {/each}
+          </div>
+        {/each}
+      </div>
+    </div>
+    <form class="w-full grid grid-cols-[1fr_auto] gap-6 shrink-0 pt-4" onsubmit={handleSubmit} data-name="prompt-input">
+      <input name="chat-input" class="rounded-lg border border-gray-300 shadow h-10" placeholder="City name" bind:value={input} />
+      <button class="bg-blue-600 text-white shadow-lg border border-blue-400 px-4 whitespace-nowrap rounded-lg text-sm font-medium transition-all disabled:pointer-events-none disabled:opacity-50 shrink-0 outline-none focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px]" type="submit">Send</button>
+    </form>
+  </div>
+</main>
+```
+
+This page connects [`Chat`](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-chat) to the `api/chat` endpoint, sending prompts there and streaming the response back in chunks.
+
+It renders the response text using custom message and tool components.
+
+## Test your agent
+
+1. Run your SvelteKit app with `npm run dev`
+2. Open the chat at <http://localhost:5173>
+3. Try asking about the weather. If your API key is set up correctly, you'll get a response
+
+## Next steps
+
+Congratulations on building your Mastra agent with SvelteKit! 🎉
+
+From here, you can extend the project with your own tools and logic:
+
+- Learn more about [agents](https://mastra.ai/docs/agents/overview)
+- Give your agent its own [tools](https://mastra.ai/docs/agents/using-tools)
+- Add human-like [memory](https://mastra.ai/docs/agents/agent-memory) to your agent
+
+When you're ready, read more about how Mastra integrates with AI SDK UI and SvelteKit, and how to deploy your agent anywhere:
+
+- Integrate Mastra with [AI SDK UI](https://mastra.ai/guides/build-your-ui/ai-sdk-ui)
+- Deploy your agent [anywhere](https://mastra.ai/docs/deployment/overview)
+- Try the [unofficial Svelte AI Elements](https://svelte-ai-elements.vercel.app/)

package/.docs/guides/getting-started/vite-react.md

@@ -0,0 +1,425 @@
+# Integrate Mastra in your React + Vite project
+
+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.
+
+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.
+
+## Before you begin
+
+- You'll need an API key from a supported [model provider](https://mastra.ai/models). If you don't have a preference, use [OpenAI](https://mastra.ai/models/providers/openai).
+- Install Node.js `v22.13.0` or later
+
+## Create a new React + Vite app (optional)
+
+If you already have a React + Vite app using Tailwind, skip to the next step.
+
+### Project scaffold
+
+Run the following command to [create a new React + Vite app](https://vite.dev/guide/#scaffolding-your-first-vite-project):
+
+**npm**:
+
+```bash
+npm create vite@latest mastra-react -- --template react-ts
+```
+
+**pnpm**:
+
+```bash
+pnpm create vite mastra-react --template react-ts
+```
+
+**Yarn**:
+
+```bash
+yarn create vite mastra-react --template react-ts
+```
+
+**Bun**:
+
+```bash
+bunx create-vite mastra-react --template react-ts
+```
+
+This creates a project called `mastra-react`, but you can replace it with any name you want.
+
+Navigate to your project directory:
+
+```bash
+cd mastra-react
+```
+
+### Tailwind
+
+Next, install Tailwind:
+
+**npm**:
+
+```bash
+npm install tailwindcss @tailwindcss/vite
+```
+
+**pnpm**:
+
+```bash
+pnpm add tailwindcss @tailwindcss/vite
+```
+
+**Yarn**:
+
+```bash
+yarn add tailwindcss @tailwindcss/vite
+```
+
+**Bun**:
+
+```bash
+bun add tailwindcss @tailwindcss/vite
+```
+
+Configure the Vite plugins:
+
+```typescript
+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:
+
+```css
+@import 'tailwindcss';
+```
+
+Add these `compilerOptions` to `tsconfig.json`:
+
+```jsonc
+{
+  // ...
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./src/*"],
+    },
+  },
+}
+```
+
+Edit `tsconfig.app.json` to resolve paths:
+
+```jsonc
+{
+  "compilerOptions": {
+    // ...
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./src/*"],
+    },
+    // ...
+  },
+}
+```
+
+## Initialize Mastra
+
+Run [`mastra init`](https://mastra.ai/reference/cli/mastra). When prompted, choose a provider (e.g. OpenAI) and enter your key:
+
+**npm**:
+
+```bash
+npx mastra@latest init
+```
+
+**pnpm**:
+
+```bash
+pnpm dlx mastra@latest init
+```
+
+**Yarn**:
+
+```bash
+yarn dlx mastra@latest init
+```
+
+**Bun**:
+
+```bash
+bun x mastra@latest init
+```
+
+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.
+
+## Install AI SDK UI & AI Elements
+
+Install AI SDK UI along with the Mastra adapter:
+
+**npm**:
+
+```bash
+npm install @mastra/ai-sdk@latest @ai-sdk/react ai
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/ai-sdk@latest @ai-sdk/react ai
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/ai-sdk@latest @ai-sdk/react ai
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/ai-sdk@latest @ai-sdk/react ai
+```
+
+Next, initialize AI Elements. When prompted, choose the default options:
+
+**npm**:
+
+```bash
+npx ai-elements@latest
+```
+
+**pnpm**:
+
+```bash
+pnpm dlx ai-elements@latest
+```
+
+**Yarn**:
+
+```bash
+yarn dlx ai-elements@latest
+```
+
+**Bun**:
+
+```bash
+bun x ai-elements@latest
+```
+
+This downloads the entire AI Elements UI component library into a `@/components/ai-elements` folder.
+
+## Create a chat route
+
+Open ⁠`src/mastra/index.ts` and add a [⁠chatRoute()](https://mastra.ai/reference/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.
+
+```ts
+import { Mastra } from '@mastra/core/mastra'
+// Existing imports...
+import { chatRoute } from '@mastra/ai-sdk'
+
+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
+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 (
+    <div className="relative mx-auto size-full h-screen max-w-4xl p-6">
+      <div className="flex h-full flex-col">
+        <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>
+  )
+}
+```
+
+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.
+
+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.
+
+## 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:
+
+   **npm**:
+
+   ```bash
+   npx mastra dev
+   ```
+
+   **pnpm**:
+
+   ```bash
+   pnpm dlx mastra dev
+   ```
+
+   **Yarn**:
+
+   ```bash
+   yarn dlx mastra dev
+   ```
+
+   **Bun**:
+
+   ```bash
+   bun x mastra dev
+   ```
+
+2. In a separate terminal window, start the Vite development server:
+
+   **npm**:
+
+   ```bash
+   npm run dev
+   ```
+
+   **pnpm**:
+
+   ```bash
+   pnpm run dev
+   ```
+
+   **Yarn**:
+
+   ```bash
+   yarn dev
+   ```
+
+   **Bun**:
+
+   ```bash
+   bun run dev
+   ```
+
+3. Open your application at <http://localhost:5173>
+
+4. Try asking about the weather. If your API key is set up correctly, you'll get a response
+
+## Next steps
+
+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](https://mastra.ai/docs/agents/overview)
+- Give your agent its own [tools](https://mastra.ai/docs/agents/using-tools)
+- Add human-like [memory](https://mastra.ai/docs/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](https://mastra.ai/guides/build-your-ui/ai-sdk-ui)
+- Deploy your agent [anywhere](https://mastra.ai/docs/deployment/overview)