@mastra/mcp-docs-server 0.0.0-default-storage-virtual-file-20250410035748

package/.docs/raw/faq/index.mdx

@@ -0,0 +1,63 @@
+---
+title: "Licensing"
+description: "Mastra License"
+---
+
+# License
+
+## Elastic License 2.0 (ELv2)
+
+Mastra is licensed under the Elastic License 2.0 (ELv2), a modern license designed to balance open-source principles with sustainable business practices.
+
+### What is Elastic License 2.0?
+
+The Elastic License 2.0 is a source-available license that grants users broad rights to use, modify, and distribute the software while including specific limitations to protect the project's sustainability. It allows:
+
+- Free use for most purposes
+- Viewing, modifying, and redistributing the source code
+- Creating and distributing derivative works
+- Commercial use within your organization
+
+The primary limitation is that you cannot provide Mastra as a hosted or managed service that offers users access to the substantial functionality of the software.
+
+### Why We Chose Elastic License 2.0
+
+We selected the Elastic License 2.0 for several important reasons:
+
+1. **Sustainability**: It enables us to maintain a healthy balance between openness and the ability to sustain long-term development.
+
+2. **Innovation Protection**: It ensures we can continue investing in innovation without concerns about our work being repackaged as competing services.
+
+3. **Community Focus**: It maintains the spirit of open source by allowing users to view, modify, and learn from our code while protecting our ability to support the community.
+
+4. **Business Clarity**: It provides clear guidelines for how Mastra can be used in commercial contexts.
+
+### Building Your Business with Mastra
+
+Despite the licensing restrictions, there are numerous ways to build successful businesses using Mastra:
+
+#### Allowed Business Models
+
+- **Building Applications**: Create and sell applications built with Mastra
+- **Offering Consulting Services**: Provide expertise, implementation, and customization services
+- **Developing Custom Solutions**: Build bespoke AI solutions for clients using Mastra
+- **Creating Add-ons and Extensions**: Develop and sell complementary tools that extend Mastra's functionality
+- **Training and Education**: Offer courses and educational materials about using Mastra effectively
+
+#### Examples of Compliant Usage
+
+- A company builds an AI-powered customer service application using Mastra and sells it to clients
+- A consulting firm offers implementation and customization services for Mastra
+- A developer creates specialized agents and tools with Mastra and licenses them to other businesses
+- A startup builds a vertical-specific solution (e.g., healthcare AI assistant) powered by Mastra
+
+#### What to Avoid
+
+The main restriction is that you cannot offer Mastra itself as a hosted service where users access its core functionality. This means:
+
+- Don't create a SaaS platform that is essentially Mastra with minimal modifications
+- Don't offer a managed Mastra service where customers are primarily paying to use Mastra's features
+
+### Questions About Licensing?
+
+If you have specific questions about how the Elastic License 2.0 applies to your use case, please [contact us](https://discord.gg/BTYqqHKUrf) on Discord for clarification. We're committed to supporting legitimate business use cases while protecting the sustainability of the project.

package/.docs/raw/frameworks/ai-sdk.mdx

@@ -0,0 +1,296 @@
+---
+title: "Using with AI SDK"
+description: "Learn how Mastra leverages the AI SDK library and how you can leverage it further with Mastra"
+---
+
+# AI SDK
+
+Mastra leverages AI SDK's model routing (a unified interface on top of OpenAI, Anthropic, etc), structured output, and tool calling.
+
+We explain this in greater detail in [this blog post](https://mastra.ai/blog/using-ai-sdk-with-mastra)
+
+## Mastra + AI SDK
+
+Mastra acts as a layer on top of AI SDK to help teams productionize their proof-of-concepts quickly and easily.
+
+<img
+  src="/docs/mastra-ai-sdk.png"
+  alt="Agent interaction trace showing spans, LLM calls, and tool executions"
+  style={{ maxWidth: "800px", width: "100%", margin: "8px 0" }}
+  className="nextra-image rounded-md py-8"
+  data-zoom
+  width={800}
+  height={400}
+/>
+
+## Model routing
+
+When creating agents in Mastra, you can specify any AI SDK-supported model:
+
+```typescript
+import { openai } from "@ai-sdk/openai";
+import { Agent } from "@mastra/core/agent";
+
+const agent = new Agent({
+  name: "WeatherAgent",
+  instructions: "Instructions for the agent...",
+  model: openai("gpt-4-turbo"), // Model comes directly from AI SDK
+});
+
+const result = await agent.generate("What is the weather like?");
+```
+
+## AI SDK Hooks
+
+Mastra is compatible with AI SDK's hooks for seamless frontend integration:
+
+### useChat
+
+The `useChat` hook enables real-time chat interactions in your frontend application
+
+- Works with agent data streams i.e. `.toDataStreamResponse()`
+- The useChat `api` defaults to `/api/chat`
+- Works with the Mastra REST API agent stream endpoint `{MASTRA_BASE_URL}/agents/:agentId/stream` for data streams,
+  i.e. no structured output is defined.
+
+```typescript filename="app/api/chat/route.ts" copy
+import { mastra } from "@/src/mastra";
+
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+  const myAgent = mastra.getAgent("weatherAgent");
+  const stream = await myAgent.stream(messages);
+
+  return stream.toDataStreamResponse();
+}
+```
+
+```typescript copy
+import { useChat } from '@ai-sdk/react';
+
+export function ChatComponent() {
+  const { messages, input, handleInputChange, handleSubmit } = useChat({
+    api: '/path-to-your-agent-stream-api-endpoint'
+  });
+
+  return (
+    <div>
+      {messages.map(m => (
+        <div key={m.id}>
+          {m.role}: {m.content}
+        </div>
+      ))}
+      <form onSubmit={handleSubmit}>
+        <input
+          value={input}
+          onChange={handleInputChange}
+          placeholder="Say something..."
+        />
+      </form>
+    </div>
+  );
+}
+```
+
+> **Gotcha**: When using `useChat` with agent memory functionality, make sure to check out the [Agent Memory section](/docs/agents/agent-memory#usechat) for important implementation details.
+
+### useCompletion
+
+For single-turn completions, use the `useCompletion` hook:
+
+- Works with agent data streams i.e. `.toDataStreamResponse()`
+- The useCompletion `api` defaults to `/api/completion`
+- Works with the Mastra REST API agent stream endpoint `{MASTRA_BASE_URL}/agents/:agentId/stream` for data streams,
+  i.e. no structured output is defined.
+
+```typescript filename="app/api/completion/route.ts" copy
+import { mastra } from "@/src/mastra";
+
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+  const myAgent = mastra.getAgent("weatherAgent");
+  const stream = await myAgent.stream(messages);
+
+  return stream.toDataStreamResponse();
+}
+```
+
+```typescript
+import { useCompletion } from "@ai-sdk/react";
+
+export function CompletionComponent() {
+  const {
+    completion,
+    input,
+    handleInputChange,
+    handleSubmit,
+  } = useCompletion({
+  api: '/path-to-your-agent-stream-api-endpoint'
+  });
+
+  return (
+    <div>
+      <form onSubmit={handleSubmit}>
+        <input
+          value={input}
+          onChange={handleInputChange}
+          placeholder="Enter a prompt..."
+        />
+      </form>
+      <p>Completion result: {completion}</p>
+    </div>
+  );
+}
+```
+
+### useObject
+
+For consuming text streams that represent JSON objects and parsing them into a complete object based on a schema.
+
+- Works with agent text streams i.e. `.toTextStreamResponse()`
+- The useObject `api` defaults to `/api/completion`
+- Works with the Mastra REST API agent stream endpoint `{MASTRA_BASE_URL}/agents/:agentId/stream` for text streams,
+  i.e. structured output is defined.
+
+```typescript filename="app/api/use-object/route.ts" copy
+import { mastra } from "@/src/mastra";
+
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+  const myAgent = mastra.getAgent("weatherAgent");
+  const stream = await myAgent.stream(messages, {
+    output: z.object({
+      weather: z.string(),
+    }),
+  });
+
+  return stream.toTextStreamResponse();
+}
+```
+
+```typescript
+import { experimental_useObject as useObject } from '@ai-sdk/react';
+
+export default function Page() {
+  const { object, submit } = useObject({
+    api: '/api/use-object',
+    schema: z.object({
+      weather: z.string(),
+    }),
+  });
+
+  return (
+    <div>
+      <button onClick={() => submit('example input')}>Generate</button>
+      {object?.content && <p>{object.content}</p>}
+    </div>
+  );
+}
+```
+
+## Tool Calling
+
+### AI SDK Tool Format
+
+Mastra supports tools created using the AI SDK format, so you can use
+them directly with Mastra agents. See our tools doc on [Vercel AI SDK Tool Format
+](/docs/agents/adding-tools#vercel-ai-sdk-tool-format) for more details.
+
+### Client-side tool calling
+
+Mastra leverages AI SDK's tool calling, so what applies in AI SDK applies here still.
+[Agent Tools](/docs/agents/adding-tools) in Mastra are 100% percent compatible with AI SDK tools.
+
+Mastra tools also expose an optional `execute` async function. It is optional because you might want to forward tool calls to the client or to a queue instead of executing them in the same process.
+
+One way to then leverage client-side tool calling is to use the `@ai-sdk/react` `useChat` hook's `onToolCall` property for
+client-side tool execution
+
+## Custom DataStream
+In certain scenarios you need to write custom data, message annotations to an agent's dataStream.
+This can be useful for:
+
+- Streaming additional data to the client
+- Passing progress info back to the client in real time
+
+Mastra integrates well with AI SDK to make this possible
+
+### CreateDataStream
+The `createDataStream` function allows you to stream additional data to the client
+
+```typescript  copy
+    import { createDataStream } from "ai"
+    import { Agent } from '@mastra/core/agent';
+
+    export const weatherAgent = new Agent({
+      name: 'Weather Agent',
+      instructions: `
+          You are a helpful weather assistant that provides accurate weather information.
+
+          Your primary function is to help users get weather details for specific locations. When responding:
+          - Always ask for a location if none is provided
+          - If the location name isn’t in English, please translate it
+          - If giving a location with multiple parts (e.g. "New York, NY"), use the most relevant part (e.g. "New York")
+          - Include relevant details like humidity, wind conditions, and precipitation
+          - Keep responses concise but informative
+
+          Use the weatherTool to fetch current weather data.
+    `,
+      model: openai('gpt-4o'),
+      tools: { weatherTool },
+    });
+
+    const stream = createDataStream({
+      async execute(dataStream) {
+        // Write data
+        dataStream.writeData({ value: 'Hello' });
+
+        // Write annotation
+        dataStream.writeMessageAnnotation({ type: 'status', value: 'processing' });
+  
+        //mastra agent stream
+        const agentStream = await weatherAgent.stream('What is the weather')
+
+        // Merge agent stream
+         agentStream.mergeIntoDataStream(dataStream);
+      },
+      onError: error => `Custom error: ${error.message}`,
+  });
+
+```
+### CreateDataStreamResponse
+The `createDataStreamResponse` function creates a Response object that streams data to the client
+
+```typescript filename="app/api/chat/route.ts" copy
+import { mastra } from "@/src/mastra";
+
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+  const myAgent = mastra.getAgent("weatherAgent");
+  //mastra agent stream
+  const agentStream = await myAgent.stream(messages);
+
+  const response = createDataStreamResponse({
+    status: 200,
+    statusText: 'OK',
+    headers: {
+      'Custom-Header': 'value',
+    },
+    async execute(dataStream) {
+      // Write data
+      dataStream.writeData({ value: 'Hello' });
+
+      // Write annotation
+      dataStream.writeMessageAnnotation({ type: 'status', value: 'processing' });
+
+      // Merge agent stream
+      agentStream.mergeIntoDataStream(dataStream);
+    },
+    onError: error => `Custom error: ${error.message}`,
+  });
+
+  return response
+}
+```
+
+

package/.docs/raw/frameworks/next-js.mdx

@@ -0,0 +1,238 @@
+---
+title: "Getting started with Mastra and NextJS | Mastra Guides"
+description: Guide on integrating Mastra with NextJS.
+---
+import { Callout, Steps, Tabs } from "nextra/components";
+
+# Integrate Mastra in your Next.js project
+
+There are two main ways to integrate Mastra with your Next.js application: as a separate backend service or directly integrated into your Next.js app.
+
+## 1. Separate Backend Integration
+
+Best for larger projects where you want to:
+- Scale your AI backend independently
+- Keep clear separation of concerns
+- Have more deployment flexibility
+
+<Steps>
+### Create Mastra Backend
+
+Create a new Mastra project using our CLI:
+
+<Tabs items={["npx", "npm", "yarn", "pnpm"]}>
+  <Tabs.Tab>
+```bash copy
+npx create-mastra@latest
+```
+  </Tabs.Tab>
+  <Tabs.Tab>
+```bash copy
+npm create mastra
+```
+  </Tabs.Tab>
+  <Tabs.Tab>
+```bash copy
+yarn create mastra
+```
+  </Tabs.Tab>
+  <Tabs.Tab>
+```bash copy
+pnpm create mastra
+```
+  </Tabs.Tab>
+</Tabs>
+
+For detailed setup instructions, see our [installation guide](/docs/getting-started/installation).
+
+### Install  MastraClient
+
+<Tabs items={["npm", "yarn", "pnpm"]}>
+  <Tabs.Tab>
+```bash copy
+npm install @mastra/client-js
+```
+  </Tabs.Tab>
+  <Tabs.Tab>
+```bash copy
+yarn add @mastra/client-js
+```
+  </Tabs.Tab>
+  <Tabs.Tab>
+```bash copy
+pnpm add @mastra/client-js
+```
+  </Tabs.Tab>
+</Tabs>
+
+### Use MastraClient
+
+Create a client instance and use it in your Next.js application:
+
+```typescript filename="lib/mastra.ts" copy
+import { MastraClient } from '@mastra/client-js';
+
+// Initialize the client
+export const mastraClient = new MastraClient({
+  baseUrl: process.env.NEXT_PUBLIC_MASTRA_API_URL || 'http://localhost:4111',
+});
+```
+
+Example usage in your React component:
+
+```typescript filename="app/components/SimpleWeather.tsx" copy
+'use client'
+
+import { mastraClient } from '@/lib/mastra'
+
+export function SimpleWeather() {
+  async function handleSubmit(formData: FormData) {
+    const city = formData.get('city')
+    const agent = mastraClient.getAgent('weatherAgent')
+    
+    try {
+      const response = await agent.generate({
+        messages: [{ role: 'user', content: `What's the weather like in ${city}?` }],
+      })
+      // Handle the response
+      console.log(response.text)
+    } catch (error) {
+      console.error('Error:', error)
+    }
+  }
+
+  return (
+    <form action={handleSubmit}>
+      <input name="city" placeholder="Enter city name" />
+      <button type="submit">Get Weather</button>
+    </form>
+  )
+}
+```
+
+### Deployment
+
+When you're ready to deploy, you can use any of our platform-specific deployers (Vercel, Netlify, Cloudflare) or deploy to any Node.js hosting platform. Check our [deployment guide](/docs/deployment/deployment) for detailed instructions.
+</Steps>
+
+## 2. Direct Integration
+
+Better for smaller projects or prototypes. This approach bundles Mastra directly with your Next.js application.
+
+<Steps>
+### Initialize Mastra in your Next.js Root
+
+First, navigate to your Next.js project root and initialize Mastra:
+
+```bash copy
+cd your-nextjs-app
+```
+
+Then run the initialization command:
+
+<Tabs items={["npm", "yarn", "pnpm"]}>
+  <Tabs.Tab>
+```bash copy
+npx mastra@latest init
+```
+  </Tabs.Tab>
+  <Tabs.Tab>
+```bash copy
+yarn dlx mastra@latest init
+```
+  </Tabs.Tab>
+  <Tabs.Tab>
+```bash copy
+pnpm dlx mastra@latest init
+```
+  </Tabs.Tab>
+</Tabs>
+
+This will set up Mastra in your Next.js project. For more details about init and other configuration options, see our [mastra init reference](/docs/reference/cli/init).
+
+### Configure Next.js
+
+Add to your `next.config.js`:
+
+```js filename="next.config.js" copy
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  serverExternalPackages: ["@mastra/*"],
+  // ... your other Next.js config
+}
+
+module.exports = nextConfig
+```
+
+#### Server Actions Example
+
+```typescript filename="app/actions.ts" copy
+'use server'
+
+import { mastra } from '@/mastra'
+
+export async function getWeatherInfo(city: string) {
+  const agent = mastra.getAgent('weatherAgent')
+  
+  const result = await agent.generate(`What's the weather like in ${city}?`)
+
+  return result
+}
+```
+
+Use it in your component:
+
+```typescript filename="app/components/Weather.tsx" copy
+'use client'
+
+import { getWeatherInfo } from '../actions'
+
+export function Weather() {
+  async function handleSubmit(formData: FormData) {
+    const city = formData.get('city') as string
+    const result = await getWeatherInfo(city)
+    // Handle the result
+    console.log(result)
+  }
+
+  return (
+    <form action={handleSubmit}>
+      <input name="city" placeholder="Enter city name" />
+      <button type="submit">Get Weather</button>
+    </form>
+  )
+}
+```
+
+#### API Routes Example
+
+```typescript filename="app/api/chat/route.ts" copy
+import { mastra } from '@/mastra'
+import { NextResponse } from 'next/server'
+
+export async function POST(req: Request) {
+  const { city } = await req.json()
+  const agent = mastra.getAgent('weatherAgent')
+
+  const result = await agent.stream(`What's the weather like in ${city}?`)
+
+  return result.toDataStreamResponse()
+}
+```
+
+### Deployment
+
+When using direct integration, your Mastra instance will be deployed alongside your Next.js application. Ensure you:
+- Set up environment variables for your LLM API keys in your deployment platform
+- Implement proper error handling for production use
+- Monitor your AI agent's performance and costs
+</Steps>
+
+## Observability
+
+Mastra provides built-in observability features to help you monitor, debug, and optimize your AI operations. This includes:
+- Tracing of AI operations and their performance
+- Logging of prompts, completions, and errors
+- Integration with observability platforms like Langfuse and LangSmith
+
+For detailed setup instructions and configuration options specific to Next.js local development, see our [Next.js Observability Configuration Guide](/docs/deployment/logging-and-tracing#nextjs-configuration).