@muzikanto/nestjs-mcp 1.5.0 → 1.6.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @muzikanto/nestjs-mcp
 
+## 1.6.0
+
+### Minor Changes
+
+- add resources routes
+
+## 1.5.1
+
+### Patch Changes
+
+- custom mcp errors for filters
+
 ## 1.5.0
 
 ### Minor Changes

package/README.md

@@ -21,8 +21,10 @@ NestJS MCP (Model Context Protocol) module — allows you to create “tools”,
   - [Dynamic creation](#dynamic-creation)
   - [Calling MCP tools via HTTP](#calling-mcp-tools-via-http)
   - [Calling MCP prompt via HTTP](#obtain-prompt)
+  - [Calling MCP resource via HTTP](#obtain-resource)
   - [Obtaining all tools](#obtaining-all-tools)
   - [Obtaining all prompts](#obtaining-all-prompts)
+  - [Obtaining all resources](#obtaining-all-resources)
   - [Guards](#guards)
     - [For one](#for-one)
     - [For all](#for-all)
@@ -39,9 +41,9 @@ NestJS MCP (Model Context Protocol) module — allows you to create “tools”,
 - 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 calling a tool (`POST /mcp/tools`)
 - Endpoint for a list of all tools (`GET /mcp/tools`)
-- Endpoint for calling prompt (`POST /mcp/prompts/:name`)
+- Endpoint for calling a prompt (`POST /mcp/prompts/:name`)
 - Endpoint for a list of all prompts (`GET /mcp/prompts`)
 - Easy integration with LLM (OpenAI Function Calls)
 - Support http adapters (default fastify)
@@ -56,7 +58,7 @@ NestJS MCP (Model Context Protocol) module — allows you to create “tools”,
 yarn add @muzikanto/nestjs-mcp
 ```
 
-Peer dependencies: `@nestjs/common, @nestjs/core, @nestjs/swagger, reflect-metadata`
+Peer dependencies: `@nestjs/common, @nestjs/core, @nestjs/swagger, @nestjs/axios, reflect-metadata`
 
 ## Usage
 
@@ -86,7 +88,7 @@ import { Telegraf } from "telegraf";
 import z from "zod";
 
 const schema = {
-  chatId: z.string().describe("Telegram chat id"), // строка с описанием
+  chatId: z.number().describe("Telegram chat id"), // строка с описанием
   text: z.string().describe("Message text"), // строка с описанием
 };
 
@@ -110,7 +112,7 @@ export class TelegramSendMessageTool implements IMcpTool<
 
 ### Calling MCP tools via HTTP
 
-POST /mcp
+POST /mcp/tools
 
 ```json
 {
@@ -134,29 +136,31 @@ POST /mcp
 
 ### Obtaining all tools
 
-GET /mcp/tool
+GET /mcp/tools
 
 ```json
-[
-  {
-    "name": "telegram.sendMessage",
-    "description": "Sent message via Telegram",
-    "inputSchema": {
-      "type": "object",
-      "properties": {
-        "chatId": {
-          "type": "number",
-          "description": "Telegram chat ID"
+{
+  "tools": [
+    {
+      "name": "telegram.sendMessage",
+      "description": "Sent message via Telegram",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "chatId": {
+            "type": "number",
+            "description": "Telegram chat ID"
+          },
+          "text": {
+            "type": "string",
+            "description": "Message text"
+          }
         },
-        "text": {
-          "type": "string",
-          "description": "Message text"
-        }
-      },
-      "required": ["chatId", "text"]
+        "required": ["chatId", "text"]
+      }
     }
-  }
-]
+  ]
+}
 ```
 
 ### Create MCP prompt
@@ -166,7 +170,7 @@ import { IMcpPrompt, McpPrompt } from "@muzikanto/nestjs-mcp";
 import z from "zod";
 
 const schema = {
-  chatId: z.string().describe("Telegram chat id"), // строка с описанием
+  chatId: z.number().describe("Telegram chat id"), // строка с описанием
   text: z.string().describe("Message text"), // строка с описанием
 };
 
@@ -177,7 +181,7 @@ export class TelegramAutoReplyPrompt implements IMcpPrompt<{
 }> {
   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";
+    "Generate a short, friendly reply to an incoming Telegram message and send it back to the same chat using telegram.sendMessage tool";
   schema = schema;
 
   async execute({ text, chatId }: { text: string; chatId: number }) {
@@ -210,26 +214,28 @@ export class TelegramAutoReplyPrompt implements IMcpPrompt<{
 GET /mcp/prompts
 
 ```json
-[
-  {
-    "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",
-    "inputSchema": {
-      "type": "object",
-      "properties": {
-        "chatId": {
-          "type": "number",
-          "description": "Telegram chat ID"
+{
+  "prompts": [
+    {
+      "name": "telegram_auto_reply",
+      "description": "Generate a short, friendly reply to an incoming Telegram message and send it back to the same chat using telegram.sendMessage tool",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "chatId": {
+            "type": "number",
+            "description": "Telegram chat ID"
+          },
+          "text": {
+            "type": "string",
+            "description": "Message text"
+          }
         },
-        "text": {
-          "type": "string",
-          "description": "Message text"
-        }
-      },
-      "required": ["chatId", "text"]
+        "required": ["chatId", "text"]
+      }
     }
-  }
-]
+  ]
+}
 ```
 
 ### Calling MCP prompt via HTTP
@@ -282,12 +288,51 @@ export class TestResource implements IMcpResource<{ userId: string }> {
   title = "Get test user";
   description = "Get user by id";
 
-  async execute(url: URL, vars: { userId: string }) {
-    return [{ uri: url.href, text: `Hello ${vars.userId}` }];
+  async execute(uri: string, vars: { userId: string }) {
+    return [{ uri, text: `Hello ${vars.userId}` }];
   }
 }
 ```
 
+### Calling MCP resource via HTTP
+
+POST /mcp/resources/users.get
+
+```json
+{
+  "uri": "users://user/1"
+}
+```
+
+Response
+
+```json
+{
+  "contents": [
+    {
+      "uri": "users://user/1",
+      "content": "Hello 1"
+    }
+  ]
+}
+```
+
+### Obtaining all resources
+
+GET /mcp/resources
+
+```json
+{
+  "resources": [
+    {
+      "name": "users.get",
+      "title": "Get user by id",
+      "uri": "users://user/{userId}"
+    }
+  ]
+}
+```
+
 ### Dynamic creation
 
 ```ts
@@ -350,7 +395,7 @@ class TestGuard implements CanActivate {
   }
 }
 
-@UseGuard(TestGuard)
+@UseGuards(TestGuard)
 @McpTool()
 export class TelegramSendMessageTool implements IMcpTool<
   { chatId: string; text: string },
@@ -359,7 +404,7 @@ export class TelegramSendMessageTool implements IMcpTool<
   name = "telegram.sendMessage";
 
   async execute() {
-    await this.bot.telegram.sendMessage(input.chatId, input.text);
+    // await this.bot.telegram.sendMessage(input.chatId, input.text);
     return { success: true };
   }
 }
@@ -418,7 +463,7 @@ export class ExampleInterceptor implements NestInterceptor {
   }
 }
 
-@UseInterceptors(TestInterceptor)
+@UseInterceptors(ExampleInterceptor)
 @McpTool()
 export class TelegramSendMessageTool implements IMcpTool<
   { chatId: string; text: string },
@@ -427,7 +472,7 @@ export class TelegramSendMessageTool implements IMcpTool<
   name = "telegram.sendMessage";
 
   async execute() {
-    await this.bot.telegram.sendMessage(input.chatId, input.text);
+    // await this.bot.telegram.sendMessage(input.chatId, input.text);
     return { success: true };
   }
 }
@@ -447,7 +492,7 @@ import { APP_INTERCEPTOR } from "@nestjs/core";
     McpModule.forRoot({
       providers: [
         ToolWithoutInterceptors,
-        TestGuard,
+        TestInterceptor,
         { provide: APP_INTERCEPTOR, useExisting: TestInterceptor },
       ],
     }),
@@ -456,28 +501,43 @@ import { APP_INTERCEPTOR } from "@nestjs/core";
 export class TestModule {}
 ```
 
-### Fitlers
+### Filters
 
 ```ts
-import { IMcpTool, McpTool } from "@muzikanto/nestjs-mcp";
+import {
+  IMcpTool,
+  McpTool,
+  McpUnauthorizedException,
+} from "@muzikanto/nestjs-mcp";
 import {
   ExceptionFilter,
   Catch,
   ArgumentsHost,
-  NotImplementedException,
   UseFilters,
 } from "@nestjs/common";
 
 @Catch(NotImplementedException)
-class ExampleFilter implements ExceptionFilter {
+class NotImplExceptionFilter implements ExceptionFilter {
+  catch(exception: unknown, host: ArgumentsHost) {
+    return {
+      isError: true,
+      text: (exception as Error).message,
+    };
+  }
+}
+
+@Catch(McpUnauthorizedException)
+class AuthExceptionFilter implements ExceptionFilter {
   catch(exception: unknown, host: ArgumentsHost) {
     return {
-      message: (exception as Error).message,
+      isError: true,
+      text: (exception as Error).message,
     };
   }
 }
 
-@UseFilters(ExampleFilter)
+@UseGuards(AuthGuard)
+@UseFilters(AuthExceptionFilter, NotImplExceptionFilter)
 @McpTool()
 export class TelegramSendMessageTool implements IMcpTool<
   { chatId: string; text: string },
@@ -508,14 +568,18 @@ const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
  */
 async function getMcpTools() {
   const response = await axios.get(MCP_TOOLS_URL);
-  return response.data.tools.map(el => ({ name: el.name, description: el.description, parameters: el.inputSchema }));
+  return response.data.tools.map(el => ({
+    name: el.name,
+    description: el.description,
+    parameters: el.inputSchema,
+  }));
 }
 
 /**
  * Get all prompts
  */
 async function getMcpPrompt() {
-  const response = await axios.post(MCP_TELEGRAM_PROMPT_URL, {/* propmpt generation arguments */});
+  const response = await axios.post(MCP_TELEGRAM_PROMPT_URL, {/* prompt generation arguments */});
   return response.data;
 
 /**

package/dist/index.d.ts

@@ -4,4 +4,5 @@ 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";
+export * from "./mcp-server/services/mcp-dynamic.service";
+export * from "./mcp-server/exceptions";

package/dist/index.js

@@ -20,4 +20,5 @@ __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);
+__exportStar(require("./mcp-server/services/mcp-dynamic.service"), exports);
+__exportStar(require("./mcp-server/exceptions"), exports);

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

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

package/dist/mcp-server/controllers/mcp.controller.d.ts

@@ -0,0 +1,23 @@
+import { ExecutionContext, CanActivate } from "@nestjs/common";
+import { McpService } from "../services/mcp.service";
+import { McpMessageDto } from "../dto/McpMessage.dto";
+import { McpToolsDto } from "../dto/McpTools.dto";
+import { McpPromptsDto } from "../dto/McpPrompts.dto";
+import { McpPromptMessagesDto } from "../dto/McpPromptMessages.dto";
+import { IMcpConfig } from "../config";
+import { McpResourcesDto } from "../dto/McpResources.dto";
+import { McpResourceItemsDto } from "../dto/McpResourceItems.dto";
+import { McpResourceRequestDto } from "../dto/McpResourceRequest.dto";
+export declare class McpController {
+    private readonly service;
+    private readonly guard;
+    private readonly config;
+    constructor(service: McpService, guard: CanActivate, config: IMcpConfig);
+    handleTool(body: McpMessageDto, request: any, context: ExecutionContext): Promise<any>;
+    getTools(context: ExecutionContext): Promise<McpToolsDto>;
+    getPrompts(context: ExecutionContext): Promise<McpPromptsDto>;
+    getPrompt(name: string, body: object, context: ExecutionContext): Promise<McpPromptMessagesDto>;
+    getResources(context: ExecutionContext): Promise<McpResourcesDto>;
+    executeResource(name: string, body: McpResourceRequestDto, context: ExecutionContext): Promise<McpResourceItemsDto>;
+    private checkGuard;
+}

package/dist/mcp-server/controllers/mcp.controller.js

@@ -0,0 +1,226 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.McpController = void 0;
+const common_1 = require("@nestjs/common");
+const mcp_service_1 = require("../services/mcp.service");
+const McpMessage_dto_1 = require("../dto/McpMessage.dto");
+const swagger_1 = require("@nestjs/swagger");
+const McpTools_dto_1 = require("../dto/McpTools.dto");
+const McpPrompts_dto_1 = require("../dto/McpPrompts.dto");
+const McpPromptMessages_dto_1 = require("../dto/McpPromptMessages.dto");
+const context_decorator_1 = require("../utils/context.decorator");
+const inject_tokens_1 = require("../utils/inject-tokens");
+const config_1 = require("../config");
+const rxjs_1 = require("rxjs");
+const McpResources_dto_1 = require("../dto/McpResources.dto");
+const McpResourceItems_dto_1 = require("../dto/McpResourceItems.dto");
+const McpResourceRequest_dto_1 = require("../dto/McpResourceRequest.dto");
+const uri_1 = require("../utils/uri");
+let McpController = class McpController {
+    service;
+    guard;
+    config;
+    constructor(service, guard, config) {
+        this.service = service;
+        this.guard = guard;
+        this.config = config;
+    }
+    async handleTool(body, request, context) {
+        await this.checkGuard(context);
+        const observable = await this.service.executeTool(body, context);
+        const result = await (0, rxjs_1.firstValueFrom)(observable);
+        return result;
+    }
+    async getTools(context) {
+        await this.checkGuard(context);
+        const tools = this.service.listTools();
+        return { tools };
+    }
+    async getPrompts(context) {
+        await this.checkGuard(context);
+        const prompts = this.service.listPrompts();
+        return { prompts };
+    }
+    async getPrompt(name, body, context) {
+        await this.checkGuard(context);
+        const observable = await this.service.executePrompt(name, body, context);
+        const messages = await (0, rxjs_1.firstValueFrom)(observable);
+        return {
+            messages,
+        };
+    }
+    async getResources(context) {
+        await this.checkGuard(context);
+        const resources = this.service.listResources();
+        return { resources };
+    }
+    async executeResource(name, body, context) {
+        await this.checkGuard(context);
+        const url = new URL(body.uri);
+        const resource = this.service.resources.get(name);
+        const params = resource
+            ? (0, uri_1.extractResourceParams)(resource.instance.uri, body.uri)
+            : {};
+        const observable = await this.service.executeResource(name, url, params, context);
+        const contents = await (0, rxjs_1.firstValueFrom)(observable);
+        return { contents };
+    }
+    async checkGuard(context) {
+        if (!(await this.guard.canActivate(context))) {
+            throw new common_1.ForbiddenException();
+        }
+    }
+};
+exports.McpController = McpController;
+__decorate([
+    (0, common_1.Post)("/tools"),
+    (0, common_1.Header)("Content-Type", "application/json"),
+    (0, swagger_1.ApiOperation)({
+        summary: "Request tool",
+    }),
+    (0, swagger_1.ApiResponse)({
+        status: 200,
+        description: "Tool execution result",
+    }),
+    (0, swagger_1.ApiBadRequestResponse)({
+        description: "Invalid request body",
+    }),
+    (0, swagger_1.ApiForbiddenResponse)({
+        description: "No access to method",
+    }),
+    __param(0, (0, common_1.Body)()),
+    __param(1, (0, common_1.Request)()),
+    __param(2, (0, context_decorator_1.Context)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [McpMessage_dto_1.McpMessageDto, Object, Object]),
+    __metadata("design:returntype", Promise)
+], McpController.prototype, "handleTool", null);
+__decorate([
+    (0, common_1.Get)("tools"),
+    (0, swagger_1.ApiOperation)({
+        summary: "Get tool list",
+    }),
+    (0, swagger_1.ApiResponse)({
+        status: 200,
+        description: "Tools list",
+        type: McpTools_dto_1.McpToolsDto,
+    }),
+    (0, swagger_1.ApiForbiddenResponse)({
+        description: "No access to method",
+    }),
+    __param(0, (0, context_decorator_1.Context)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], McpController.prototype, "getTools", null);
+__decorate([
+    (0, common_1.Get)("prompts"),
+    (0, swagger_1.ApiOperation)({
+        summary: "Get prompt list",
+    }),
+    (0, swagger_1.ApiResponse)({
+        status: 200,
+        description: "Prompts list",
+        type: McpPrompts_dto_1.McpPromptsDto,
+    }),
+    (0, swagger_1.ApiForbiddenResponse)({
+        description: "No access to method",
+    }),
+    __param(0, (0, context_decorator_1.Context)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], McpController.prototype, "getPrompts", null);
+__decorate([
+    (0, common_1.Post)("prompts/:name"),
+    (0, swagger_1.ApiOperation)({
+        summary: "Generate messages by prompt name",
+    }),
+    (0, swagger_1.ApiBody)({
+        description: "Any body structure",
+        type: Object, // Указываем, что тело может быть любым объектом
+    }),
+    (0, swagger_1.ApiResponse)({
+        status: 200,
+        description: "Prompt messages",
+        type: McpPromptMessages_dto_1.McpPromptMessagesDto,
+    }),
+    (0, swagger_1.ApiNotFoundResponse)({
+        description: "Not found prompt",
+    }),
+    (0, swagger_1.ApiBadRequestResponse)({
+        description: "Invalid prompt arguments",
+    }),
+    (0, swagger_1.ApiForbiddenResponse)({
+        description: "No access to method",
+    }),
+    __param(0, (0, common_1.Param)("name")),
+    __param(1, (0, common_1.Body)()),
+    __param(2, (0, context_decorator_1.Context)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, Object, Object]),
+    __metadata("design:returntype", Promise)
+], McpController.prototype, "getPrompt", null);
+__decorate([
+    (0, common_1.Get)("resources/templates"),
+    (0, swagger_1.ApiOperation)({
+        summary: "Get resources templates list",
+    }),
+    (0, swagger_1.ApiResponse)({
+        status: 200,
+        description: "Resources templates list",
+        type: McpResources_dto_1.McpResourcesDto,
+    }),
+    (0, swagger_1.ApiForbiddenResponse)({
+        description: "No access to method",
+    }),
+    __param(0, (0, context_decorator_1.Context)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], McpController.prototype, "getResources", null);
+__decorate([
+    (0, common_1.Post)("resources/templates/:name"),
+    (0, swagger_1.ApiOperation)({
+        summary: "Get resource template result",
+    }),
+    (0, swagger_1.ApiBody)({
+        description: "Any body structure",
+        type: Object, // Указываем, что тело может быть любым объектом
+    }),
+    (0, swagger_1.ApiResponse)({
+        status: 200,
+        description: "Resource template result",
+        type: McpResourceItems_dto_1.McpResourceItemsDto,
+    }),
+    (0, swagger_1.ApiNotFoundResponse)({
+        description: "Not found resource template",
+    }),
+    (0, swagger_1.ApiForbiddenResponse)({
+        description: "No access to method",
+    }),
+    __param(0, (0, common_1.Param)("name")),
+    __param(1, (0, common_1.Body)()),
+    __param(2, (0, context_decorator_1.Context)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, McpResourceRequest_dto_1.McpResourceRequestDto, Object]),
+    __metadata("design:returntype", Promise)
+], McpController.prototype, "executeResource", null);
+exports.McpController = McpController = __decorate([
+    (0, common_1.Controller)("mcp"),
+    __param(1, (0, common_1.Inject)(inject_tokens_1.MCP_GUARD)),
+    __param(2, (0, config_1.InjectMcpConfig)()),
+    __metadata("design:paramtypes", [mcp_service_1.McpService, Object, Object])
+], McpController);

package/dist/mcp-server/controllers/mcp.sse.controller.d.ts

@@ -0,0 +1,12 @@
+import { ExecutionContext, CanActivate } from "@nestjs/common";
+import { IMcpConfig } from "../config";
+import { McpSseService } from "../services/mcp.sse.service";
+export declare class McpSseController {
+    private readonly service;
+    private readonly guard;
+    private readonly config;
+    constructor(service: McpSseService, guard: CanActivate, config: IMcpConfig);
+    handleSse(rawReq: any, rawRes: any, context: ExecutionContext): Promise<void>;
+    handleSseMessages(rawReq: any, rawRes: any, context: ExecutionContext): Promise<void>;
+    private checkGuard;
+}