@mastra/mcp-docs-server 0.0.12-alpha.6 → 0.0.12
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.docs/organized/code-examples/agent-network.md +1 -1
- package/.docs/organized/code-examples/agent.md +1 -1
- package/.docs/organized/code-examples/ai-sdk-useChat.md +1 -1
- package/.docs/organized/code-examples/assistant-ui.md +1 -1
- package/.docs/organized/code-examples/bird-checker-with-express.md +1 -1
- package/.docs/organized/code-examples/bird-checker-with-nextjs-and-eval.md +1 -1
- package/.docs/organized/code-examples/bird-checker-with-nextjs.md +1 -1
- package/.docs/organized/code-examples/client-side-tools.md +1 -1
- package/.docs/organized/code-examples/fireworks-r1.md +1 -1
- package/.docs/organized/code-examples/mcp-registry-registry.md +1 -1
- package/.docs/organized/code-examples/memory-with-mem0.md +1 -1
- package/.docs/organized/code-examples/quick-start.md +1 -1
- package/.docs/organized/code-examples/stock-price-tool.md +1 -1
- package/.docs/organized/code-examples/weather-agent.md +1 -1
- package/.docs/organized/code-examples/workflow-ai-recruiter.md +1 -1
- package/.docs/organized/code-examples/workflow-with-inline-steps.md +1 -1
- package/.docs/organized/code-examples/workflow-with-memory.md +1 -1
- package/.docs/organized/code-examples/workflow-with-separate-steps.md +1 -1
- package/.docs/raw/deployment/custom-api-routes.mdx +56 -0
- package/.docs/raw/deployment/middleware.mdx +145 -0
- package/.docs/raw/deployment/server.mdx +4 -182
- package/package.json +6 -6
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Custom API Routes"
|
|
3
|
+
description: "Expose additional HTTP endpoints from your Mastra server."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Custom API Routes
|
|
7
|
+
|
|
8
|
+
By default Mastra automatically exposes registered agents and workflows via the
|
|
9
|
+
server. For additional behaviour you can define your own HTTP routes.
|
|
10
|
+
|
|
11
|
+
Routes are provided with a helper `registerApiRoute` from `@mastra/core/server`.
|
|
12
|
+
Routes can live in the same file as the `Mastra` instance but separating them
|
|
13
|
+
helps keep configuration concise.
|
|
14
|
+
|
|
15
|
+
```typescript copy showLineNumbers
|
|
16
|
+
import { Mastra } from '@mastra/core';
|
|
17
|
+
import { registerApiRoute } from '@mastra/core/server';
|
|
18
|
+
|
|
19
|
+
export const mastra = new Mastra({
|
|
20
|
+
server: {
|
|
21
|
+
apiRoutes: [
|
|
22
|
+
registerApiRoute('/my-custom-route', {
|
|
23
|
+
method: 'GET',
|
|
24
|
+
handler: async (c) => {
|
|
25
|
+
const mastra = c.get('mastra');
|
|
26
|
+
const agents = await mastra.getAgent('my-agent');
|
|
27
|
+
|
|
28
|
+
return c.json({ message: 'Hello, world!' });
|
|
29
|
+
},
|
|
30
|
+
}),
|
|
31
|
+
],
|
|
32
|
+
},
|
|
33
|
+
});
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
Each route's handler receives the Hono `Context`. Within the handler you can
|
|
37
|
+
access the `Mastra` instance to fetch or call agents and workflows.
|
|
38
|
+
|
|
39
|
+
To add route-specific middleware pass a `middleware` array when calling
|
|
40
|
+
`registerApiRoute`.
|
|
41
|
+
|
|
42
|
+
```typescript copy showLineNumbers
|
|
43
|
+
registerApiRoute('/my-custom-route', {
|
|
44
|
+
method: 'GET',
|
|
45
|
+
middleware: [
|
|
46
|
+
async (c, next) => {
|
|
47
|
+
console.log(`${c.req.method} ${c.req.url}`);
|
|
48
|
+
await next();
|
|
49
|
+
},
|
|
50
|
+
],
|
|
51
|
+
handler: async (c) => {
|
|
52
|
+
return c.json({ message: 'My route with custom middleware' });
|
|
53
|
+
},
|
|
54
|
+
});
|
|
55
|
+
```
|
|
56
|
+
|
|
@@ -0,0 +1,145 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Middleware"
|
|
3
|
+
description: "Apply custom middleware functions to intercept requests."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Middleware
|
|
7
|
+
|
|
8
|
+
Mastra servers can execute custom middleware functions before or after an API
|
|
9
|
+
route handler is invoked. This is useful for things like authentication,
|
|
10
|
+
logging, injecting request-specific context or adding CORS headers.
|
|
11
|
+
|
|
12
|
+
A middleware receives the [Hono](https://hono.dev) `Context` (`c`) and a `next`
|
|
13
|
+
function. If it returns a `Response` the request is short-circuited. Calling
|
|
14
|
+
`next()` continues processing the next middleware or route handler.
|
|
15
|
+
|
|
16
|
+
```typescript copy showLineNumbers
|
|
17
|
+
import { Mastra } from '@mastra/core';
|
|
18
|
+
|
|
19
|
+
export const mastra = new Mastra({
|
|
20
|
+
server: {
|
|
21
|
+
middleware: [
|
|
22
|
+
{
|
|
23
|
+
handler: async (c, next) => {
|
|
24
|
+
// Example: Add authentication check
|
|
25
|
+
const authHeader = c.req.header('Authorization');
|
|
26
|
+
if (!authHeader) {
|
|
27
|
+
return new Response('Unauthorized', { status: 401 });
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
await next();
|
|
31
|
+
},
|
|
32
|
+
path: '/api/*',
|
|
33
|
+
},
|
|
34
|
+
// Add a global request logger
|
|
35
|
+
async (c, next) => {
|
|
36
|
+
console.log(`${c.req.method} ${c.req.url}`);
|
|
37
|
+
await next();
|
|
38
|
+
},
|
|
39
|
+
],
|
|
40
|
+
},
|
|
41
|
+
});
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
To attach middleware to a single route pass the `middleware` option to
|
|
45
|
+
`registerApiRoute`:
|
|
46
|
+
|
|
47
|
+
```typescript copy showLineNumbers
|
|
48
|
+
registerApiRoute('/my-custom-route', {
|
|
49
|
+
method: 'GET',
|
|
50
|
+
middleware: [
|
|
51
|
+
async (c, next) => {
|
|
52
|
+
console.log(`${c.req.method} ${c.req.url}`);
|
|
53
|
+
await next();
|
|
54
|
+
},
|
|
55
|
+
],
|
|
56
|
+
handler: async (c) => {
|
|
57
|
+
const mastra = c.get('mastra');
|
|
58
|
+
return c.json({ message: 'Hello, world!' });
|
|
59
|
+
},
|
|
60
|
+
});
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
---
|
|
64
|
+
|
|
65
|
+
## Common examples
|
|
66
|
+
|
|
67
|
+
### Authentication
|
|
68
|
+
|
|
69
|
+
```typescript copy
|
|
70
|
+
{
|
|
71
|
+
handler: async (c, next) => {
|
|
72
|
+
const authHeader = c.req.header('Authorization');
|
|
73
|
+
if (!authHeader || !authHeader.startsWith('Bearer ')) {
|
|
74
|
+
return new Response('Unauthorized', { status: 401 });
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
// Validate token here
|
|
78
|
+
await next();
|
|
79
|
+
},
|
|
80
|
+
path: '/api/*',
|
|
81
|
+
}
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
### CORS support
|
|
85
|
+
|
|
86
|
+
```typescript copy
|
|
87
|
+
{
|
|
88
|
+
handler: async (c, next) => {
|
|
89
|
+
c.header('Access-Control-Allow-Origin', '*');
|
|
90
|
+
c.header(
|
|
91
|
+
'Access-Control-Allow-Methods',
|
|
92
|
+
'GET, POST, PUT, DELETE, OPTIONS',
|
|
93
|
+
);
|
|
94
|
+
c.header(
|
|
95
|
+
'Access-Control-Allow-Headers',
|
|
96
|
+
'Content-Type, Authorization',
|
|
97
|
+
);
|
|
98
|
+
|
|
99
|
+
if (c.req.method === 'OPTIONS') {
|
|
100
|
+
return new Response(null, { status: 204 });
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
await next();
|
|
104
|
+
},
|
|
105
|
+
}
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
### Request logging
|
|
109
|
+
|
|
110
|
+
```typescript copy
|
|
111
|
+
{
|
|
112
|
+
handler: async (c, next) => {
|
|
113
|
+
const start = Date.now();
|
|
114
|
+
await next();
|
|
115
|
+
const duration = Date.now() - start;
|
|
116
|
+
console.log(`${c.req.method} ${c.req.url} - ${duration}ms`);
|
|
117
|
+
},
|
|
118
|
+
}
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
### Special Mastra headers
|
|
122
|
+
|
|
123
|
+
When integrating with Mastra Cloud or custom clients the following headers can
|
|
124
|
+
be inspected by middleware to tailor behaviour:
|
|
125
|
+
|
|
126
|
+
```typescript copy
|
|
127
|
+
{
|
|
128
|
+
handler: async (c, next) => {
|
|
129
|
+
const isFromMastraCloud = c.req.header('x-mastra-cloud') === 'true';
|
|
130
|
+
const clientType = c.req.header('x-mastra-client-type');
|
|
131
|
+
const isDevPlayground =
|
|
132
|
+
c.req.header('x-mastra-dev-playground') === 'true';
|
|
133
|
+
|
|
134
|
+
if (isFromMastraCloud) {
|
|
135
|
+
// Special handling
|
|
136
|
+
}
|
|
137
|
+
await next();
|
|
138
|
+
},
|
|
139
|
+
}
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
- `x-mastra-cloud`: request originates from Mastra Cloud
|
|
143
|
+
- `x-mastra-client-type`: identifies the client SDK, e.g. `js` or `python`
|
|
144
|
+
- `x-mastra-dev-playground`: request triggered from a local playground
|
|
145
|
+
|
|
@@ -20,6 +20,10 @@ The server provides:
|
|
|
20
20
|
- Configuration of timeout
|
|
21
21
|
- Configuration of port
|
|
22
22
|
|
|
23
|
+
See the [Middleware](/docs/deployment/middleware) and
|
|
24
|
+
[Custom API Routes](/docs/deployment/custom-api-routes) pages for details on
|
|
25
|
+
adding additional server behaviour.
|
|
26
|
+
|
|
23
27
|
## Server configuration
|
|
24
28
|
|
|
25
29
|
You can configure server `port` and `timeout` in the Mastra instance.
|
|
@@ -35,36 +39,6 @@ export const mastra = new Mastra({
|
|
|
35
39
|
});
|
|
36
40
|
```
|
|
37
41
|
|
|
38
|
-
## Custom API Routes
|
|
39
|
-
|
|
40
|
-
Mastra provides a list of api routes that are automatically generated based on the registered agents and workflows. You can also define custom api routes on the Mastra instance.
|
|
41
|
-
|
|
42
|
-
These routes can live in the same file as the Mastra instance or in a separate file. We recommend keeping them in a separate file to keep the Mastra instance clean.
|
|
43
|
-
|
|
44
|
-
```typescript copy showLineNumbers
|
|
45
|
-
import { Mastra } from "@mastra/core";
|
|
46
|
-
import { registerApiRoute } from "@mastra/core/server";
|
|
47
|
-
|
|
48
|
-
export const mastra = new Mastra({
|
|
49
|
-
server: {
|
|
50
|
-
apiRoutes: [
|
|
51
|
-
registerApiRoute("/my-custom-route", {
|
|
52
|
-
method: "GET",
|
|
53
|
-
handler: async (c) => {
|
|
54
|
-
// you have access to mastra instance here
|
|
55
|
-
const mastra = c.get("mastra");
|
|
56
|
-
|
|
57
|
-
// you can use the mastra instance to get agents, workflows, etc.
|
|
58
|
-
const agents = await mastra.getAgent("my-agent");
|
|
59
|
-
|
|
60
|
-
return c.json({ message: "Hello, world!" });
|
|
61
|
-
},
|
|
62
|
-
}),
|
|
63
|
-
],
|
|
64
|
-
},
|
|
65
|
-
// Other configuration options
|
|
66
|
-
});
|
|
67
|
-
```
|
|
68
42
|
|
|
69
43
|
## Custom CORS Config
|
|
70
44
|
|
|
@@ -85,158 +59,6 @@ export const mastra = new Mastra({
|
|
|
85
59
|
});
|
|
86
60
|
```
|
|
87
61
|
|
|
88
|
-
## Middleware
|
|
89
|
-
|
|
90
|
-
Mastra allows you to configure custom middleware functions that will be applied to API routes. This is useful for adding authentication, logging, CORS, or other HTTP-level functionality to your API endpoints.
|
|
91
|
-
|
|
92
|
-
```typescript copy showLineNumbers
|
|
93
|
-
import { Mastra } from '@mastra/core';
|
|
94
|
-
|
|
95
|
-
export const mastra = new Mastra({
|
|
96
|
-
// Other configuration options
|
|
97
|
-
server: {
|
|
98
|
-
middleware: [
|
|
99
|
-
{
|
|
100
|
-
handler: async (c, next) => {
|
|
101
|
-
// Example: Add authentication check
|
|
102
|
-
const authHeader = c.req.header('Authorization');
|
|
103
|
-
if (!authHeader) {
|
|
104
|
-
return new Response('Unauthorized', { status: 401 });
|
|
105
|
-
}
|
|
106
|
-
|
|
107
|
-
// Continue to the next middleware or route handler
|
|
108
|
-
await next();
|
|
109
|
-
},
|
|
110
|
-
path: '/api/*'
|
|
111
|
-
},
|
|
112
|
-
// add middleware to all routes
|
|
113
|
-
async (c, next) => {
|
|
114
|
-
// Example: Add request logging
|
|
115
|
-
console.log(`${c.req.method} ${c.req.url}`);
|
|
116
|
-
await next();
|
|
117
|
-
},
|
|
118
|
-
]
|
|
119
|
-
});
|
|
120
|
-
```
|
|
121
|
-
|
|
122
|
-
if you want to add a middleware to a single route, you can also specify that in the registerApiRoute using `registerApiRoute`.
|
|
123
|
-
|
|
124
|
-
```typescript copy showLineNumbers
|
|
125
|
-
registerApiRoute("/my-custom-route", {
|
|
126
|
-
method: "GET",
|
|
127
|
-
middleware: [
|
|
128
|
-
async (c, next) => {
|
|
129
|
-
// Example: Add request logging
|
|
130
|
-
console.log(`${c.req.method} ${c.req.url}`);
|
|
131
|
-
await next();
|
|
132
|
-
},
|
|
133
|
-
],
|
|
134
|
-
handler: async (c) => {
|
|
135
|
-
// you have access to mastra instance here
|
|
136
|
-
const mastra = c.get("mastra");
|
|
137
|
-
|
|
138
|
-
// you can use the mastra instance to get agents, workflows, etc.
|
|
139
|
-
const agents = await mastra.getAgent("my-agent");
|
|
140
|
-
|
|
141
|
-
return c.json({ message: "Hello, world!" });
|
|
142
|
-
},
|
|
143
|
-
});
|
|
144
|
-
```
|
|
145
|
-
|
|
146
|
-
### Middleware Behavior
|
|
147
|
-
|
|
148
|
-
Each middleware function:
|
|
149
|
-
|
|
150
|
-
- Receives a Hono context object (`c`) and a `next` function
|
|
151
|
-
- Can return a `Response` to short-circuit the request handling
|
|
152
|
-
- Can call `next()` to continue to the next middleware or route handler
|
|
153
|
-
- Can optionally specify a path pattern (defaults to '/api/\*')
|
|
154
|
-
- Inject request specific data for agent tool calling or workflows
|
|
155
|
-
|
|
156
|
-
### Common Middleware Use Cases
|
|
157
|
-
|
|
158
|
-
#### Authentication
|
|
159
|
-
|
|
160
|
-
```typescript copy
|
|
161
|
-
{
|
|
162
|
-
handler: async (c, next) => {
|
|
163
|
-
const authHeader = c.req.header('Authorization');
|
|
164
|
-
if (!authHeader || !authHeader.startsWith('Bearer ')) {
|
|
165
|
-
return new Response('Unauthorized', { status: 401 });
|
|
166
|
-
}
|
|
167
|
-
|
|
168
|
-
const token = authHeader.split(' ')[1];
|
|
169
|
-
// Validate token here
|
|
170
|
-
|
|
171
|
-
await next();
|
|
172
|
-
},
|
|
173
|
-
path: '/api/*',
|
|
174
|
-
}
|
|
175
|
-
```
|
|
176
|
-
|
|
177
|
-
#### CORS Support
|
|
178
|
-
|
|
179
|
-
```typescript copy
|
|
180
|
-
{
|
|
181
|
-
handler: async (c, next) => {
|
|
182
|
-
// Add CORS headers
|
|
183
|
-
c.header("Access-Control-Allow-Origin", "*");
|
|
184
|
-
c.header("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, OPTIONS");
|
|
185
|
-
c.header("Access-Control-Allow-Headers", "Content-Type, Authorization");
|
|
186
|
-
|
|
187
|
-
// Handle preflight requests
|
|
188
|
-
if (c.req.method === "OPTIONS") {
|
|
189
|
-
return new Response(null, { status: 204 });
|
|
190
|
-
}
|
|
191
|
-
|
|
192
|
-
await next();
|
|
193
|
-
};
|
|
194
|
-
}
|
|
195
|
-
```
|
|
196
|
-
|
|
197
|
-
#### Request Logging
|
|
198
|
-
|
|
199
|
-
```typescript copy
|
|
200
|
-
{
|
|
201
|
-
handler: async (c, next) => {
|
|
202
|
-
const start = Date.now();
|
|
203
|
-
await next();
|
|
204
|
-
const duration = Date.now() - start;
|
|
205
|
-
console.log(`${c.req.method} ${c.req.url} - ${duration}ms`);
|
|
206
|
-
};
|
|
207
|
-
}
|
|
208
|
-
```
|
|
209
|
-
|
|
210
|
-
### Special Mastra Headers
|
|
211
|
-
|
|
212
|
-
When integrating with Mastra Cloud or building custom clients, there are special headers that clients send to identify themselves and enable specific features. Your server middleware can check for these headers to customize behavior:
|
|
213
|
-
|
|
214
|
-
```typescript copy
|
|
215
|
-
{
|
|
216
|
-
handler: async (c, next) => {
|
|
217
|
-
// Check for Mastra-specific headers in incoming requests
|
|
218
|
-
const isFromMastraCloud = c.req.header("x-mastra-cloud") === "true";
|
|
219
|
-
const clientType = c.req.header("x-mastra-client-type"); // e.g., 'js', 'python'
|
|
220
|
-
const isDevPlayground = c.req.header("x-mastra-dev-playground") === "true";
|
|
221
|
-
|
|
222
|
-
// Customize behavior based on client information
|
|
223
|
-
if (isFromMastraCloud) {
|
|
224
|
-
// Special handling for Mastra Cloud requests
|
|
225
|
-
}
|
|
226
|
-
|
|
227
|
-
await next();
|
|
228
|
-
};
|
|
229
|
-
}
|
|
230
|
-
```
|
|
231
|
-
|
|
232
|
-
These headers have the following purposes:
|
|
233
|
-
|
|
234
|
-
- `x-mastra-cloud`: Indicates that the request is coming from Mastra Cloud
|
|
235
|
-
- `x-mastra-client-type`: Specifies the client SDK type (e.g., 'js', 'python')
|
|
236
|
-
- `x-mastra-dev-playground`: Indicates that the request is from the development playground
|
|
237
|
-
|
|
238
|
-
You can use these headers in your middleware to implement client-specific logic or enable features only for certain environments.
|
|
239
|
-
|
|
240
62
|
## Deployment
|
|
241
63
|
|
|
242
64
|
Since Mastra builds to a standard Node.js server, you can deploy to any platform that runs Node.js applications:
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@mastra/mcp-docs-server",
|
|
3
|
-
"version": "0.0.12
|
|
3
|
+
"version": "0.0.12",
|
|
4
4
|
"description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "dist/index.js",
|
|
@@ -30,10 +30,10 @@
|
|
|
30
30
|
"jsdom": "^26.0.0",
|
|
31
31
|
"turndown": "^7.1.2",
|
|
32
32
|
"uuid": "^11.1.0",
|
|
33
|
-
"zod": "^3.
|
|
34
|
-
"zod-to-json-schema": "^3.
|
|
35
|
-
"@mastra/
|
|
36
|
-
"@mastra/
|
|
33
|
+
"zod": "^3.24.3",
|
|
34
|
+
"zod-to-json-schema": "^3.24.5",
|
|
35
|
+
"@mastra/core": "^0.9.2",
|
|
36
|
+
"@mastra/mcp": "^0.4.2"
|
|
37
37
|
},
|
|
38
38
|
"devDependencies": {
|
|
39
39
|
"@hono/node-server": "^1.13.8",
|
|
@@ -48,7 +48,7 @@
|
|
|
48
48
|
"tsx": "^4.19.3",
|
|
49
49
|
"typescript": "^5.3.3",
|
|
50
50
|
"vitest": "^3.1.2",
|
|
51
|
-
"@internal/lint": "0.0.
|
|
51
|
+
"@internal/lint": "0.0.3"
|
|
52
52
|
},
|
|
53
53
|
"scripts": {
|
|
54
54
|
"prepare-docs": "cross-env PREPARE=true node dist/prepare-docs/prepare.js",
|