@mastra/mcp-docs-server 0.13.37 → 0.13.38

package/.docs/raw/frameworks/web-frameworks/astro.mdx

@@ -1,9 +1,12 @@
 ---
-title: "Getting Started with Mastra and Astro | Mastra Guides"
+title: "Integrate Mastra in your Astro project | Frameworks | Mastra Docs"
 description: A step-by-step guide to integrating Mastra with Astro.
 ---
 
-import { Callout, Steps, Tabs } from "nextra/components";
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+import Steps from "@site/src/components/Steps";
+import StepItem from "@site/src/components/StepItem";
 
 # Integrate Mastra in your Astro project
 
@@ -15,72 +18,79 @@ Mastra integrates with Astro, making it easy to:
 
 Use this guide to scaffold and integrate Mastra with your Astro project.
 
-<Tabs items={["Actions", "Server Endpoints"]}>
-  <Tabs.Tab>
+<Tabs>
+  <TabItem value="actions" label="Actions">
 
-<Callout type="warning">
-  This guide assumes you're using Astro's Actions with React and the Vercel adapter.
-</Callout>
+:::warning
+
+This guide assumes you're using Astro's Actions with React and the Vercel adapter.
+
+:::
 
   <Steps>
-## Install Mastra
 
-Install the required Mastra packages:
-{/*
-LLM CONTEXT: This Tabs component shows commands for integrating a new Mastra backend project using different package managers.
-Each tab displays the command for that specific package manager to create an integrated Mastra backend service.
-This is part of the "Integrated Backend Integration" approach for Astro projects.
-All commands create the same Mastra project but use different package manager syntax.
-*/}
-
-<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>
+<StepItem>
 
-## Integrate Mastra
+Install the required Mastra packages:
 
-To integrate Mastra into your project, you have two options:
+<Tabs>
+<TabItem value="npm" label="npm">
 
-### 1. Use the One-Liner
+```bash copy
+npm install mastra@latest @mastra/core@latest @mastra/libsql@latest
+```
 
-Run the following command to quickly scaffold the default Weather agent with sensible defaults:
+</TabItem>
+<TabItem value="yarn" label="yarn">
 
 ```bash copy
-npx mastra@latest init --default
+yarn add mastra@latest @mastra/core@latest @mastra/libsql@latest
 ```
 
-> See [mastra init](/reference/cli/init) for more information.
+</TabItem>
+<TabItem value="pnpm" label="pnpm">
 
-### 2. Use the Interactive CLI
+```bash copy
+pnpm add mastra@latest @mastra/core@latest @mastra/libsql@latest
+```
 
-If you prefer to customize the setup, run the `init` command and choose from the options when prompted:
+</TabItem>
+<TabItem value="bun" label="bun">
 
 ```bash copy
-npx mastra@latest init
+bun add mastra@latest @mastra/core@latest @mastra/libsql@latest
 ```
 
+</TabItem>
+</Tabs>
+
+</StepItem>
+
+<StepItem>
+
+To integrate Mastra into your project, you have two options:
+
+- Use the One-Liner
+
+  Run the following command to quickly scaffold the default Weather agent with sensible defaults:
+
+  ```bash copy
+  npx mastra@latest init --default
+  ```
+
+  > See [mastra init](/reference/cli/create-mastra) for more information.
+
+- Use the Interactive CLI
+
+  If you prefer to customize the setup, run the `init` command and choose from the options when prompted:
+
+  ```bash copy
+  npx mastra@latest init
+  ```
+
 Add the `dev` and `build` scripts to `package.json`:
 
-```json filename="package.json"
+```json title="package.json"
 {
   "scripts": {
     ...
@@ -90,37 +100,47 @@ Add the `dev` and `build` scripts to `package.json`:
 }
 ```
 
-## Configure TypeScript
+</StepItem>
+
+<StepItem>
 
 Modify the `tsconfig.json` file in your project root:
 
-```json filename="tsconfig.json"
+```json title="tsconfig.json"
 {
   ...
   "exclude": ["dist", ".mastra"]
 }
 ```
 
-## Set Up API Key
+</StepItem>
 
-```bash filename=".env" copy
+<StepItem>
+
+Setup your API key in a `.env` file:
+
+```bash title=".env" copy
 OPENAI_API_KEY=<your-api-key>
 ```
 
-## Update .gitignore
+</StepItem>
+
+<StepItem>
 
 Add `.mastra` and `.vercel` to your `.gitignore` file:
 
-```bash filename=".gitignore" copy
+```bash title=".gitignore" copy
 .mastra
 .vercel
 ```
 
-## Update the Mastra Agent
+</StepItem>
+
+<StepItem>
 
 Astro uses Vite, which accesses environment variables via `import.meta.env` rather than `process.env`. As a result, the model constructor must explicitly receive the `apiKey` from the Vite environment like this:
 
-```diff filename="src/mastra/agents/weather-agent.ts"
+```diff title="src/mastra/agents/weather-agent.ts"
 - import { openai } from "@ai-sdk/openai";
 + import { createOpenAI } from "@ai-sdk/openai";
 
@@ -132,36 +152,50 @@ Astro uses Vite, which accesses environment variables via `import.meta.env` rath
 
 > More configuration details are available in the AI SDK docs. See [Provider Instance](https://ai-sdk.dev/providers/ai-sdk-providers/openai#provider-instance) for more information.
 
-## Start the Mastra Dev Server
+</StepItem>
+
+<StepItem>
 
 Start the Mastra Dev Server to expose your agents as REST endpoints:
 
-<Tabs items={["npm", "CLI"]}>
-  <Tabs.Tab>
-    ```bash copy
-    npm run dev:mastra
-    ```
-  </Tabs.Tab>
-  <Tabs.Tab>
-    ```bash copy
-    mastra dev:mastra
-    ```
-  </Tabs.Tab>
+<Tabs>
+<TabItem value="npm" label="npm">
+
+```bash copy
+npm run dev:mastra
+```
+
+</TabItem>
+<TabItem value="cli" label="CLI">
+
+```bash copy
+mastra dev:mastra
+```
+
+</TabItem>
 </Tabs>
 
-> Once running, your agents are available locally. See [Local Development Environment](/docs/server-db/local-dev-playground) for more information.
+> Once running, your agents are available locally. See [Local Development Environment](/docs/getting-started/studio) for more information.
+
+</StepItem>
 
-## Start Astro Dev Server
+<StepItem>
 
 With the Mastra Dev Server running, you can start your Astro site in the usual way.
 
-## Create Actions Directory
+</StepItem>
+
+<StepItem>
+
+Create an `actions` directory:
 
 ```bash copy
 mkdir src/actions
 ```
 
-### Create Test Action
+</StepItem>
+
+<StepItem>
 
 Create a new Action, and add the example code:
 
@@ -169,7 +203,7 @@ Create a new Action, and add the example code:
 touch src/actions/index.ts
 ```
 
-```typescript filename="src/actions/index.ts" showLineNumbers copy
+```typescript title="src/actions/index.ts" showLineNumbers copy
 import { defineAction } from "astro:actions";
 import { z } from "astro:schema";
 
@@ -178,21 +212,25 @@ import { mastra } from "../mastra";
 export const server = {
   getWeatherInfo: defineAction({
     input: z.object({
-      city: z.string()
+      city: z.string(),
     }),
     handler: async (input) => {
       const city = input.city;
       const agent = mastra.getAgent("weatherAgent");
 
-      const result = await agent.generate(`What's the weather like in ${city}?`);
+      const result = await agent.generate(
+        `What's the weather like in ${city}?`,
+      );
 
       return result.text;
-    }
-  })
+    },
+  }),
 };
 ```
 
-### Create Test Form
+</StepItem>
+
+<StepItem>
 
 Create a new Form component, and add the example code:
 
@@ -200,7 +238,7 @@ Create a new Form component, and add the example code:
 touch src/components/form.tsx
 ```
 
-```typescript filename="src/components/form.tsx" showLineNumbers copy
+```typescript title="src/components/form.tsx" showLineNumbers copy
 import { actions } from "astro:actions";
 import { useState } from "react";
 
@@ -226,7 +264,9 @@ export const Form = () => {
 };
 ```
 
-### Create Test Page
+</StepItem>
+
+<StepItem>
 
 Create a new Page, and add the example code:
 
@@ -234,7 +274,7 @@ Create a new Page, and add the example code:
 touch src/pages/test.astro
 ```
 
-```astro filename="src/pages/test.astro" showLineNumbers copy
+```astro title="src/pages/test.astro" showLineNumbers copy
 ---
 import { Form } from '../components/form'
 ---
@@ -258,82 +298,92 @@ Agent response: The current weather in London is as follows:
 
 Let me know if you need more information!
 ```
+
+</StepItem>
+
   </Steps>
-  </Tabs.Tab>
+  </TabItem>
+
+  <TabItem value="server-endpoints" label="Server Endpoints">
+
+:::warning
 
-  <Tabs.Tab>
+This guide assumes you're using Astro's Endpoints with React and the Vercel adapter, and your output is set to server.
 
-<Callout type="warning">
-  This guide assumes you're using Astro's Endpoints with React and the Vercel adapter, and your output is set to server.
-</Callout>
+:::
 
 ## Prerequisites
 
 Before proceeding, ensure your Astro project is configured as follows:
 
- - Astro React integration: [@astrojs/react](https://docs.astro.build/en/guides/integrations-guide/react/)
- - Vercel adapter: [@astrojs/vercel](https://docs.astro.build/en/guides/integrations-guide/vercel/)
- - `astro.config.mjs` is set to `output: "server"`
+- Astro React integration: [@astrojs/react](https://docs.astro.build/en/guides/integrations-guide/react/)
+- Vercel adapter: [@astrojs/vercel](https://docs.astro.build/en/guides/integrations-guide/vercel/)
+- `astro.config.mjs` is set to `output: "server"`
 
-  <Steps>
-## Install Mastra
+<Steps>
 
-Install the required Mastra packages:
-{/*
-LLM CONTEXT: This Tabs component shows commands for integrating a new Mastra backend project using different package managers.
-Each tab displays the command for that specific package manager to create an integrated Mastra backend service.
-This is part of the "Integrated Backend Integration" approach for Astro projects.
-All commands create the same Mastra project but use different package manager syntax.
-*/}
-
-<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>
+<StepItem>
 
-## Integrate Mastra
+Install the required Mastra packages:
 
-To integrate Mastra into your project, you have two options:
+<Tabs>
+<TabItem value="npm" label="npm">
 
-### 1. Use the One-Liner
+```bash copy
+npm install mastra@latest @mastra/core@latest @mastra/libsql@latest
+```
 
-Run the following command to quickly scaffold the default Weather agent with sensible defaults:
+</TabItem>
+<TabItem value="yarn" label="yarn">
 
 ```bash copy
-npx mastra@latest init --default
+yarn add mastra@latest @mastra/core@latest @mastra/libsql@latest
 ```
 
-> See [mastra init](/reference/cli/init) for more information.
+</TabItem>
+<TabItem value="pnpm" label="pnpm">
 
-### 2. Use the Interactive CLI
+```bash copy
+pnpm add mastra@latest @mastra/core@latest @mastra/libsql@latest
+```
 
-If you prefer to customize the setup, run the `init` command and choose from the options when prompted:
+</TabItem>
+<TabItem value="bun" label="bun">
 
 ```bash copy
-npx mastra@latest init
+bun add mastra@latest @mastra/core@latest @mastra/libsql@latest
 ```
 
+</TabItem>
+</Tabs>
+
+</StepItem>
+
+<StepItem>
+
+To integrate Mastra into your project, you have two options:
+
+- Use the One-Liner
+
+  Run the following command to quickly scaffold the default Weather agent with sensible defaults:
+
+  ```bash copy
+  npx mastra@latest init --default
+  ```
+
+  > See [mastra init](/reference/cli/create-mastra) for more information.
+
+- Use the Interactive CLI
+
+  If you prefer to customize the setup, run the `init` command and choose from the options when prompted:
+
+  ```bash copy
+  npx mastra@latest init
+  ```
+
 Add the `dev` and `build` scripts to `package.json`:
 
-```json filename="package.json"
+```json title="package.json"
 {
   "scripts": {
     ...
@@ -343,37 +393,47 @@ Add the `dev` and `build` scripts to `package.json`:
 }
 ```
 
-## Configure TypeScript
+</StepItem>
+
+<StepItem>
 
 Modify the `tsconfig.json` file in your project root:
 
-```json filename="tsconfig.json"
+```json title="tsconfig.json"
 {
   ...
   "exclude": ["dist", ".mastra"]
 }
 ```
 
-## Set Up API Key
+</StepItem>
 
-```bash filename=".env" copy
+<StepItem>
+
+Setup your API key in a `.env` file:
+
+```bash title=".env" copy
 OPENAI_API_KEY=<your-api-key>
 ```
 
-## Update .gitignore
+</StepItem>
+
+<StepItem>
 
 Add `.mastra` to your `.gitignore` file:
 
-```bash filename=".gitignore" copy
+```bash title=".gitignore" copy
 .mastra
 .vercel
 ```
 
-## Update the Mastra Agent
+</StepItem>
+
+<StepItem>
 
 Astro uses Vite, which accesses environment variables via `import.meta.env` rather than `process.env`. As a result, the model constructor must explicitly receive the `apiKey` from the Vite environment like this:
 
-```diff filename="src/mastra/agents/weather-agent.ts"
+```diff title="src/mastra/agents/weather-agent.ts"
 - import { openai } from "@ai-sdk/openai";
 + import { createOpenAI } from "@ai-sdk/openai";
 
@@ -385,36 +445,50 @@ Astro uses Vite, which accesses environment variables via `import.meta.env` rath
 
 > More configuration details are available in the AI SDK docs. See [Provider Instance](https://ai-sdk.dev/providers/ai-sdk-providers/openai#provider-instance) for more information.
 
-## Start the Mastra Dev Server
+</StepItem>
+
+<StepItem>
 
 Start the Mastra Dev Server to expose your agents as REST endpoints:
 
-<Tabs items={["npm", "CLI"]}>
-  <Tabs.Tab>
-    ```bash copy
-    npm run dev:mastra
-    ```
-  </Tabs.Tab>
-  <Tabs.Tab>
-    ```bash copy
-    mastra dev:mastra
-    ```
-  </Tabs.Tab>
+<Tabs>
+<TabItem value="npm" label="npm">
+
+```bash copy
+npm run dev:mastra
+```
+
+</TabItem>
+<TabItem value="cli" label="CLI">
+
+```bash copy
+mastra dev:mastra
+```
+
+</TabItem>
 </Tabs>
 
-> Once running, your agents are available locally. See [Local Development Environment](/docs/server-db/local-dev-playground) for more information.
+> Once running, your agents are available locally. See [Local Development Environment](/docs/getting-started/studio) for more information.
+
+</StepItem>
 
-## Start Astro Dev Server
+<StepItem>
 
 With the Mastra Dev Server running, you can start your Astro site in the usual way.
 
-## Create API Directory
+</StepItem>
+
+<StepItem>
+
+Create an `api` directory:
 
 ```bash copy
 mkdir src/pages/api
 ```
 
-### Create Test Endpoint
+</StepItem>
+
+<StepItem>
 
 Create a new Endpoint, and add the example code:
 
@@ -422,7 +496,7 @@ Create a new Endpoint, and add the example code:
 touch src/pages/api/test.ts
 ```
 
-```typescript filename="src/pages/api/test.ts" showLineNumbers copy
+```typescript title="src/pages/api/test.ts" showLineNumbers copy
 import type { APIRoute } from "astro";
 
 import { mastra } from "../../mastra";
@@ -437,7 +511,9 @@ export const POST: APIRoute = async ({ request }) => {
 };
 ```
 
-### Create Test Form
+</StepItem>
+
+<StepItem>
 
 Create a new Form component, and add the example code:
 
@@ -445,7 +521,7 @@ Create a new Form component, and add the example code:
 touch src/components/form.tsx
 ```
 
-```typescript filename="src/components/form.tsx" showLineNumbers copy
+```typescript title="src/components/form.tsx" showLineNumbers copy
 import { useState } from "react";
 
 export const Form = () => {
@@ -479,14 +555,17 @@ export const Form = () => {
 };
 ```
 
-### Create Test Page
+</StepItem>
+
+<StepItem>
 
 Create a new Page, and add the example code:
 
 ```bash copy
 touch src/pages/test.astro
 ```
-```astro filename="src/pages/test.astro" showLineNumbers copy
+
+```astro title="src/pages/test.astro" showLineNumbers copy
 ---
 import { Form } from '../components/form'
 ---
@@ -494,6 +573,7 @@ import { Form } from '../components/form'
 <h1>Test</h1>
 <Form client:load />
 ```
+
 > You can now navigate to `/test` in your browser to try it out.
 
 Submitting **London** as the city would return a result similar to:
@@ -509,11 +589,14 @@ Agent response: The current weather in London is as follows:
 
 Let me know if you need more information!
 ```
+
+</StepItem>
+
   </Steps>
-  </Tabs.Tab>
+  </TabItem>
 </Tabs>
 
 ## Next Steps
 
 - [Deployment | With Astro on Vercel](/docs/deployment/web-framework#with-astro-on-vercel)
-- [Monorepo Deployment](../../deployment/monorepo.mdx)
+- [Monorepo Deployment](../../deployment/monorepo)