xmcp: декларативный TypeScript-фреймворк для быстрой сборки серверов MCP

Протокол Model Context Protocol (MCP), предложенный создателями Claude, стремительно превратился в индустриальный стандарт подключения внешних инструментов к ИИ-агентам. Но если ты пробовал написать собственный MCP-сервер с нуля на официальном низкоуровневом SDK @modelcontextprotocol/sdk, то наверняка почувствовал легкую тоску.

Вместо того чтобы сосредоточиться на полезной логике инструмента (сходить в базу, дернуть API, прочитать файл), разработчик вынужден писать килобайты инфраструктурного клея: вручную настраивать каналы ввода-вывода (stdio или Server-Sent Events), регистрировать хэндлеры событий жизненного цикла, руками преобразовывать ошибки и клеить JSON-схемы.

Эту рутину берет на себя xmcp — элегантный и декларативный TypeScript-фреймворк от студии basementstudio (исходный код открыт в репозитории на GitHub).

Парадигма «инструмент — это файл»: файловый роутинг для агентов

Создатели xmcp перенесли в мир MCP ту самую концепцию, которая сделала популярными Next.js и Astro: файловую маршрутизацию (File System Routing).

Вместо одного раздутого файла server.ts, где свалены в кучу десятки функций, ты просто создаешь папку tools/. Каждый файл внутри этой папки автоматически становится изолированным инструментом для ИИ:

my-mcp-server/
├── tools/
│   ├── check-balance.ts
│   ├── send-notification.ts
│   └── query-database.ts
├── xmcp.config.ts
└── package.json

Рантайм xmcp сканирует каталог, автоматически регистрирует инструменты в протоколе, валидирует входящие параметры и формирует манифест возможностей.

Как пишется инструмент: строгая валидация через Zod

Внутри файла инструмента ты экспортируешь декларативную функцию defineTool:

// tools/create-invoice.ts
import { defineTool } from 'xmcp';
import { z } from 'zod';

export default defineTool({
  name: 'create_invoice',
  description: 'Создает счет на оплату для клиента в бухгалтерской системе',
  parameters: z.object({
    clientEmail: z.string().email().describe('Электронная почта получателя счета'),
    amount: z.number().positive().describe('Сумма счета в рублях'),
    currency: z.enum(['RUB', 'USD', 'EUR']).default('RUB'),
  }),
  async execute({ clientEmail, amount, currency }) {
    // Вся валидация уже выполнена рантаймом!
    const invoice = await billingService.create({ clientEmail, amount, currency });
    
    return {
      status: 'success',
      invoiceId: invoice.id,
      paymentUrl: invoice.url,
    };
  },
});

Обрати внимание на то, как исчез весь бойлерплейт: типизация аргументов в методе execute автоматически выводится из схемы parameters. Если агент передаст некорректный email или отрицательную сумму, xmcp перехватит ошибку до вызова бизнес-логики и вернет понятное для LLM сообщение об ошибке валидации.

Транспорты из коробки и режим быстрой разработки

Фреймворк берет на себя все низкоуровневые детали коммуникации:

• Двойной транспорт: сервер может работать как через стандартные потоки stdio (для локального подключения к Claude Desktop или Cursor), так и через протокол Server-Sent Events (SSE) по HTTP для удалённого хостинга в облаке.
• Горячая перезагрузка (Hot Reload): команда npx xmcp dev запускает локальный сервер с моментальным обновлением инструментов при сохранении файла — больше не нужно перезапускать процесс вручную после каждой правки промпта или схемы.

# Старт сервера в режиме разработки с отслеживанием изменений
npx xmcp dev

# Компиляция готового оптимизированного бандла для продакшена
npx xmcp build

Если ты уже используешь терминальные инструменты для ИИ, обрати внимание на наш материал про плагины для Claude Code и перехват опасных команд. А с появлением xmcp порог создания собственных масштабируемых серверов MCP снизился буквально до пяти минут.