hono-apcore

Adaptador de Hono para el ecosistema de módulos AI-Perceivable de apcore. Convierte una aplicación de Hono en herramientas MCP y definiciones de funciones compatibles con OpenAI, ya sea declarando herramientas explícitamente o escaneando las rutas que ya tienes.

Características

• Dos formas de entrada — declara herramientas con defineTool() / defineToolset(), o escanea tus rutas existentes sin cambios de código.

• Reproducción de rutas — una ruta escaneada se convierte en un módulo que vuelve a llamar a través de app.request(), de modo que el middleware, los validadores y los manejadores de errores siguen ejecutándose.

• Un solo puerto — mountMcp() sirve el endpoint de MCP, el Tool Explorer y /health desde la misma aplicación de Hono.

• Inferencia de anotaciones — GET → readonly + cacheable, PUT → idempotent, DELETE → destructive (semántica de métodos seguros de RFC 9110).

• Multi-esquema — TypeBox, Zod 3, Zod 4 y JSON Schema plano, auto-detectados mediante una cadena de prioridad.

• Contexto, ACL e identidad — el middleware apcore() construye un Context de apcore por petición con propagación de trazas W3C, de modo que las reglas ACL también gobiernan tus rutas.

• Núcleo independiente del runtime — apcore-mcp, apcore-cli y apcore-a2a son pares opcionales que se cargan de forma diferida, por lo que importar hono-apcore nunca arrastra node:http a una compilación de edge.

• CLI — hono-apcore scan | serve | export funciona con una aplicación de Hono simple.

• Enlaces YAML — registra módulos de forma declarativa, sin tocar el código fuente.

Related MCP server: Graft

Instalación

npm install hono-apcore hono

Pares opcionales, instalados solo para las superficies que uses:

npm install apcore-mcp @modelcontextprotocol/sdk   # MCP server + Tool Explorer
npm install @hono/node-server                      # mountMcp() on the Node runtime
npm install apcore-cli                             # CLI surface
npm install apcore-a2a                             # A2A agent surface
npm install @sinclair/typebox                      # TypeBox schemas (recommended)
npm install zod                                    # Zod schemas

Requisitos: Node.js >= 18, Hono >= 4 (probado con Hono 4.13).

Inicio rápido

1. Declara algunas herramientas

// todo.tools.ts
import { Type } from '@sinclair/typebox';
import { defineToolset } from 'hono-apcore';

export const todoTools = defineToolset({
  namespace: 'todo',
  description: 'Todo list management',
  tags: ['todo'],
  tools: {
    list: {
      description: 'List all todos, optionally filtered by status',
      inputSchema: Type.Object({ done: Type.Optional(Type.Boolean()) }),
      annotations: { readonly: true, idempotent: true },
      handler: (inputs) => ({ todos: store.list(inputs.done as boolean | undefined) }),
    },
    add: {
      description: 'Add a new todo item',
      inputSchema: Type.Object({ title: Type.String() }),
      annotations: { readonly: false },
      handler: (inputs) => ({ todo: store.add(String(inputs.title)) }),
    },
  },
});

2. Conéctalo a la aplicación

// app.ts
import { Hono } from 'hono';
import { apcore, createApcore } from 'hono-apcore';
import { todoTools } from './todo.tools.js';

export const ap = createApcore({
  tools: todoTools,
  mcp: { name: 'my-app', explorer: true, allowExecute: true },
});

export const app = new Hono();
app.use('*', apcore(ap));
app.get('/todos', (c) => c.json(store.list()));

3. Arranca

// main.ts
import { serve } from '@hono/node-server';
import { app, ap } from './app.js';

await ap.init(app);              // register tools + scan routes
await ap.mountMcp(app);          // mount /mcp, /explorer, /health

serve({ fetch: app.fetch, port: 3000 });

Tu aplicación ahora responde:

• REST en http://localhost:3000/todos

• MCP en http://localhost:3000/mcp

• Tool Explorer en http://localhost:3000/explorer/

Dos formas de exponer una capacidad

defineTool() — herramientas explícitas

La contraparte de Hono al decorador @ApTool de NestJS. Hono no tiene clases ni contenedor de DI que decorar, por lo que una herramienta es un objeto plano que lleva su propio metadato y manejador.

import { defineTool } from 'hono-apcore';

const sendEmail = defineTool({
  namespace: 'email',
  name: 'send',                 // -> module id "email.send"
  description: 'Send an email',
  inputSchema: Type.Object({ to: Type.String(), body: Type.String() }),
  outputSchema: Type.Object({ messageId: Type.String() }),
  annotations: { readonly: false, destructive: false, requiresApproval: true },
  tags: ['email'],
  params: { to: 'Recipient address' },   // merged into the schema descriptions
  handler: async (inputs, context) => mailer.send(inputs, context),
});

Escaneo de rutas — herramientas sin intrusión

Apunta el escáner a una aplicación y cada ruta se convierte en un módulo que la reproduce en proceso a través de app.request():

const ap = createApcore({
  routes: {
    excludePaths: ['/health', '/mcp*', '/explorer*'],
    modulePrefix: 'api',
  },
});

await ap.init(app);   // -> api.todos.list, api.todos.get, api.todos.create, …

Los IDs de módulo provienen de la ruta y del verbo HTTP:

El esquema de entrada generado lleva una propiedad de cadena obligatoria por parámetro de ruta, más un objeto query de forma libre (GET/DELETE) o un objeto body (POST/PUT/PATCH). Sobrescribe cualquiera de ellos por ruta:

routes: {
  overrides: {
    'GET /todos': {
      id: 'todo.all',
      description: 'Every todo, newest first',
      inputSchema: Type.Object({ done: Type.Optional(Type.Boolean()) }),
      annotations: { readonly: true, idempotent: true },
    },
    'DELETE /admin/wipe': { skip: true },
  },
}

Debido a que la ejecución vuelve a pasar por app.request(), una llamada de IA ejecuta el mismo camino de código que una llamada HTTP — middleware de autenticación, validadores, manejadores de errores y todo. La identidad y las cabeceras de traza W3C del Context de apcore se reenvían a la petición reproducida.

Referencia de la API

createApcore(options)

Devuelve un HonoApcore — el Registry, el Executor y todas las superficies cuelgan de él.

createApcore({
  extensionsDir?: string | null,   // scanned by Registry.discover()
  acl?: ACL,                       // enforced by the Executor on every call
  middleware?: Middleware[],       // apcore middleware installed on the Executor
  bindings?: string,               // YAML bindings file loaded during init()
  tools?: ApToolDefinition[],      // registered during init()
  routes?: RouteScanOptions,       // route-scanner configuration
  settings?: Partial<ApcoreSettings>,  // overrides for the APCORE_* settings
  mcp?: ApcoreMcpOptions,          // presence enables the MCP surface
  cli?: ApcoreCliOptions,          // presence enables the CLI surface
  a2a?: ApcoreA2aOptions,          // presence enables the A2A surface
})

apcore(instance | options, middlewareOptions?)

Middleware de Hono que coloca la instancia y un Context de apcore por petición en el contexto de Hono.

app.use('*', apcore(ap));

app.get('/orders', async (c) =>
  c.json(await getApcore(c).executor.call('orders.list', {}, getApcoreContext(c))),
);

El mapa de variables se amplía, por lo que c.get('apcore') y c.get('apcoreContext') también están tipados. Pasa { skipContext: true } en rutas que nunca llaman a módulos, o { contextFactory } para conectar autenticación real.

HonoContextFactory

Construye el Context de apcore a partir de un contexto de Hono, una Request o Headers simples.

Resolución de identidad, en orden: x-user-id → Authorization: Bearer … (id de identidad "bearer") → una cabecera x-roles simple (un atajo de demostración) → anónimo. Una cabecera traceparent proporciona el id de traza; x-correlation-id (o x-request-id) aterriza en context.data.

new HonoContextFactory({
  resolveIdentity: (headers) => identityFromSession(headers),  // wins over the above
  data: (headers) => ({ tenant: headers.get('x-tenant') }),
});

MCP

ApcoreMcpService ejecuta el servidor MCP de dos maneras.

Integrado — un proceso, un puerto:

await ap.mountMcp(app, { endpoint: '/mcp', explorer: true, allowExecute: true });

Esto necesita los objetos de petición y respuesta de Node en bruto que @hono/node-server expone en c.env, por lo que es solo para Node; un manejador montado en otro runtime responde 501 con esa explicación. endpoint debe ser la ruta tal como la ve el servidor HTTP — incluye el prefijo si la aplicación está bajo un basePath.

Independiente — un puerto separado, o stdio para un servidor lanzado por CLI:

createApcore({ mcp: { transport: 'streamable-http', host: '0.0.0.0', port: 8000 } });
// init() starts it, because `transport` was set explicitly

Opciones clave de MCP:

Adaptadores de esquema

Los esquemas se auto-detectan y convierten mediante una cadena de prioridad:

La detección es estructural — ni TypeBox ni Zod se importan en tiempo de ejecución — por lo que cualquiera que instale la aplicación anfitriona (o ninguno) está bien. Registra el tuyo con SchemaExtractor.registerAdapter().

Enlaces YAML

Registra módulos sin tocar el código fuente:

bindings:
  - module_id: email.send
    target: EmailService.send
    description: Send an email
    input_schema:
      type: object
      properties:
        to: { type: string }
    tags: [email, mutate]
    annotations:
      readonly: false

import { resolverFromObjects } from 'hono-apcore';

await ap.loadBindings('./bindings.yaml', resolverFromObjects({ EmailService: mailer }));

En el otro sentido, writeBindingsFile() serializa los módulos escaneados de vuelta — que es lo que hace hono-apcore scan --format yaml.

CLI

hono-apcore scan   ./src/app.ts            # print the modules a scan would produce
hono-apcore scan   ./src/app.ts --format yaml --out bindings.yaml
hono-apcore serve  ./src/app.ts --transport http --port 8000 --explorer
hono-apcore export ./src/app.ts --out tools.json

La entrada es path[:export]; la exportación por defecto es default, luego app. Si el módulo exporta un HonoApcore bajo cualquier nombre, su configuración — filtros de ruta, prefijo de módulo, opciones de MCP — se respeta, por lo que scan informa exactamente los módulos que la propia aplicación registra; las banderas de CLI lo sobrescriben. Una entrada sin instancia también funciona, por lo que serve se ejecuta contra una aplicación que nunca ha oído hablar de apcore. Las entradas TypeScript necesitan un cargador:

npx tsx node_modules/.bin/hono-apcore scan ./src/app.ts

Configuración (APCORE_*)

La configuración canónica que implementa cada integración de apcore, leída del entorno y sobrescribible mediante settings:

Los pares opcionales no se reexportan

A diferencia del adaptador NestJS, hono-apcore no reexporta las superficies apcore-mcp / apcore-cli / apcore-a2a. Hacerlo haría que se cargaran de forma anticipada, y apcore-mcp incorpora node:http, lo que rompe una compilación de Workers, Deno o Bun de una aplicación que nunca usa la superficie MCP. Importa esos símbolos desde sus propios paquetes:

import { JWTAuthenticator, getCurrentIdentity } from 'apcore-mcp';
import { createCli } from 'apcore-cli';
import { A2AClient } from 'apcore-a2a';

apcore-js y apcore-toolkit sí son dependencias directas, por lo que sus símbolos comunes (ACL, Config, registerSysModules, TraceContext, BaseScanner, formatModules, …) se reexportan desde hono-apcore directamente.

Ejemplos

pnpm install && pnpm build
cd examples/demo && pnpm install && pnpm dev

Documentación detallada

• Resumen de funciones — arquitectura y grafo de dependencias

• Definición de herramientas — defineTool, defineToolset, IDs de módulo

• Escáner de rutas — cómo las rutas se convierten en módulos y qué cuesta la reproducción

• Integración MCP — integrado vs independiente, el puente Node

• Extracción de esquemas — la cadena de adaptadores y los adaptadores personalizados

• Contexto y ACL — identidad, trazabilidad y rutas gobernadas

Scripts

Licencia

Apache-2.0