@mastra/koa 0.1.0-beta.15

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.
Files changed (3) hide show
  1. package/CHANGELOG.md +68 -0
  2. package/README.md +76 -0
  3. package/package.json +74 -0
package/CHANGELOG.md ADDED
@@ -0,0 +1,68 @@
1
+ # @mastra/koa
2
+
3
+ ## 0.1.0-beta.15
4
+
5
+ ### Minor Changes
6
+
7
+ - feat: Add Fastify and Koa server adapters ([#11568](https://github.com/mastra-ai/mastra/pull/11568))
8
+
9
+ Introduces two new server adapters for Mastra:
10
+ - **@mastra/fastify**: Enables running Mastra applications on Fastify
11
+ - **@mastra/koa**: Enables running Mastra applications on Koa
12
+
13
+ Both adapters provide full MastraServerBase implementation including route registration, streaming responses, multipart uploads, auth middleware, and MCP transport support.
14
+
15
+ ## Usage
16
+
17
+ ### Fastify
18
+
19
+ ```typescript
20
+ import Fastify from 'fastify';
21
+ import { MastraServer } from '@mastra/fastify';
22
+ import { mastra } from './mastra';
23
+
24
+ const app = Fastify();
25
+ const server = new MastraServer({ app, mastra });
26
+
27
+ await server.init();
28
+
29
+ app.listen({ port: 4111 });
30
+ ```
31
+
32
+ ### Koa
33
+
34
+ ```typescript
35
+ import Koa from 'koa';
36
+ import bodyParser from 'koa-bodyparser';
37
+ import { MastraServer } from '@mastra/koa';
38
+ import { mastra } from './mastra';
39
+
40
+ const app = new Koa();
41
+ app.use(bodyParser());
42
+
43
+ const server = new MastraServer({ app, mastra });
44
+
45
+ await server.init();
46
+
47
+ app.listen(4111);
48
+ ```
49
+
50
+ ### Patch Changes
51
+
52
+ - Fixed inconsistent query parameter handling across server adapters. ([#11429](https://github.com/mastra-ai/mastra/pull/11429))
53
+
54
+ **What changed:** Query parameters are now processed consistently across all server adapters (Express, Hono, Fastify, Koa). Added internal helper `normalizeQueryParams` and `ParsedRequestParams` type to `@mastra/server` for adapter implementations.
55
+
56
+ **Why:** Different HTTP frameworks handle query parameters differently - some return single strings while others return arrays for repeated params like `?tag=a&tag=b`. This caused type inconsistencies that could lead to validation failures in certain adapters.
57
+
58
+ **User impact:** None for typical usage - HTTP endpoints and client SDK behavior are unchanged. If you extend server adapter classes and override `getParams` or `parseQueryParams`, update your implementation to use `Record<string, string | string[]>` for query parameters.
59
+
60
+ - Updated dependencies [[`d2d3e22`](https://github.com/mastra-ai/mastra/commit/d2d3e22a419ee243f8812a84e3453dd44365ecb0), [`bc72b52`](https://github.com/mastra-ai/mastra/commit/bc72b529ee4478fe89ecd85a8be47ce0127b82a0), [`05b8bee`](https://github.com/mastra-ai/mastra/commit/05b8bee9e50e6c2a4a2bf210eca25ee212ca24fa), [`c042bd0`](https://github.com/mastra-ai/mastra/commit/c042bd0b743e0e86199d0cb83344ca7690e34a9c), [`940a2b2`](https://github.com/mastra-ai/mastra/commit/940a2b27480626ed7e74f55806dcd2181c1dd0c2), [`08bb631`](https://github.com/mastra-ai/mastra/commit/08bb631ae2b14684b2678e3549d0b399a6f0561e), [`e0941c3`](https://github.com/mastra-ai/mastra/commit/e0941c3d7fc75695d5d258e7008fd5d6e650800c), [`0c0580a`](https://github.com/mastra-ai/mastra/commit/0c0580a42f697cd2a7d5973f25bfe7da9055038a), [`28f5f89`](https://github.com/mastra-ai/mastra/commit/28f5f89705f2409921e3c45178796c0e0d0bbb64), [`e601b27`](https://github.com/mastra-ai/mastra/commit/e601b272c70f3a5ecca610373aa6223012704892), [`3d3366f`](https://github.com/mastra-ai/mastra/commit/3d3366f31683e7137d126a3a57174a222c5801fb), [`5a4953f`](https://github.com/mastra-ai/mastra/commit/5a4953f7d25bb15ca31ed16038092a39cb3f98b3), [`eb9e522`](https://github.com/mastra-ai/mastra/commit/eb9e522ce3070a405e5b949b7bf5609ca51d7fe2), [`20e6f19`](https://github.com/mastra-ai/mastra/commit/20e6f1971d51d3ff6dd7accad8aaaae826d540ed), [`4f0b3c6`](https://github.com/mastra-ai/mastra/commit/4f0b3c66f196c06448487f680ccbb614d281e2f7), [`74c4f22`](https://github.com/mastra-ai/mastra/commit/74c4f22ed4c71e72598eacc346ba95cdbc00294f), [`81b6a8f`](https://github.com/mastra-ai/mastra/commit/81b6a8ff79f49a7549d15d66624ac1a0b8f5f971), [`e4d366a`](https://github.com/mastra-ai/mastra/commit/e4d366aeb500371dd4210d6aa8361a4c21d87034), [`a4f010b`](https://github.com/mastra-ai/mastra/commit/a4f010b22e4355a5fdee70a1fe0f6e4a692cc29e), [`73b0bb3`](https://github.com/mastra-ai/mastra/commit/73b0bb394dba7c9482eb467a97ab283dbc0ef4db), [`5627a8c`](https://github.com/mastra-ai/mastra/commit/5627a8c6dc11fe3711b3fa7a6ffd6eb34100a306), [`3ff45d1`](https://github.com/mastra-ai/mastra/commit/3ff45d10e0c80c5335a957ab563da72feb623520), [`251df45`](https://github.com/mastra-ai/mastra/commit/251df4531407dfa46d805feb40ff3fb49769f455), [`f894d14`](https://github.com/mastra-ai/mastra/commit/f894d148946629af7b1f452d65a9cf864cec3765), [`c2b9547`](https://github.com/mastra-ai/mastra/commit/c2b9547bf435f56339f23625a743b2147ab1c7a6), [`580b592`](https://github.com/mastra-ai/mastra/commit/580b5927afc82fe460dfdf9a38a902511b6b7e7f), [`58e3931`](https://github.com/mastra-ai/mastra/commit/58e3931af9baa5921688566210f00fb0c10479fa), [`08bb631`](https://github.com/mastra-ai/mastra/commit/08bb631ae2b14684b2678e3549d0b399a6f0561e), [`4fba91b`](https://github.com/mastra-ai/mastra/commit/4fba91bec7c95911dc28e369437596b152b04cd0), [`106c960`](https://github.com/mastra-ai/mastra/commit/106c960df5d110ec15ac8f45de8858597fb90ad5), [`12b0cc4`](https://github.com/mastra-ai/mastra/commit/12b0cc4077d886b1a552637dedb70a7ade93528c)]:
61
+ - @mastra/core@1.0.0-beta.20
62
+ - @mastra/server@1.0.0-beta.20
63
+
64
+ ## 0.1.0-beta.14
65
+
66
+ ### Minor Changes
67
+
68
+ - Initial release of Koa server adapter for Mastra
package/README.md ADDED
@@ -0,0 +1,76 @@
1
+ # @mastra/koa
2
+
3
+ Koa server adapter for Mastra, enabling you to run Mastra with the [Koa](https://koajs.com) framework.
4
+
5
+ ## Installation
6
+
7
+ ```bash
8
+ npm install @mastra/koa koa koa-bodyparser
9
+ ```
10
+
11
+ ## Usage
12
+
13
+ ```typescript
14
+ import Koa from 'koa';
15
+ import bodyParser from 'koa-bodyparser';
16
+ import { MastraServer } from '@mastra/koa';
17
+ import { mastra } from './mastra';
18
+
19
+ const app = new Koa();
20
+ app.use(bodyParser());
21
+
22
+ const server = new MastraServer({ app, mastra });
23
+
24
+ await server.init();
25
+
26
+ app.listen(3000, () => {
27
+ console.log('Server running on http://localhost:3000');
28
+ });
29
+ ```
30
+
31
+ ## Adding Custom Routes
32
+
33
+ Add routes directly to the Koa app with access to Mastra context:
34
+
35
+ ```typescript
36
+ // Routes added after init() have access to Mastra context via ctx.state
37
+ app.use(async ctx => {
38
+ if (ctx.path === '/health' && ctx.method === 'GET') {
39
+ const mastraInstance = ctx.state.mastra;
40
+ const agents = Object.keys(mastraInstance.listAgents());
41
+ ctx.body = { status: 'ok', agents };
42
+ }
43
+ });
44
+ ```
45
+
46
+ ## Configuration Options
47
+
48
+ ```typescript
49
+ const server = new MastraServer({
50
+ app,
51
+ mastra,
52
+ prefix: '/api/v2', // Route prefix
53
+ openapiPath: '/openapi.json', // OpenAPI spec endpoint
54
+ bodyLimitOptions: {
55
+ maxSize: 10 * 1024 * 1024, // 10MB
56
+ onError: err => ({ error: 'Payload too large' }),
57
+ },
58
+ streamOptions: { redact: true }, // Redact sensitive data from streams
59
+ });
60
+ ```
61
+
62
+ ## Context Variables
63
+
64
+ Access these in route handlers via `ctx.state`:
65
+
66
+ | Key | Description |
67
+ | ---------------- | --------------------------- |
68
+ | `mastra` | Mastra instance |
69
+ | `requestContext` | Request context map |
70
+ | `abortSignal` | Request cancellation signal |
71
+ | `tools` | Available tools |
72
+
73
+ ## Related Links
74
+
75
+ - [Server Adapters Documentation](https://mastra.ai/docs/v1/server-db/server-adapters)
76
+ - [Koa Documentation](https://koajs.com)
package/package.json ADDED
@@ -0,0 +1,74 @@
1
+ {
2
+ "name": "@mastra/koa",
3
+ "version": "0.1.0-beta.15",
4
+ "description": "Mastra Koa adapter for the server",
5
+ "type": "module",
6
+ "main": "dist/index.js",
7
+ "types": "dist/index.d.ts",
8
+ "exports": {
9
+ ".": {
10
+ "import": {
11
+ "types": "./dist/index.d.ts",
12
+ "default": "./dist/index.js"
13
+ },
14
+ "require": {
15
+ "types": "./dist/index.d.ts",
16
+ "default": "./dist/index.cjs"
17
+ }
18
+ },
19
+ "./package.json": "./package.json"
20
+ },
21
+ "scripts": {
22
+ "build": "tsup --silent --config tsup.config.ts",
23
+ "build:watch": "pnpm build --watch",
24
+ "test": "vitest run",
25
+ "lint": "eslint ."
26
+ },
27
+ "license": "Apache-2.0",
28
+ "dependencies": {
29
+ "@mastra/server": "workspace:*",
30
+ "@fastify/busboy": "^3.2.0"
31
+ },
32
+ "devDependencies": {
33
+ "@internal/lint": "workspace:*",
34
+ "@internal/server-adapter-test-utils": "workspace:*",
35
+ "@internal/storage-test-utils": "workspace:*",
36
+ "@mastra/core": "workspace:*",
37
+ "@mastra/evals": "workspace:*",
38
+ "@mastra/libsql": "workspace:*",
39
+ "@mastra/observability": "workspace:*",
40
+ "@mastra/memory": "workspace:*",
41
+ "@types/node": "^20.19.0",
42
+ "eslint": "^9.37.0",
43
+ "tsup": "^8.5.0",
44
+ "typescript": "^5.8.3",
45
+ "vitest": "^3.2.4",
46
+ "@internal/types-builder": "workspace:*",
47
+ "koa": "^3.1.1",
48
+ "@types/koa": "^2.15.0",
49
+ "koa-bodyparser": "^4.4.1",
50
+ "@types/koa-bodyparser": "^4.3.13",
51
+ "@ai-sdk/openai": "^2.0.62",
52
+ "zod": "^3.25.0"
53
+ },
54
+ "peerDependencies": {
55
+ "@mastra/core": ">=1.0.0-0 <2.0.0-0",
56
+ "koa": "^3.0.0"
57
+ },
58
+ "engines": {
59
+ "node": ">=22.13.0"
60
+ },
61
+ "files": [
62
+ "dist",
63
+ "CHANGELOG.md"
64
+ ],
65
+ "homepage": "https://mastra.ai",
66
+ "repository": {
67
+ "type": "git",
68
+ "url": "git+https://github.com/mastra-ai/mastra.git",
69
+ "directory": "server-adapters/koa"
70
+ },
71
+ "bugs": {
72
+ "url": "https://github.com/mastra-ai/mastra/issues"
73
+ }
74
+ }