@mastra/mcp-docs-server 1.0.0-beta.11 → 1.0.0-beta.14

package/.docs/raw/guides/getting-started/express.mdx

@@ -1,209 +1,128 @@
 ---
-title: "Integrate Mastra in your Express project | Frameworks"
-description: A step-by-step guide to integrating Mastra with an Express backend.
+title: "Express | Frameworks"
+description: "Get started with Mastra and Express"
 ---
 
-# Integrate Mastra in your Express project
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
 
-Mastra integrates with Express, making it easy to:
+# Integrate Mastra in your Express project
 
-- Build flexible APIs to serve AI-powered features
-- Maintain full control over your server logic and routing
-- Scale your backend independently of your frontend
+In this guide, you'll build a tool-calling AI agent using Mastra and Express. Using the [Express server adapter](/reference/v1/server/express-adapter), you can expose your agents as HTTP endpoints without writing the routing yourself or running a separate Mastra server.
 
-Express can invoke Mastra directly so you don't need to run a Mastra server alongside your Express server.
+## Before you begin
 
-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.
+- You'll need an API key from a supported [model provider](/models/v1). If you don't have a preference, use [OpenAI](/models/v1/providers/openai).
+- Install Node.js `v22.13.0` or later
 
-## Prerequisites
+## Create a new Express app (optional)
 
-- An existing Express app set up with TypeScript
-- Node.js `v22.13.0` or later
-- An API key from a supported [Model Provider](/models/v1)
+If you already have an Express app, skip to the next step.
 
-## Adding Mastra
+Clone this [boilerplate repository](https://github.com/mastra-ai/express-ts-boilerplate) and install dependencies:
 
-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](/models/v1).
+<Tabs>
+<TabItem value="https" label="HTTPS">
 
-```bash copy
-npm install mastra@beta @mastra/core@beta @mastra/libsql@beta zod@^3.0.0
+```bash
+git clone https://github.com/mastra-ai/express-ts-boilerplate.git
+cd express-ts-boilerplate
+npm install
 ```
 
-If not existent yet, create an `.env` file and add your OpenAI API key:
-
-```bash title=".env" copy
-OPENAI_API_KEY=<your-api-key>
-```
-
-:::note
-
-Each LLM provider uses a different env var. See [Model Providers](/models/v1/providers/) for more information.
-
-:::
+</TabItem>
+<TabItem value="ssh" label="SSH">
 
-Create a Mastra configuration file at `src/mastra/index.ts`:
-
-```ts title="src/mastra/index.ts" copy
-import { Mastra } from "@mastra/core";
-
-export const mastra = new Mastra({});
+```bash
+git clone git@github.com:mastra-ai/express-ts-boilerplate.git
+cd express-ts-boilerplate
+npm install
 ```
 
-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 title="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",
-    };
-  },
-});
-```
+</TabItem>
+</Tabs>
 
-Add a `weatherAgent` at `src/mastra/agents/weather-agent.ts`:
-
-```ts title="src/mastra/agents/weather-agent.ts" copy
-import { Agent } from "@mastra/core/agent";
-import { weatherTool } from "../tools/weather-tool";
-
-export const weatherAgent = new Agent({
-  id: "weather-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-5.1",
-  tools: { weatherTool },
-});
-```
+## Initialize Mastra
 
-Lastly, add the `weatherAgent` to `src/mastra/index.ts`:
+Inside your Express project directory, run [`mastra init`](/reference/v1/cli/mastra#mastra-init).
 
-```ts title="src/mastra/index.ts" copy {2, 5}
-import { Mastra } from "@mastra/core";
-import { weatherAgent } from "./agents/weather-agent";
+When prompted, choose a provider (e.g. OpenAI) and enter your key:
 
-export const mastra = new Mastra({
-  agents: { weatherAgent },
-});
+```bash
+npx mastra@beta init
 ```
 
-Now you're done with setting up the Mastra boilerplate code and are ready to integrate it into your Express routes.
+This creates a `src/mastra` folder with an example weather agent and the following files:
 
-## Using Mastra with Express
+-	`index.ts` - Mastra config, including memory
+- `tools/weather-tool.ts` - a tool to fetch weather for a given location
+-	`agents/weather-agent.ts`- a weather agent with a prompt that uses the tool
 
-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.
+You'll pass the `src/mastra/index.ts` file to the Express server adapter later.
 
-You might have a file like this in your existing project:
+## Add server adapter
 
-```ts title="src/server.ts" copy
-import express, { Request, Response } from "express";
+Install the Express server adapter package:
 
-const app = express();
-const port = 3456;
-
-app.get("/", (req: Request, res: Response) => {
-  res.send("Hello, world!");
-});
-
-app.listen(port, () => {
-  console.log(`Server is running at http://localhost:${port}`);
-});
+```bash
+npm install @mastra/express@beta
 ```
 
-Adding the `/api/weather` endpoint looks like this:
+Open the Express entry file at `src/index.ts` and add the required import and initialization code:
 
-```ts title="src/server.ts" copy {2, 11-27}
-import express, { Request, Response } from "express";
+```typescript {2-3,11-12} title="src/index.ts"
+import express, { type Request, type Response } from "express";
+import { MastraServer } from "@mastra/express";
 import { mastra } from "./mastra";
 
 const app = express();
-const port = 3456;
-
-app.get("/", (req: Request, res: Response) => {
-  res.send("Hello, world!");
-});
+const PORT = process.env.PORT || 3000;
 
-app.get("/api/weather", async (req: Request, res: Response) => {
-  const { city } = req.query as { city?: string };
+// Middleware
+app.use(express.json());
 
-  if (!city) {
-    return res.status(400).send("Missing 'city' query parameter");
-  }
+const server = new MastraServer({ app, mastra });
+await server.init();
 
-  const agent = mastra.getAgent("weatherAgent");
-
-  try {
-    const result = await agent.generate(`What's the weather like in ${city}?`);
-    res.send(result.text);
-  } catch (error) {
-    console.error("Agent error:", error);
-    res.status(500).send("An error occurred while processing your request");
-  }
+// Routes
+app.get("/", (_req: Request, res: Response) => {
+  res.json({ message: "Hello, World!" });
 });
 
-app.listen(port, () => {
-  console.log(`Server is running at http://localhost:${port}`);
+// Start server
+app.listen(PORT, () => {
+  console.log(`Server is running on http://localhost:${PORT}`);
 });
 ```
 
-By importing the `src/mastra/index.ts` file you can use methods like [`.getAgent()`](/reference/v1/core/getAgent) to get programmatic access. With [`.generate()`](/reference/v1/agents/generate) you then can interact with the respective agent.
-
-:::note
+The ⁠`MastraServer` is initialized with the existing Express `app` and the root ⁠`mastra` instance. Calling `⁠init()` registers the Mastra middleware and exposes all available Mastra endpoints.
 
-Read the [Agent reference docs](/reference/v1/agents/agent) to learn more.
+## Test your agent
 
-:::
+By default, Mastra's endpoints are added under the `/api` subpath and use your agent/workflow IDs. The default `weather-agent` created by `mastra init` is available at `/api/agents/weather-agent`.
 
-Start your Express server and visit the `/api/weather` endpoint. For example:
+Start your Express server:
 
-```
-http://localhost:3456/api/weather?city=London
+```bash
+npm run start
 ```
 
-You should get a response back similar to this:
+In a separate terminal window, use `curl` to ask the weather agent:
 
-```
-The weather in London is currently sunny. If you need more details like humidity, wind conditions, or precipitation, just let me know!
+```bash
+curl -X POST http://localhost:3000/api/agents/weather-agent/generate -H "Content-Type: application/json" -d "{\"messages\":[{\"role\":\"user\",\"content\":\"What is the weather like in Seoul?\"}]}"
 ```
 
-## Running the Agent Server
+## Next steps
 
-In production it's not necessary to run Mastra alongside your Express server. But for development Mastra offers a [Local Development Environment](/docs/v1/getting-started/studio) which you can use to improve and debug your agent.
+Congratulations on building your Mastra agent with Express! 🎉
 
-Add a script to your `package.json`:
+From here, you can extend the project with your own tools and logic:
 
-```json title="package.json" copy
-{
-  "scripts": {
-    "mastra:dev": "mastra dev"
-  }
-}
-```
+- Learn more about [agents](/docs/v1/agents/overview)
+- Give your agent its own [tools](/docs/v1/agents/using-tools)
+- Add human-like [memory](/docs/v1/agents/agent-memory) to your agent
 
-Start the Mastra dev server:
+When you're ready, read more about how Mastra integrates with Express:
 
-```bash copy
-npm run mastra:dev
-```
+- [Server Adapters](/docs/v1/server/server-adapters)

package/.docs/raw/guides/getting-started/hono.mdx

@@ -0,0 +1,227 @@
+---
+title: "Hono | Frameworks"
+description: "Get started with Mastra and Hono"
+---
+
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+
+# Integrate Mastra in your Hono project
+
+In this guide, you'll build a tool-calling AI agent using Mastra and Hono. Using the [Hono server adapter](/reference/v1/server/hono-adapter), you can expose your agents as HTTP endpoints without writing the routing yourself or running a separate Mastra server.
+
+## Before you begin
+
+- You'll need an API key from a supported [model provider](/models/v1). If you don't have a preference, use [OpenAI](/models/v1/providers/openai).
+- Install Node.js `v22.13.0` or later
+
+## Create a new Hono app (optional)
+
+If you already have a Hono app, skip to the next step.
+
+Run the following command to [create a new Hono app](https://hono.dev/docs/getting-started/basic):
+
+<Tabs groupId="pm">
+<TabItem value="npm" label="npm">
+
+```bash
+npm create hono@latest mastra-hono -- --template nodejs --install --pm npm
+```
+
+</TabItem>
+<TabItem value="pnpm" label="pnpm">
+
+```bash
+pnpm create hono@latest mastra-hono --template nodejs --install --pm pnpm
+```
+
+</TabItem>
+<TabItem value="yarn" label="yarn">
+
+```bash
+yarn create hono@latest mastra-hono --template nodejs --install --pm yarn
+```
+
+</TabItem>
+<TabItem value="bun" label="bun">
+
+```bash
+bun create hono@latest mastra-hono --template nodejs --install --pm bun
+```
+
+</TabItem>
+</Tabs>
+
+This creates a project called `mastra-hono`, but you can replace it with any name you want.
+
+## Initialize Mastra
+
+Inside your Hono project directory, run [`mastra init`](/reference/v1/cli/mastra#mastra-init).
+
+When prompted, choose a provider (e.g. OpenAI) and enter your key:
+
+<Tabs groupId="pm">
+<TabItem value="npm" label="npm">
+
+```bash
+cd mastra-hono
+npx mastra@beta init
+```
+
+</TabItem>
+<TabItem value="pnpm" label="pnpm">
+
+```bash
+cd mastra-hono
+pnpm dlx mastra@beta init
+```
+
+</TabItem>
+<TabItem value="yarn" label="yarn">
+
+```bash
+cd mastra-hono
+yarn dlx mastra@beta init
+```
+
+</TabItem>
+<TabItem value="bun" label="bun">
+
+```bash
+cd mastra-hono
+bunx mastra@beta init
+```
+
+</TabItem>
+</Tabs>
+
+This creates a `src/mastra` folder with an example weather agent and the following files:
+
+-	`index.ts` - Mastra config, including memory
+- `tools/weather-tool.ts` - a tool to fetch weather for a given location
+-	`agents/weather-agent.ts`- a weather agent with a prompt that uses the tool
+
+You'll pass the `src/mastra/index.ts` file to the Hono server adapter later.
+
+## Add server adapter
+
+Install the Hono server adapter package:
+
+<Tabs groupId="pm">
+<TabItem value="npm" label="npm">
+
+```bash
+npm install @mastra/hono@beta
+```
+
+</TabItem>
+<TabItem value="pnpm" label="pnpm">
+
+```bash
+pnpm add @mastra/hono@beta
+```
+
+</TabItem>
+<TabItem value="yarn" label="yarn">
+
+```bash
+yarn add @mastra/hono@beta
+```
+
+</TabItem>
+<TabItem value="bun" label="bun">
+
+```bash
+bun add @mastra/hono@beta
+```
+
+</TabItem>
+</Tabs>
+
+Open the Hono entry file at `src/index.ts` and add the required import and initialization code:
+
+```typescript title="src/index.ts" {3-8,10-11,13}
+import { serve } from '@hono/node-server'
+import { Hono } from 'hono'
+import {
+  type HonoBindings,
+  type HonoVariables,
+  MastraServer
+} from '@mastra/hono';
+import { mastra } from './mastra/index.js';
+
+const app = new Hono<{ Bindings: HonoBindings; Variables: HonoVariables }>();
+const server = new MastraServer({ app, mastra });
+
+await server.init();
+
+app.get('/', (c) => {
+  return c.text('Hello Hono!')
+})
+
+serve({
+  fetch: app.fetch,
+  port: 3000
+}, (info) => {
+  console.log(`Server is running on http://localhost:${info.port}`)
+})
+```
+
+The ⁠`MastraServer` is initialized with the existing Hono `app` and the root ⁠`mastra` instance. Calling `⁠init()` registers the Mastra middleware and exposes all available Mastra endpoints.
+
+## Test your agent
+
+By default, Mastra's endpoints are added under the `/api` subpath and use your agent/workflow IDs. The default `weather-agent` created by `mastra init` is available at `/api/agents/weather-agent`.
+
+Start your Hono server:
+
+<Tabs groupId="pm">
+<TabItem value="npm" label="npm">
+
+```bash
+npm run dev
+```
+
+</TabItem>
+<TabItem value="pnpm" label="pnpm">
+
+```bash
+pnpm run dev
+```
+
+</TabItem>
+<TabItem value="yarn" label="yarn">
+
+```bash
+yarn run dev
+```
+
+</TabItem>
+<TabItem value="bun" label="bun">
+
+```bash
+bun run dev
+```
+
+</TabItem>
+</Tabs>
+
+In a separate terminal window, use `curl` to ask the weather agent:
+
+```bash
+curl -X POST http://localhost:3000/api/agents/weather-agent/generate -H "Content-Type: application/json" -d "{\"messages\":[{\"role\":\"user\",\"content\":\"What is the weather like in Seoul?\"}]}"
+```
+
+## Next steps
+
+Congratulations on building your Mastra agent with Hono! 🎉
+
+From here, you can extend the project with your own tools and logic:
+
+- Learn more about [agents](/docs/v1/agents/overview)
+- Give your agent its own [tools](/docs/v1/agents/using-tools)
+- Add human-like [memory](/docs/v1/agents/agent-memory) to your agent
+
+When you're ready, read more about how Mastra integrates with Hono:
+
+- [Server Adapters](/docs/v1/server/server-adapters)