@nestjs-mcp/server 0.1.1 → 0.2.0-alpha.1

package/src/interfaces/capabilities.interface.ts

@@ -1,206 +0,0 @@
-import {
-  CompleteResourceTemplateCallback,
-  ListResourcesCallback,
-} from '@modelcontextprotocol/sdk/server/mcp.js';
-import { RequestHandlerExtra as SdkRequestHandlerExtra } from '@modelcontextprotocol/sdk/shared/protocol.js';
-import {
-  ServerNotification,
-  ServerRequest,
-} from '@modelcontextprotocol/sdk/types.js';
-import {
-  z,
-  ZodOptional,
-  ZodRawShape,
-  ZodType,
-  ZodTypeAny,
-  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;
-  };
-}
-
-export type RequestHandlerExtra = SdkRequestHandlerExtra<
-  ServerRequest,
-  ServerNotification
->;
-
-export class ResourceUriHandlerParams {
-  public readonly uri: URL;
-  public readonly extra: RequestHandlerExtra;
-
-  private constructor(uri: URL, extra: RequestHandlerExtra) {
-    this.uri = uri;
-    this.extra = extra;
-  }
-
-  static from(uri: URL, extra: RequestHandlerExtra): ResourceUriHandlerParams {
-    return new ResourceUriHandlerParams(uri, extra);
-  }
-}
-
-export class ResourceTemplateHandlerParams {
-  public readonly uri: URL;
-  public readonly variables?: Record<string, string>;
-  public readonly extra: RequestHandlerExtra;
-
-  private constructor(
-    uri: URL,
-    extra: RequestHandlerExtra,
-    variables?: Record<string, string>,
-  ) {
-    this.uri = uri;
-    this.extra = extra;
-    this.variables = variables;
-  }
-
-  static from(
-    uri: URL,
-    extra: RequestHandlerExtra,
-    variables?: Record<string, string>,
-  ): ResourceTemplateHandlerParams {
-    return new ResourceTemplateHandlerParams(uri, extra, variables);
-  }
-}
-
-export class PromptHandlerParams<
-  Args extends PromptArgsRawShape | undefined = undefined,
-> {
-  public readonly args?: Args extends PromptArgsRawShape
-    ? z.objectOutputType<Args, ZodTypeAny>
-    : undefined;
-  public readonly extra: RequestHandlerExtra;
-
-  private constructor(
-    extra: RequestHandlerExtra,
-    args?: Args extends PromptArgsRawShape
-      ? z.objectOutputType<Args, ZodTypeAny>
-      : undefined,
-  ) {
-    this.extra = extra;
-    this.args = args;
-  }
-
-  static from<Args extends PromptArgsRawShape | undefined>(
-    extra: RequestHandlerExtra,
-    args?: Args extends PromptArgsRawShape
-      ? z.objectOutputType<Args, ZodTypeAny>
-      : undefined,
-  ): PromptHandlerParams<Args> {
-    return new PromptHandlerParams<Args>(extra, args);
-  }
-}
-
-export class ToolHandlerParams<
-  Args extends ZodRawShape | undefined = undefined,
-> {
-  public readonly args?: Args extends ZodRawShape
-    ? z.objectOutputType<Args, ZodTypeAny>
-    : undefined;
-  public readonly extra: RequestHandlerExtra;
-
-  private constructor(
-    extra: RequestHandlerExtra,
-    args?: Args extends ZodRawShape
-      ? z.objectOutputType<Args, ZodTypeAny>
-      : undefined,
-  ) {
-    this.extra = extra;
-    this.args = args;
-  }
-
-  static from<Args extends ZodRawShape | undefined>(
-    extra: RequestHandlerExtra,
-    args?: Args extends ZodRawShape
-      ? z.objectOutputType<Args, ZodTypeAny>
-      : undefined,
-  ): ToolHandlerParams<Args> {
-    return new ToolHandlerParams<Args>(extra, args);
-  }
-}

package/src/interfaces/context.interface.ts

@@ -1,33 +0,0 @@
-import { ExecutionContext } from '@nestjs/common';
-
-import {
-  PromptHandlerParams,
-  ResourceTemplateHandlerParams,
-  ResourceUriHandlerParams,
-  ToolHandlerParams,
-} from './capabilities.interface';
-/**
- * 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: Remove extends ExecutionContext we don't need it
-export interface McpExecutionContext extends ExecutionContext {
-  // TODO: Remove this once the getArgs method implementation is complete.
-  args:
-    | ResourceUriHandlerParams
-    | ResourceTemplateHandlerParams
-    | PromptHandlerParams
-    | ToolHandlerParams;
-
-  // TODO: Uncomment this once the getArgs type is fixed
-  // getArgs: () =>
-  //   | ResourceUriHandlerParams
-  //   | ResourceTemplateHandlerParams
-  //   | PromptHandlerParams
-  //   | ToolHandlerParams;
-
-  getSessionId: () => string;
-}

package/src/interfaces/index.ts

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

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

@@ -1,105 +0,0 @@
-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

@@ -1,13 +0,0 @@
-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

@@ -1,244 +0,0 @@
-import { Implementation } from '@modelcontextprotocol/sdk/types.js';
-import { DynamicModule, Module, Provider, Type } from '@nestjs/common';
-import { DiscoveryModule } from '@nestjs/core';
-import { AsyncLocalStorage } from 'async_hooks';
-
-import { SseController, SseService } from './controllers/sse';
-import {
-  StreamableController,
-  StreamableService,
-} from './controllers/streamable';
-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 { SessionManager } from './services/session.manager';
-@Module({
-  imports: [DiscoveryModule],
-  providers: [
-    RegistryService,
-    DiscoveryService,
-    {
-      provide: AsyncLocalStorage,
-      useValue: new AsyncLocalStorage(),
-    },
-    McpLoggerService,
-    SessionManager,
-  ],
-  exports: [SessionManager],
-})
-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

@@ -1,28 +0,0 @@
-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();
-  });
-});