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

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

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

Функции

• 🚀 Поддержка всех типов транспорта:

  • Потоковое HTTP

  • HTTP+SSE

  • СТДИО

• 🔍 Автоматическое обнаружение и регистрация tool , resource и prompt

• 💯 Проверка вызова инструмента на основе Zod

• 📊 Уведомления о ходе выполнения

• 🔒 Аутентификация на основе Guard

• 🌐 Доступ к информации HTTP-запроса в ресурсах MCP (инструменты, ресурсы, подсказки)

Related MCP server: mcp-nestjs

Установка

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 для настройки сервера. Вот доступные параметры: