Hono アダプター

@mastra/hono パッケージは、Mastra を Hono で実行するためのサーバーアダプターを提供します。アダプターの一般的な概念（コンストラクターオプション、初期化フローなど）については、サーバーアダプターを参照してください。

インストール

Hono アダプターと Hono フレームワークをインストールします。

npm

npm install @mastra/hono@latest hono

pnpm

pnpm add @mastra/hono@latest hono

Yarn

yarn add @mastra/hono@latest hono

Bun

bun add @mastra/hono@latest hono

使用例

server.ts

import { Hono } from 'hono'
import { HonoBindings, HonoVariables, MastraServer } from '@mastra/hono'
import { mastra } from './mastra'

const app = new Hono<{ Bindings: HonoBindings; Variables: HonoVariables }>()
const server = new MastraServer({ app, mastra })

await server.init()

export default app

コンストラクターのパラメーター

app:

Hono

Hono アプリのインスタンス

mastra:

Mastra

Mastra のインスタンス

prefix?:

string

= ''

ルートパスのプレフィックス（例：/api/v2）

openapiPath?:

string

= ''

OpenAPI 仕様を配信するパス（例：/openapi.json）

bodyLimitOptions?:

{ maxSize: number, onError: (err) => unknown }

リクエストボディのサイズ制限

streamOptions?:

{ redact?: boolean }

= { redact: true }

ストリームの秘匿化設定。true の場合、ストリームから機密データを秘匿します。

customRouteAuthConfig?:

Map<string, boolean>

ルートごとの認証オーバーライド。キーは METHOD:PATH（例：GET:/api/health）です。値が false の場合はルートを公開し、true の場合は認証を必須にします。

tools?:

Record<string, Tool>

サーバーで利用可能な Tool

taskStore?:

InMemoryTaskStore

A2A（Agent-to-Agent）操作用のタスクストア

mcpOptions?:

MCPOptions

MCP トランスポートのオプション。Cloudflare Workers や Vercel Edge などのステートレス環境では serverless: true を設定します。

カスタムルートの追加

Hono アプリにルートを直接追加します。

server.ts

import { Hono } from 'hono'
import { HonoBindings, HonoVariables, MastraServer } from '@mastra/hono'

const app = new Hono<{ Bindings: HonoBindings; Variables: HonoVariables }>()
const server = new MastraServer({ app, mastra })

// Before init - runs before Mastra middleware
app.get('/early-health', c => c.json({ status: 'ok' }))

await server.init()

// After init - has access to Mastra context
app.get('/custom', c => {
  const mastraInstance = c.get('mastra')
  return c.json({ agents: Object.keys(mastraInstance.listAgents()) })
})

ヒント

init() より前に追加したルートは、Mastra コンテキストなしで実行されます。Mastra インスタンスとリクエストコンテキストにアクセスするには、init() より後にルートを追加してください。

Mastra が管理する認証や requiresAuth などのルートメタデータが必要な場合は、registerApiRoute() を推奨します。app に直接マウントする生の Hono ルートでは、createAuthMiddleware() を使用します。

server.ts

import { Hono } from 'hono'
import { createAuthMiddleware, HonoBindings, HonoVariables, MastraServer } from '@mastra/hono'
import { mastra } from './mastra'

const app = new Hono<{ Bindings: HonoBindings; Variables: HonoVariables }>()
const server = new MastraServer({ app, mastra })

await server.init()

app.get('/custom/protected', createAuthMiddleware({ mastra }), c => {
  const user = c.get('requestContext').get('user')
  return c.json({ user })
})

app.get('/custom/public', createAuthMiddleware({ mastra, requiresAuth: false }), c => {
  return c.json({ ok: true })
})

コンテキストへのアクセス

Hono のミドルウェアとルートハンドラーでは、c.get() を介して Mastra コンテキストにアクセスします。

app.get('/custom', async c => {
  const mastra = c.get('mastra')
  const requestContext = c.get('requestContext')
  const abortSignal = c.get('abortSignal')

  const agent = mastra.getAgent('myAgent')
  return c.json({ agent: agent.name })
})

利用可能なコンテキストキーは次のとおりです。

キー	説明
mastra	Mastra のインスタンス
requestContext	リクエストコンテキストのマップ
abortSignal	リクエストのキャンセルシグナル
tools	利用可能な Tool
taskStore	A2A 操作用のタスクストア
customRouteAuthConfig	ルートごとの認証オーバーライド
user	認証済みユーザー（認証が設定されている場合）

ミドルウェアの追加

Hono のミドルウェアは init() の前後に追加できます。

server.ts

import { Hono } from 'hono'
import { HonoBindings, HonoVariables, MastraServer } from '@mastra/hono'

const app = new Hono<{ Bindings: HonoBindings; Variables: HonoVariables }>()

// Middleware before init
app.use('*', async (c, next) => {
  console.log(`${c.req.method} ${c.req.url}`)
  await next()
})

const server = new MastraServer({ app, mastra })
await server.init()

// Middleware after init has access to Mastra context
app.use('*', async (c, next) => {
  const mastra = c.get('mastra')
  await next()
})

手動初期化

ミドルウェアの順序をカスタマイズするには、init() の代わりに各メソッドを個別に呼び出します。詳しくは、手動初期化を参照してください。

例

• Hono アダプター：Hono サーバーの基本的なセットアップ

関連項目

• サーバーアダプター：アダプターに共通する概念
• MastraServer リファレンス：完全な API リファレンス
• createRoute() リファレンス：型安全なカスタムルートの作成