Vovk.ts: cómo convertir endpoints de Next.js en herramientas para agentes de IANota · digest del 27 de octubre
Modelo isométrico en 3D de la arquitectura de Vovk.ts que proyecta un único controlador de Next.js en un endpoint HTTP, un cliente RPC y una herramienta MCP.
Nota2 secciones≈ 4 min

Vovk.ts: cómo convertir endpoints de Next.js en herramientas para agentes de IA

Si desarrollas aplicaciones web con Next.js y sigues el auge de los agentes de IA autónomos, seguro que te has topado con un dilema arquitectónico incómodo.

Ya tienes tu proyecto funcionando en Next.js App Router: en la carpeta app/api hay decenas de route handlers, la autenticación está lista, la base de datos conectada y la validación montada con Zod. De pronto llega el requisito de negocio: «Conectemos un agente con Claude o un LLM local a nuestro servicio para que pueda crear pedidos, generar facturas o consultar stock mediante Model Context Protocol (MCP)».

¿Cómo se resuelve esto a la manera tradicional? El desarrollador se sienta y empieza a duplicar código: crea un repositorio aparte para el servidor MCP, describe manualmente los esquemas de parámetros, repite las llamadas a la base de datos o hace de proxy hacia peticiones HTTP. Al final acabas con dos bases de código paralelas que se desincronizan en cuanto cambias la firma de un método.

Ese dolor de cabeza lo elimina con elegancia la librería abierta Vovk.ts (su código fuente está en el repositorio de GitHub).

El principio del procedimiento único: un endpoint para la web y para la IA

La idea arquitectónica de Vovk.ts es brillantemente simple: el principio del procedimiento único (Unified Procedure). Describes la lógica de negocio de un método una sola vez dentro de la estructura de Next.js, y la librería genera al vuelo tres proyecciones independientes:

  1. Un endpoint HTTP estándar de Next.js Route Handler.
  2. Un cliente RPC estrictamente tipado para invocarlo desde componentes frontend sin generación previa de código (al estilo de tRPC).
  3. ¡Una herramienta (Tool) para el protocolo Model Context Protocol (MCP) con su esquema JSON de argumentos listo para el agente de IA!

Veamos cómo luce esto en código real:

// app/api/controllers/OrdersController.ts
import { prefix, get, post } from 'vovk';
import { z } from 'zod';

const CreateOrderSchema = z.object({
  customerId: z.string().describe('ID único del cliente'),
  itemsCount: z.number().int().positive().describe('Cantidad de artículos en el pedido'),
  totalAmount: z.number().describe('Importe total en rublos'),
});

@prefix('orders')
export class OrdersController {
  @post('create')
  async createOrder({ body }: { body: z.infer<typeof CreateOrderSchema> }) {
    // Tu lógica de negocio habitual con la base de datos
    const order = await db.orders.create({ data: body });
    return { success: true, orderId: order.id };
  }
}

Y ahora viene la magia: para exponer este endpoint a un asistente de IA en Claude Desktop o Cursor, te basta con conectar el handler MCP generado:

// app/api/mcp/route.ts
import { createMcpHandler } from 'vovk/mcp';
import { OrdersController } from '../controllers/OrdersController';

// Exportación automática de herramientas MCP con esquemas Zod
export const { GET, POST } = createMcpHandler({
  controllers: [OrdersController],
  serverInfo: {
    name: 'store-management-mcp',
    version: '1.0.0',
  },
});

Por qué esto cambia el desarrollo para agentes de IA

Ya no necesitas mantener un zoológico de microservicios:

  • Cero desincronización de tipos: si cambias un campo en el esquema Zod, TypeScript marca al instante los errores en el frontend y el agente recibe la especificación de argumentos actualizada sin reiniciar ni reescribir manifiestos.
  • Autenticación unificada: todas las sesiones de Next.js, cookies y tokens JWT siguen funcionando tal cual.
  • Ecosistema de documentación: además de MCP, Vovk.ts sabe exportar OpenAPI 3.1 limpio. Si necesitas generar portales autónomos de documentación a partir de especificaciones OpenAPI y MCP, échale un vistazo a nuestro análisis de Sourcey: generador de portales estáticos de documentación.

Vovk.ts convierte un monolito o API existente en Next.js en una pasarela completa de herramientas para IA en literalmente 15 minutos.

Quiero un análisis detalladoLos votos ayudan a elegir qué analizar a fondo. Este material tiene 0 votos.
Fuentes · 3