@nestjs-mcp/server 0.1.0-alpha.10

package/package.json

@@ -0,0 +1,109 @@
+{
+  "name": "@nestjs-mcp/server",
+  "version": "0.1.0-alpha.10",
+  "description": "Modular library for building scalable MCP servers with NestJS, providing decorators and integration patterns as a wrapper for the official MCP TypeScript SDK.",
+  "author": "Adrián Darío Hidalgo Flores",
+  "license": "MIT",
+  "engines": {
+    "node": ">=22",
+    "pnpm": ">=10"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/adrian-d-hidalgo/nestjs-mcp-server.git"
+  },
+  "homepage": "https://github.com/adrian-d-hidalgo/nestjs-mcp-server#readme",
+  "bugs": {
+    "url": "https://github.com/adrian-d-hidalgo/nestjs-mcp-server/issues"
+  },
+  "keywords": [
+    "decorators",
+    "integration",
+    "large-language-models",
+    "llm",
+    "mcp",
+    "model-context-protocol",
+    "module",
+    "nestjs",
+    "sdk",
+    "server",
+    "typescript"
+  ],
+  "scripts": {
+    "build": "nest build",
+    "prepare": "husky install",
+    "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\"",
+    "start:example": "npx -y ts-node-dev --respawn examples/$EXAMPLE/main.ts",
+    "start:inspector": "npx -y @modelcontextprotocol/inspector",
+    "lint": "eslint \"{src,test,examples}/**/*.ts\" --fix",
+    "typecheck": "tsc --noEmit",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:cov": "jest --coverage",
+    "test:debug": "node --inspect-brk -r tsconfig-paths/register -r ts-node/register node_modules/.bin/jest --runInBand",
+    "test:e2e": "jest --config ./test/jest-e2e.json",
+    "npm:publish": "node scripts/npm-publish.js"
+  },
+  "peerDependencies": {
+    "@nestjs/common": "^11.0.1",
+    "@nestjs/core": "^11.0.1",
+    "@nestjs/platform-express": "^11.0.1",
+    "reflect-metadata": "^0.2.2",
+    "rxjs": "^7.8.1"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.10.2",
+    "zod": "^3.24.3"
+  },
+  "devDependencies": {
+    "@eslint/eslintrc": "^3.2.0",
+    "@eslint/js": "^9.18.0",
+    "@nestjs/cli": "^11.0.0",
+    "@nestjs/config": "^4.0.2",
+    "@nestjs/schematics": "^11.0.0",
+    "@nestjs/testing": "^11.0.1",
+    "@swc/cli": "^0.6.0",
+    "@swc/core": "^1.10.7",
+    "@types/express": "^5.0.0",
+    "@types/jest": "^29.5.14",
+    "@types/node": "^22.10.7",
+    "@types/supertest": "^6.0.2",
+    "eslint": "^9.18.0",
+    "eslint-config-prettier": "^10.0.1",
+    "eslint-plugin-prettier": "^5.2.2",
+    "globals": "^16.0.0",
+    "husky": "^9.1.7",
+    "jest": "^29.7.0",
+    "prettier": "^3.4.2",
+    "source-map-support": "^0.5.21",
+    "supertest": "^7.0.0",
+    "ts-jest": "^29.2.5",
+    "ts-loader": "^9.5.2",
+    "ts-node": "^10.9.2",
+    "tsconfig-paths": "^4.2.0",
+    "typescript": "^5.7.3",
+    "typescript-eslint": "^8.20.0"
+  },
+  "jest": {
+    "moduleFileExtensions": [
+      "js",
+      "json",
+      "ts"
+    ],
+    "rootDir": "src",
+    "testRegex": ".*\\.spec\\.ts$",
+    "transform": {
+      "^.+\\.(t|j)s$": "ts-jest"
+    },
+    "collectCoverageFrom": [
+      "**/*.(t|j)s"
+    ],
+    "coverageDirectory": "../coverage",
+    "testEnvironment": "node"
+  }
+}

package/src/controllers/sse/index.ts

@@ -0,0 +1,2 @@
+export * from './sse.controller';
+export * from './sse.service';

package/src/controllers/sse/sse.controller.ts

@@ -0,0 +1,25 @@
+import { Controller, Get, Post, Req, Res } from '@nestjs/common';
+import { Request, Response } from 'express';
+
+import { McpLoggerService } from '../../registry/logger.service';
+import { SseService } from './sse.service';
+
+@Controller()
+export class SseController {
+  constructor(
+    private readonly logger: McpLoggerService,
+    private readonly service: SseService,
+  ) {}
+
+  @Get('sse')
+  async handleSse(@Req() req: Request, @Res() res: Response) {
+    this.logger.log('[SSE] Connection established');
+    await this.service.handleSse(req, res);
+  }
+
+  @Post('messages')
+  async handleMessages(@Req() req: Request, @Res() res: Response) {
+    this.logger.log('[SSE] Message received');
+    await this.service.handleMessage(req, res);
+  }
+}

package/src/controllers/sse/sse.service.ts

@@ -0,0 +1,90 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
+import { Inject, Injectable, OnModuleInit } from '@nestjs/common';
+import { Request, Response } from 'express';
+
+import { McpServerOptions } from '../../interfaces/mcp-server-options.interface';
+import { McpLoggerService } from '../../registry/logger.service';
+import { RegistryService } from '../../registry/registry.service';
+
+@Injectable()
+export class SseService implements OnModuleInit {
+  private server: McpServer;
+
+  private transports = {} as Record<string, SSEServerTransport>;
+
+  constructor(
+    @Inject('MCP_SERVER_OPTIONS')
+    private readonly options: McpServerOptions,
+    private readonly registry: RegistryService,
+    private readonly logger: McpLoggerService,
+  ) {
+    this.server = new McpServer(this.options.serverInfo, this.options.options);
+  }
+
+  async onModuleInit() {
+    this.logger.log('Starting MCP controller registration', 'MCP_SERVER');
+    await this.registry.registerAll(this.server);
+    this.logger.log('MCP initialization completed', 'MCP_SERVER');
+  }
+
+  /**
+   * Handle an SSE request for server-sent events
+   *
+   * This establishes a connection for server-to-client notifications
+   */
+  async handleSse(req: Request, res: Response) {
+    // Create SSE transport for legacy clients
+    const transport = new SSEServerTransport('/messages', res);
+    this.transports[transport.sessionId] = transport;
+
+    this.logger.debug(
+      `Starting SSE for sessionId: ${transport.sessionId}`,
+      'api',
+    );
+
+    res.on('close', () => {
+      delete this.transports[transport.sessionId];
+    });
+
+    await this.server.connect(transport);
+  }
+
+  /**
+   * Handle SSE messages sent from client to server
+   */
+  async handleMessage(req: Request, res: Response) {
+    const sessionId = req.query.sessionId as string;
+    const transport = this.transports[sessionId];
+
+    this.logger.debug(
+      `Receiving SSE message for sessionId: ${sessionId}`,
+      'api',
+    );
+
+    this.logger.debug(`SSE message: ${JSON.stringify(req.body)}`, 'MCP_SERVER');
+
+    try {
+      if (transport) {
+        await transport.handlePostMessage(req, res, req.body);
+      } else {
+        res.status(400).send('No transport found for sessionId');
+      }
+    } catch (error) {
+      const errorMessage =
+        error instanceof Error ? error.message : 'Unknown error';
+
+      this.logger.error(
+        'Error al manejar mensaje SSE',
+        errorMessage,
+        'MCP_SERVER',
+      );
+
+      res.status(500).send({
+        statusCode: 500,
+        error: 'Internal Server Error',
+        message: errorMessage,
+      });
+    }
+  }
+}

package/src/controllers/streamable/index.ts

@@ -0,0 +1,2 @@
+export * from './streamable.controller';
+export * from './streamable.service';

package/src/controllers/streamable/streamable.controller.ts

@@ -0,0 +1,24 @@
+import { Controller, Delete, Get, Post, Req, Res } from '@nestjs/common';
+import { Request, Response } from 'express';
+
+import { StreamableService } from './streamable.service';
+
+@Controller()
+export class StreamableController {
+  constructor(private readonly service: StreamableService) {}
+
+  @Post('mcp')
+  async handleMcpPost(@Req() req: Request, @Res() res: Response) {
+    await this.service.handlePostRequest(req, res);
+  }
+
+  @Get('mcp')
+  async handleMcpGet(@Req() req: Request, @Res() res: Response) {
+    await this.service.handleGetRequest(req, res);
+  }
+
+  @Delete('mcp')
+  async handleMcpDelete(@Req() req: Request, @Res() res: Response) {
+    await this.service.handleDeleteRequest(req, res);
+  }
+}

package/src/controllers/streamable/streamable.service.ts

@@ -0,0 +1,169 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { isInitializeRequest } from '@modelcontextprotocol/sdk/types.js';
+import { Inject, Injectable, OnModuleInit } from '@nestjs/common';
+import { randomUUID } from 'crypto';
+import { Request, Response } from 'express';
+
+import {
+  McpModuleTransportOptions,
+  McpServerOptions,
+} from '../../interfaces/mcp-server-options.interface';
+import { McpLoggerService } from '../../registry/logger.service';
+import { RegistryService } from '../../registry/registry.service';
+// TODO: Stateless mode should be handled here or in another service
+
+@Injectable()
+export class StreamableService implements OnModuleInit {
+  private server: McpServer;
+
+  private transports = {} as Record<string, StreamableHTTPServerTransport>;
+
+  constructor(
+    @Inject('MCP_SERVER_OPTIONS')
+    private readonly options: McpServerOptions,
+    @Inject('MCP_TRANSPORT_OPTIONS')
+    private readonly transportOptions: McpModuleTransportOptions,
+    private readonly registry: RegistryService,
+    private readonly logger: McpLoggerService,
+  ) {
+    this.server = new McpServer(this.options.serverInfo, this.options.options);
+  }
+
+  async onModuleInit() {
+    await this.registry.registerAll(this.server);
+
+    this.logger.log('MCP STREAMEABLE initialization completed');
+  }
+
+  /**
+   * Handle a streamable HTTP POST request from a client
+   *
+   * - Uses sessionId from query or generates a new one if missing
+   * - Stores the transport by sessionId for later retrieval
+   * - Cleans up transport on connection close
+   *
+   * @param req Express Request object (expects sessionId in query)
+   * @param res Express Response object
+   */
+  async handlePostRequest(
+    req: Request<any, any, any, { sessionId?: string }>,
+    res: Response,
+  ) {
+    const sessionId = req.headers['mcp-session-id'] as string | undefined;
+    let transport: StreamableHTTPServerTransport;
+
+    const { options } = this.transportOptions?.streamable || {};
+
+    if (sessionId && this.transports[sessionId]) {
+      transport = this.transports[sessionId];
+    } else if (!sessionId && isInitializeRequest(req.body)) {
+      transport = new StreamableHTTPServerTransport({
+        sessionIdGenerator: () =>
+          options?.sessionIdGenerator?.() || randomUUID(),
+        onsessioninitialized: (sessionId) => {
+          this.transports[sessionId] = transport;
+        },
+        enableJsonResponse: options?.enableJsonResponse,
+        eventStore: options?.eventStore,
+      });
+
+      transport.onclose = () => {
+        if (transport.sessionId) {
+          delete this.transports[transport.sessionId];
+        }
+      };
+
+      await this.server.connect(transport);
+    } else {
+      // Invalid request
+      res.status(400).json({
+        jsonrpc: '2.0',
+        error: {
+          code: -32000,
+          message: 'Bad Request: No valid session ID provided',
+        },
+        id: null,
+      });
+
+      return;
+    }
+
+    await transport.handleRequest(req, res, req.body);
+  }
+
+  /**
+   * Handle a streamable HTTP GET request from a client
+   *
+   * This method retrieves the existing streamable transport for the session and delegates the request.
+   *
+   * @param req Express Request object (expects sessionId in query)
+   * @param res Express Response object
+   */
+  async handleGetRequest(
+    req: Request<any, any, any, { sessionId?: string }>,
+    res: Response,
+  ) {
+    const sessionId = req.headers['mcp-session-id'] as string | undefined;
+
+    if (!sessionId || !this.transports[sessionId]) {
+      res.status(400).send('Invalid or missing session ID');
+      return;
+    }
+
+    const transport = this.transports[sessionId];
+
+    await transport.handleRequest(req, res);
+  }
+
+  /**
+   * Handle a streamable HTTP DELETE request to clean up a session
+   *
+   * - Accepts sessionId from query or x-mcp-session-id header
+   * - Closes and removes the transport if found
+   * - Always sends a response
+   *
+   * @param req Express Request object
+   * @param res Express Response object
+   */
+  async handleDeleteRequest(
+    req: Request<any, any, any, { sessionId?: string }>,
+    res: Response,
+  ) {
+    const sessionId = req.headers['mcp-session-id'] as string | undefined;
+
+    if (!sessionId) {
+      res.status(400).json({ error: 'Missing sessionId' });
+      return;
+    }
+
+    const transport = this.transports[sessionId];
+
+    if (transport) {
+      this.logger.debug(
+        `Closing streamable transport for sessionId: ${sessionId}`,
+        'STREAMABLE',
+      );
+
+      await transport.close();
+
+      const uuidV4Regex =
+        /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+      if (!uuidV4Regex.test(sessionId)) {
+        res.status(400).json({ error: 'Invalid sessionId format' });
+        return;
+      }
+
+      delete this.transports[sessionId];
+
+      res.status(200).json({ success: true, sessionId });
+    } else {
+      this.logger.debug(
+        `No streamable transport found for sessionId: ${sessionId}`,
+        'STREAMABLE',
+      );
+      res.status(404).json({ error: 'Transport not found', sessionId });
+    }
+  }
+}

package/src/decorators/capabilities.constants.ts

@@ -0,0 +1,7 @@
+// Prefijo para todas las constantes de metadatos
+export const PREFIX = 'MCP';
+
+// Constantes de metadatos para decoradores de método
+export const MCP_TOOL = `${PREFIX}:tool`;
+export const MCP_PROMPT = `${PREFIX}:prompt`;
+export const MCP_RESOURCE = `${PREFIX}:resource`;

package/src/decorators/capabilities.decorators.ts

@@ -0,0 +1,150 @@
+import { Injectable, SetMetadata } from '@nestjs/common';
+
+import {
+  PromptOptions,
+  ResourceOptions,
+  ToolOptions,
+} from '../interfaces/capabilities.interface';
+import { MCP_PROMPT, MCP_RESOURCE, MCP_TOOL } from './capabilities.constants';
+
+/**
+ * Metadata key to mark a class as an MCP Resolver.
+ */
+export const MCP_RESOLVER = '__mcp_resolver__';
+
+/**
+ * Metadata key to attach guards to a Resolver class or method.
+ */
+export const MCP_GUARDS = '__mcp_guards__';
+
+/**
+ * Decorator for marking a class as an MCP Resolver.
+ * Enables dependency injection and workspace grouping for MCP capabilities.
+ *
+ * @param workspace Optional workspace/namespace for grouping capabilities
+ * @example
+ * @Resolver('my-workspace')
+ * export class MyResolver { ... }
+ */
+export function Resolver(workspace?: string): ClassDecorator {
+  return function (target: any) {
+    Injectable()(target);
+    SetMetadata(MCP_RESOLVER, workspace || true)(target);
+  };
+}
+
+/**
+ * Decorator to attach one or more guards to a Resolver class or method.
+ * Accepts guard classes or instances implementing CanActivate.
+ *
+ * @param guards One or more guard classes or instances
+ * @example
+ * @UseGuards(MyGuard)
+ * @Resolver('workspace')
+ * export class MyResolver { ... }
+ */
+export function UseGuards(...guards: any[]): ClassDecorator & MethodDecorator {
+  return SetMetadata(MCP_GUARDS, guards);
+}
+
+/**
+ * Decorator for marking a method as an MCP Tool.
+ * Use with @McpProvider.
+ *
+ * La herramienta debe devolver un objeto con el formato:
+ * {
+ *   content: [
+ *     {
+ *       type: 'text', // Puede ser 'text', 'image', 'video', 'audio', etc.
+ *       text: 'Texto de la respuesta',
+ *     }
+ *   ]
+ * }
+ *
+ * @param options Tool configuration
+ */
+export function Tool(options: ToolOptions) {
+  return function (
+    target: object,
+    propertyKey: string,
+    descriptor: PropertyDescriptor,
+  ) {
+    SetMetadata(MCP_TOOL, {
+      ...options,
+      methodName: propertyKey,
+    })(target, propertyKey, descriptor);
+
+    return descriptor;
+  };
+}
+
+/**
+ * Decorator for marking a method as an MCP Prompt.
+ * Use with @McpProvider.
+ *
+ * El prompt debe devolver un objeto con el formato:
+ * {
+ *   messages: [
+ *     {
+ *       role: 'assistant',
+ *       content: {
+ *         type: 'text',
+ *         text: 'Texto del mensaje'
+ *       }
+ *     }
+ *   ]
+ * }
+ *
+ * @param options Prompt configuration
+ */
+export function Prompt(options: PromptOptions) {
+  return function (
+    target: object,
+    propertyKey: string,
+    descriptor: PropertyDescriptor,
+  ) {
+    SetMetadata(MCP_PROMPT, {
+      ...options,
+      methodName: propertyKey,
+    })(target, propertyKey, descriptor);
+
+    return descriptor;
+  };
+}
+
+/**
+ * Decorator for marking a method as an MCP Resource provider.
+ * Use with @McpProvider.
+ *
+ * Hay dos modos de uso para los recursos:
+ *
+ * 1. Recurso con URI fija:
+ * @Resource({
+ *   name: 'nombreRecurso',
+ *   uri: 'resource://midominio/recurso'
+ * })
+ *
+ * 2. Recurso con plantilla (para parámetros dinámicos):
+ * @Resource({
+ *   name: 'nombreRecurso',
+ *   template: 'resource://midominio/recurso/{parametro}'
+ * })
+ *
+ * También se puede proporcionar solo el nombre como string:
+ * @Resource('nombreRecurso')
+ *
+ * @param options Resource configuration or just the name as a string
+ */
+export function Resource(options: ResourceOptions) {
+  return function (
+    target: object,
+    propertyKey: string,
+    descriptor: PropertyDescriptor,
+  ) {
+    SetMetadata(MCP_RESOURCE, {
+      ...options,
+      methodName: propertyKey,
+    })(target, propertyKey, descriptor);
+    return descriptor;
+  };
+}

package/src/decorators/index.ts

@@ -0,0 +1,2 @@
+export * from './capabilities.constants';
+export * from './capabilities.decorators';

package/src/index.ts

@@ -0,0 +1,11 @@
+// Core components
+export * from './mcp.module';
+
+// Interfaces
+export * from './interfaces';
+
+// Registry components
+export * from './registry';
+
+// Decorators
+export * from './decorators';

package/src/interceptors/message.interceptor.ts

@@ -0,0 +1,70 @@
+import {
+  CallHandler,
+  ExecutionContext,
+  Injectable,
+  NestInterceptor,
+} from '@nestjs/common';
+import { Request, Response } from 'express';
+import { Observable } from 'rxjs';
+
+import { McpMessage } from '../interfaces/message.types';
+import { McpLoggerService } from '../registry/logger.service';
+import { MessageService } from '../services/message.service';
+@Injectable()
+export class RequestContextInterceptor implements NestInterceptor {
+  constructor(
+    private readonly logger: McpLoggerService,
+    private readonly messageService: MessageService,
+  ) {}
+
+  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
+    const request = context.switchToHttp().getRequest<Request>();
+    const response = context.switchToHttp().getResponse<Response>();
+    let message: McpMessage | undefined;
+
+    this.logger.log(
+      `Request path: ${request.path}`,
+      '[RequestContextInterceptor]',
+    );
+
+    switch (request.path) {
+      case '/sse':
+        this.logger.log(
+          'SSE connection detected',
+          '[RequestContextInterceptor]',
+        );
+
+        message = {
+          req: request,
+          res: response,
+        };
+
+        this.messageService.set(message);
+
+        break;
+      case '/messages':
+        this.logger.log('SSE message received', '[RequestContextInterceptor]');
+
+        message = {
+          req: request,
+          res: response,
+        };
+
+        this.messageService.set(message);
+
+        break;
+      case '/mcp':
+        this.logger.log('MCP request detected', '[RequestContextInterceptor]');
+        // TODO: Handle MCP request
+        break;
+      default:
+        this.logger.log(
+          `Regular request: ${request.method} ${request.url}`,
+          '[RequestContextInterceptor]',
+        );
+        break;
+    }
+
+    return next.handle();
+  }
+}