@mastra/mcp-docs-server 1.1.5 → 1.1.6

package/.docs/guides/deployment/netlify.md

@@ -0,0 +1,77 @@
+# Deploy Mastra to Netlify
+
+Use `@mastra/deployer-netlify` to deploy your Mastra server as serverless functions on Netlify. The deployer bundles your code and generates a `.netlify` directory conforming to Netlify's [frameworks API](https://docs.netlify.com/build/frameworks/frameworks-api/#netlifyv1functions), ready to deploy.
+
+> **Info:** This guide covers deploying the [Mastra server](https://mastra.ai/docs/server/mastra-server). If you're using a [server adapter](https://mastra.ai/docs/server/server-adapters) or [web framework](https://mastra.ai/docs/deployment/web-framework), deploy the way you normally would for that framework.
+
+## Before you begin
+
+You'll need a [Mastra application](https://mastra.ai/guides/getting-started/quickstart) and a [Netlify](https://www.netlify.com/) account.
+
+Netlify Functions use an ephemeral filesystem, so any storage you configure (including observability storage) must be hosted externally. If you're using [LibSQLStore](https://mastra.ai/reference/storage/libsql) with a file URL, switch to a remotely hosted database.
+
+## Installation
+
+Add the `@mastra/deployer-netlify` package to your project:
+
+**npm**:
+
+```bash
+npm install @mastra/deployer-netlify@latest
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/deployer-netlify@latest
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/deployer-netlify@latest
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/deployer-netlify@latest
+```
+
+Import [`NetlifyDeployer`](https://mastra.ai/reference/deployer/netlify) and set it as the deployer in your Mastra configuration:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { NetlifyDeployer } from '@mastra/deployer-netlify'
+
+export const mastra = new Mastra({
+  deployer: new NetlifyDeployer(),
+})
+```
+
+Create a `netlify.toml` file with the following contents in your project root:
+
+```toml
+[build]
+  command = "mastra build"
+```
+
+## Deploy
+
+After setting up your project, push it to your remote Git provider of choice (e.g. GitHub).
+
+1. Connect your repository to Netlify. During the setup process, Netlify will detect your `netlify.toml` file and set the build command to `mastra build`.
+
+   > **Note:** Remember to set your environment variables needed to run your application (e.g. your [model provider](https://mastra.ai/models/providers) API key).
+
+2. Once you're ready, click the **Deploy** button and wait for the first deployment to complete. It'll tell you that one function has been deployed.
+
+3. Verify your deployment at `https://<random-slug>.netlify.app/api/agents`, which should return a JSON list of your agents.
+
+   Since the [Mastra server](https://mastra.ai/docs/server/mastra-server) prefixes every API endpoint with `/api`, you have to add it to your URLs when making requests.
+
+   > **Info:** Netlify functions are typically deployed at `https://<random-slug>.netlify.app/.netlify/functions/api`. The `NetlifyDeployer` redirects any request from `/*` to `/.netlify/functions/api/:splat`, so you don't need to include the `.netlify/functions` prefix in your URLs.
+
+4. You can now call your Mastra endpoints over HTTP.
+
+   > **Warning:** Set up [authentication](https://mastra.ai/docs/server/auth) before exposing your endpoints publicly.

package/.docs/guides/deployment/vercel.md

@@ -0,0 +1,101 @@
+# Deploy Mastra to Vercel
+
+Use `@mastra/deployer-vercel` to deploy your Mastra server as serverless functions on Vercel. The deployer bundles your code and generates a `.vercel/output` directory conforming to Vercel's [Build Output API](https://vercel.com/docs/build-output-api/v3), ready to deploy with no additional configuration.
+
+> **Info:** This guide covers deploying the [Mastra server](https://mastra.ai/docs/server/mastra-server). If you're using a [server adapter](https://mastra.ai/docs/server/server-adapters) or [web framework](https://mastra.ai/docs/deployment/web-framework), deploy the way you normally would for that framework.
+
+## Before you begin
+
+You'll need a [Mastra application](https://mastra.ai/guides/getting-started/quickstart) and a [Vercel](https://vercel.com/) account.
+
+Vercel Functions use an ephemeral filesystem, so any storage you configure (including observability storage) must be hosted externally. If you're using [LibSQLStore](https://mastra.ai/reference/storage/libsql) with a file URL, switch to a remotely hosted database.
+
+## Installation
+
+Add the `@mastra/deployer-vercel` package to your project:
+
+**npm**:
+
+```bash
+npm install @mastra/deployer-vercel@latest
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/deployer-vercel@latest
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/deployer-vercel@latest
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/deployer-vercel@latest
+```
+
+Import [`VercelDeployer`](https://mastra.ai/reference/deployer/vercel) and set it as the deployer in your Mastra configuration:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { VercelDeployer } from '@mastra/deployer-vercel'
+
+export const mastra = new Mastra({
+  deployer: new VercelDeployer(),
+})
+```
+
+## Deploy
+
+1. Push your project to a remote Git provider (e.g. GitHub) and connect your repository to Vercel.
+
+   By default, Vercel runs `npm run build`, which triggers `mastra build`. If you don't have a build script, add `"build": "mastra build"` to your `package.json`.
+
+   > **Note:** Remember to set your environment variables needed to run your application (e.g. your [model provider](https://mastra.ai/models/providers) API key).
+
+2. Once you're ready, click **Deploy** and wait for the first deployment to complete.
+
+3. Verify your deployment at `https://<your-project>.vercel.app/api/agents`, which should return a JSON list of your agents.
+
+   Since the Mastra server prefixes every endpoint with `/api`, you have to add it to your URLs when making requests.
+
+4. You can now call your Mastra endpoints over HTTP.
+
+   > **Warning:** Set up [authentication](https://mastra.ai/docs/server/auth) before exposing your endpoints publicly.
+
+## Optional overrides
+
+The Vercel deployer supports configuration options that are written to the Vercel Output API function config. See the [`VercelDeployer` reference](https://mastra.ai/reference/deployer/vercel) for available options like `maxDuration`, `memory`, and `regions`.
+
+## Observability
+
+Serverless functions can terminate immediately after returning a response. Any pending async work - like sending telemetry - may get killed before completing. Awaiting `flush()` ensures all traces are sent before the function exits.
+
+```typescript
+import type { VercelRequest, VercelResponse } from '@vercel/node'
+import { mastra } from '../src/mastra'
+
+export default async function handler(req: VercelRequest, res: VercelResponse) {
+  const { message } = req.body
+  const agent = mastra.getAgent('myAgent')
+  const result = await agent.generate([{ role: 'user', content: message }])
+
+  const observability = mastra.getObservability()
+  await observability?.flush()
+
+  return res.json(result)
+}
+```
+
+> **Warning:** The Vercel deployer doesn't include `flush` calls. If you need this, you'll need to wrap the handler yourself to add the logic before returning the response. Alternatively, deploy to a long-running server like a [virtual machine](https://mastra.ai/guides/deployment/digital-ocean) where this isn't an issue.
+
+## Related
+
+- [VercelDeployer reference](https://mastra.ai/reference/deployer/vercel)
+- [Deployment overview](https://mastra.ai/docs/deployment/overview)
+- [Server adapters](https://mastra.ai/docs/server/server-adapters)
+- [Web framework integration](https://mastra.ai/docs/deployment/web-framework)

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

@@ -0,0 +1,398 @@
+# Integrate Mastra in your Astro project
+
+In this guide, you'll build a tool-calling AI agent using Mastra, then connect it to Astro 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) and [AI Elements](https://ai-sdk.dev/elements) to create a beautiful, interactive chat experience.
+
+> **Note:** While this guide shows you how to use Astro with React and full server-side rendering (SSR), there are many ways to use Astro with Mastra. You can [opt-in to SSR](https://docs.astro.build/en/guides/on-demand-rendering/#enabling-on-demand-rendering) on a per-file basis and use other frameworks like Svelte, Vue, Solid, or Preact. You can use Astro to build out a chat interface and call endpoints [natively in Astro](https://docs.astro.build/en/recipes/call-endpoints/).
+
+## 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 Astro app (optional)
+
+If you already have an Astro app, skip to the next step. Your Astro app should be setup like this:
+
+- Use SSR (`output: "server"` in `astro.config.mjs`)
+- Use the [React integration](https://docs.astro.build/en/guides/integrations-guide/react/)
+- Tailwind installed
+
+To support [on-demand rendering](https://docs.astro.build/en/guides/on-demand-rendering/) this guide will use the [Node.js adapter](https://docs.astro.build/en/guides/integrations-guide/node/) but any of the supported server adapters will work.
+
+**npm**:
+
+```bash
+npm create astro@latest mastra-astro -- --add node --add react --add tailwind --install --skip-houston --template minimal --git
+```
+
+**pnpm**:
+
+```bash
+pnpm create astro mastra-astro --add node --add react --add tailwind --install --skip-houston --template minimal --git
+```
+
+**Yarn**:
+
+```bash
+yarn create astro mastra-astro --add node --add react --add tailwind --install --skip-houston --template minimal --git
+```
+
+**Bun**:
+
+```bash
+bunx create-astro mastra-astro --add node --add react --add tailwind --install --skip-houston --template minimal --git
+```
+
+This creates a project called `mastra-astro`, but you can replace it with any name you want.
+
+`cd` into your project and edit the `astro.config.mjs` file to set the [`output` setting](https://docs.astro.build/en/reference/configuration-reference/#output) to `"server"`:
+
+```js
+// @ts-check
+import { defineConfig } from 'astro/config'
+
+import node from '@astrojs/node'
+import react from '@astrojs/react'
+import tailwindcss from '@tailwindcss/vite'
+
+// https://astro.build/config
+export default defineConfig({
+  output: 'server',
+  adapter: node({
+    mode: 'standalone',
+  }),
+
+  integrations: [react()],
+
+  vite: {
+    plugins: [tailwindcss()],
+  },
+})
+```
+
+Lastly, edit the `tsconfig.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 Astro routes 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
+
+Create `src/pages/api/chat.ts`:
+
+```ts
+import type { APIRoute } from 'astro'
+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: APIRoute = 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: APIRoute = 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.
+
+## Create a chat component
+
+Create `src/components/chat.tsx`:
+
+```tsx
+import '@/styles/global.css'
+import { useEffect, useState } 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'
+
+function Chat() {
+  const [input, setInput] = useState<string>('')
+
+  const { messages, setMessages, sendMessage, status } = useChat({
+    transport: new DefaultChatTransport({
+      api: '/api/chat',
+    }),
+  })
+
+  useEffect(() => {
+    const fetchMessages = async () => {
+      const res = await fetch('/api/chat')
+      const data = await res.json()
+      setMessages([...data])
+    }
+    fetchMessages()
+  }, [setMessages])
+
+  const handleSubmit = async () => {
+    if (!input.trim()) return
+
+    sendMessage({ text: input })
+    setInput('')
+  }
+
+  return (
+    <div className="relative size-full h-screen w-full 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="Type your message..."
+              disabled={status !== 'ready'}
+            />
+          </PromptInputBody>
+        </PromptInput>
+      </div>
+    </div>
+  )
+}
+
+export default Chat
+```
+
+This component connects [`useChat()`](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 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.
+
+## Render the chat component
+
+The last step is to render the chat component on your index page. Edit `src/pages/index.astro`:
+
+```html
+---
+import Chat from '@/components/chat';
+---
+
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <meta name="viewport" content="width=device-width" />
+    <meta name="generator" content="{Astro.generator}" />
+    <title>Astro</title>
+  </head>
+  <body>
+    <Chat client:load />
+  </body>
+</html>
+```
+
+Import the `Chat` component and add it to the body with the `client:load` [directive](https://docs.astro.build/en/reference/directives-reference/#client-directives) so it runs on the client side.
+
+## Test your agent
+
+1. Run your Astro app with `npm run dev`
+2. Open the chat at <http://localhost:4321>
+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 Astro! 🎉
+
+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 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)