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

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

@@ -0,0 +1,497 @@
+# Integrate Mastra in your Nuxt project
+
+In this guide, you'll build a tool-calling AI agent using Mastra, then connect it to Nuxt by importing and calling the agent directly from your server routes.
+
+You'll use [AI SDK UI](https://ai-sdk.dev/docs/ai-sdk-ui/overview) to create a beautiful, interactive chat experience with Vue.
+
+## 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 Nuxt app (optional)
+
+If you already have a Nuxt app, skip to the next step.
+
+Run the following command to [create a new Nuxt app](https://nuxt.com/docs/getting-started/installation):
+
+**npm**:
+
+```bash
+npm create nuxt@latest mastra-nuxt -- --template minimal --packageManager npm --gitInit --modules
+```
+
+**pnpm**:
+
+```bash
+pnpm create nuxt mastra-nuxt --template minimal --packageManager npm --gitInit --modules
+```
+
+**Yarn**:
+
+```bash
+yarn create nuxt mastra-nuxt --template minimal --packageManager npm --gitInit --modules
+```
+
+**Bun**:
+
+```bash
+bunx create-nuxt mastra-nuxt --template minimal --packageManager npm --gitInit --modules
+```
+
+This creates a project called `mastra-nuxt`, but you can replace it with any name you want.
+
+## Initialize Mastra
+
+Navigate to your Nuxt project:
+
+```bash
+cd mastra-nuxt
+```
+
+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 `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 Nuxt server 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/vue ai
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/ai-sdk@latest @ai-sdk/vue ai
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/ai-sdk@latest @ai-sdk/vue ai
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/ai-sdk@latest @ai-sdk/vue ai
+```
+
+## Create a chat route
+
+Create `server/api/chat.ts`:
+
+```ts
+import { handleChatStream } from '@mastra/ai-sdk'
+import { toAISdkV5Messages } from '@mastra/ai-sdk/ui'
+import { createUIMessageStreamResponse } from 'ai'
+import { mastra } from '../../src/mastra'
+
+const THREAD_ID = 'example-user-id'
+const RESOURCE_ID = 'weather-chat'
+
+export default defineEventHandler(async event => {
+  const method = event.method
+
+  if (method === 'POST') {
+    const params = await readBody(event)
+    const stream = await handleChatStream({
+      mastra,
+      agentId: 'weather-agent',
+      params: {
+        ...params,
+        memory: {
+          ...params.memory,
+          thread: THREAD_ID,
+          resource: RESOURCE_ID,
+        },
+      },
+    })
+
+    return createUIMessageStreamResponse({ stream })
+  }
+
+  if (method === 'GET') {
+    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 uiMessages
+  }
+})
+```
+
+The `POST` handler accepts a prompt and streams the agent's response back in AI SDK format, while the `GET` handler fetches message history from memory so the UI can be hydrated when the client reloads.
+
+## Add the chat UI
+
+Replace the contents of `app/app.vue` with the following:
+
+```html
+<script setup lang="ts">
+  import { ref, onMounted } from 'vue'
+  import { Chat } from '@ai-sdk/vue'
+  import { DefaultChatTransport, type ToolUIPart } from 'ai'
+
+  const chat = new Chat({
+    transport: new DefaultChatTransport({
+      api: '/api/chat',
+    }),
+  })
+
+  const STATE_TO_LABEL_MAP: Record<string, string> = {
+    'input-streaming': 'Pending',
+    'input-available': 'Running',
+    'output-available': 'Completed',
+    'output-error': 'Error',
+    'output-denied': 'Denied',
+  }
+
+  const input = ref('')
+
+  onMounted(async () => {
+    const res = await fetch('/api/chat')
+    const data = await res.json()
+    chat.messages = [...data]
+  })
+
+  function handleSubmit() {
+    if (!input.value.trim()) return
+
+    chat.sendMessage({ text: input.value })
+    input.value = ''
+  }
+</script>
+
+<template>
+  <div class="chat-container">
+    <div class="messages">
+      <div v-for="message in chat.messages" :key="message.id" class="message-wrapper">
+        <div v-for="(part, i) in message.parts" :key="`${message.id}-${i}`">
+          <div v-if="part.type === 'text'" :class="['message', message.role]">
+            <div class="message-content">{{ part.text }}</div>
+          </div>
+
+          <details v-else-if="part.type?.startsWith('tool-')" class="tool">
+            <summary class="tool-header">
+              {{ (part as ToolUIPart).type?.split('-').slice(1).join('-') }} - {{
+              STATE_TO_LABEL_MAP[(part as ToolUIPart).state ?? 'output-available'] }}
+            </summary>
+            <div class="tool-content">
+              <div class="tool-section">
+                <div class="tool-label">Parameters</div>
+                <pre><code>{{ JSON.stringify((part as ToolUIPart).input, null, 2) }}</code></pre>
+              </div>
+              <div class="tool-section">
+                <div class="tool-label">
+                  {{ (part as ToolUIPart).errorText ? 'Error' : 'Result' }}
+                </div>
+                <pre><code>{{ JSON.stringify((part as ToolUIPart).output, null, 2) }}</code></pre>
+                <div v-if="(part as ToolUIPart).errorText" class="tool-error">
+                  {{ (part as ToolUIPart).errorText }}
+                </div>
+              </div>
+            </div>
+          </details>
+        </div>
+      </div>
+    </div>
+
+    <form class="input-form" @submit.prevent="handleSubmit">
+      <input
+        v-model="input"
+        type="text"
+        placeholder="Ask about the weather..."
+        :disabled="chat.status !== 'ready'"
+        class="chat-input"
+      />
+      <button type="submit" class="submit-button" :disabled="chat.status !== 'ready'">Send</button>
+    </form>
+  </div>
+</template>
+
+<style>
+  *,
+  *::before,
+  *::after {
+    box-sizing: border-box;
+  }
+
+  *:not(dialog) {
+    margin: 0;
+  }
+
+  @media (prefers-reduced-motion: no-preference) {
+    html {
+      interpolate-size: allow-keywords;
+    }
+  }
+
+  html {
+    font-family:
+      -apple-system,
+      BlinkMacSystemFont,
+      avenir next,
+      avenir,
+      segoe ui,
+      helvetica neue,
+      Adwaita Sans,
+      Cantarell,
+      Ubuntu,
+      roboto,
+      noto,
+      helvetica,
+      arial,
+      sans-serif;
+  }
+
+  body {
+    line-height: 1.5;
+    -webkit-font-smoothing: antialiased;
+  }
+
+  img,
+  picture,
+  video,
+  canvas,
+  svg {
+    display: block;
+    max-width: 100%;
+  }
+
+  input,
+  button,
+  textarea,
+  select {
+    font: inherit;
+  }
+
+  p,
+  h1,
+  h2,
+  h3,
+  h4,
+  h5,
+  h6 {
+    overflow-wrap: break-word;
+  }
+
+  p {
+    text-wrap: pretty;
+  }
+  h1,
+  h2,
+  h3,
+  h4,
+  h5,
+  h6 {
+    text-wrap: balance;
+  }
+
+  .chat-container {
+    max-width: 48rem;
+    margin: 0 auto;
+    padding: 1.5rem;
+    height: 100vh;
+    display: flex;
+    flex-direction: column;
+  }
+
+  .messages {
+    flex: 1;
+    overflow-y: auto;
+    display: flex;
+    flex-direction: column;
+    gap: 1rem;
+  }
+
+  .message-wrapper {
+    display: flex;
+    flex-direction: column;
+    gap: 0.5rem;
+  }
+
+  .message {
+    padding: 0.75rem 1rem;
+    border-radius: 0.5rem;
+  }
+
+  .message.user {
+    background-color: #3b82f6;
+    color: white;
+    margin-left: auto;
+    max-width: 60%;
+  }
+
+  .message.assistant {
+    background-color: #f3f4f6;
+    color: #1f2937;
+    max-width: 80%;
+  }
+
+  .tool {
+    border: 1px solid #d1d5db;
+    border-radius: 0.5rem;
+    margin: 0.5rem 0;
+    overflow: hidden;
+  }
+
+  .tool-header {
+    padding: 0.75rem 1rem;
+    background-color: #f9fafb;
+    cursor: pointer;
+    font-weight: 500;
+    font-size: 0.875rem;
+  }
+
+  .tool-content {
+    padding: 1rem;
+    border-top: 1px solid #d1d5db;
+  }
+
+  .tool-section {
+    margin-bottom: 1rem;
+  }
+
+  .tool-section:last-child {
+    margin-bottom: 0;
+  }
+
+  .tool-label {
+    font-size: 0.75rem;
+    font-weight: 500;
+    text-transform: uppercase;
+    color: #6b7280;
+    margin-bottom: 0.5rem;
+  }
+
+  .tool pre {
+    background-color: #f3f4f6;
+    padding: 0.75rem;
+    border-radius: 0.375rem;
+    overflow-x: auto;
+    font-size: 0.875rem;
+  }
+
+  .tool-error {
+    color: #dc2626;
+    margin-top: 0.5rem;
+  }
+
+  .input-form {
+    display: grid;
+    grid-template-columns: 1fr auto;
+    gap: 0.75rem;
+    padding-top: 1rem;
+    border-top: 1px solid #e5e7eb;
+    margin-top: 1rem;
+  }
+
+  .chat-input {
+    padding: 0.75rem 1rem;
+    border: 1px solid #d1d5db;
+    border-radius: 0.5rem;
+    font-size: 1rem;
+  }
+
+  .chat-input:focus {
+    outline: none;
+    border-color: #3b82f6;
+    box-shadow: 0 0 0 3px rgba(59, 130, 246, 0.1);
+  }
+
+  .chat-input:disabled {
+    background-color: #f3f4f6;
+    cursor: not-allowed;
+  }
+
+  .submit-button {
+    padding: 0.75rem 1.5rem;
+    background-color: #3b82f6;
+    color: white;
+    border: none;
+    border-radius: 0.5rem;
+    font-weight: 500;
+    cursor: pointer;
+    transition: background-color 0.2s;
+  }
+
+  .submit-button:hover:not(:disabled) {
+    background-color: #2563eb;
+  }
+
+  .submit-button:disabled {
+    background-color: #9ca3af;
+    cursor: not-allowed;
+  }
+</style>
+```
+
+This component 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 styling and shows any tool invocations in a collapsible details element.
+
+## Test your agent
+
+1. Run your Nuxt app with `npm run dev`
+2. Open the chat at <http://localhost:3000>
+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 Nuxt! 🎉
+
+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 Nuxt, 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)

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

@@ -0,0 +1,67 @@
+# Mastra Quickstart
+
+The `create mastra` CLI command is the quickest way to get started. It walks you through setup and creates example agents, workflows, and tools for you to run locally or adapt.
+
+If you need more control over the setup, see the [manual installation guide](https://mastra.ai/docs/getting-started/manual-install). You can also use [`mastra init`](https://mastra.ai/reference/cli/mastra) for existing projects.
+
+## 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).
+
+## Initialize Mastra
+
+You can run `create mastra` anywhere on your machine.
+
+When prompted, choose a provider (e.g. OpenAI) and enter your key:
+
+**npm**:
+
+```bash
+npm create mastra@latest
+```
+
+**pnpm**:
+
+```bash
+pnpm create mastra
+```
+
+**Yarn**:
+
+```bash
+yarn create mastra
+```
+
+**Bun**:
+
+```bash
+bunx create-mastra
+```
+
+This creates a new directory for your project with a `src/mastra` folder containing an example weather agent and the following files:
+
+- `index.ts`: Entry point for all Mastra-related code and configuration
+- `agents/weather-agent.ts`: A weather agent with a prompt that uses the tool
+- `tools/weather-tool.ts`: A tool to fetch weather for a given location
+- `workflows/weather-workflow.ts`: A workflow that runs the weather agent
+- `scorers/weather-scorer.ts`: A scorer to evaluate the weather agent's responses
+
+Depending on your choices, you'll also end up with [Mastra Skills](https://mastra.ai/docs/build-with-ai/skills) or the [MCP Docs Server](https://mastra.ai/docs/build-with-ai/mcp-docs-server) installed.
+
+> **Tip:** You can use [flags](https://mastra.ai/reference/cli/create-mastra) with `create mastra` like `--no-example` to skip the example weather agent or `--template` to start from a specific [template](https://mastra.ai/templates).
+
+## Test your agent
+
+Once setup is complete, follow the instructions in your terminal to start the Mastra dev server, then open Studio at [localhost:4111](http://localhost:4111).
+
+Try asking about the weather. If your API key is set up correctly, you'll get a response:
+
+[Studio](https://mastra.ai/docs/getting-started/studio) lets you rapidly build and prototype agents without needing to build a UI. Once you're ready, you can integrate your Mastra agent into your app using the guides below.
+
+## Next steps
+
+- Integrate Mastra with your frontend framework: [Next.js](https://mastra.ai/guides/getting-started/next-js), [React](https://mastra.ai/guides/getting-started/vite-react), or [Astro](https://mastra.ai/guides/getting-started/astro)
+- Read more about [Mastra's features](https://mastra.ai/docs)
+- Learn how you can [build Mastra with AI](https://mastra.ai/docs/getting-started/build-with-ai)
+- Build an agent from scratch following one of our [guides](https://mastra.ai/guides)
+- Watch conceptual guides on our [YouTube channel](https://www.youtube.com/@mastra-ai) and [subscribe](https://www.youtube.com/@mastra-ai?sub_confirmation=1)