@nestjs-mcp/server 0.1.0 → 0.1.2-rc.0

package/dist/interfaces/guards.interface.d.ts

@@ -1,4 +0,0 @@
-import { ExecutionContext } from '@nestjs/common';
-export interface McpExecutionContext extends ExecutionContext {
-    args: unknown[];
-}

package/dist/interfaces/guards.interface.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"guards.interface.js","sourceRoot":"","sources":["../../src/interfaces/guards.interface.ts"],"names":[],"mappings":""}

package/eslint.config.mjs

@@ -1,40 +0,0 @@
-// @ts-check
-import eslint from '@eslint/js';
-import eslintPluginPrettierRecommended from 'eslint-plugin-prettier/recommended';
-import globals from 'globals';
-import tseslint from 'typescript-eslint';
-
-export default tseslint.config(
-  {
-    ignores: ['eslint.config.mjs', 'scripts'],
-  },
-  eslint.configs.recommended,
-  ...tseslint.configs.recommendedTypeChecked,
-  eslintPluginPrettierRecommended,
-  {
-    languageOptions: {
-      globals: {
-        ...globals.node,
-        ...globals.jest,
-      },
-      ecmaVersion: 5,
-      sourceType: 'module',
-      parserOptions: {
-        projectService: true,
-        tsconfigRootDir: import.meta.dirname,
-      },
-    },
-  },
-  {
-    rules: {
-      // Allow unused variables/arguments if they start with '_'
-      '@typescript-eslint/no-unused-vars': [
-        'error',
-        { argsIgnorePattern: '^_' }
-      ],
-      '@typescript-eslint/no-explicit-any': 'off',
-      '@typescript-eslint/no-floating-promises': 'warn',
-      '@typescript-eslint/no-unsafe-argument': 'warn'
-    },
-  },
-);

package/src/controllers/sse/index.ts

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

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

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

@@ -1,106 +0,0 @@
-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';
-import { SessionManager } from '../../services/session.manager';
-
-@Injectable()
-export class SseService implements OnModuleInit {
-  private server: McpServer;
-
-  constructor(
-    @Inject('MCP_SERVER_OPTIONS')
-    private readonly options: McpServerOptions,
-    private readonly registry: RegistryService,
-    private readonly logger: McpLoggerService,
-    private readonly sessionManager: SessionManager,
-  ) {
-    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.sessionManager.setSession(transport.sessionId, {
-      transport,
-      request: req,
-    });
-
-    this.logger.debug(
-      `Starting SSE for sessionId: ${transport.sessionId}`,
-      'api',
-    );
-
-    res.on('close', () => {
-      this.sessionManager.deleteSession(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 session = this.sessionManager.getSession(sessionId);
-
-    if (!session) {
-      res.status(400).send('Invalid or missing sessionId');
-      return;
-    }
-
-    this.logger.debug(
-      `Receiving SSE message for sessionId: ${sessionId}`,
-      'api',
-    );
-
-    this.logger.debug(`SSE message: ${JSON.stringify(req.body)}`, 'MCP_SERVER');
-
-    const transport = session.transport;
-
-    if (!(transport instanceof SSEServerTransport)) {
-      res.status(400).send('Invalid transport');
-      return;
-    }
-
-    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

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

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

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

@@ -1,190 +0,0 @@
-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';
-import { SessionManager } from '../../services/session.manager';
-// TODO: Stateless mode should be handled here or in another service
-
-@Injectable()
-export class StreamableService implements OnModuleInit {
-  private server: McpServer;
-
-  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,
-    private readonly sessionManager: SessionManager,
-  ) {
-    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, res: Response) {
-    const sessionId = req.headers['mcp-session-id'] as string | undefined;
-    let transport: StreamableHTTPServerTransport;
-
-    const { options } = this.transportOptions?.streamable || {};
-
-    if (sessionId && this.sessionManager.getSession(sessionId)) {
-      const session = this.sessionManager.getSession(sessionId);
-
-      if (!session) {
-        throw new Error('Session not found');
-      }
-
-      if (!(session.transport instanceof StreamableHTTPServerTransport)) {
-        throw new Error('Invalid transport');
-      }
-
-      transport = session.transport;
-    } else if (!sessionId && isInitializeRequest(req.body)) {
-      // This is called only when method is initialize
-      transport = new StreamableHTTPServerTransport({
-        sessionIdGenerator: () =>
-          options?.sessionIdGenerator?.() || randomUUID(),
-        onsessioninitialized: (sessionId) => {
-          this.sessionManager.setSession(sessionId, {
-            transport,
-            request: req,
-          });
-        },
-        enableJsonResponse: options?.enableJsonResponse,
-        eventStore: options?.eventStore,
-      });
-
-      transport.onclose = () => {
-        if (transport.sessionId) {
-          this.sessionManager.deleteSession(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, res: Response) {
-    const sessionId = req.headers['mcp-session-id'] as string | undefined;
-
-    if (!sessionId || !this.sessionManager.getSession(sessionId)) {
-      res.status(400).send('Invalid or missing session ID');
-      return;
-    }
-
-    const session = this.sessionManager.getSession(sessionId);
-
-    if (!session) {
-      throw new Error('Session not found');
-    }
-
-    const { transport } = session;
-
-    if (!(transport instanceof StreamableHTTPServerTransport)) {
-      throw new Error('Invalid transport');
-    }
-
-    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, res: Response) {
-    const sessionId = req.headers['mcp-session-id'] as string | undefined;
-
-    if (!sessionId) {
-      res.status(400).json({ error: 'Missing sessionId' });
-      return;
-    }
-
-    const session = this.sessionManager.getSession(sessionId);
-
-    if (!session) {
-      throw new Error('Session not found');
-    }
-
-    const { transport } = session;
-
-    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;
-      }
-
-      this.sessionManager.deleteSession(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

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

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

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

package/src/index.ts

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