@muzikanto/nestjs-mcp 1.5.1 → 1.7.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @muzikanto/nestjs-mcp
 
+## 1.7.0
+
+### Minor Changes
+
+- fix tool result format
+
+## 1.6.0
+
+### Minor Changes
+
+- add resources routes
+
 ## 1.5.1
 
 ### Patch 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
 
@@ -83,10 +85,10 @@ export class AppModule {}
 ```ts
 import { IMcpTool, McpTool } from "@muzikanto/nestjs-mcp";
 import { Telegraf } from "telegraf";
-import z from "zod";
+import z from "zod/v3";
 
 const schema = {
-  chatId: z.string().describe("Telegram chat id"), // строка с описанием
+  chatId: z.number().describe("Telegram chat id"), // строка с описанием
   text: z.string().describe("Message text"), // строка с описанием
 };
 
@@ -96,21 +98,23 @@ export class TelegramSendMessageTool implements IMcpTool<
   { success: boolean }
 > {
   name = "telegram.sendMessage";
-
   inputSchema = schema;
 
   constructor(private readonly bot: Telegraf) {}
 
   async execute(input: { chatId: string; text: string }) {
     await this.bot.telegram.sendMessage(input.chatId, input.text);
-    return { success: true };
+    return {
+      structuredContent: { success: true },
+      messages: [{ type: "text", text: "Success sent to user" }],
+    };
   }
 }
 ```
 
 ### Calling MCP tools via HTTP
 
-POST /mcp
+POST /mcp/tools
 
 ```json
 {
@@ -126,47 +130,50 @@ POST /mcp
 
 ```json
 {
-  "data": {
+  "structuredContent": {
     "success": true
-  }
+  },
+  "messages": [{ "type": "text", "text": "Success sent to user" }]"
 }
 ```
 
 ### 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
 
 ```ts
 import { IMcpPrompt, McpPrompt } from "@muzikanto/nestjs-mcp";
-import z from "zod";
+import z from "zod/v3";
 
 const schema = {
-  chatId: z.string().describe("Telegram chat id"), // строка с описанием
+  chatId: z.number().describe("Telegram chat id"), // строка с описанием
   text: z.string().describe("Message text"), // строка с описанием
 };
 
@@ -177,30 +184,32 @@ 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 }) {
-    return [
-      {
-        role: "system",
-        content: `You are a friendly Telegram bot. Reply briefly and to the point.`,
-      },
-      {
-        role: "user",
-        content: text,
-      },
-      {
-        role: "assistant",
-        tool_call: {
-          name: "telegram.sendMessage",
-          arguments: {
-            chatId,
-            text: "{{model_output}}",
+    return {
+      messages: [
+        {
+          role: "system",
+          content: `You are a friendly Telegram bot. Reply briefly and to the point.`,
+        },
+        {
+          role: "user",
+          content: text,
+        },
+        {
+          role: "assistant",
+          tool_call: {
+            name: "telegram.sendMessage",
+            arguments: {
+              chatId,
+              text: "{{model_output}}",
+            },
           },
         },
-      },
-    ];
+      ],
+    };
   }
 }
 ```
@@ -210,26 +219,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 +293,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
@@ -304,7 +354,11 @@ export class McpDynamic {
     this.mcpDynamicService.registerTool({
       name: "dynamic_tool",
       title: "Dynamic tool",
-      execute: () => Promise.resolve("test"),
+      execute: () =>
+        Promise.resolve({
+          structuredContent: { text: "test" },
+          messages: [{ type: "text" as const, text: "test" }],
+        }),
       guards: [ExampleGuard],
       interceptors: [ExampleInterceptor],
     });
@@ -312,7 +366,8 @@ export class McpDynamic {
     this.mcpDynamicService.registerPrompt({
       name: "dynamic_prompt",
       title: "Dynamic prompt",
-      execute: () => Promise.resolve([{ role: "assistant", content: "test" }]),
+      execute: () =>
+        Promise.resolve({ messages: [{ role: "assistant", content: "test" }] }),
       guards: [ExampleGuard],
       interceptors: [ExampleInterceptor],
     });
@@ -325,6 +380,11 @@ export class McpDynamic {
         Promise.resolve([{ uri: uri.href, text: `ID: ${input.testId}` }]),
       guards: [ExampleGuard],
       interceptors: [ExampleInterceptor],
+      list: async () => {
+        return [
+          { uri: "dynamic://test/1", name: "dynamice_1", title: "Dynamic 1" },
+        ];
+      },
     });
   }
 }
@@ -350,7 +410,7 @@ class TestGuard implements CanActivate {
   }
 }
 
-@UseGuard(TestGuard)
+@UseGuards(TestGuard)
 @McpTool()
 export class TelegramSendMessageTool implements IMcpTool<
   { chatId: string; text: string },
@@ -359,8 +419,11 @@ export class TelegramSendMessageTool implements IMcpTool<
   name = "telegram.sendMessage";
 
   async execute() {
-    await this.bot.telegram.sendMessage(input.chatId, input.text);
-    return { success: true };
+    // await this.bot.telegram.sendMessage(input.chatId, input.text);
+    return {
+      structuredContent: { success: true },
+      messages: { type: "text", text: "Success sent" },
+    };
   }
 }
 ```
@@ -418,7 +481,7 @@ export class ExampleInterceptor implements NestInterceptor {
   }
 }
 
-@UseInterceptors(TestInterceptor)
+@UseInterceptors(ExampleInterceptor)
 @McpTool()
 export class TelegramSendMessageTool implements IMcpTool<
   { chatId: string; text: string },
@@ -427,8 +490,11 @@ export class TelegramSendMessageTool implements IMcpTool<
   name = "telegram.sendMessage";
 
   async execute() {
-    await this.bot.telegram.sendMessage(input.chatId, input.text);
-    return { success: true };
+    // await this.bot.telegram.sendMessage(input.chatId, input.text);
+    return {
+      success: true,
+      messagse: [{ type: "text", text: "Success sent" }],
+    };
   }
 }
 ```
@@ -447,7 +513,7 @@ import { APP_INTERCEPTOR } from "@nestjs/core";
     McpModule.forRoot({
       providers: [
         ToolWithoutInterceptors,
-        TestGuard,
+        TestInterceptor,
         { provide: APP_INTERCEPTOR, useExisting: TestInterceptor },
       ],
     }),
@@ -459,7 +525,11 @@ export class TestModule {}
 ### Filters
 
 ```ts
-import { IMcpTool, McpTool, McpUnauthorizedException } from "@muzikanto/nestjs-mcp";
+import {
+  IMcpTool,
+  McpTool,
+  McpUnauthorizedException,
+} from "@muzikanto/nestjs-mcp";
 import {
   ExceptionFilter,
   Catch,
@@ -467,8 +537,18 @@ import {
   UseFilters,
 } from "@nestjs/common";
 
+@Catch(NotImplementedException)
+class NotImplExceptionFilter implements ExceptionFilter {
+  catch(exception: unknown, host: ArgumentsHost) {
+    return {
+      isError: true,
+      text: (exception as Error).message,
+    };
+  }
+}
+
 @Catch(McpUnauthorizedException)
-class ExampleFilter implements ExceptionFilter {
+class AuthExceptionFilter implements ExceptionFilter {
   catch(exception: unknown, host: ArgumentsHost) {
     return {
       isError: true,
@@ -477,7 +557,8 @@ class ExampleFilter implements ExceptionFilter {
   }
 }
 
-@UseFilters(ExampleFilter)
+@UseGuards(AuthGuard)
+@UseFilters(AuthExceptionFilter, NotImplExceptionFilter)
 @McpTool()
 export class TelegramSendMessageTool implements IMcpTool<
   { chatId: string; text: string },
@@ -494,11 +575,12 @@ export class TelegramSendMessageTool implements IMcpTool<
 ### Integration with OpenAI Function Calls
 
 ```ts
-import axios from 'axios';
-import OpenAI from 'openai';
+import axios from "axios";
+import OpenAI from "openai";
 
-const MCP_TOOLS_URL = 'http://localhost:3000/mcp/tools';
-const MCP_TELEGRAM_PROMPT_URL = 'http://localhost:3000/mcp/prompts/telegram_auto_reply';
+const MCP_TOOLS_URL = "http://localhost:3000/mcp/tools";
+const MCP_TELEGRAM_PROMPT_URL =
+  "http://localhost:3000/mcp/prompts/telegram_auto_reply";
 
 // Create OpenAI client
 const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
@@ -508,24 +590,28 @@ 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;
+}
 
 /**
  * Request mcp tool
  */
 async function callMcpTool(toolName: string, payload: Record<string, any>) {
-  const response = await axios.post(
-    MCP_TOOLS_URL,
-    { type: toolName, payload },
-  );
+  const response = await axios.post(MCP_TOOLS_URL, { type: toolName, payload });
   return response.data;
 }
 
@@ -537,10 +623,10 @@ async function callMcpTool(toolName: string, payload: Record<string, any>) {
   const promptResponse = await getMcpPrompt();
 
   const completion = await client.chat.completions.create({
-    model: 'gpt-4.1-mini',
+    model: "gpt-4.1-mini",
     messages: promptResponse.messages,
     functions: toolsResponse.tools,
-    function_call: 'auto',
+    function_call: "auto",
   });
 
   const message = completion.choices[0].message;
@@ -549,8 +635,8 @@ async function callMcpTool(toolName: string, payload: Record<string, any>) {
     const { name, arguments: argsJson } = message.function_call;
     const args = JSON.parse(argsJson);
 
-    const result = await callMcpTool(name, args);
-    console.log('Result from MCP tool:', result);
+    const { messages, structuredContent } = await callMcpTool(name, args);
+    console.log("Result from MCP tool:", messages, structuredContent);
   }
 })();
 ```

package/dist/index.d.ts

@@ -4,5 +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,5 +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-client/mcp-client.service.d.ts

@@ -1,12 +1,12 @@
 import { HttpService } from "@nestjs/axios";
 import { McpToolsDto } from "../mcp-server/dto/McpTools.dto";
 import { McpPromptsDto } from "../mcp-server/dto/McpPrompts.dto";
-import { McpPromptMessagesDto } from "../mcp-server/dto/McpPromptMessages.dto";
+import { McpPromptResultDto } from "../mcp-server/dto/McpPrompResult.dto";
 export declare class McpClientService {
     private readonly httpService;
     constructor(httpService: HttpService);
     getAllTools(): Promise<McpToolsDto>;
     getAllPrompts(): Promise<McpPromptsDto>;
-    getPromptByName<Payload = any>(promptName: string, params: Payload): Promise<McpPromptMessagesDto>;
+    getPromptByName<Payload = any>(promptName: string, params: Payload): Promise<McpPromptResultDto>;
     callMcpTool<Payload = any, Result = any>(toolName: string, payload: Payload): Promise<Result>;
 }

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,24 @@
+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 { McpPromptResultDto } from "../dto/McpPrompResult.dto";
+import { IMcpConfig } from "../config";
+import { McpResourcesDto } from "../dto/McpResources.dto";
+import { McpResourceItemsDto } from "../dto/McpResourceItems.dto";
+import { McpResourceRequestDto } from "../dto/McpResourceRequest.dto";
+import { McpToolResultDto } from "../dto/McpToolResult.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<McpToolResultDto>;
+    getTools(context: ExecutionContext): Promise<McpToolsDto>;
+    getPrompts(context: ExecutionContext): Promise<McpPromptsDto>;
+    getPrompt(name: string, body: object, context: ExecutionContext): Promise<McpPromptResultDto>;
+    getResources(context: ExecutionContext): Promise<McpResourcesDto>;
+    executeResource(name: string, body: McpResourceRequestDto, context: ExecutionContext): Promise<McpResourceItemsDto>;
+    private checkGuard;
+}