@muzikanto/nestjs-mcp 1.2.0 → 1.5.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @muzikanto/nestjs-mcp
 
+## 1.5.0
+
+### Minor Changes
+
+- add UseFilters support
+
+## 1.4.0
+
+### Minor Changes
+
+- Dynamic tools, prompts, resources initialization
+
+## 1.3.0
+
+### Minor Changes
+
+- a5c79ec: add guards and interceptors
+
 ## 1.2.0
 
 ### Minor Changes

package/README.md

@@ -1,7 +1,7 @@
 # @muzikanto/nestjs-mcp
 
 [![npm](https://img.shields.io/npm/v/@muzikanto/nestjs-mcp)](https://www.npmjs.com/package/@muzikanto/nestjs-mcp)
-[![downloads](https://img.shields.io/npm/dt/@muzikanto/nestjs-mcp)]((https://www.npmjs.com/package/@muzikanto/nestjs-mcp))
+[![downloads](https://img.shields.io/npm/dt/@muzikanto/nestjs-mcp)](<(https://www.npmjs.com/package/@muzikanto/nestjs-mcp)>)
 [![GitHub stars](https://img.shields.io/github/stars/Muzikanto/nestjs-mcp?style=social)](https://github.com/Muzikanto/nestjs-mcp)
 [![License](https://img.shields.io/npm/l/@muzikanto/nestjs-mcp)](https://github.com/Muzikanto/nestjs-mcp/blob/main/LICENSE)
 
@@ -10,6 +10,7 @@ NestJS MCP (Model Context Protocol) module — allows you to create “tools”,
 ---
 
 ## Contents
+
 - [Features](#features)
 - [Installation](#installation)
 - [Usage](#usage)
@@ -17,11 +18,18 @@ NestJS MCP (Model Context Protocol) module — allows you to create “tools”,
   - [Create MCP tool](#create-mcp-tool)
   - [Create MCP prompt](#create-mcp-prompt)
   - [Create MCP resource](#create-mcp-resource)
+  - [Dynamic creation](#dynamic-creation)
   - [Calling MCP tools via HTTP](#calling-mcp-tools-via-http)
   - [Calling MCP prompt via HTTP](#obtain-prompt)
   - [Obtaining all tools](#obtaining-all-tools)
   - [Obtaining all prompts](#obtaining-all-prompts)
-  - [Auth guard](#auth-guard)
+  - [Guards](#guards)
+    - [For one](#for-one)
+    - [For all](#for-all)
+  - [Interceptors](#interceptors)
+    - [For one](#for-one-1)
+    - [For all](#for-all-1)
+  - [Filters](#filters)
   - [Integration with OpenAI Function Calls](#integration-with-openai-function-calls)
 
 ## Features
@@ -30,13 +38,15 @@ NestJS MCP (Model Context Protocol) module — allows you to create “tools”,
 - Register MCP prompts using the `@McpPrompt()` decorator
 - Automatic detection of all providers (tools) in the module
 - Input data validation
-- SSE endpoints for MCP  (`GET /mcp/sse, POST /mcp/messages`)
-- Endpoint for calling tool (`POST /mcp/toos`)  
-- Endpoint for a list of all tools (`GET /mcp/tools`)  
+- SSE endpoints for MCP (`GET /mcp/sse, POST /mcp/messages`)
+- Endpoint for calling tool (`POST /mcp/toos`)
+- Endpoint for a list of all tools (`GET /mcp/tools`)
 - Endpoint for calling prompt (`POST /mcp/prompts/:name`)
-- Endpoint for a list of all prompts (`GET /mcp/prompts`)  
-- Easy integration with LLM (OpenAI Function Calls)  
-- Full TypeScript typing  
+- Endpoint for a list of all prompts (`GET /mcp/prompts`)
+- Easy integration with LLM (OpenAI Function Calls)
+- Support http adapters (default fastify)
+- Full TypeScript typing
+- Support `@UseGuards`, `@UseInterceptors`, `@UseFilters`
 
 ---
 
@@ -46,17 +56,17 @@ NestJS MCP (Model Context Protocol) module — allows you to create “tools”,
 yarn add @muzikanto/nestjs-mcp
 ```
 
-Peer dependencies: `@nestjs/common, @nestjs/core, reflect-metadata`
+Peer dependencies: `@nestjs/common, @nestjs/core, @nestjs/swagger, reflect-metadata`
 
 ## Usage
 
 ### Connecting the MCP module
 
 ```ts
-import { Module } from '@nestjs/common';
-import { McpModule } from '@muzikanto/nestjs-mcp';
-import { TelegramSendMessageTool } from './tools/telegram-send-message.tool';
-import { TelegramAutoReplyPrompt } from './prompts/telegram-auto-reply.prompt';
+import { Module } from "@nestjs/common";
+import { McpModule } from "@muzikanto/nestjs-mcp";
+import { TelegramSendMessageTool } from "./tools/telegram-send-message.tool";
+import { TelegramAutoReplyPrompt } from "./prompts/telegram-auto-reply.prompt";
 
 @Module({
   imports: [
@@ -71,13 +81,13 @@ export class AppModule {}
 ### Create MCP tool
 
 ```ts
-import { IMcpTool, McpTool } from '@muzikanto/nestjs-mcp';
-import { Telegraf } from 'telegraf';
-import z from 'zod';
+import { IMcpTool, McpTool } from "@muzikanto/nestjs-mcp";
+import { Telegraf } from "telegraf";
+import z from "zod";
 
 const schema = {
-  chatId: z.string().describe('Telegram chat id'),  // строка с описанием
-  text: z.string().describe('Message text'),  // строка с описанием
+  chatId: z.string().describe("Telegram chat id"), // строка с описанием
+  text: z.string().describe("Message text"), // строка с описанием
 };
 
 @McpTool()
@@ -85,7 +95,7 @@ export class TelegramSendMessageTool implements IMcpTool<
   { chatId: string; text: string },
   { success: boolean }
 > {
-  name = 'telegram.sendMessage';
+  name = "telegram.sendMessage";
 
   inputSchema = schema;
 
@@ -112,7 +122,8 @@ POST /mcp
 }
 ```
 
-Ответ 
+Ответ
+
 ```json
 {
   "data": {
@@ -133,7 +144,7 @@ GET /mcp/tool
     "inputSchema": {
       "type": "object",
       "properties": {
-          "chatId": {
+        "chatId": {
           "type": "number",
           "description": "Telegram chat ID"
         },
@@ -142,10 +153,7 @@ GET /mcp/tool
           "description": "Message text"
         }
       },
-      "required": [
-          "chatId",
-          "text"
-      ]
+      "required": ["chatId", "text"]
     }
   }
 ]
@@ -154,29 +162,33 @@ GET /mcp/tool
 ### Create MCP prompt
 
 ```ts
-import { IMcpPrompt, McpPrompt } from '@muzikanto/nestjs-mcp';
-import z from 'zod';
+import { IMcpPrompt, McpPrompt } from "@muzikanto/nestjs-mcp";
+import z from "zod";
 
 const schema = {
-  chatId: z.string().describe('Telegram chat id'),  // строка с описанием
-  text: z.string().describe('Message text'),  // строка с описанием
+  chatId: z.string().describe("Telegram chat id"), // строка с описанием
+  text: z.string().describe("Message text"), // строка с описанием
 };
 
 @McpPrompt()
-export class TelegramAutoReplyPrompt implements IMcpPrompt<{ text: string; chatId: number; }> {
-  name = 'telegram_auto_reply';
-  description = 'Generate a short, fiendly reply to an incoming Telegram message and send it back to the same chat using teegram.sendMessage tool';
+export class TelegramAutoReplyPrompt implements IMcpPrompt<{
+  text: string;
+  chatId: number;
+}> {
+  name = "telegram_auto_reply";
+  description =
+    "Generate a short, fiendly reply to an incoming Telegram message and send it back to the same chat using teegram.sendMessage tool";
   schema = schema;
 
   async execute({ text, chatId }: { text: string; chatId: number }) {
     return [
       {
         role: "system",
-        content: `You are a friendly Telegram bot. Reply briefly and to the point.`
+        content: `You are a friendly Telegram bot. Reply briefly and to the point.`,
       },
       {
         role: "user",
-        content: text
+        content: text,
       },
       {
         role: "assistant",
@@ -184,10 +196,10 @@ export class TelegramAutoReplyPrompt implements IMcpPrompt<{ text: string; chatI
           name: "telegram.sendMessage",
           arguments: {
             chatId,
-            text: "{{model_output}}"
-          }
-        }
-      }
+            text: "{{model_output}}",
+          },
+        },
+      },
     ];
   }
 }
@@ -205,7 +217,7 @@ GET /mcp/prompts
     "inputSchema": {
       "type": "object",
       "properties": {
-          "chatId": {
+        "chatId": {
           "type": "number",
           "description": "Telegram chat ID"
         },
@@ -214,10 +226,7 @@ GET /mcp/prompts
           "description": "Message text"
         }
       },
-      "required": [
-          "chatId",
-          "text"
-      ]
+      "required": ["chatId", "text"]
     }
   }
 ]
@@ -235,42 +244,43 @@ POST /mcp/prompts/telegram_auto_reply
 ```
 
 Response
+
 ```json
 {
   "messages": [
-      {
-        "role": "system",
-        "content": "You are a friendly Telegram bot. Reply briefly and to the point."
-      },
-      {
-        "role": "user",
-        "content": "Hi. How are you ?"
-      },
-      {
-        "role": "assistant",
-        "tool_call": {
-          "name": "telegram.sendMessage",
-          "arguments": {
-            "chatId": 100000000,
-            "text": "{{model_output}}"
-          }
+    {
+      "role": "system",
+      "content": "You are a friendly Telegram bot. Reply briefly and to the point."
+    },
+    {
+      "role": "user",
+      "content": "Hi. How are you ?"
+    },
+    {
+      "role": "assistant",
+      "tool_call": {
+        "name": "telegram.sendMessage",
+        "arguments": {
+          "chatId": 100000000,
+          "text": "{{model_output}}"
         }
       }
-    ]
+    }
+  ]
 }
 ```
 
 ### Create MCP resource
 
 ```ts
-import { IMcpResource, McpResource } from '@muzikanto/nestjs-mcp';
+import { IMcpResource, McpResource } from "@muzikanto/nestjs-mcp";
 
 @McpResource()
 export class TestResource implements IMcpResource<{ userId: string }> {
-  name = 'users.get';
-  uri = 'users://{userId}';
-  title = 'Get test user';
-  description = 'Get user by id';
+  name = "users.get";
+  uri = "users://{userId}";
+  title = "Get test user";
+  description = "Get user by id";
 
   async execute(url: URL, vars: { userId: string }) {
     return [{ uri: url.href, text: `Hello ${vars.userId}` }];
@@ -278,29 +288,207 @@ export class TestResource implements IMcpResource<{ userId: string }> {
 }
 ```
 
-### Auth guard
+### Dynamic creation
+
 ```ts
-import { McpModule } from '@muzikanto/nestjs-mcp';
-import { Module, CanActivate, ExecutionContext, Injectable } from "@nestjs/common";
+import { McpDynamicService } from "@muzikanto/nestjs-mcp";
+import { Injectable } from "@nestjs/common";
+import { ExampleInterceptor } from "./example.interceptor";
+import { ExampleGuard } from "./example.guard";
 
 @Injectable()
-export class TestGuard implements CanActivate {
-    canActivate(context: ExecutionContext): Promise<boolean> {
-      const request = context.switchToHttp().getRequest();
-      const authHeader = request.headers['authorization'];
-    
-      return true;
-    }
+export class McpDynamic {
+  constructor(protected readonly mcpDynamicService: McpDynamicService) {}
+
+  onModuleInit() {
+    this.mcpDynamicService.registerTool({
+      name: "dynamic_tool",
+      title: "Dynamic tool",
+      execute: () => Promise.resolve("test"),
+      guards: [ExampleGuard],
+      interceptors: [ExampleInterceptor],
+    });
+
+    this.mcpDynamicService.registerPrompt({
+      name: "dynamic_prompt",
+      title: "Dynamic prompt",
+      execute: () => Promise.resolve([{ role: "assistant", content: "test" }]),
+      guards: [ExampleGuard],
+      interceptors: [ExampleInterceptor],
+    });
+
+    this.mcpDynamicService.registerResource<{ testId: string }>({
+      name: "dynamic_resource",
+      title: "Dynamic resource",
+      uri: "dynamic://test/{testId}",
+      execute: (uri, input) =>
+        Promise.resolve([{ uri: uri.href, text: `ID: ${input.testId}` }]),
+      guards: [ExampleGuard],
+      interceptors: [ExampleInterceptor],
+    });
+  }
+}
+```
+
+### Guards
+
+### For one
+
+```ts
+import { IMcpTool, McpTool } from "@muzikanto/nestjs-mcp";
+import { UseGuards } from "@nestjs/common";
+import { CanActivate, ExecutionContext, Injectable } from "@nestjs/common";
+import { Observable } from "rxjs";
+
+@Injectable()
+class TestGuard implements CanActivate {
+  canActivate(
+    context: ExecutionContext,
+  ): boolean | Promise<boolean> | Observable<boolean> {
+    console.log("TestGuard called");
+    return true;
+  }
 }
 
+@UseGuard(TestGuard)
+@McpTool()
+export class TelegramSendMessageTool implements IMcpTool<
+  { chatId: string; text: string },
+  { success: boolean }
+> {
+  name = "telegram.sendMessage";
+
+  async execute() {
+    await this.bot.telegram.sendMessage(input.chatId, input.text);
+    return { success: true };
+  }
+}
+```
+
+#### For all
+
+```ts
+import { McpModule } from "@muzikanto/nestjs-mcp";
+import { Module } from "@nestjs/common";
+import { TestGuard } from "./other/test.guard";
+import { ToolWithoutGuards } from "./test.tool";
+import { APP_GUARD } from "@nestjs/core";
+
 @Module({
   imports: [
     McpModule.forRoot({
-      guard: TestGuard
+      providers: [
+        ToolWithoutGuards,
+        TestGuard,
+        { provide: APP_GUARD, useExisting: TestGuard },
+      ],
     }),
   ],
 })
-export class AppModule {}
+export class TestModule {}
+```
+
+### Interceptors
+
+#### For one
+
+```ts
+import { IMcpTool, McpTool } from "@muzikanto/nestjs-mcp";
+import {
+  ExecutionContext,
+  NestInterceptor,
+  CallHandler,
+  Injectable,
+  UseInterceptors,
+} from "@nestjs/common";
+import { map } from "rxjs";
+
+@Injectable()
+export class ExampleInterceptor implements NestInterceptor {
+  intercept(context: ExecutionContext, next: CallHandler) {
+    console.log("Before execute");
+
+    return next.handle().pipe(
+      map((data: unknown) => {
+        console.log("After execute", data);
+
+        return data;
+      }),
+    );
+  }
+}
+
+@UseInterceptors(TestInterceptor)
+@McpTool()
+export class TelegramSendMessageTool implements IMcpTool<
+  { chatId: string; text: string },
+  { success: boolean }
+> {
+  name = "telegram.sendMessage";
+
+  async execute() {
+    await this.bot.telegram.sendMessage(input.chatId, input.text);
+    return { success: true };
+  }
+}
+```
+
+#### For all
+
+```ts
+import { McpModule } from "@muzikanto/nestjs-mcp";
+import { Module } from "@nestjs/common";
+import { TestInterceptor } from "./other/test.interceptor";
+import { ToolWithoutInterceptors } from "./test.tool";
+import { APP_INTERCEPTOR } from "@nestjs/core";
+
+@Module({
+  imports: [
+    McpModule.forRoot({
+      providers: [
+        ToolWithoutInterceptors,
+        TestGuard,
+        { provide: APP_INTERCEPTOR, useExisting: TestInterceptor },
+      ],
+    }),
+  ],
+})
+export class TestModule {}
+```
+
+### Fitlers
+
+```ts
+import { IMcpTool, McpTool } from "@muzikanto/nestjs-mcp";
+import {
+  ExceptionFilter,
+  Catch,
+  ArgumentsHost,
+  NotImplementedException,
+  UseFilters,
+} from "@nestjs/common";
+
+@Catch(NotImplementedException)
+class ExampleFilter implements ExceptionFilter {
+  catch(exception: unknown, host: ArgumentsHost) {
+    return {
+      message: (exception as Error).message,
+    };
+  }
+}
+
+@UseFilters(ExampleFilter)
+@McpTool()
+export class TelegramSendMessageTool implements IMcpTool<
+  { chatId: string; text: string },
+  { success: boolean }
+> {
+  name = "telegram.sendMessage";
+
+  async execute() {
+    throw new NotImplementedException();
+  }
+}
 ```
 
 ### Integration with OpenAI Function Calls
@@ -368,7 +556,9 @@ async function callMcpTool(toolName: string, payload: Record<string, any>) {
 ```
 
 ## Contributing
+
 Contributions are welcome! Please open issues or submit PRs.
 
 ## Changelog
+
 See [CHANGELOG](https://github.com/Muzikanto/nestjs-mcp/blob/main/CHANGELOG.md) for detailed version history and updates.

package/dist/index.d.ts

@@ -4,3 +4,4 @@ export * from "./mcp-server/decorators/mcp-prompt.decorator";
 export * from "./mcp-server/decorators/mcp-resource.decorator";
 export * from "./mcp-client/mcp-client.module";
 export * from "./mcp-client/mcp-client.service";
+export * from "./mcp-server/mcp-dynamic.service";

package/dist/index.js

@@ -20,3 +20,4 @@ __exportStar(require("./mcp-server/decorators/mcp-prompt.decorator"), exports);
 __exportStar(require("./mcp-server/decorators/mcp-resource.decorator"), exports);
 __exportStar(require("./mcp-client/mcp-client.module"), exports);
 __exportStar(require("./mcp-client/mcp-client.service"), exports);
+__exportStar(require("./mcp-server/mcp-dynamic.service"), exports);

package/dist/mcp-server/config.d.ts

@@ -0,0 +1,6 @@
+import { IHttpAdapter } from "./utils/http-adapter";
+export declare const MCP_CONFIG_TOKEN = "mcl:config-token";
+export type IMcpConfig = {
+    httpAdapter: IHttpAdapter;
+};
+export declare const InjectMcpConfig: () => PropertyDecorator & ParameterDecorator;

package/dist/mcp-server/config.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InjectMcpConfig = exports.MCP_CONFIG_TOKEN = void 0;
+const common_1 = require("@nestjs/common");
+exports.MCP_CONFIG_TOKEN = "mcl:config-token";
+const InjectMcpConfig = () => (0, common_1.Inject)(exports.MCP_CONFIG_TOKEN);
+exports.InjectMcpConfig = InjectMcpConfig;

package/dist/mcp-server/decorators/mcp-tool.decorator.d.ts

@@ -2,19 +2,16 @@ import "reflect-metadata";
 import type * as z3 from "zod/v3";
 type AnySchema = z3.ZodTypeAny;
 type ZodRawShapeCompat = Record<string, AnySchema>;
-export type IMcpToolContext = {
-    request: any;
-};
 export interface IMcpTool<Payload = any, Result = any> {
     name: string;
     title?: string;
     description?: string;
     inputSchema?: ZodRawShapeCompat;
-    execute(input: Payload, context: IMcpToolContext): Promise<Result>;
+    execute(input: Payload): Promise<Result>;
 }
 export declare const MCP_TOOL_METADATA = "mcp:tool-class";
 /**
  * Декоратор класса для MCP тулзы
  */
-export declare const McpTool: () => (target: any) => void;
+export declare const McpTool: () => ClassDecorator;
 export {};

package/dist/mcp-server/mcp-dynamic.service.d.ts

@@ -0,0 +1,31 @@
+import { CanActivate, NestInterceptor, Type } from "@nestjs/common";
+import { ModuleRef } from "@nestjs/core";
+import { McpService } from "./mcp.service";
+import { IMcpTool } from "./decorators/mcp-tool.decorator";
+import { IMcpResource } from "./decorators/mcp-resource.decorator";
+import { IMcpPrompt } from "./decorators/mcp-prompt.decorator";
+export type IMcpDynamicTool<Input, Result> = IMcpTool<Input, Result> & {
+    guards?: Type<CanActivate>[];
+    interceptors?: Type<NestInterceptor>[];
+};
+export type IMcpDynamicPrompt<Input> = IMcpPrompt<Input> & {
+    guards?: Type<CanActivate>[];
+    interceptors?: Type<NestInterceptor>[];
+};
+export type IMcpDynamicResource<Input> = IMcpResource<Input> & {
+    guards?: Type<CanActivate>[];
+    interceptors?: Type<NestInterceptor>[];
+};
+export declare class McpDynamicService {
+    private readonly moduleRef;
+    private readonly mcpService;
+    constructor(moduleRef: ModuleRef, mcpService: McpService);
+    /** Динамически регистрирует MCP tools */
+    registerTool<Input, Result>(tool: IMcpDynamicTool<Input, Result>): Promise<void>;
+    /** Динамически регистрирует MCP prompts */
+    registerPrompt<Input>(prompt: IMcpDynamicPrompt<Input>): Promise<void>;
+    /** Динамически регистрирует MCP resources */
+    registerResource<Input>(resource: IMcpDynamicResource<Input>): Promise<void>;
+    protected applyGuards(item: Function, guards: Type<CanActivate>[]): void;
+    protected applyInterceptors(item: Function, interceptors: Type<NestInterceptor>[]): void;
+}