@nestjs-mcp/server 0.1.0-alpha.10

package/src/interfaces/capabilities.interface.ts

@@ -0,0 +1,95 @@
+import {
+  CompleteResourceTemplateCallback,
+  ListResourcesCallback,
+} from '@modelcontextprotocol/sdk/server/mcp.js';
+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/context.interface.ts

@@ -0,0 +1,18 @@
+import { ExecutionContext } from '@nestjs/common';
+
+import { McpMessage } from './message.types';
+/**
+ * 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
+ * @property message - The current message from the request
+ */
+// TODO: Type Args correctly
+export interface McpExecutionContext extends ExecutionContext {
+  /** The arguments passed to the MCP method */
+  args: unknown[];
+
+  /** The current message from the request */
+  message: McpMessage | undefined;
+}

package/src/interfaces/index.ts

@@ -0,0 +1,2 @@
+export * from './context.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.js';
+import {
+  Implementation,
+  ServerCapabilities,
+} from '@modelcontextprotocol/sdk/types.js';
+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
+}

package/src/interfaces/message.types.ts

@@ -0,0 +1,13 @@
+import {
+  Request as ExpressRequest,
+  Response as ExpressResponse,
+} from 'express';
+
+export type Request = ExpressRequest & {
+  auth?: any;
+};
+
+export type McpMessage = {
+  req: Request;
+  res: ExpressResponse;
+};

package/src/mcp.module.ts

@@ -0,0 +1,250 @@
+import { Implementation } from '@modelcontextprotocol/sdk/types.js';
+import { DynamicModule, Module, Provider, Type } from '@nestjs/common';
+import { APP_INTERCEPTOR, DiscoveryModule } from '@nestjs/core';
+import { AsyncLocalStorage } from 'async_hooks';
+
+import { SseController, SseService } from './controllers/sse';
+import {
+  StreamableController,
+  StreamableService,
+} from './controllers/streamable';
+import { RequestContextInterceptor } from './interceptors/message.interceptor';
+import {
+  McpFeatureOptions,
+  McpLoggingOptions,
+  McpModuleOptions,
+  McpModuleTransportOptions,
+  ServerOptions,
+} from './interfaces/mcp-server-options.interface';
+import { DiscoveryService } from './registry/discovery.service';
+import { McpLoggerService } from './registry/logger.service';
+import { RegistryService } from './registry/registry.service';
+import { MessageService } from './services/message.service';
+
+@Module({
+  imports: [DiscoveryModule],
+  providers: [
+    RegistryService,
+    DiscoveryService,
+    {
+      provide: AsyncLocalStorage,
+      useValue: new AsyncLocalStorage(),
+    },
+    McpLoggerService,
+    MessageService,
+    {
+      provide: APP_INTERCEPTOR,
+      useClass: RequestContextInterceptor,
+    },
+  ],
+  exports: [MessageService],
+})
+export class McpModule {
+  /**
+   * Helper: Get active transport controllers and providers
+   */
+  private static getActiveTransportControllersAndProviders(
+    transports?: McpModuleTransportOptions,
+  ) {
+    const controllers = new Set<Type<any>>();
+    const providers = new Set<Provider>();
+
+    // Transport configurations
+    const STREAMABLE_TRANSPORT = {
+      controller: StreamableController,
+      service: StreamableService,
+    };
+
+    const SSE_TRANSPORT = {
+      controller: SseController,
+      service: SseService,
+    };
+
+    // Default configuration
+    const defaultTransports: McpModuleTransportOptions = {
+      streamable: { enabled: true },
+      sse: { enabled: true },
+    };
+
+    // Merge default with provided transports
+    const config = {
+      streamable: {
+        ...defaultTransports.streamable,
+        ...(transports?.streamable ?? {}),
+      },
+      sse: {
+        ...defaultTransports.sse,
+        ...(transports?.sse ?? {}),
+      },
+    };
+
+    // Add controllers and providers based on enabled transports
+    if (config.streamable.enabled) {
+      controllers.add(STREAMABLE_TRANSPORT.controller);
+      providers.add(STREAMABLE_TRANSPORT.service);
+    }
+
+    if (config.sse.enabled) {
+      controllers.add(SSE_TRANSPORT.controller);
+      providers.add(SSE_TRANSPORT.service);
+    }
+
+    return {
+      controllers: Array.from(controllers),
+      providers: Array.from(providers),
+    };
+  }
+
+  /**
+   * Helper to build server info, options, and logging config
+   */
+  private static buildServerConfig(options: McpModuleOptions) {
+    const serverInfo: Implementation = {
+      name: options.name,
+      version: options.version,
+    };
+    const serverOptions: ServerOptions = {
+      instructions: options?.instructions,
+      capabilities: options?.capabilities,
+      ...(options?.protocolOptions || {}),
+    };
+    const loggingOptions: McpLoggingOptions = {
+      enabled: options.logging?.enabled !== false,
+      level: options.logging?.level || 'verbose',
+    };
+    return { serverInfo, serverOptions, loggingOptions };
+  }
+
+  /**
+   * Configures the MCP module with global options
+   *
+   * @param options Configuration options for the MCP server
+   * @returns Dynamic module configuration
+   */
+  static forRoot(options: McpModuleOptions): DynamicModule {
+    const imports = options.imports || [];
+    const { controllers, providers } =
+      this.getActiveTransportControllersAndProviders(options.transports);
+    const allProviders = [...(options.providers || []), ...providers];
+    const { serverInfo, serverOptions, loggingOptions } =
+      this.buildServerConfig(options);
+    return {
+      module: McpModule,
+      imports,
+      controllers,
+      providers: [
+        ...allProviders,
+        {
+          provide: 'MCP_SERVER_OPTIONS',
+          useValue: {
+            serverInfo,
+            options: serverOptions,
+            logging: loggingOptions,
+          },
+        },
+        {
+          provide: 'MCP_LOGGING_OPTIONS',
+          useValue: loggingOptions,
+        },
+        {
+          provide: 'MCP_TRANSPORT_OPTIONS',
+          useValue: options.transports,
+        },
+      ],
+      global: true,
+    };
+  }
+
+  /**
+   * Configures the MCP module with global options and ConfigModule support
+   * Allows using environment variables and centralized configurations
+   *
+   * @param options Configuration options for the MCP server
+   * @returns Dynamic module configuration
+   */
+  static forRootAsync(options: {
+    imports?: any[];
+    useFactory: (
+      ...args: unknown[]
+    ) => Promise<McpModuleOptions> | McpModuleOptions;
+    inject?: any[];
+  }): DynamicModule {
+    const { imports = [], useFactory, inject = [] } = options;
+    const safeInject = Array.isArray(inject) ? inject : [];
+    const safeImports = Array.isArray(imports) ? imports : [];
+    const providers = [
+      {
+        provide: 'MCP_SERVER_OPTIONS',
+        useFactory: async (...args: unknown[]) => {
+          const mcpOptions = await useFactory(...args);
+          const { serverInfo, serverOptions, loggingOptions } =
+            this.buildServerConfig(mcpOptions);
+          return {
+            serverInfo,
+            options: serverOptions,
+            logging: loggingOptions,
+          };
+        },
+        inject: safeInject,
+      },
+      {
+        provide: 'MCP_LOGGING_OPTIONS',
+        useFactory: async (...args: unknown[]) => {
+          const mcpOptions = await useFactory(...args);
+          return {
+            enabled: mcpOptions.logging?.enabled !== false,
+            level: mcpOptions.logging?.level || 'verbose',
+          };
+        },
+        inject: safeInject,
+      },
+    ];
+    const asyncControllersFactory = async (...args: unknown[]) => {
+      const mcpOptions = await useFactory(...args);
+      return this.getActiveTransportControllersAndProviders(
+        mcpOptions.transports,
+      ).controllers;
+    };
+    const asyncProvidersFactory = async (...args: unknown[]) => {
+      const mcpOptions = await useFactory(...args);
+      const { providers } = this.getActiveTransportControllersAndProviders(
+        mcpOptions.transports,
+      );
+      return [...(mcpOptions.providers || []), ...providers];
+    };
+    return {
+      module: McpModule,
+      imports: safeImports,
+      controllers: [], // Will be resolved at runtime by NestJS
+      providers: [
+        ...providers,
+        {
+          provide: '__MCP_ASYNC_CONTROLLERS__',
+          useFactory: asyncControllersFactory,
+          inject: safeInject,
+        },
+        {
+          provide: '__MCP_ASYNC_PROVIDERS__',
+          useFactory: asyncProvidersFactory,
+          inject: safeInject,
+        },
+      ],
+      global: true,
+    };
+  }
+
+  /**
+   * Registers feature-specific capabilities like tools, prompts, and resources
+   * through dedicated service providers
+   *
+   * @param options Configuration options for the feature module
+   * @returns A dynamic module configuration
+   */
+  // TODO: Implement specific Module options
+
+  static forFeature(_options?: McpFeatureOptions): DynamicModule {
+    return {
+      module: McpModule,
+    };
+  }
+}

package/src/mcp.service.spec.ts

@@ -0,0 +1,28 @@
+import { Test, TestingModule } from '@nestjs/testing';
+
+import { SseService } from './controllers/sse';
+import { StreamableService } from './controllers/streamable';
+import { McpModule } from './mcp.module';
+describe('NestjsMcpServerService', () => {
+  let streamableService: StreamableService;
+  let sseService: SseService;
+
+  beforeEach(async () => {
+    const module: TestingModule = await Test.createTestingModule({
+      imports: [
+        McpModule.forRoot({
+          name: 'test',
+          version: '1.0.0',
+        }),
+      ],
+    }).compile();
+
+    streamableService = module.get<StreamableService>(StreamableService);
+    sseService = module.get<SseService>(SseService);
+  });
+
+  it('should be defined', () => {
+    expect(streamableService).toBeDefined();
+    expect(sseService).toBeDefined();
+  });
+});

package/src/registry/discovery.service.ts

@@ -0,0 +1,116 @@
+import { Injectable } from '@nestjs/common';
+import {
+  MetadataScanner,
+  DiscoveryService as NestDiscoveryService,
+  Reflector,
+} from '@nestjs/core';
+import { InstanceWrapper } from '@nestjs/core/injector/instance-wrapper';
+
+export interface MethodWithMetadata<T = unknown> {
+  method: string;
+  metadata: T;
+  handler: (...args: any[]) => any;
+  instance: object;
+}
+
+type ProviderInstance = Record<string, unknown>;
+
+@Injectable()
+export class DiscoveryService {
+  constructor(
+    private readonly discoveryService: NestDiscoveryService,
+    private readonly metadataScanner: MetadataScanner,
+    private readonly reflector: Reflector,
+  ) {}
+
+  /**
+   * Get all methods with specific metadata from all providers (now scans all @Injectable, not just @McpProvider)
+   */
+  public getAllMethodsWithMetadata<T = unknown>(
+    metadataKey: string,
+  ): MethodWithMetadata<T>[] {
+    const providers = this.discoveryService.getProviders();
+    const result: MethodWithMetadata<T>[] = [];
+
+    // Scan ALL providers, not just those with MCP_PROVIDER
+    for (const provider of providers) {
+      if (!provider.instance) {
+        continue;
+      }
+
+      const methods = this.getMethodsWithMetadataFromProvider<T>(
+        provider,
+        metadataKey,
+      );
+
+      if (methods.length > 0) {
+        result.push(...methods);
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Get all methods with a specific metadata from a single provider.
+   */
+  public getMethodsWithMetadataFromProvider<T = unknown>(
+    provider: InstanceWrapper,
+    metadataKey: string,
+  ): MethodWithMetadata<T>[] {
+    if (!provider.instance) {
+      return [];
+    }
+
+    const instance = provider.instance as ProviderInstance;
+    const instancePrototype = Object.getPrototypeOf(instance) as Record<
+      string,
+      unknown
+    >;
+
+    if (!instancePrototype) {
+      return [];
+    }
+
+    const methodNames =
+      this.metadataScanner.getAllMethodNames(instancePrototype);
+    const result: MethodWithMetadata<T>[] = [];
+
+    for (const methodName of methodNames) {
+      // Removed hasOwnProperty check to allow inherited methods
+      const methodFunction = instancePrototype[methodName];
+      if (typeof methodFunction !== 'function') {
+        continue;
+      }
+
+      const metadata = this.reflector.get<T>(metadataKey, methodFunction);
+
+      if (metadata) {
+        const handlerProperty = instance[methodName];
+
+        if (typeof handlerProperty !== 'function') {
+          continue;
+        }
+
+        const handler = ((...args: unknown[]): unknown => {
+          return handlerProperty.apply(instance, args);
+        }) as (...args: any[]) => any;
+
+        // Preserve the original method name
+        Object.defineProperty(handler, 'name', {
+          value: methodName,
+          writable: false,
+        });
+
+        result.push({
+          method: methodName,
+          metadata: metadata as T,
+          handler,
+          instance,
+        });
+      }
+    }
+
+    return result;
+  }
+}

package/src/registry/index.ts

@@ -0,0 +1,2 @@
+export * from './discovery.service';
+export * from './registry.service';