@mastra/mcp-docs-server 1.0.0-beta.9 → 1.0.0

package/.docs/raw/course/02-agent-tools-mcp/16-updating-agent-instructions-github.md

@@ -22,7 +22,7 @@ export const personalAssistantAgent = new Agent({
     
     Keep your responses concise and friendly.
   `,
-  model: openai("gpt-4o"),
+  model: "openai/gpt-4.1-mini",
   tools: { ...mcpTools },
   memory,
 });

package/.docs/raw/course/02-agent-tools-mcp/21-updating-agent-instructions-hackernews.md

@@ -27,7 +27,7 @@ export const personalAssistantAgent = new Agent({
     
     Keep your responses concise and friendly.
   `,
-  model: openai("gpt-4o"),
+  model: "openai/gpt-4.1-mini",
   tools: { ...mcpTools },
   memory,
 });

package/.docs/raw/course/02-agent-tools-mcp/27-updating-agent-instructions-filesystem.md

@@ -34,7 +34,7 @@ export const personalAssistantAgent = new Agent({
     
     Keep your responses concise and friendly.
   `,
-  model: openai("gpt-4o"),
+  model: "openai/gpt-4.1-mini",
   tools: { ...mcpTools },
   memory,
 });

package/.docs/raw/course/02-agent-tools-mcp/31-enhancing-memory-configuration.md

@@ -12,9 +12,9 @@ const memory = new Memory({
   }),
   vector: new LibSQLVector({
     id: "learning-memory-vector",
-    connectionUrl: "file:../../memory.db",
+    url: "file:../../memory.db",
   }),
-  embedder: openai.embedding("text-embedding-3-small"),
+  embedder: "openai/text-embedding-3-small",
   options: {
     // Keep last 20 messages in context
     lastMessages: 20,
@@ -61,7 +61,7 @@ export const personalAssistantAgent = new Agent({
     Always maintain a helpful and professional tone.
     Use the stored information to provide more personalized responses.
   `,
-  model: openai("gpt-4o"),
+  model: "openai/gpt-4.1-mini",
   tools: { ...mcpTools },
   memory,
 });

package/.docs/raw/course/03-agent-memory/04-creating-basic-memory-agent.md

@@ -8,7 +8,6 @@ Create or update your `src/mastra/agents/index.ts` file:
 import { Agent } from "@mastra/core/agent";
 import { Memory } from "@mastra/memory";
 import { LibSQLStore } from "@mastra/libsql";
-import { openai } from "@ai-sdk/openai";
 
 // Create a basic memory instance
 const memory = new Memory({
@@ -27,7 +26,7 @@ export const memoryAgent = new Agent({
     When a user shares information about themselves, acknowledge it and remember it for future reference.
     If asked about something mentioned earlier in the conversation, recall it accurately.
   `,
-  model: openai("gpt-4o"), // You can use "gpt-3.5-turbo" if you prefer
+  model: "openai/gpt-4.1-mini",
   memory: memory,
 });
 ```

package/.docs/raw/course/03-agent-memory/07-understanding-memory-threads.md

@@ -12,3 +12,38 @@ Mastra organizes memory into threads, which are records that identify specific c
 These identifiers allow memory to work properly outside of the playground. They help Mastra distinguish between different conversations and users, ensuring that the right memory is associated with the right conversation.
 
 Without these identifiers, your agent would have no way to know which conversation history to retrieve when a user sends a message. The playground handles these identifiers automatically, but you'll need to manage them yourself when using memory in your own applications.
+
+## Thread ID and Resource ID Relationship
+
+**Important:** Each thread has an owner (its `resourceId`) that is set when the thread is created. Once created, a thread's owner cannot be changed.
+
+The relationship works like this:
+
+- **One thread → One owner** (each thread has exactly one `resourceId` that identifies its owner)
+- **One resource → Many threads** (a user can have multiple separate conversations)
+- **One thread → Messages with different resourceIds** (messages can have varying `resourceId` values for attribution and filtering purposes)
+
+### Common Pitfall: Thread ID Reuse
+
+If you create a thread with `threadId: "abc"` and `resourceId: "user-alice"`, you cannot later query or create another thread with `threadId: "abc"` but `resourceId: "user-bob"`. This will cause an error:
+
+```text
+Thread with id <thread_id> is for resource with id <resource_a>
+but resource <resource_b> was queried
+```
+
+This error means you're trying to access a thread with the wrong owner's ID. Thread IDs are database primary keys and must be globally unique - you cannot reuse the same thread ID for different thread owners.
+
+### Generating Thread IDs
+
+The safest approach is to use UUIDs to avoid accidentally reusing thread IDs:
+
+```typescript
+// Using UUIDs (recommended)
+const threadId = crypto.randomUUID(); // "550e8400-e29b-41d4-a716-446655440000"
+
+// Or combine resource ID with a unique suffix
+const threadId = `${resourceId}_${Date.now()}`; // "user_alice_1737907200000"
+```
+
+Avoid reusing simple identifiers like `"conversation_1"` for threads owned by different users, as this creates confusion about thread ownership.

package/.docs/raw/course/03-agent-memory/08-configuring-conversation-history.md

@@ -5,7 +5,6 @@ By default, the `Memory` instance includes the last 10 messages from the current
 ```typescript
 import { Agent } from "@mastra/core/agent";
 import { Memory } from "@mastra/memory";
-import { openai } from "@ai-sdk/openai";
 import { LibSQLStore } from "@mastra/libsql";
 
 // Create a memory instance with custom conversation history settings
@@ -27,7 +26,7 @@ export const memoryAgent = new Agent({
     When a user shares information about themselves, acknowledge it and remember it for future reference.
     If asked about something mentioned earlier in the conversation, recall it accurately.
   `,
-  model: openai("gpt-4o"),
+  model: "openai/gpt-4.1-mini",
   memory: memory,
 });
 ```

package/.docs/raw/course/03-agent-memory/13-vector-store-configuration.md

@@ -13,7 +13,7 @@ const memory = new Memory({
   }),
   vector: new LibSQLVector({
     id: "learning-memory-vector",
-    connectionUrl: "file:../../vector.db", // relative path from the `.mastra/output` directory
+    url: "file:../../vector.db", // relative path from the `.mastra/output` directory
   }),
 });
 ```

package/.docs/raw/course/03-agent-memory/16-configuring-semantic-recall.md

@@ -5,7 +5,6 @@ Let's update our agent with custom semantic recall settings:
 ```typescript
 import { Agent } from "@mastra/core/agent";
 import { Memory } from "@mastra/memory";
-import { openai } from "@ai-sdk/openai";
 import { LibSQLStore, LibSQLVector } from "@mastra/libsql";
 
 // Create a memory instance with semantic recall configuration
@@ -16,9 +15,9 @@ const memory = new Memory({
   }), // Storage for message history
   vector: new LibSQLVector({
     id: "learning-memory-vector",
-    connectionUrl: "file:../../vector.db", // relative path from the `.mastra/output` directory
+    url: "file:../../vector.db", // relative path from the `.mastra/output` directory
   }), // Vector database for semantic search
-  embedder: openai.embedding("text-embedding-3-small"), // Embedder for message embeddings
+  embedder: "openai/text-embedding-3-small", // Embedder for message embeddings
   options: {
     lastMessages: 20, // Include the last 20 messages in the context
     semanticRecall: true, // Enable semantic recall with default settings
@@ -35,9 +34,9 @@ export const memoryAgent = new Agent({
     If asked about something mentioned earlier in the conversation, recall it accurately.
     You can also recall relevant information from older conversations when appropriate.
   `,
-  model: openai("gpt-4o"),
+  model: "openai/gpt-4.1-mini",
   memory: memory,
 });
 ```
 
-For semantic recall to work, you need to have a **vector store** configured. You also need to have an **embedder** configured. You may use any `@ai-sdk`-compatible embedding model for this. In this example, we're using OpenAI's `text-embedding-3-small` model.
+For semantic recall to work, you need to have a **vector store** configured. You also need to have an **embedder** configured. You may use any compatible embedding model for this. In this example, we're using OpenAI's `openai/text-embedding-3-small` model.

package/.docs/raw/course/03-agent-memory/18-advanced-configuration-semantic-recall.md

@@ -9,7 +9,7 @@ const memory = new Memory({
     url: "file:../../memory.db", // relative path from the `.mastra/output` directory
   }),
   vector: new LibSQLVector({
-    connectionUrl: "file:../../vector.db", // relative path from the `.mastra/output` directory
+    url: "file:../../vector.db", // relative path from the `.mastra/output` directory
   }),
   embedder: openai.embedding("text-embedding-3-small"),
   options: {

package/.docs/raw/course/03-agent-memory/21-configuring-working-memory.md

@@ -5,7 +5,6 @@ Let's update our agent with working memory capabilities:
 ```typescript
 import { Agent } from "@mastra/core/agent";
 import { Memory } from "@mastra/memory";
-import { openai } from "@ai-sdk/openai";
 import { LibSQLStore, LibSQLVector } from "@mastra/libsql";
 
 // Create a memory instance with working memory configuration
@@ -16,9 +15,9 @@ const memory = new Memory({
   }), // Storage for message history
   vector: new LibSQLVector({
     id: "learning-memory-vector",
-    connectionUrl: "file:../../vector.db", // relative path from the `.mastra/output` directory
+    url: "file:../../vector.db", // relative path from the `.mastra/output` directory
   }), // Vector database for semantic search
-  embedder: openai.embedding("text-embedding-3-small"), // Embedder for message embeddings
+  embedder: "openai/text-embedding-3-small", // Embedder for message embeddings
   options: {
     semanticRecall: {
       topK: 3,
@@ -52,7 +51,7 @@ export const memoryAgent = new Agent({
     Always refer to your working memory before asking for information the user has already provided.
     Use the information in your working memory to provide personalized responses.
   `,
-  model: openai("gpt-4o"),
+  model: "openai/gpt-4.1-mini",
   memory: memory,
 });
 ```

package/.docs/raw/course/03-agent-memory/22-custom-working-memory-templates.md

@@ -7,7 +7,6 @@ Let's update our agent with a custom working memory template:
 ```typescript
 import { Agent } from "@mastra/core/agent";
 import { Memory } from "@mastra/memory";
-import { openai } from "@ai-sdk/openai";
 
 // Create a memory instance with a custom working memory template
 const memory = new Memory({
@@ -16,9 +15,9 @@ const memory = new Memory({
     url: "file:../../memory.db", // relative path from the `.mastra/output` directory
   }), // Storage for message history
   vector: new LibSQLVector({
-    connectionUrl: "file:../../vector.db", // relative path from the `.mastra/output` directory
+    url: "file:../../vector.db", // relative path from the `.mastra/output` directory
   }), // Vector database for semantic search
-  embedder: openai.embedding("text-embedding-3-small"), // Embedder for message embeddings
+  embedder: "openai/text-embedding-3-small", // Embedder for message embeddings
   options: {
     semanticRecall: {
       topK: 3,
@@ -74,7 +73,7 @@ export const memoryAgent = new Agent({
     When the user shares personal information such as their name, location, or preferences,
     acknowledge it and update your working memory accordingly.
   `,
-  model: openai("gpt-4o"),
+  model: "openai/gpt-4.1-mini",
   memory: memory,
 });
 ```

package/.docs/raw/course/03-agent-memory/25-combining-memory-features.md

@@ -10,7 +10,6 @@ Let's create a comprehensive agent that utilizes conversation history, semantic
 // src/mastra/agents/memory-agent.ts
 import { Agent } from "@mastra/core/agent";
 import { Memory } from "@mastra/memory";
-import { openai } from "@ai-sdk/openai";
 import { LibSQLStore, LibSQLVector } from "@mastra/libsql";
 
 // Create a comprehensive memory configuration
@@ -20,9 +19,9 @@ const memory = new Memory({
     url: "file:../../memory.db", // relative path from the `.mastra/output` directory
   }),
   vector: new LibSQLVector({
-    connectionUrl: "file:../../vector.db", // relative path from the `.mastra/output` directory
+    url: "file:../../vector.db", // relative path from the `.mastra/output` directory
   }),
-  embedder: openai.embedding("text-embedding-3-small"),
+  embedder: "openai/text-embedding-3-small",
   options: {
     // Conversation history configuration
     lastMessages: 20, // Include the last 20 messages in the context
@@ -78,4 +77,4 @@ This comprehensive memory configuration combines all three memory features we've
 2. **Semantic recall** with the `semanticRecall` option
 3. **Working memory** with the `workingMemory` option
 
-Each feature serves a different purpose in enhancing your agent's memory capabilities, and together they create a powerful memory system that can maintain context across conversations and provide personalized responses.
+Each feature serves a different purpose in enhancing your agent's memory capabilities, and together they create a memory system that maintains context across conversations and provides personalized responses.

package/.docs/raw/course/03-agent-memory/27-creating-learning-assistant.md

@@ -6,7 +6,6 @@ Let's create a practical example of a memory-enhanced agent: a Personal Learning
 // src/mastra/agents/learning-assistant.ts
 import { Agent } from "@mastra/core/agent";
 import { Memory } from "@mastra/memory";
-import { openai } from "@ai-sdk/openai";
 import { LibSQLStore, LibSQLVector } from "@mastra/libsql";
 
 // Create a specialized memory configuration for the learning assistant
@@ -16,9 +15,9 @@ const learningMemory = new Memory({
     url: "file:../../memory.db", // relative path from the `.mastra/output` directory
   }),
   vector: new LibSQLVector({
-    connectionUrl: "file:../../vector.db", // relative path from the `.mastra/output` directory
+    url: "file:../../vector.db", // relative path from the `.mastra/output` directory
   }),
-  embedder: openai.embedding("text-embedding-3-small"),
+  embedder: "openai/text-embedding-3-small",
   options: {
     lastMessages: 20,
     semanticRecall: {
@@ -88,7 +87,7 @@ export const learningAssistantAgent = new Agent({
     Always be encouraging and supportive. Focus on building the user's confidence
     and celebrating their progress.
   `,
-  model: openai("gpt-4o"),
+  model: "openai/gpt-4.1-mini",
   memory: learningMemory,
 });
 

package/.docs/raw/course/04-workflows/11-creating-an-ai-agent.md

@@ -8,7 +8,6 @@ Create a new file for your agent in the `src/mastra/agents` directory. Use `cont
 
 ```typescript
 // src/mastra/agents/content-agent.ts
-import { openai } from "@ai-sdk/openai";
 import { Agent } from "@mastra/core/agent";
 
 export const contentAgent = new Agent({
@@ -23,7 +22,7 @@ export const contentAgent = new Agent({
     
     Always provide constructive, actionable feedback.
   `,
-  model: openai("gpt-4o-mini"),
+  model: "openai/gpt-4.1-mini",
 });
 ```
 
@@ -32,7 +31,7 @@ export const contentAgent = new Agent({
 - **Name**: Unique identifier for the agent
 - **Description**: What the agent does
 - **Instructions**: Detailed prompts that guide the AI's behavior
-- **Model**: Which AI model to use (GPT-4o-mini is fast and cost-effective)
+- **Model**: Which AI model to use (GPT-4.1-mini is fast and cost-effective)
 
 ## Registering and Testing Your Agent
 

package/.docs/raw/deployment/cloud-providers.mdx

@@ -0,0 +1,22 @@
+---
+title: "Deploy to Cloud Providers | Deployment"
+description: Deploy your Mastra applications to cloud providers
+packages:
+  - "@mastra/deployer"
+---
+
+# Deploy to Cloud Providers
+
+Mastra applications can be deployed to cloud providers and serverless platforms. Mastra includes optional built-in deployers for Vercel, Netlify, and Cloudflare to automate the deployment process.
+
+## Supported Cloud Providers
+
+The following guides show how to deploy Mastra to specific cloud providers:
+
+- [Amazon EC2](/guides/v1/deployment/amazon-ec2)
+- [AWS Lambda](/guides/v1/deployment/aws-lambda)
+- [Azure App Services](/guides/v1/deployment/azure-app-services)
+- [Cloudflare](/guides/v1/deployment/cloudflare-deployer)
+- [Digital Ocean](/guides/v1/deployment/digital-ocean)
+- [Netlify](/guides/v1/deployment/netlify-deployer)
+- [Vercel](/guides/v1/deployment/vercel-deployer)

package/.docs/raw/deployment/mastra-server.mdx

@@ -0,0 +1,140 @@
+---
+title: "Deploy a Mastra Server | Deployment"
+description: "Learn how to build and deploy a Mastra server."
+packages:
+  - "@mastra/deployer"
+---
+
+# Deploy a Mastra Server
+
+Mastra compiles your application into a standalone Node.js server that can run on any platform supporting Node.js, Bun, or Deno.
+
+:::tip
+
+This guide covers deploying the standalone server generated by `mastra build`. If you need to integrate Mastra into an existing Express or Hono application, see [Server Adapters](/docs/v1/server/server-adapters) instead.
+
+:::
+
+## Building your application
+
+Run the build command from your project root:
+
+```bash
+mastra build
+```
+
+This creates a `.mastra` directory containing your production-ready server.
+
+:::info
+
+Read the [`mastra build`](/reference/v1/cli/mastra#mastra-build) reference for all available flags.
+
+:::
+
+## Build output
+
+After building, Mastra creates the following structure:
+
+```
+.mastra/
+├── .build/                # Intermediate build artifacts (module maps, analysis)
+└── output/
+    ├── index.mjs          # Server entry point
+    ├── mastra.mjs         # Your bundled Mastra configuration
+    ├── tools.mjs          # Aggregated tool exports
+    ├── tools/             # Individual tool bundles
+    ├── package.json       # Production dependencies
+    ├── node_modules/      # Installed dependencies
+    ├── .npmrc             # Copied from your project (if present)
+    ├── public/            # Static assets (if src/mastra/public exists)
+    └── playground/        # Studio UI (if --studio flag used)
+```
+
+The `output` directory is self-contained. You can copy it to any server and run it directly.
+
+## Running the server
+
+Start the server using the Mastra CLI:
+
+```bash
+mastra start
+```
+
+Or run directly with Node.js:
+
+```bash
+node .mastra/output/index.mjs
+```
+
+The `mastra start` command provides additional features:
+- Loads environment variables from `.env.production` and `.env`
+- Provides helpful error messages for missing modules
+- Handles process signals for graceful shutdown
+
+:::info
+
+Read the [`mastra start`](/reference/v1/cli/mastra#mastra-start) reference for all available flags.
+
+:::
+
+## Build configuration
+
+### Public folder
+
+If a `public` folder exists in your Mastra directory (`src/mastra/public`), its contents are copied to the output directory during build. These files are served as static assets by the server.
+
+### Mastra configuration
+
+The build process respects configuration in your Mastra instance. For server behavior like CORS, timeouts, and middleware, see [server overview](/docs/v1/server/mastra-server). For all available options, see the [configuration reference](/reference/v1/configuration).
+
+## Build process
+
+The build follows these steps:
+
+1. **Locates entry file**: Finds `index.ts` or `index.js` in your Mastra directory.
+2. **Discovers tools**: Scans for tool files matching `{mastraDir}/tools/**/*.{js,ts}`, excluding test files.
+3. **Analyzes dependencies**: Determines which packages to bundle vs. install externally.
+4. **Bundles code**: Uses Rollup with tree-shaking and optional source maps.
+5. **Generates server**: Creates a Hono-based HTTP server as `index.mjs`.
+6. **Installs dependencies**: Runs `npm install` in the output directory.
+7. **Copies assets**: Copies `public` folder and `.npmrc` if present.
+
+## Environment variables
+
+| Variable | Description |
+|----------|-------------|
+| `PORT` | Server port (default: `4111`) |
+| `MASTRA_STUDIO_PATH` | Path to Studio build directory (default: `./playground`) |
+| `MASTRA_SKIP_DOTENV` | Skip loading `.env` files when set |
+| `NODE_OPTIONS` | Node.js options (e.g., `--max-old-space-size=4096` for build memory issues) |
+
+## Server endpoints
+
+The built server exposes endpoints for health checks, agents, workflows, and more:
+
+| Endpoint | Description |
+|----------|-------------|
+| `GET /health` | Health check endpoint, returns `200 OK` |
+| `GET /openapi.json` | OpenAPI specification (if `server.build.openAPIDocs` is enabled) |
+| `GET /swagger-ui` | Interactive API documentation (if `server.build.swaggerUI` is enabled) |
+
+This list is not exhaustive. To view all endpoints, run `mastra dev` and visit `http://localhost:4111/swagger-ui`.
+
+To add your own endpoints, see [Custom API Routes](/docs/v1/server/custom-api-routes).
+
+## Troubleshooting
+
+### Memory errors during build
+
+If you encounter `JavaScript heap out of memory` errors:
+
+```bash
+NODE_OPTIONS="--max-old-space-size=4096" mastra build
+```
+
+## Related
+
+- [Server Overview](/docs/v1/server/mastra-server) - Configure server behavior, middleware, and authentication
+- [Server Adapters](/docs/v1/server/server-adapters) - Use Express or Hono instead of `mastra build`
+- [Custom API Routes](/docs/v1/server/custom-api-routes) - Add custom HTTP endpoints
+- [Configuration Reference](/reference/v1/configuration) - Full configuration options