@mastra/mcp-docs-server 1.1.5 → 1.1.6-alpha.0

package/.docs/guides/getting-started/express.md

@@ -0,0 +1,251 @@
+# Integrate Mastra in your Express project
+
+In this guide, you'll build a tool-calling AI agent using Mastra and Express. Using the [Express server adapter](https://mastra.ai/reference/server/express-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](https://mastra.ai/models). If you don't have a preference, use [OpenAI](https://mastra.ai/models/providers/openai).
+- Install Node.js `v22.13.0` or later
+
+## Create a new Express app (optional)
+
+If you already have an Express app, skip to the next step.
+
+Clone this [boilerplate repository](https://github.com/mastra-ai/express-ts-boilerplate) and install dependencies:
+
+**HTTPS**:
+
+**npm**:
+
+```bash
+git clone https://github.com/mastra-ai/express-ts-boilerplate.git
+cd express-ts-boilerplate
+npm install
+```
+
+**pnpm**:
+
+```bash
+git clone https://github.com/mastra-ai/express-ts-boilerplate.git
+cd express-ts-boilerplate
+pnpm install
+```
+
+**Yarn**:
+
+```bash
+git clone https://github.com/mastra-ai/express-ts-boilerplate.git
+cd express-ts-boilerplate
+yarn install
+```
+
+**Bun**:
+
+```bash
+git clone https://github.com/mastra-ai/express-ts-boilerplate.git
+cd express-ts-boilerplate
+bun install
+```
+
+**SSH**:
+
+```bash
+git clone https://github.com/mastra-ai/express-ts-boilerplate.git
+cd express-ts-boilerplate
+npm install
+```
+
+**Tab 3**:
+
+```bash
+git clone https://github.com/mastra-ai/express-ts-boilerplate.git
+cd express-ts-boilerplate
+pnpm install
+```
+
+**Tab 4**:
+
+```bash
+git clone https://github.com/mastra-ai/express-ts-boilerplate.git
+cd express-ts-boilerplate
+yarn install
+```
+
+**Tab 5**:
+
+```bash
+git clone https://github.com/mastra-ai/express-ts-boilerplate.git
+cd express-ts-boilerplate
+bun install
+```
+
+**Tab 6**:
+
+**npm**:
+
+```bash
+git clone git@github.com:mastra-ai/express-ts-boilerplate.git
+cd express-ts-boilerplate
+npm install
+```
+
+**pnpm**:
+
+```bash
+git clone git@github.com:mastra-ai/express-ts-boilerplate.git
+cd express-ts-boilerplate
+pnpm install
+```
+
+**Yarn**:
+
+```bash
+git clone git@github.com:mastra-ai/express-ts-boilerplate.git
+cd express-ts-boilerplate
+yarn install
+```
+
+**Bun**:
+
+```bash
+git clone git@github.com:mastra-ai/express-ts-boilerplate.git
+cd express-ts-boilerplate
+bun install
+```
+
+**Tab 7**:
+
+```bash
+git clone git@github.com:mastra-ai/express-ts-boilerplate.git
+cd express-ts-boilerplate
+npm install
+```
+
+**Tab 8**:
+
+```bash
+git clone git@github.com:mastra-ai/express-ts-boilerplate.git
+cd express-ts-boilerplate
+pnpm install
+```
+
+**Tab 9**:
+
+```bash
+git clone git@github.com:mastra-ai/express-ts-boilerplate.git
+cd express-ts-boilerplate
+yarn install
+```
+
+**Tab 10**:
+
+```bash
+git clone git@github.com:mastra-ai/express-ts-boilerplate.git
+cd express-ts-boilerplate
+bun install
+```
+
+## Initialize Mastra
+
+Inside your Express project directory, run [`mastra init`](https://mastra.ai/reference/cli/mastra).
+
+When prompted, choose a provider (e.g. OpenAI) and enter your key:
+
+```bash
+npx mastra@latest init
+```
+
+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 Express server adapter later.
+
+## Add server adapter
+
+Install the Express server adapter package:
+
+**npm**:
+
+```bash
+npm install @mastra/express@latest
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/express@latest
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/express@latest
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/express@latest
+```
+
+Open the Express entry file at `src/index.ts` and add the required import and initialization code:
+
+```typescript
+import express, { type Request, type Response } from 'express'
+import { MastraServer } from '@mastra/express'
+import { mastra } from './mastra'
+
+const app = express()
+const PORT = process.env.PORT || 3000
+
+// Middleware
+app.use(express.json())
+
+const server = new MastraServer({ app, mastra })
+await server.init()
+
+// Routes
+app.get('/', (_req: Request, res: Response) => {
+  res.json({ message: 'Hello, World!' })
+})
+
+// Start server
+app.listen(PORT, () => {
+  console.log(`Server is running on http://localhost:${PORT}`)
+})
+```
+
+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.
+
+## 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:
+
+```bash
+npm run start
+```
+
+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 Express! 🎉
+
+From here, you can extend the project with your own tools and logic:
+
+- Learn more about [agents](https://mastra.ai/docs/agents/overview)
+- Give your agent its own [tools](https://mastra.ai/docs/agents/using-tools)
+- Add human-like [memory](https://mastra.ai/docs/agents/agent-memory) to your agent
+
+When you're ready, read more about how Mastra integrates with Express:
+
+- [Server Adapters](https://mastra.ai/docs/server/server-adapters)

package/.docs/guides/getting-started/hono.md

@@ -0,0 +1,190 @@
+# 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](https://mastra.ai/reference/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](https://mastra.ai/models). If you don't have a preference, use [OpenAI](https://mastra.ai/models/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):
+
+**npm**:
+
+```bash
+npm create hono@latest mastra-hono -- --template nodejs --install --pm npm
+```
+
+**pnpm**:
+
+```bash
+pnpm create hono mastra-hono --template nodejs --install --pm npm
+```
+
+**Yarn**:
+
+```bash
+yarn create hono mastra-hono --template nodejs --install --pm npm
+```
+
+**Bun**:
+
+```bash
+bunx create-hono mastra-hono --template nodejs --install --pm npm
+```
+
+This creates a project called `mastra-hono`, but you can replace it with any name you want.
+
+## Initialize Mastra
+
+Navigate to your Hono project directory:
+
+```bash
+cd mastra-hono
+```
+
+Run [`mastra init`](https://mastra.ai/reference/cli/mastra). When prompted, choose a provider (e.g. OpenAI) and enter your key:
+
+**npm**:
+
+```bash
+npx mastra@latest init
+```
+
+**pnpm**:
+
+```bash
+pnpm dlx mastra@latest init
+```
+
+**Yarn**:
+
+```bash
+yarn dlx mastra@latest init
+```
+
+**Bun**:
+
+```bash
+bun x mastra@latest init
+```
+
+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:
+
+**npm**:
+
+```bash
+npm install @mastra/hono@latest
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/hono@latest
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/hono@latest
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/hono@latest
+```
+
+Open the Hono entry file at `src/index.ts` and add the required import and initialization code:
+
+```typescript
+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:
+
+**npm**:
+
+```bash
+npm run dev
+```
+
+**pnpm**:
+
+```bash
+pnpm run dev
+```
+
+**Yarn**:
+
+```bash
+yarn dev
+```
+
+**Bun**:
+
+```bash
+bun run dev
+```
+
+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](https://mastra.ai/docs/agents/overview)
+- Give your agent its own [tools](https://mastra.ai/docs/agents/using-tools)
+- Add human-like [memory](https://mastra.ai/docs/agents/agent-memory) to your agent
+
+When you're ready, read more about how Mastra integrates with Hono:
+
+- [Server Adapters](https://mastra.ai/docs/server/server-adapters)