@mastra/mcp-docs-server 0.0.0-commonjs-20250414101718

package/.docs/raw/evals/running-in-ci.mdx

@@ -0,0 +1,81 @@
+---
+title: "Running in CI"
+description: "Learn how to run Mastra evals in your CI/CD pipeline to monitor agent quality over time."
+---
+
+# Running Evals in CI
+
+Running evals in your CI pipeline helps bridge this gap by providing quantifiable metrics for measuring agent quality over time.
+
+## Setting Up CI Integration
+
+We support any testing framework that supports ESM modules. For example, you can use [Vitest](https://vitest.dev/), [Jest](https://jestjs.io/) or [Mocha](https://mochajs.org/) to run evals in your CI/CD pipeline.
+
+```typescript copy showLineNumbers filename="src/mastra/agents/index.test.ts"
+import { describe, it, expect } from 'vitest';
+import { evaluate } from "@mastra/evals";
+import { ToneConsistencyMetric } from "@mastra/evals/nlp";
+import { myAgent } from './index';
+
+describe('My Agent', () => {
+  it('should validate tone consistency', async () => {
+    const metric = new ToneConsistencyMetric();
+    const result = await evaluate(myAgent, 'Hello, world!', metric)
+
+    expect(result.score).toBe(1);
+  });
+});
+```
+
+You will need to configure a testSetup and globalSetup script for your testing framework to capture the eval results. It allows us to show these results in your mastra dashboard.
+
+## Framework Configuration
+
+### Vitest Setup
+
+Add these files to your project to run evals in your CI/CD pipeline:
+
+```typescript copy showLineNumbers filename="globalSetup.ts"
+import { globalSetup } from '@mastra/evals';
+
+export default function setup() {
+  globalSetup()
+}
+```
+
+```typescript copy showLineNumbers filename="testSetup.ts"
+import { beforeAll } from 'vitest';
+import { attachListeners } from '@mastra/evals';
+
+beforeAll(async () => {
+  await attachListeners();
+});
+```
+
+```typescript copy showLineNumbers filename="vitest.config.ts"
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    globalSetup: './globalSetup.ts',
+    setupFiles: ['./testSetup.ts'],
+  },
+})
+```
+
+## Storage Configuration
+
+To store eval results in Mastra Storage and capture results in the Mastra dashboard:
+
+```typescript copy showLineNumbers filename="testSetup.ts"
+import { beforeAll } from 'vitest';
+import { attachListeners } from '@mastra/evals';
+import { mastra } from './your-mastra-setup';
+
+beforeAll(async () => {
+  // Store evals in Mastra Storage (requires storage to be enabled)
+  await attachListeners(mastra);
+});
+```
+
+With file storage, evals persist and can be queried later. With memory storage, evals are isolated to the test process.

package/.docs/raw/evals/textual-evals.mdx

@@ -0,0 +1,54 @@
+---
+title: "Textual Evals"
+description: "Understand how Mastra uses LLM-as-judge methodology to evaluate text quality."
+---
+
+# Textual Evals
+
+Textual evals use an LLM-as-judge methodology to evaluate agent outputs. This approach leverages language models to assess various aspects of text quality, similar to how a teaching assistant might grade assignments using a rubric.
+
+Each eval focuses on specific quality aspects and returns a score between 0 and 1, providing quantifiable metrics for non-deterministic AI outputs.
+
+Mastra provides several eval metrics for assessing Agent outputs. Mastra is not limited to these metrics, and you can also [define your own evals](/docs/evals/custom-eval).
+
+## Why Use Textual Evals?
+
+Textual evals help ensure your agent:
+
+- Produces accurate and reliable responses
+- Uses context effectively
+- Follows output requirements
+- Maintains consistent quality over time
+
+## Available Metrics
+
+### Accuracy and Reliability
+
+These metrics evaluate how correct, truthful, and complete your agent's answers are:
+
+- [`hallucination`](/reference/evals/hallucination): Detects facts or claims not present in provided context
+- [`faithfulness`](/reference/evals/faithfulness): Measures how accurately responses represent provided context
+- [`content-similarity`](/reference/evals/content-similarity): Evaluates consistency of information across different phrasings
+- [`completeness`](/reference/evals/completeness): Checks if responses include all necessary information
+- [`answer-relevancy`](/reference/evals/answer-relevancy): Assesses how well responses address the original query
+- [`textual-difference`](/reference/evals/textual-difference): Measures textual differences between strings
+
+### Understanding Context
+
+These metrics evaluate how well your agent uses provided context:
+
+- [`context-position`](/reference/evals/context-position): Analyzes where context appears in responses
+- [`context-precision`](/reference/evals/context-precision): Evaluates whether context chunks are grouped logically
+- [`context-relevancy`](/reference/evals/context-relevancy): Measures use of appropriate context pieces
+- [`contextual-recall`](/reference/evals/contextual-recall): Assesses completeness of context usage
+
+### Output Quality
+
+These metrics evaluate adherence to format and style requirements:
+
+- [`tone`](/reference/evals/tone-consistency): Measures consistency in formality, complexity, and style
+- [`toxicity`](/reference/evals/toxicity): Detects harmful or inappropriate content
+- [`bias`](/reference/evals/bias): Detects potential biases in the output
+- [`prompt-alignment`](/reference/evals/prompt-alignment): Checks adherence to explicit instructions like length restrictions, formatting requirements, or other constraints
+- [`summarization`](/reference/evals/summarization): Evaluates information retention and conciseness
+- [`keyword-coverage`](/reference/evals/keyword-coverage): Assesses technical terminology usage

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
+}
+```
+
+