@nestjs-mcp/server 0.1.0-alpha.4

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,168 @@
+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];
+        }
+      };
+    } 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/interfaces/capabilities.interface.ts

@@ -0,0 +1,95 @@
+import {
+  CompleteResourceTemplateCallback,
+  ListResourcesCallback,
+} from '@modelcontextprotocol/sdk/server/mcp';
+import { ZodOptional, ZodRawShape, ZodType, ZodTypeDef } from 'zod';
+
+export interface ResourceBaseOptions {
+  name: string;
+}
+
+export interface ResourceUriOptions extends ResourceBaseOptions {
+  uri: string;
+}
+
+export interface ResourceUriWithMetadataOptions extends ResourceUriOptions {
+  metadata: Record<string, any>;
+}
+
+export interface ResourceTemplateOptions extends ResourceBaseOptions {
+  template: string;
+}
+
+export interface ResourceTemplateWithMetadataOptions
+  extends ResourceTemplateOptions {
+  metadata: Record<string, any>;
+}
+
+export type ResourceOptions =
+  | ResourceUriOptions
+  | ResourceUriWithMetadataOptions
+  | ResourceTemplateOptions
+  | ResourceTemplateWithMetadataOptions;
+
+export interface ToolNameOptions {
+  name: string;
+}
+
+export interface ToolWithDescriptionOptions extends ToolNameOptions {
+  description: string;
+}
+
+export interface ToolWithParamSchemaOptions extends ToolNameOptions {
+  paramSchema: ZodRawShape;
+}
+
+export interface ToolWithDescriptionAndParamSchemaOptions
+  extends ToolWithDescriptionOptions,
+    ToolWithParamSchemaOptions {}
+
+export type ToolOptions =
+  | ToolNameOptions
+  | ToolWithDescriptionOptions
+  | ToolWithParamSchemaOptions
+  | ToolWithDescriptionAndParamSchemaOptions;
+
+export interface PromptBaseOptions {
+  name: string;
+}
+
+export interface PromptWithDescriptionOptions extends PromptBaseOptions {
+  description: string;
+}
+
+type PromptArgsRawShape = {
+  [k: string]:
+    | ZodType<string, ZodTypeDef, string>
+    | ZodOptional<ZodType<string, ZodTypeDef, string>>;
+};
+
+export interface PromptWithArgsSchemaOptions extends PromptBaseOptions {
+  argsSchema: PromptArgsRawShape;
+}
+
+export interface PromptWithDescriptionAndArgsSchemaOptions
+  extends PromptWithDescriptionOptions,
+    PromptWithArgsSchemaOptions {}
+
+export type PromptOptions =
+  | PromptBaseOptions
+  | PromptWithDescriptionOptions
+  | PromptWithArgsSchemaOptions
+  | PromptWithDescriptionAndArgsSchemaOptions;
+
+export interface TemplateCallbacks {
+  /**
+   * A callback to list all resources matching this template. This is required to specified, even if `undefined`, to avoid accidentally forgetting resource listing.
+   */
+  list: ListResourcesCallback | undefined;
+  /**
+   * An optional callback to autocomplete variables within the URI template. Useful for clients and users to discover possible values.
+   */
+  complete?: {
+    [variable: string]: CompleteResourceTemplateCallback;
+  };
+}

package/src/interfaces/guards.interface.ts

@@ -0,0 +1,13 @@
+import { ExecutionContext } from '@nestjs/common';
+
+/**
+ * Custom execution context for MCP guards.
+ * Extends NestJS ExecutionContext and adds args for MCP method arguments.
+ *
+ * @property args - The arguments passed to the MCP method
+ */
+// TODO: Type Args correctly
+export interface McpExecutionContext extends ExecutionContext {
+  /** The arguments passed to the MCP method */
+  args: unknown[];
+}

package/src/interfaces/index.ts

@@ -0,0 +1,2 @@
+export * from './guards.interface';
+export * from './mcp-server-options.interface';

package/src/interfaces/mcp-server-options.interface.ts

@@ -0,0 +1,105 @@
+import { StreamableHTTPServerTransportOptions } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { ProtocolOptions } from '@modelcontextprotocol/sdk/shared/protocol';
+import {
+  Implementation,
+  ServerCapabilities,
+} from '@modelcontextprotocol/sdk/types';
+import { Provider, Type } from '@nestjs/common';
+
+export type ServerOptions = {
+  instructions?: string;
+  capabilities?: ServerCapabilities;
+  protocolOptions?: ProtocolOptions;
+};
+
+export type McpServerOptions = {
+  serverInfo: Implementation;
+  options?: ServerOptions;
+  logging?: McpLoggingOptions;
+};
+
+/**
+ * Opciones para configurar el logging del servidor MCP
+ */
+export interface McpLoggingOptions {
+  /**
+   * Habilitar o deshabilitar el logging
+   * @default true
+   */
+  enabled?: boolean;
+
+  /**
+   * Nivel de detalle del logging
+   * @default 'verbose'
+   */
+  level?: 'debug' | 'verbose' | 'log' | 'warn' | 'error';
+}
+
+/**
+ * Options for configuring the global MCP server module
+ */
+export interface McpModuleOptions {
+  /**
+   * Additional modules to import
+   */
+  imports?: Type<any>[];
+  /**
+   * Providers to register in the module
+   * These will be available globally
+   */
+  providers?: Provider[];
+  /**
+   * Name of the MCP server
+   */
+  name: string;
+  /**
+   * Version of the MCP server
+   */
+  version: string;
+  /**
+   * Description to give the AI about the server
+   */
+  instructions?: string;
+  /**
+   * Describes the server's purpose or behavior for the AI
+   */
+  capabilities?: ServerCapabilities;
+  /**
+   * Protocol-specific options
+   */
+  protocolOptions?: ProtocolOptions;
+  /**
+   * Options for configuring MCP server logging
+   */
+  logging?: McpLoggingOptions;
+  /**
+   * Options for configuring a feature module with MCP capabilities
+   */
+  transports?: McpModuleTransportOptions;
+}
+
+export type McpModuleTransportOptions = {
+  streamable?: {
+    enabled: boolean;
+    /**
+     * Streamable transport options. sessionIdGenerator is optional here, even if required in the SDK type.
+     */
+    options?: Omit<
+      StreamableHTTPServerTransportOptions,
+      'onsessioninitialized' | 'sessionIdGenerator'
+    > & {
+      sessionIdGenerator?: () => string | undefined;
+    };
+  };
+  sse?: {
+    enabled: boolean;
+  };
+};
+
+/**
+ * Options for configuring a feature module with MCP capabilities
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface McpFeatureOptions {
+  // TODO: Maybe its needed to implement Guards for all capabilities in this module o a specific logger configuration
+}