@rekog/mcp-nest 1.9.10 → 2.0.0-alpha.0

package/src/mcp/services/sse-ping.service.ts

@@ -1,144 +0,0 @@
-import {
-  Injectable,
-  OnModuleInit,
-  OnModuleDestroy,
-  Logger,
-  Inject,
-  Optional,
-} from '@nestjs/common';
-import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
-import { HttpResponse } from '../interfaces/http-adapter.interface';
-import type { McpOptions } from '../interfaces';
-import { createMcpLogger } from '../utils/mcp-logger.factory';
-
-/**
- * Service that implements automatic ping for SSE connections
- * This prevents browser/client timeouts for long-lived connections
- */
-@Injectable()
-export class SsePingService implements OnModuleInit, OnModuleDestroy {
-  private pingInterval: NodeJS.Timeout | null = null;
-  private readonly logger: Logger;
-  private readonly activeConnections = new Map<
-    string,
-    {
-      transport: SSEServerTransport;
-      res: HttpResponse;
-    }
-  >();
-
-  // Default to 30 seconds - this is a reasonable interval for most clients
-  private pingIntervalMs = 30000;
-
-  constructor(@Optional() @Inject('MCP_OPTIONS') options?: McpOptions) {
-    this.logger = createMcpLogger(SsePingService.name, options);
-  }
-
-  onModuleInit() {
-    this.logger.log('Initializing SSE ping service');
-  }
-
-  onModuleDestroy() {
-    this.stopPingInterval();
-    this.logger.log('SSE ping service stopped');
-  }
-
-  /**
-   * Configure the ping service
-   */
-  configure(options: { pingEnabled?: boolean; pingIntervalMs?: number }) {
-    if (options.pingIntervalMs !== undefined) {
-      this.pingIntervalMs = options.pingIntervalMs;
-    }
-
-    if (options.pingEnabled !== false) {
-      this.startPingInterval();
-    } else {
-      this.stopPingInterval();
-    }
-  }
-
-  /**
-   * Register a new SSE connection to receive pings
-   */
-  registerConnection(
-    sessionId: string,
-    transport: SSEServerTransport,
-    res: HttpResponse,
-  ) {
-    this.activeConnections.set(sessionId, { transport, res });
-    this.logger.debug(`SSE connection registered: ${sessionId}`);
-  }
-
-  /**
-   * Remove an SSE connection
-   */
-  removeConnection(sessionId: string) {
-    this.activeConnections.delete(sessionId);
-    this.logger.debug(`SSE connection removed: ${sessionId}`);
-  }
-
-  /**
-   * Start the ping interval timer
-   */
-  private startPingInterval() {
-    if (this.pingInterval) {
-      this.stopPingInterval();
-    }
-
-    this.logger.log(
-      `Starting SSE ping service (interval: ${this.pingIntervalMs}ms)`,
-    );
-    this.pingInterval = setInterval(() => {
-      this.sendPingToAllConnections();
-    }, this.pingIntervalMs);
-  }
-
-  /**
-   * Stop the ping interval timer
-   */
-  private stopPingInterval() {
-    if (this.pingInterval) {
-      clearInterval(this.pingInterval);
-      this.pingInterval = null;
-      this.logger.log('SSE ping interval stopped');
-    }
-  }
-
-  /**
-   * Send a ping to all active connections
-   */
-  private sendPingToAllConnections() {
-    const timestamp = Date.now();
-    const connectionCount = this.activeConnections.size;
-
-    if (connectionCount === 0) {
-      return;
-    }
-
-    this.logger.debug(`Sending SSE ping to ${connectionCount} connections`);
-
-    for (const [sessionId, { res }] of this.activeConnections.entries()) {
-      try {
-        // Send a comment-type SSE message (line starting with ':')
-        // This keeps the connection alive without triggering an event in the client
-        if (!res.closed && res.writable) {
-          res.write(`: ping - ${new Date(timestamp).toISOString()}\n\n`);
-        } else {
-          this.logger.debug(
-            `Connection ${sessionId} is no longer writable, removing`,
-          );
-          // TODO: After non writable connections are discovered it'd be useful to cleanup transports/mcp servers
-          // for that connection in  sse.controller.factory.ts
-          this.removeConnection(sessionId);
-        }
-      } catch (error) {
-        this.logger.error(
-          `Error sending ping to connection ${sessionId}`,
-          error,
-        );
-        this.removeConnection(sessionId);
-      }
-    }
-  }
-}

package/src/mcp/transport/custom-decorator.spec.ts

@@ -1,75 +0,0 @@
-import { SetMetadata } from '@nestjs/common';
-import { createSseController } from './sse.controller.factory';
-import { createStreamableHttpController } from './streamable-http.controller.factory';
-
-describe('Custom Decorators', () => {
-  // Custom decorator for testing
-  const testCustomDecorator = SetMetadata('test:decorator', true);
-
-  describe('SSE Controller Factory', () => {
-    it('should apply custom decorators to the SSE controller', () => {
-      // Arrange
-      const decorators = [testCustomDecorator];
-
-      // Act
-      const sseController = createSseController(
-        'test-sse-endpoint',
-        'test-messages-endpoint',
-        '/api',
-        [],
-        decorators,
-      );
-
-      // Assert
-      expect(sseController).toBeDefined();
-      expect(Reflect.getMetadata('test:decorator', sseController)).toBeTruthy();
-    });
-
-    it('should work without custom decorators', () => {
-      // Act
-      const sseController = createSseController(
-        'test-sse-endpoint',
-        'test-messages-endpoint',
-        '/api',
-      );
-
-      // Assert
-      expect(sseController).toBeDefined();
-      expect(
-        Reflect.getMetadata('test:decorator', sseController),
-      ).toBeUndefined();
-    });
-  });
-
-  describe('Streamable HTTP Controller Factory', () => {
-    it('should apply custom decorators to the Streamable HTTP controller', () => {
-      // Arrange
-      const decorators = [testCustomDecorator];
-
-      // Act
-      const streamableController = createStreamableHttpController(
-        'test-http-endpoint',
-        '/api',
-        [],
-        decorators,
-      );
-
-      // Assert
-      expect(streamableController).toBeDefined();
-      expect(
-        Reflect.getMetadata('test:decorator', streamableController),
-      ).toBeTruthy();
-    });
-
-    it('should work without custom decorators', () => {
-      // Act
-      const StreamableController = createStreamableHttpController(
-        'test-http-endpoint',
-        '/api',
-      );
-
-      // Assert
-      expect(StreamableController).toBeDefined();
-    });
-  });
-});

package/src/mcp/transport/sse.controller.factory.ts

@@ -1,84 +0,0 @@
-import {
-  Body,
-  CanActivate,
-  Controller,
-  Get,
-  Inject,
-  Logger,
-  OnModuleInit,
-  Post,
-  Req,
-  Res,
-  Type,
-  UseGuards,
-  VERSION_NEUTRAL,
-  applyDecorators,
-} from '@nestjs/common';
-
-import type { McpOptions } from '../interfaces';
-import { McpSseService } from '../services/mcp-sse.service';
-import { normalizeEndpoint } from '../utils/normalize-endpoint';
-import { createMcpLogger } from '../utils/mcp-logger.factory';
-
-/**
- * Creates a controller for handling SSE connections and tool executions
- */
-export function createSseController(
-  sseEndpoint: string,
-  messagesEndpoint: string,
-  apiPrefix: string,
-  guards: Type<CanActivate>[] = [],
-  decorators: ClassDecorator[] = [],
-  options?: McpOptions,
-) {
-  @Controller({
-    version: VERSION_NEUTRAL,
-  })
-  @applyDecorators(...decorators)
-  class SseController implements OnModuleInit {
-    readonly logger: Logger;
-
-    constructor(
-      @Inject('MCP_OPTIONS') public readonly mcpOptions: McpOptions,
-      public readonly mcpSseService: McpSseService,
-    ) {
-      this.logger = createMcpLogger(SseController.name, options || mcpOptions);
-    }
-
-    /**
-     * Initialize the controller and configure SSE service
-     */
-    onModuleInit() {
-      this.mcpSseService.initialize();
-    }
-
-    /**
-     * SSE connection endpoint
-     */
-    @Get(normalizeEndpoint(`${apiPrefix}/${sseEndpoint}`))
-    @UseGuards(...guards)
-    async sse(@Req() rawReq: any, @Res() rawRes: any) {
-      return this.mcpSseService.createSseConnection(
-        rawReq,
-        rawRes,
-        messagesEndpoint,
-        apiPrefix,
-      );
-    }
-
-    /**
-     * Tool execution endpoint - protected by the provided guards
-     */
-    @Post(normalizeEndpoint(`${apiPrefix}/${messagesEndpoint}`))
-    @UseGuards(...guards)
-    async messages(
-      @Req() rawReq: any,
-      @Res() rawRes: any,
-      @Body() body: unknown,
-    ): Promise<void> {
-      await this.mcpSseService.handleMessage(rawReq, rawRes, body);
-    }
-  }
-
-  return SseController;
-}

package/src/mcp/transport/stdio.service.ts

@@ -1,75 +0,0 @@
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import {
-  Inject,
-  Injectable,
-  Logger,
-  OnApplicationBootstrap,
-} from '@nestjs/common';
-import { ContextIdFactory, ModuleRef } from '@nestjs/core';
-import { McpTransportType } from '../interfaces';
-import type { McpOptions } from '../interfaces';
-import { McpExecutorService } from '../services/mcp-executor.service';
-import { McpRegistryDiscoveryService } from '../services/mcp-registry-discovery.service';
-import { createMcpLogger } from '../utils/mcp-logger.factory';
-import { createMcpServer } from '../utils/mcp-server.factory';
-
-@Injectable()
-export class StdioService implements OnApplicationBootstrap {
-  private readonly logger: Logger;
-
-  constructor(
-    @Inject('MCP_OPTIONS') private readonly options: McpOptions,
-    @Inject('MCP_MODULE_ID') private readonly mcpModuleId: string,
-    private readonly moduleRef: ModuleRef,
-    private readonly toolRegistry: McpRegistryDiscoveryService,
-  ) {
-    this.logger = createMcpLogger(StdioService.name, this.options);
-  }
-
-  async onApplicationBootstrap() {
-    const transports = Array.isArray(this.options.transport)
-      ? this.options.transport
-      : [this.options.transport];
-    if (!transports.includes(McpTransportType.STDIO)) return;
-
-    this.logger.log('Bootstrapping MCP STDIO...');
-
-    // Warn about tools with @ToolGuards() - they require HTTP context
-    const toolsWithGuards = this.toolRegistry
-      .getTools(this.mcpModuleId)
-      .filter(
-        (tool) => tool.metadata.guards && tool.metadata.guards.length > 0,
-      );
-
-    if (toolsWithGuards.length > 0) {
-      const toolNames = toolsWithGuards.map((t) => t.metadata.name).join(', ');
-      this.logger.warn(
-        `@ToolGuards() are not supported with STDIO transport. ` +
-          `The following tools have guards configured and will be hidden: ${toolNames}. ` +
-          `Consider using HTTP transport.`,
-      );
-    }
-
-    const mcpServer = createMcpServer(
-      this.mcpModuleId,
-      this.toolRegistry,
-      this.options,
-      this.logger,
-    );
-
-    const contextId = ContextIdFactory.create();
-    const executor = await this.moduleRef.resolve(
-      McpExecutorService,
-      contextId,
-      { strict: false },
-    );
-
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
-    executor.registerRequestHandlers(mcpServer, {} as any);
-
-    const transport = new StdioServerTransport();
-    await mcpServer.connect(transport);
-
-    this.logger.log('MCP STDIO ready');
-  }
-}

package/src/mcp/transport/streamable-http.controller.factory.ts

@@ -1,80 +0,0 @@
-import {
-  Body,
-  CanActivate,
-  Controller,
-  Delete,
-  Get,
-  Inject,
-  Logger,
-  Post,
-  Req,
-  Res,
-  Type,
-  UseGuards,
-  applyDecorators,
-} from '@nestjs/common';
-
-import type { McpOptions } from '../interfaces';
-import { McpStreamableHttpService } from '../services/mcp-streamable-http.service';
-import { normalizeEndpoint } from '../utils/normalize-endpoint';
-import { createMcpLogger } from '../utils/mcp-logger.factory';
-
-/**
- * Creates a controller for handling Streamable HTTP connections and tool executions
- */
-export function createStreamableHttpController(
-  endpoint: string,
-  apiPrefix: string,
-  guards: Type<CanActivate>[] = [],
-  decorators: ClassDecorator[] = [],
-  options?: McpOptions,
-) {
-  @Controller()
-  @applyDecorators(...decorators)
-  class StreamableHttpController {
-    public readonly logger: Logger;
-
-    constructor(
-      @Inject('MCP_OPTIONS') public readonly mcpOptions: McpOptions,
-      public readonly mcpStreamableHttpService: McpStreamableHttpService,
-    ) {
-      this.logger = createMcpLogger(
-        StreamableHttpController.name,
-        options || mcpOptions,
-      );
-    }
-
-    /**
-     * Main HTTP endpoint for both initialization and subsequent requests
-     */
-    @Post(`${normalizeEndpoint(`${apiPrefix}/${endpoint}`)}`)
-    @UseGuards(...guards)
-    async handlePostRequest(
-      @Req() req: any,
-      @Res() res: any,
-      @Body() body: unknown,
-    ): Promise<void> {
-      await this.mcpStreamableHttpService.handlePostRequest(req, res, body);
-    }
-
-    /**
-     * GET endpoint for SSE streams - not supported in stateless mode
-     */
-    @Get(`${normalizeEndpoint(`${apiPrefix}/${endpoint}`)}`)
-    @UseGuards(...guards)
-    async handleGetRequest(@Req() req: any, @Res() res: any): Promise<void> {
-      await this.mcpStreamableHttpService.handleGetRequest(req, res);
-    }
-
-    /**
-     * DELETE endpoint for terminating sessions - not supported in stateless mode
-     */
-    @Delete(`${normalizeEndpoint(`${apiPrefix}/${endpoint}`)}`)
-    @UseGuards(...guards)
-    async handleDeleteRequest(@Req() req: any, @Res() res: any): Promise<void> {
-      await this.mcpStreamableHttpService.handleDeleteRequest(req, res);
-    }
-  }
-
-  return StreamableHttpController;
-}

package/src/mcp/utils/capabilities-builder.ts

@@ -1,43 +0,0 @@
-import { ServerCapabilities } from '@modelcontextprotocol/sdk/types.js';
-import { McpRegistryDiscoveryService } from '../services/mcp-registry-discovery.service';
-import type { McpOptions } from '../interfaces';
-
-/**
- * Utility function to build MCP server capabilities dynamically based on
- * discovered tools, resources, and prompts
- */
-export function buildMcpCapabilities(
-  mcpModuleId: string,
-  registry: McpRegistryDiscoveryService,
-  options: McpOptions,
-): ServerCapabilities {
-  // Start with user-provided capabilities or empty object
-  const baseCapabilities = options.capabilities || {};
-
-  const capabilities: ServerCapabilities = { ...baseCapabilities };
-
-  // Add tools capability if tools are discovered
-  if (registry.getTools(mcpModuleId).length > 0) {
-    capabilities.tools = capabilities.tools || {
-      listChanged: true,
-    };
-  }
-
-  if (
-    registry.getResources(mcpModuleId).length > 0 ||
-    registry.getResourceTemplates(mcpModuleId).length > 0
-  ) {
-    capabilities.resources = capabilities.resources || {
-      listChanged: true,
-    };
-  }
-
-  // Add prompts capability if prompts are discovered
-  if (registry.getPrompts(mcpModuleId).length > 0) {
-    capabilities.prompts = capabilities.prompts || {
-      listChanged: true,
-    };
-  }
-
-  return capabilities;
-}

package/src/mcp/utils/mcp-server.factory.ts

@@ -1,33 +0,0 @@
-import { McpOptions } from '../interfaces';
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { buildMcpCapabilities } from './capabilities-builder';
-import { McpRegistryDiscoveryService } from '../services/mcp-registry-discovery.service';
-import { Logger } from '@nestjs/common';
-
-export function createMcpServer(
-  mcpModuleId: string,
-  registry: McpRegistryDiscoveryService,
-  options: McpOptions,
-  logger: Logger,
-): McpServer {
-  const capabilities = buildMcpCapabilities(mcpModuleId, registry, options);
-
-  logger.debug(`Built MCP capabilities: ${JSON.stringify(capabilities)}`);
-
-  const mcpServer = new McpServer(
-    {
-      name: options.name,
-      version: options.version,
-      ...(options.title && { title: options.title }),
-      ...(options.description && { description: options.description }),
-      ...(options.websiteUrl && { websiteUrl: options.websiteUrl }),
-      ...(options.icons && { icons: options.icons }),
-    },
-    {
-      capabilities,
-      instructions: options.instructions || '',
-    },
-  );
-
-  return options.serverMutator ? options.serverMutator(mcpServer) : mcpServer;
-}