Модуль сервера NestJS MCP

Покрытие кода Версия НПМ Загрузки НПМ Лицензия НПМ

Модуль NestJS для легкого предоставления инструментов, ресурсов и подсказок для ИИ из ваших приложений NestJS с использованием протокола контекста модели (MCP) .

С помощью @rekog/mcp-nest вы определяете инструменты, ресурсы и запросы так, как это привычно в NestJS, и используете всю мощь внедрения зависимостей, чтобы использовать существующую кодовую базу для создания сложных корпоративных серверов MCP.

Функции

🚀 Поддержка всех типов транспорта:
- Потоковое HTTP
- HTTP+SSE
- СТДИО
🔍 Автоматическое обнаружение и регистрация tool , resource и prompt
💯 Проверка вызова инструмента на основе Zod
📊 Уведомления о ходе выполнения
🔒 Аутентификация на основе Guard
🌐 Доступ к информации HTTP-запроса в ресурсах MCP (инструменты, ресурсы, подсказки)

Related MCP server: SSE MCP Server

Установка

npm install @rekog/mcp-nest @modelcontextprotocol/sdk zod

Быстрый старт

1. Модуль импорта

// app.module.ts import { Module } from '@nestjs/common'; import { McpModule } from '@rekog/mcp-nest'; import { GreetingTool } from './greeting.tool'; @Module({ imports: [ McpModule.forRoot({ name: 'my-mcp-server', version: '1.0.0', }), ], providers: [GreetingTool], }) export class AppModule {}

2. Определите инструменты и ресурсы

// greeting.tool.ts import type { Request } from 'express'; import { Injectable } from '@nestjs/common'; import { Tool, Resource, Context } from '@rekog/mcp-nest'; import { z } from 'zod'; import { Progress } from '@modelcontextprotocol/sdk/types'; @Injectable() export class GreetingTool { constructor() {} @Tool({ name: 'hello-world', description: 'Returns a greeting and simulates a long operation with progress updates', parameters: z.object({ name: z.string().default('World'), }), }) async sayHello({ name }, context: Context, request: Request) { const userAgent = request.get('user-agent') || 'Unknown'; const greeting = `Hello, ${name}! Your user agent is: ${userAgent}`; const totalSteps = 5; for (let i = 0; i < totalSteps; i++) { await new Promise((resolve) => setTimeout(resolve, 100)); // Send a progress update. await context.reportProgress({ progress: (i + 1) * 20, total: 100, } as Progress); } return { content: [{ type: 'text', text: greeting }], }; } @Resource({ uri: 'mcp://hello-world/{userName}', name: 'Hello World', description: 'A simple greeting resource', mimeType: 'text/plain', }) // Different from the SDK, we put the parameters and URI in the same object. async getCurrentSchema({ uri, userName }) { return { content: [ { uri, text: `User is ${userName}`, mimeType: 'text/plain', }, ], }; } }

Готово!

TIP

В примере выше показано, как осуществляется доступ к заголовкам HTTP-Request в MCP Tools. Это полезно для идентификации пользователей, добавления клиентской логики и многих других вариантов использования. Дополнительные примеры см. в разделе Тесты аутентификации .

Быстрый старт для STDIO

Главное отличие заключается в том, что при импорте модуля необходимо указать опцию transport .

McpModule.forRoot({ name: 'playground-stdio-server', version: '0.0.1', transport: McpTransportType.STDIO, });

Остальное то же самое, вы можете определить инструменты, ресурсы и подсказки как обычно. Пример автономного приложения NestJS, использующего транспорт STDIO, следующий:

async function bootstrap() { const app = await NestFactory.createApplicationContext(AppModule, { logger: false, }); return app.close(); } void bootstrap();

Далее вы можете использовать сервер MCP с клиентом MCP Stdio ( см. пример ) или после сборки проекта вы можете использовать его со следующей конфигурацией клиента MCP:

{ "mcpServers": { "greeting": { "command": "node", "args": [ "<path to dist js file>", ] } } }

Конечные точки API

Транспорт HTTP+SSE предоставляет две конечные точки:

GET /sse : конечная точка соединения SSE (защищена защитой, если настроена)
POST /messages : Конечная точка выполнения инструмента (защищена защитой, если настроена)

Потоковый HTTP-транспорт предоставляет следующие конечные точки:

POST /mcp : Основная конечная точка для всех операций MCP (выполнение инструмента, доступ к ресурсам и т. д.). В режиме сохранения состояния создает и поддерживает сеансы.
GET /mcp : Устанавливает потоки Server-Sent Events (SSE) для обновлений в реальном времени и уведомлений о ходе выполнения. Доступно только в режиме с отслеживанием состояния.
DELETE /mcp : Завершает сеансы MCP. Доступно только в режиме с отслеживанием состояния.

Советы

Можно использовать модуль с глобальным префиксом, но рекомендуется исключить эти конечные точки с помощью:

app.setGlobalPrefix('/api', { exclude: ['sse', 'messages', 'mcp'] });

Аутентификация

Вы можете защитить свои конечные точки MCP с помощью стандартных средств защиты NestJS.

1. Создайте стражу

Реализуйте интерфейс CanActivate . Guard должен обрабатывать проверку запроса (например, проверку JWT, ключей API) и опционально прикреплять информацию о пользователе к объекту запроса.

Ничего особенного, более подробную информацию можно найти в документации NestJS.

2. Применить защиту

Передайте ваши защитные меры в конфигурацию McpModule.forRoot . Защитные меры будут применены к обеим конечным точкам /sse и /messages .

// app.module.ts import { Module } from '@nestjs/common'; import { McpModule } from '@rekog/mcp-nest'; import { GreetingTool } from './greeting.tool'; import { AuthGuard } from './auth.guard'; @Module({ imports: [ McpModule.forRoot({ name: 'my-mcp-server', version: '1.0.0', guards: [AuthGuard], // Apply the guard here }), ], providers: [GreetingTool, AuthGuard], // Ensure the Guard is also provided }) export class AppModule {}

Вот и все! Остальное то же самое, что и у NestJS Guards.

Детская площадка

Каталог playground содержит примеры для быстрого тестирования функций MCP и @rekog/mcp-nest . Более подробную информацию см. в playground/README.md .

Конфигурация

Метод McpModule.forRoot() принимает объект McpOptions для настройки сервера. Вот доступные параметры:

Вариант	Описание	По умолчанию
`name`	Обязательно. Имя вашего MCP-сервера.	-
`version`	Обязательно. Версия вашего сервера MCP.	-
`capabilities`	Дополнительные возможности сервера MCP для рекламы. См. @modelcontextprotocol/sdk .	`undefined`
`instructions`	Дополнительные инструкции для клиента по взаимодействию с сервером.	`undefined`
`transport`	Указывает тип(ы) транспорта, которые необходимо включить.	`[McpTransportType.SSE, McpTransportType.STREAMABLE_HTTP, McpTransportType.STDIO]`
`sseEndpoint`	Путь конечной точки для соединения SSE (используется с транспортом `SSE` ).	`'sse'`
`messagesEndpoint`	Конечный путь для отправки сообщений (используется с транспортом `SSE` ).	`'messages'`
`mcpEndpoint`	Базовый путь конечной точки для операций MCP (используется с транспортом `STREAMABLE_HTTP` ).	`'mcp'`
`globalApiPrefix`	Глобальный префикс для всех конечных точек MCP. Полезно при интеграции в существующее приложение.	`''`
`guards`	Массив NestJS Guards для применения к конечным точкам MCP для аутентификации/авторизации.	`[]`
`decorators`	Массив декораторов классов NestJS для применения к сгенерированным контроллерам MCP.	`[]`
`sse`	Конфигурация, специфичная для транспорта `SSE` .	`{ pingEnabled: true, pingIntervalMs: 30000 }`
`sse.pingEnabled`	Следует ли включать периодические сообщения SSE ping для поддержания соединения.	`true`
`sse.pingIntervalMs`	Интервал (в миллисекундах) отправки сообщений SSE ping.	`30000`
`streamableHttp`	Конфигурация, специфичная для транспорта `STREAMABLE_HTTP` .	`{ enableJsonResponse: true, sessionIdGenerator: undefined, statelessMode: true }`
`streamableHttp.enableJsonResponse`	Если `true` , позволяет конечной точке `/mcp` возвращать ответы JSON для непотоковых запросов (например, `listTools` ).	`true`
`streamableHttp.sessionIdGenerator`	Функция для генерации уникальных идентификаторов сеансов при работе в режиме с сохранением состояния. Требуется, если `statelessMode` имеет значение `false` .	`undefined`
`streamableHttp.statelessMode`	Если `true` , транспорт `STREAMABLE_HTTP` работает без сохранения состояния (без сессий). Если `false` , он работает с сохранением состояния, требуя `sessionIdGenerator` .	`true`

NestJS MCP Server Module