@muzikanto/nestjs-mcp 1.0.0-canary

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 [Muzikanto]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,164 @@
+# @muzikanto/nestjs-mcp
+
+NestJS MCP (Model Context Protocol) module — allows you to create “tools” (functions) for LLM or HTTP, with automatic detection via decorators, validation, and integration with OpenAI Function Calls.
+
+---
+
+## Features
+
+- Register MCP tools using the `@McpTool()` decorator
+- Automatic detection of all providers (tools) in the module
+- Input data validation
+- HTTP endpoint for calling tools (`POST /mcp`)  
+- Endpoint for a list of all tools (`GET /mcp/tools`)  
+- Easy integration with LLM (OpenAI Function Calls)  
+- Full TypeScript typing  
+
+---
+
+## Installation
+
+```bash
+yarn add @muzikanto/nestjs-mcp
+```
+
+Peer dependencies: `@nestjs/common, @nestjs/core, reflect-metadata`
+
+## Usage
+
+### Connecting the MCP module
+
+```ts
+import { Module } from '@nestjs/common';
+import { McpModule } from '@muzikanto/nestjs-mcp';
+import { PaymentTool } from './tools/payment.tool';
+
+@Module({
+  imports: [
+    McpModule.forRoot(),
+  ],
+  providers: [
+    PaymentTool,
+  ],
+})
+export class AppModule {}
+```
+
+### Create MCP tool
+
+```ts
+import { IMcpTool, McpTool } from '../decorators/mcp-tool.decorator';
+
+@McpTool()
+export class GetCurrentDate implements IMcpTool<{ country: string; }, { date: string }> {
+  name = 'get-date';
+
+  inputSchema = {
+    "type": "object",
+    "properties": {
+      "country": { "type": "string", "description": "Country" }
+    },
+    "required": ["country"]
+  };
+
+  async execute(input: { country: string }) {
+    return { date: new Date().toLocaleString() };
+  }
+}
+```
+
+### Calling MCP tools via HTTP
+
+POST /mcp
+
+```json
+{
+  "type": "get-date",
+  "payload": {
+    "country": "ru"
+  }
+}
+```
+
+Ответ 
+```json
+{
+  "data": {
+    "date": "21/02/2026, 16:17:00"
+  }
+}
+```
+
+### Obtaining all tools
+
+GET /mcp/tool
+
+```json
+[
+  {
+    "name": "get-date",
+    "description": "",
+    "inputSchema": {
+      "country": { "type": "string", "description": "Страна" },
+    }
+  }
+]
+```
+
+### Integration with OpenAI Function Calls
+
+```ts
+import axios from 'axios';
+import OpenAI from 'openai';
+import { z } from 'zod';
+
+const MCP_URL = 'http://localhost:3000/mcp';
+const MCP_TOOLS_URL = 'http://localhost:3000/mcp/tools';
+
+// Create OpenAI client
+const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
+
+/**
+ * Get all tools
+ */
+async function listMcpTools() {
+  const response = await axios.get(MCP_TOOLS_URL);
+  return response.data;
+}
+
+/**
+ * Request mcp tool
+ */
+async function callMcpTool(toolName: string, payload: Record<string, any>) {
+  const response = await axios.post(
+    MCP_URL,
+    { type: toolName, payload },
+    { headers: { 'Content-Type': 'application/json' } }
+  );
+  return response.data;
+}
+
+/**
+ * Example
+ */
+(async () => {
+  const functions = await listMcpTools();
+
+  const completion = await client.chat.completions.create({
+    model: 'gpt-4.1-mini',
+    messages: [{ role: 'user', content: 'Confirm cart abc123' }],
+    functions,
+    function_call: 'auto',
+  });
+
+  const message = completion.choices[0].message;
+
+  if (message.function_call) {
+    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);
+  }
+})();
+```

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

@@ -0,0 +1,12 @@
+import "reflect-metadata";
+export interface IMcpTool<Payload = any, Result = any> {
+    name: string;
+    description?: string;
+    inputSchema?: object | object[];
+    execute(input: Payload): Promise<Result>;
+}
+export declare const MCP_TOOL_METADATA = "mcp:tool-class";
+/**
+ * Декоратор класса для MCP тулзы
+ */
+export declare const McpTool: () => (target: any) => void;

package/dist/decorators/mcp-tool.decorator.js

@@ -0,0 +1,12 @@
+import { Injectable } from "@nestjs/common";
+import "reflect-metadata";
+export const MCP_TOOL_METADATA = "mcp:tool-class";
+/**
+ * Декоратор класса для MCP тулзы
+ */
+export const McpTool = () => {
+    return (target) => {
+        Injectable()(target);
+        Reflect.defineMetadata(MCP_TOOL_METADATA, {}, target);
+    };
+};

package/dist/example/example.tool.d.ts

@@ -0,0 +1,14 @@
+import { z } from 'zod';
+import { IMcpTool } from '../decorators/mcp-tool.decorator';
+export declare class PaymentTool implements IMcpTool {
+    name: string;
+    static inputSchema: z.ZodObject<{
+        cartId: z.ZodString;
+    }, z.core.$strip>;
+    execute(input: {
+        cartId: string;
+    }): Promise<{
+        status: string;
+        cartId: string;
+    }>;
+}

package/dist/example/example.tool.js

@@ -0,0 +1,23 @@
+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;
+};
+import { Injectable } from '@nestjs/common';
+import { z } from 'zod';
+import { McpTool } from '../decorators/mcp-tool.decorator';
+let PaymentTool = class PaymentTool {
+    name = 'example';
+    static inputSchema = z.object({
+        cartId: z.string().describe('ID'),
+    });
+    async execute(input) {
+        return { status: 'confirmed', cartId: input.cartId };
+    }
+};
+PaymentTool = __decorate([
+    McpTool('example'),
+    Injectable()
+], PaymentTool);
+export { PaymentTool };

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./mcp.module";
+export * from "./decorators/mcp-tool.decorator";

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from "./mcp.module";
+export * from "./decorators/mcp-tool.decorator";

package/dist/interfaces/mcp-options.interface.d.ts

@@ -0,0 +1,4 @@
+export interface McpModuleOptions {
+    name?: string;
+    version?: string;
+}

package/dist/interfaces/mcp-options.interface.js

@@ -0,0 +1 @@
+export {};

package/dist/mcp.controller.d.ts

@@ -0,0 +1,21 @@
+import { McpMessage, McpService } from "./mcp.service";
+export declare class McpController {
+    private readonly service;
+    constructor(service: McpService);
+    handle(body: McpMessage): Promise<{
+        success: boolean;
+        data: any;
+        error?: undefined;
+    } | {
+        success: boolean;
+        error: any;
+        data?: undefined;
+    }>;
+    getTools(): Promise<{
+        tools: {
+            name: string;
+            description: string;
+            parameters: object;
+        }[];
+    }>;
+}

package/dist/mcp.controller.js

@@ -0,0 +1,46 @@
+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); }
+};
+import { Controller, Post, Body, Header, Get } from "@nestjs/common";
+import { McpService } from "./mcp.service";
+let McpController = class McpController {
+    service;
+    constructor(service) {
+        this.service = service;
+    }
+    async handle(body) {
+        return this.service.sendMessage(body);
+    }
+    async getTools() {
+        const tools = this.service.listTools();
+        return { tools };
+    }
+};
+__decorate([
+    Post(),
+    Header("Content-Type", "application/json"),
+    __param(0, Body()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], McpController.prototype, "handle", null);
+__decorate([
+    Get("tools"),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", []),
+    __metadata("design:returntype", Promise)
+], McpController.prototype, "getTools", null);
+McpController = __decorate([
+    Controller("mcp"),
+    __metadata("design:paramtypes", [McpService])
+], McpController);
+export { McpController };

package/dist/mcp.explorer.d.ts

@@ -0,0 +1,9 @@
+import { DiscoveryService } from "@nestjs/core";
+import { OnModuleInit } from "@nestjs/common";
+import { McpService } from "./mcp.service";
+export declare class McpExplorer implements OnModuleInit {
+    private readonly discovery;
+    private readonly mcpService;
+    constructor(discovery: DiscoveryService, mcpService: McpService);
+    onModuleInit(): void;
+}

package/dist/mcp.explorer.js

@@ -0,0 +1,42 @@
+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);
+};
+import { DiscoveryService } from "@nestjs/core";
+import { Injectable } from "@nestjs/common";
+import { McpService } from "./mcp.service";
+import { MCP_TOOL_METADATA } from "./decorators/mcp-tool.decorator";
+let McpExplorer = class McpExplorer {
+    discovery;
+    mcpService;
+    constructor(discovery, mcpService) {
+        this.discovery = discovery;
+        this.mcpService = mcpService;
+    }
+    onModuleInit() {
+        const providers = this.discovery.getProviders();
+        providers.forEach(({ instance, metatype }) => {
+            if (!instance || !metatype)
+                return;
+            const metadata = Reflect.getMetadata(MCP_TOOL_METADATA, metatype);
+            if (!metadata)
+                return;
+            // Проверка интерфейса
+            if (typeof instance.execute !== "function") {
+                throw new Error(`MCP Tool ${metadata.name} must implement IMcpTool with execute() method`);
+            }
+            this.mcpService.registerTool(metadata.name, instance);
+        });
+    }
+};
+McpExplorer = __decorate([
+    Injectable(),
+    __metadata("design:paramtypes", [DiscoveryService,
+        McpService])
+], McpExplorer);
+export { McpExplorer };

package/dist/mcp.module.d.ts

@@ -0,0 +1,4 @@
+import { DynamicModule } from "@nestjs/common";
+export declare class McpModule {
+    static forRoot(): DynamicModule;
+}

package/dist/mcp.module.js

@@ -0,0 +1,27 @@
+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 McpModule_1;
+import { Module } from "@nestjs/common";
+import { DiscoveryModule } from "@nestjs/core";
+import { McpService } from "./mcp.service";
+import { McpExplorer } from "./mcp.explorer";
+import { McpController } from "./mcp.controller";
+let McpModule = McpModule_1 = class McpModule {
+    static forRoot() {
+        return {
+            module: McpModule_1,
+            imports: [DiscoveryModule],
+            providers: [McpService, McpExplorer],
+            exports: [McpService],
+            controllers: [McpController],
+        };
+    }
+};
+McpModule = McpModule_1 = __decorate([
+    Module({})
+], McpModule);
+export { McpModule };

package/dist/mcp.service.d.ts

@@ -0,0 +1,40 @@
+import { OnModuleInit } from "@nestjs/common";
+import { IMcpTool } from "./decorators/mcp-tool.decorator";
+export interface McpMessage {
+    type: string;
+    payload: any;
+}
+export interface McpResponse {
+    success: boolean;
+    data?: any;
+    error?: string;
+}
+export declare class McpService implements OnModuleInit {
+    private tools;
+    private ajv;
+    onModuleInit(): void;
+    /**
+     * Возвращает список зарегистрированных тулз
+     */
+    listTools(): {
+        name: string;
+        description: string;
+        parameters: object;
+    }[];
+    registerTool(name: string, handler: IMcpTool): void;
+    /**
+     * Отправить сообщение в MCP "сервер"
+     */
+    sendMessage(msg: {
+        type: string;
+        payload: any;
+    }): Promise<{
+        success: boolean;
+        data: any;
+        error?: undefined;
+    } | {
+        success: boolean;
+        error: any;
+        data?: undefined;
+    }>;
+}

package/dist/mcp.service.js

@@ -0,0 +1,56 @@
+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;
+};
+import { Injectable } from "@nestjs/common";
+import Ajv from "ajv";
+let McpService = class McpService {
+    tools = new Map();
+    ajv = new Ajv();
+    onModuleInit() {
+        // console.log('MCP Service initialized');
+    }
+    /**
+     * Возвращает список зарегистрированных тулз
+     */
+    listTools() {
+        return Array.from(this.tools.values()).map((t) => ({
+            name: t.name,
+            description: t.description || "",
+            parameters: t.inputSchema || {},
+        }));
+    }
+    registerTool(name, handler) {
+        this.tools.set(name, handler);
+    }
+    /**
+     * Отправить сообщение в MCP "сервер"
+     */
+    async sendMessage(msg) {
+        const tool = this.tools.get(msg.type);
+        if (!tool) {
+            return { success: false, error: `Unknown tool: ${msg.type}` };
+        }
+        // Валидация через AJV, если есть inputSchema
+        if (tool.inputSchema) {
+            const validate = this.ajv.compile(tool.inputSchema);
+            const valid = validate(msg.payload);
+            if (!valid) {
+                return { success: false, error: this.ajv.errorsText(validate.errors) };
+            }
+        }
+        try {
+            const result = await tool.execute(msg.payload);
+            return { success: true, data: result };
+        }
+        catch (err) {
+            return { success: false, error: err.message };
+        }
+    }
+};
+McpService = __decorate([
+    Injectable()
+], McpService);
+export { McpService };

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@muzikanto/nestjs-mcp",
+  "type": "module",
+  "version": "1.0.0-canary",
+  "description": "Model Context Protocol integration for NestJS",
+  "keywords": [
+    "nestjs",
+    "mcp",
+    "ai",
+    "model-context-protocol"
+  ],
+  "license": "MIT",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "@nestjs/common": "^10 || ^11",
+    "@nestjs/core": "^10 || ^11",
+    "reflect-metadata": "^0.1.13"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "ajv": "^8.18.0",
+    "@nestjs/common": "^10 || ^11",
+    "@nestjs/core": "^10 || ^11",
+    "reflect-metadata": "^0.1.13"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "prettier": "^3.8.1",
+    "typescript": "^5.0.0"
+  }
+}