Vovk.ts: как превратить эндпоинты Next.js в инструменты для ИИ-агентов

Если ты разрабатываешь веб-приложения на Next.js и следишь за бумом автономных ИИ-агентов, то наверняка сталкивался с неприятной архитектурной дилеммой.

У тебя уже есть готовый проект на Next.js App Router: в папке app/api написаны десятки роут-хендлеров, настроена авторизация, подключена база данных и валидация через Zod. И тут появляется бизнес-задача: «Давайте подключим к нашему сервису агента на базе Claude или локальной LLM, чтобы он мог через Model Context Protocol (MCP) сам создавать заказы, генерировать счета или проверять остатки на складе».

Как это решается по старинке? Разработчик садится и начинает дублировать код: создаёт отдельный репозиторий с MCP-сервером, вручную описывает схемы параметров, дублирует вызовы к базе данных или проксирует HTTP-запросы. В итоге в проекте появляются две параллельные кодовые базы, которые мгновенно рассинхронизируются при первой же правке сигнатуры метода.

Эту головную боль элегантно снимает открытая библиотека Vovk.ts (исходный код доступен в репозитории на GitHub).

Принцип единой процедуры: один эндпоинт для веба и для ИИ

Архитектурная идея Vovk.ts гениально проста: принцип единой процедуры (Unified Procedure). Ты описываешь бизнес-логику метода ровно один раз прямо в структуре Next.js, а библиотека на лету генерирует три независимые проекции:

1. Стандартный HTTP эндпоинт Next.js Route Handler.
2. Строго типизированный RPC-клиент для вызова из фронтенд-компонентов без кодогенерации (в духе tRPC).
3. Инструмент (Tool) для протокола Model Context Protocol (MCP) с готовой JSON-схемой аргументов для ИИ-агента!

Давай посмотрим, как это выглядит в реальном коде:

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

const CreateOrderSchema = z.object({
  customerId: z.string().describe('Уникальный ID клиента'),
  itemsCount: z.number().int().positive().describe('Количество позиций в заказе'),
  totalAmount: z.number().describe('Итоговая сумма в рублях'),
});

@prefix('orders')
export class OrdersController {
  @post('create')
  async createOrder({ body }: { body: z.infer<typeof CreateOrderSchema> }) {
    // Твоя обычная бизнес-логика работы с базой данных
    const order = await db.orders.create({ data: body });
    return { success: true, orderId: order.id };
  }
}

А теперь магия: чтобы сделать этот эндпоинт доступным для ИИ-ассистента в Claude Desktop или Cursor, тебе достаточно подключить сгенерированный MCP-воркер:

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

// Автоматический экспорт инструментов MCP со схемами Zod
export const { GET, POST } = createMcpHandler({
  controllers: [OrdersController],
  serverInfo: {
    name: 'store-management-mcp',
    version: '1.0.0',
  },
});

Почему это меняет разработку под ИИ-агентов

Тебе больше не нужно поддерживать зоопарк микросервисов:

• Никакой рассинхронизации типов: если ты поменял поле в схеме Zod, TypeScript мгновенно подсветит ошибки на фронтенде, а агент получит обновлённую спецификацию аргументов без перезапуска и переписывания манифестов.
• Единая авторизация: все сессии Next.js, cookies и JWT-токены продолжают работать штатно.
• Экосистема документации: помимо MCP, Vovk.ts умеет выгружать чистый OpenAPI 3.1. Если тебе требуется собирать автономные порталы документации по спецификациям OpenAPI и MCP, взгляни на наш обзор Sourcey: генератор статических порталов документации.

Vovk.ts превращает существующий монолит или API на Next.js в полноценный шлюз инструментов для ИИ буквально за 15 минут.