@mastra/mcp-docs-server 0.13.12-alpha.2 → 0.13.12-alpha.4

package/.docs/raw/frameworks/servers/express.mdx

@@ -3,7 +3,7 @@ title: "Getting started with Mastra and Express | Mastra Guides"
 description: A step-by-step guide to integrating Mastra with an Express backend.
 ---
 
-import { Callout, Steps, Tabs, FileTree } from "nextra/components";
+import { Callout } from "nextra/components";
 
 # Integrate Mastra in your Express project
 
@@ -13,153 +13,148 @@ Mastra integrates with Express, making it easy to:
 - Maintain full control over your server logic and routing
 - Scale your backend independently of your frontend
 
-Use this guide to scaffold and integrate Mastra with your Express project.
+Express can invoke Mastra directly so you don't need to run a Mastra server alongside your Express server.
 
-<Callout type="warning">
-This setup is compatible with the following package versions:
-- `express`: 4.x
-- `@types/express`: 4.x
+In this guide you'll learn how to install the necessary Mastra dependencies, create an example agent, and invoke Mastra from an Express API route.
 
-Type compatibility in 5.x can be inconsistent while `express` and `@types/express` evolve toward alignment.
+## Prerequisites
 
-</Callout>
+- An existing Express app set up with TypeScript
+- Node.js `v20.0` or higher
+- An API key from a supported [Model Provider](/docs/getting-started/model-providers)
+
+## Adding Mastra
 
-<Steps>
-## Install Mastra
-
-Install the required Mastra packages:
-
-<Tabs items={["npm", "yarn", "pnpm", "bun"]}>
-  <Tabs.Tab>
-    ```bash copy
-    npm install mastra@latest @mastra/core@latest @mastra/libsql@latest
-    ```
-  </Tabs.Tab>
-  <Tabs.Tab>
-    ```bash copy
-    yarn add mastra@latest @mastra/core@latest @mastra/libsql@latest
-    ```
-  </Tabs.Tab>
-  <Tabs.Tab>
-    ```bash copy
-    pnpm add mastra@latest @mastra/core@latest @mastra/libsql@latest
-    ```
-  </Tabs.Tab>
-  <Tabs.Tab>
-    ```bash copy
-    bun add mastra@latest @mastra/core@latest @mastra/libsql@latest
-    ```
-  </Tabs.Tab>
-</Tabs>
-
-## Integrate Mastra
-
-To integrate Mastra in your project, you have two options:
-
-### 1. Use the One-Liner
-
-Run the following command to quickly scaffold the default Weather agent with sensible defaults:
+First, install the necessary Mastra dependencies to run an Agent. This guide uses OpenAI as its model but you can use any supported [model provider](/docs/getting-started/model-providers).
 
 ```bash copy
-npx mastra@latest init --default
+npm install mastra@latest @mastra/core@latest @mastra/libsql@latest zod@^3.0.0 @ai-sdk/openai@^1.0.0
 ```
 
-> See [mastra init](/reference/cli/init) for more information.
-
-### 2. Use the Interactive CLI
-
-If you prefer to customize the setup, run the `init` command and choose from the options when prompted:
+If not existent yet, create an `.env` file and add your OpenAI API key:
 
-```bash copy
-npx mastra@latest init
+```bash filename=".env" copy
+OPENAI_API_KEY=<your-api-key>
 ```
 
-Add the `dev` and `build` scripts to `package.json`:
+<Callout>
+Each LLM provider uses a different env var. See [Model Capabilities](/docs/getting-started/model-capability) for more information.
+</Callout>
 
-```json filename="package.json"
-{
-  "scripts": {
-    ...
-    "dev": "mastra dev",
-    "build": "mastra build"
-  }
-}
-```
+Create a Mastra configuration file at `src/mastra/index.ts`:
 
-> If your project already uses `dev` and `build` scripts, we recommend using: `dev:mastra` and `build:mastra`.
+```ts filename="src/mastra/index.ts" copy
+import { Mastra } from '@mastra/core/mastra';
 
-## Initialize TypeScript
+export const mastra = new Mastra({});
+```
 
-Create a `tsconfig.json` file in your project root with the following configuration:
+Create a `weatherTool` that the `weatherAgent` will use at `src/mastra/tools/weather-tool.ts`. It returns a placeholder value inside the `execute()` function (you'd put your API calls in here).
+
+```ts filename="src/mastra/tools/weather-tool.ts" copy
+import { createTool } from "@mastra/core/tools";
+import { z } from "zod";
+ 
+export const weatherTool = createTool({
+  id: "get-weather",
+  description: "Get current weather for a location",
+  inputSchema: z.object({
+    location: z.string().describe("City name")
+  }),
+  outputSchema: z.object({
+    output: z.string()
+  }),
+  execute: async () => {
+    return {
+      output: "The weather is sunny"
+    };
+  }
+});
+```
 
-```json filename="tsconfig.json" copy
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "ES2022",
-    "moduleResolution": "bundler",
-    "esModuleInterop": true,
-    "forceConsistentCasingInFileNames": true,
-    "strict": true,
-    "skipLibCheck": true,
-    "outDir": "dist"
-  },
-  "include": ["src/**/*"],
-  "exclude": ["node_modules", "dist", ".mastra"]
-}
+Add a `weatherAgent` at `src/mastra/agents/weather-agent.ts`:
+
+```ts filename="src/mastra/agents/weather-agent.ts" copy
+import { openai } from "@ai-sdk/openai";
+import { Agent } from "@mastra/core/agent";
+import { weatherTool } from "../tools/weather-tool";
+ 
+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-mini'),
+  tools: { weatherTool }
+});
 ```
 
-> This TypeScript configuration is optimized for Mastra projects, using modern module resolution and strict type checking.
+Lastly, add the `weatherAgent` to `src/mastra/index.ts`:
 
-## Set Up API Key
+```ts filename="src/mastra/index.ts" copy {2, 5}
+import { Mastra } from '@mastra/core/mastra';
+import { weatherAgent } from './agents/weather-agent';
+
+export const mastra = new Mastra({
+  agents: { weatherAgent },
+});
 
-```bash filename=".env" copy
-OPENAI_API_KEY=<your-api-key>
 ```
 
-> Each llm provider uses a different env var. See [Model Capabilities](/docs/getting-started/model-capability) for more information.
+Now you're done with setting up the Mastra boilerplate code and are ready to integrate it into your Express routes.
 
-## Start the Mastra Dev Server
+## Using Mastra with Express
 
-Start the Mastra dev server to expose your agents as REST endpoints:
+Create an `/api/weather` endpoint that expects a `city` query parameter. The `city` parameter will be passed to the `weatherAgent` when asking it through a prompt.
 
-<Tabs items={["npm", "CLI"]}>
-  <Tabs.Tab>
-    ```bash copy
-    npm run dev
-    ```
-  </Tabs.Tab>
-  <Tabs.Tab>
-    ```bash copy
-    mastra dev
-    ```
-  </Tabs.Tab>
-</Tabs>
+You might have a file like this in your existing project:
 
-> Once running, your agents are available locally. See [Local Development Environment](/docs/server-db/local-dev-playground) for more information.
+```ts filename="src/server.ts" copy
+import express, { Request, Response } from 'express';
 
-## Example Express App
+const app = express();
+const port = 3456;
 
-This example creates an `/api/weather` endpoint that expects a `city` query parameter.
+app.get('/', (req: Request, res: Response) => {
+  res.send('Hello, world!');
+});
 
-```typescript filename="src/server.ts" showLineNumbers copy
-import "dotenv/config";
-import express, { Request, Response } from "express";
+app.listen(port, () => {
+  console.log(`Server is running at http://localhost:${port}`);
+});
+```
+
+Adding the `/api/weather` endpoint looks like this:
 
-import { mastra } from "./mastra";
+```ts filename="src/server.ts" copy {2, 11-27}
+import express, { Request, Response } from 'express';
+import { mastra } from "./mastra"
 
 const app = express();
-const port = process.env.PORT ?? 3000;
+const port = 3456;
+
+app.get('/', (req: Request, res: Response) => {
+  res.send('Hello, world!');
+});
 
 app.get("/api/weather", async (req: Request, res: Response) => {
   const { city } = req.query as { city?: string };
-
+ 
   if (!city) {
     return res.status(400).send("Missing 'city' query parameter");
   }
-
+ 
   const agent = mastra.getAgent("weatherAgent");
-
+ 
   try {
     const result = await agent.generate(`What's the weather like in ${city}?`);
     res.send(result.text);
@@ -170,47 +165,44 @@ app.get("/api/weather", async (req: Request, res: Response) => {
 });
 
 app.listen(port, () => {
-  console.log(`Server listening on port ${port}`);
+  console.log(`Server is running at http://localhost:${port}`);
 });
 ```
 
-With the Mastra dev server running, start your Express app separately. For example:
+By importing the `src/mastra/index.ts` file you can use methods like [`.getAgent()`](/reference/agents/getAgent) to get programmatic access. With [`.generate()`](/reference/agents/generate) you then can interact with the respective agent.
+
+<Callout>
+Read the [Agent reference docs](/reference/agents/agent) to learn more.
+</Callout>
+
+Start your Express server and visit the `/api/weather` endpoint. For example:
 
-```bash copy
-npx tsx --watch src/server.ts --watch-dir src
 ```
+http://localhost:3456/api/weather?city=London
+```
+
+You should get a response back similar to this:
 
-You can now make a request to the endpoint using one of the following:
-
-<Tabs items={["http", "curl"]}>
-  <Tabs.Tab>
-    ```bash copy
-    http://localhost:3000/api/weather?city=London
-    ```
-  </Tabs.Tab>
-  <Tabs.Tab>
-    ```bash copy
-    curl "http://localhost:3000/api/weather?city=London"
-    ```
-  </Tabs.Tab>
-</Tabs>
-
-You should see output similar to the below:
-
-```plaintext
-The current weather in London is as follows:
-
-- **Temperature:** 12.9°C (Feels like 9.7°C)
-- **Humidity:** 63%
-- **Wind Speed:** 14.7 km/h
-- **Wind Gusts:** 32.4 km/h
-- **Conditions:** Overcast
-
-Let me know if you need more information!
 ```
+The weather in London is currently sunny. If you need more details like humidity, wind conditions, or precipitation, just let me know!
+```
+
+## Running the Agent Server
 
-</Steps>
+In production it's not necessary to run Mastra alongside your Express server. But for development Mastra offers a [Local Development Environment](/docs/server-db/local-dev-playground) which you can use to improve and debug your agent.
 
-## Next Steps
+Add a script to your `package.json`:
 
-- [Mastra Client SDK](/docs/deployment/client)
+```json filename="package.json" copy
+{
+  "scripts": {
+    "mastra:dev": "mastra dev"
+  },
+}
+```
+
+Start the Mastra playground:
+
+```bash copy
+npm run mastra:dev
+```

package/.docs/raw/reference/agents/agent.mdx

@@ -80,7 +80,7 @@ export const agent = new Agent({
     },
     {
       name: "defaultVNextStreamOptions",
-      type: "AgentVNextStreamOptions | ({ runtimeContext: RuntimeContext }) => AgentVNextStreamOptions | Promise<AgentVNextStreamOptions>",
+      type: "AgentExecutionOptions | ({ runtimeContext: RuntimeContext }) => AgentExecutionOptions | Promise<AgentExecutionOptions>",
       isOptional: true,
       description: "Default options used when calling `stream()` in vNext mode.",
     },

package/.docs/raw/reference/agents/getDefaultVNextStreamOptions.mdx

@@ -33,7 +33,7 @@ await agent.getDefaultVNextStreamOptions();
   content={[
     {
       name: "defaultOptions",
-      type: "AgentVNextStreamOptions<Output, StructuredOutput> | Promise<AgentVNextStreamOptions<Output, StructuredOutput>>",
+      type: "AgentExecutionOptions<Output, StructuredOutput> | Promise<AgentExecutionOptions<Output, StructuredOutput>>",
       description: "The default vNext streaming options configured for the agent, either as a direct object or a promise that resolves to the options.",
     },
   ]}

package/.docs/raw/reference/agents/streamVNext.mdx

@@ -30,7 +30,7 @@ await agent.streamVNext("message for agent");
     },
     {
       name: "options",
-      type: "AgentVNextStreamOptions<Output, StructuredOutput>",
+      type: "AgentExecutionOptions<Output, StructuredOutput>",
       isOptional: true,
       description: "Optional configuration for the streaming process.",
     },

package/.docs/raw/reference/deployer/cloudflare.mdx

@@ -16,49 +16,40 @@ import { CloudflareDeployer } from "@mastra/deployer-cloudflare";
 export const mastra = new Mastra({
   // ...
   deployer: new CloudflareDeployer({
-    scope: "your-account-id",
-    projectName: "your-project-name",
+    projectName: "hello-mastra",
     routes: [
       {
         pattern: "example.com/*",
         zone_name: "example.com",
-        custom_domain: true,
-      },
+        custom_domain: true
+      }
     ],
-    workerNamespace: "your-namespace",
-    auth: {
-      apiToken: "your-api-token",
-      apiEmail: "your-email",
+    workerNamespace: "my-namespace",
+    env: {
+      NODE_ENV: "production",
+      API_KEY: "<api-key>"
     },
     d1Databases: [
       {
-        binding: "binding-name",
-        database_name: "database-name",
-        database_id: "database-id",
-      },
+        binding: "DB",
+        database_name: "my-database",
+        database_id: "d1-database-id",
+        preview_database_id: "your-preview-database-id"
+      }
     ],
     kvNamespaces: [
       {
-        binding: "binding-name",
-        id: "namespace-id",
-      },
-    ],
-  }),
+        binding: "CACHE",
+        id: "kv-namespace-id"
+      }
+    ]
 });
 ```
 
 ## Parameters
 
-### Constructor Parameters
-
 <PropertiesTable
   content={[
-    {
-      name: "scope",
-      type: "string",
-      description: "Your Cloudflare account ID.",
-      isOptional: false,
-    },
     {
       name: "projectName",
       type: "string",
@@ -69,7 +60,7 @@ export const mastra = new Mastra({
     {
       name: "routes",
       type: "CFRoute[]",
-      description: "Array of route configurations for your worker.",
+      description: "Array of route configurations for your worker. Each route requires: pattern (string), zone_name (string), custom_domain (boolean, optional).",
       isOptional: true,
     },
     {
@@ -81,122 +72,20 @@ export const mastra = new Mastra({
     {
       name: "env",
       type: "Record<string, any>",
-      description:
-        "Environment variables to be included in the worker configuration.",
+      description: "Environment variables to be included in the worker configuration.",
       isOptional: true,
     },
-    {
-      name: "auth",
-      type: "object",
-      description: "Cloudflare authentication details.",
-      isOptional: false,
-    },
     {
       name: "d1Databases",
       type: "D1DatabaseBinding[]",
-      description: "Array of D1 database bindings for your worker.",
+      description: "Array of D1 database bindings. Each binding requires: binding (string), database_name (string), database_id (string), preview_database_id (string, optional).",
       isOptional: true,
     },
     {
       name: "kvNamespaces",
       type: "KVNamespaceBinding[]",
-      description: "Array of KV namespace bindings for your worker.",
-      isOptional: true,
-    },
-  ]}
-/>
-
-### auth Object
-
-<PropertiesTable
-  content={[
-    {
-      name: "apiToken",
-      type: "string",
-      description: "Your Cloudflare API token.",
-      isOptional: false,
-    },
-    {
-      name: "apiEmail",
-      type: "string",
-      description: "Your Cloudflare account email.",
-      isOptional: true,
-    },
-  ]}
-/>
-
-### CFRoute Object
-
-<PropertiesTable
-  content={[
-    {
-      name: "pattern",
-      type: "string",
-      description: "URL pattern to match (e.g., 'example.com/*').",
-      isOptional: false,
-    },
-    {
-      name: "zone_name",
-      type: "string",
-      description: "Domain zone name.",
-      isOptional: false,
-    },
-    {
-      name: "custom_domain",
-      type: "boolean",
-      description: "Whether to use a custom domain.",
+      description: "Array of KV namespace bindings. Each binding requires: binding (string), id (string).",
       isOptional: true,
-      defaultValue: "false",
-    },
-  ]}
-/>
-
-### D1DatabaseBinding Object
-
-<PropertiesTable
-  content={[
-    {
-      name: "binding",
-      type: "string",
-      description: "Name used in Worker code (e.g., `env.testdb`).",
-      isOptional: false,
-    },
-    {
-      name: "database_name",
-      type: "string",
-      description: "Human-readable name (for dashboard).",
-      isOptional: false,
-    },
-    {
-      name: "database_id",
-      type: "string",
-      description: "Cloudflare D1 database ID.",
-      isOptional: false,
-    },
-    {
-      name: "preview_database_id",
-      type: "string",
-      description: "For preview deployments.",
-      isOptional: true,
-    },
-  ]}
-/>
-
-### KVNamespaceBinding Object
-
-<PropertiesTable
-  content={[
-    {
-      name: "binding",
-      type: "string",
-      description: "Name used in Worker code (e.g., `env.test_namespace`).",
-      isOptional: false,
-    },
-    {
-      name: "id",
-      type: "string",
-      description: "Cloudflare KV namespace ID.",
-      isOptional: false,
     },
   ]}
 />

package/.docs/raw/reference/memory/Memory.mdx

@@ -291,7 +291,7 @@ Mastra supports many embedding models through the [Vercel AI SDK](https://sdk.ve
     },
     {
       name: "threads",
-      type: "{ generateTitle?: boolean | { model: LanguageModelV1 | ((ctx: RuntimeContext) => LanguageModelV1 | Promise<LanguageModelV1>), instructions?: string | ((ctx: RuntimeContext) => string | Promise<string>) } }",
+      type: "{ generateTitle?: boolean | { model: MastraLanguageModel | ((ctx: RuntimeContext) => MastraLanguageModel | Promise<MastraLanguageModel>), instructions?: string | ((ctx: RuntimeContext) => string | Promise<string>) } }",
       description:
         "Settings related to memory thread creation. `generateTitle` controls automatic thread title generation from the user's first message. Can be a boolean to enable/disable using the agent's model, or an object specifying a custom model or custom instructions for title generation (useful for cost optimization or title customization). Example: { generateTitle: { model: openai('gpt-4.1-nano'), instructions: 'Concise title based on the initial user message.' } }",
       isOptional: true,