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

package/src/mcp/services/handlers/mcp-tools.handler.ts

@@ -1,436 +0,0 @@
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import {
-  CallToolRequestSchema,
-  CallToolResult,
-  ErrorCode,
-  ListToolsRequestSchema,
-  McpError,
-} from '@modelcontextprotocol/sdk/types.js';
-import {
-  CanActivate,
-  ExecutionContext,
-  Inject,
-  Injectable,
-  Scope,
-  Type,
-} from '@nestjs/common';
-import { ContextIdFactory, ModuleRef, Reflector } from '@nestjs/core';
-import {
-  DiscoveredCapability,
-  McpRegistryDiscoveryService,
-} from '../mcp-registry-discovery.service';
-import { ToolGuardExecutionContext, ToolMetadata } from '../../decorators';
-import { McpHandlerBase } from './mcp-handler.base';
-import { ZodType } from 'zod';
-import { HttpRequest } from '../../interfaces/http-adapter.interface';
-import { McpRequestWithUser } from 'src/authz';
-import { ToolAuthorizationService } from '../tool-authorization.service';
-import { toJsonSchemaCompat } from '@modelcontextprotocol/sdk/server/zod-json-schema-compat.js';
-import { normalizeObjectSchema } from '@modelcontextprotocol/sdk/server/zod-compat.js';
-import type { McpOptions } from '../../interfaces/mcp-options.interface';
-import {
-  McpRegistryService,
-  DYNAMIC_TOOL_HANDLER_TOKEN,
-} from '../mcp-dynamic-registry.service';
-
-@Injectable({ scope: Scope.REQUEST })
-export class McpToolsHandler extends McpHandlerBase {
-  private readonly moduleHasGuards: boolean;
-
-  constructor(
-    moduleRef: ModuleRef,
-    registry: McpRegistryDiscoveryService,
-    reflector: Reflector,
-    @Inject('MCP_MODULE_ID') private readonly mcpModuleId: string,
-    @Inject('MCP_OPTIONS') private readonly options: McpOptions,
-    private readonly authService: ToolAuthorizationService,
-  ) {
-    super(moduleRef, registry, reflector, McpToolsHandler.name, options);
-    this.moduleHasGuards =
-      this.options.guards !== undefined && this.options.guards.length > 0;
-  }
-
-  private buildDefaultContentBlock(result: any) {
-    return [
-      {
-        type: 'text',
-        text: JSON.stringify(result),
-      },
-    ];
-  }
-
-  private formatToolResult(result: any, outputSchema?: ZodType): any {
-    if (result && typeof result === 'object' && Array.isArray(result.content)) {
-      return result;
-    }
-
-    if (outputSchema) {
-      const validation = outputSchema.safeParse(result);
-      if (!validation.success) {
-        throw new McpError(
-          ErrorCode.InternalError,
-          `Tool result does not match outputSchema: ${validation.error.message}`,
-        );
-      }
-      return {
-        structuredContent: validation.data,
-        content: this.buildDefaultContentBlock(result),
-      };
-    }
-
-    return {
-      content: this.buildDefaultContentBlock(result),
-    };
-  }
-
-  protected override createErrorResponse(
-    errorText: string,
-  ): CallToolResult | never {
-    return {
-      content: [{ type: 'text', text: errorText }],
-      isError: true,
-    };
-  }
-
-  /**
-   * Creates an ExecutionContext for @ToolGuards() evaluation.
-   *
-   * Only the fields documented in ToolGuardExecutionContext are available.
-   * Invalid fields throw with a descriptive message rather than silently
-   * returning garbage.
-   *
-   * The request object returned by `switchToHttp().getRequest()` is the raw
-   * framework request enriched with `body` and `params` from the adapted
-   * HttpRequest. During `tools/call`, `toolArguments` overrides `body` so
-   * guards can inspect the validated tool input.
-   */
-  private createToolGuardExecutionContext(
-    httpRequest: HttpRequest,
-    tool: DiscoveredCapability<ToolMetadata>,
-    toolArguments?: Record<string, unknown>,
-  ): ToolGuardExecutionContext & ExecutionContext {
-    const providerClass = tool.providerClass as Type;
-    const methodHandler =
-      providerClass.prototype?.[tool.methodName] ?? (() => {});
-
-    const unavailable = (method: string): never => {
-      throw new Error(
-        `${method} is not available in @ToolGuards() context. ` +
-          `MCP tools share a single HTTP endpoint, so only a limited API is available.` +
-          `See ToolGuardExecutionContext for the supported API.`,
-      );
-    };
-
-    // Build the guard request from the raw request, enriched with parsed body and params.
-    // During tools/call, toolArguments is passed so guards can inspect the tool input as `body`.
-    const guardRequest = Object.assign(
-      Object.create(Object.getPrototypeOf(httpRequest.raw ?? {})),
-      httpRequest.raw ?? {},
-      {
-        body: toolArguments ?? httpRequest.body,
-        params: httpRequest.params ?? {},
-      },
-    );
-
-    return {
-      switchToHttp: () => ({
-        getRequest: <T = unknown>() => guardRequest as T,
-        getResponse: () => unavailable('switchToHttp().getResponse()'),
-        getNext: () => unavailable('switchToHttp().getNext()'),
-      }),
-      getClass: <T = unknown>() => providerClass as Type<T>,
-      getHandler: () => methodHandler as () => void,
-      getArgs: () => unavailable('getArgs()'),
-      getArgByIndex: () => unavailable('getArgByIndex()'),
-      getType: <TContext extends string = string>() => 'http' as TContext,
-      switchToRpc: () => unavailable('switchToRpc()'),
-      switchToWs: () => unavailable('switchToWs()'),
-    };
-  }
-
-  /**
-   * Evaluates all @ToolGuards() for a tool.
-   * Returns true if the tool has no guards or all guards pass.
-   */
-  private async checkToolGuards(
-    tool: DiscoveredCapability<ToolMetadata>,
-    httpRequest: HttpRequest,
-    toolArguments?: Record<string, unknown>,
-  ): Promise<boolean> {
-    const guards = tool.metadata.guards;
-    if (!guards || guards.length === 0) {
-      return true;
-    }
-
-    // Guards require HTTP context - not available on STDIO
-    if (!httpRequest.raw) {
-      this.logger.warn(
-        `@ToolGuards() on tool '${tool.metadata.name}' cannot be evaluated without HTTP context (STDIO transport). ` +
-          `The tool will be hidden. Use HTTP transport to support guarded tools.`,
-      );
-      return false;
-    }
-
-    const context = this.createToolGuardExecutionContext(httpRequest, tool, toolArguments);
-
-    for (const GuardClass of guards) {
-      try {
-        const guard = this.moduleRef.get<CanActivate>(GuardClass, {
-          strict: false,
-        });
-        const result = guard.canActivate(context);
-        const canActivate = result instanceof Promise ? await result : result;
-        if (!canActivate) {
-          return false;
-        }
-      } catch (error) {
-        this.logger.warn(
-          `@ToolGuards() guard ${GuardClass.name} threw on tool '${tool.metadata.name}': ${error.message}. ` +
-            `The tool will be hidden. If this is unexpected, ensure the guard only uses ` +
-            `the API available in ToolGuardExecutionContext.`,
-        );
-        return false;
-      }
-    }
-
-    return true;
-  }
-  registerHandlers(mcpServer: McpServer, httpRequest: HttpRequest) {
-    if (this.registry.getTools(this.mcpModuleId).length === 0) {
-      this.logger.debug('No tools registered, skipping tool handlers');
-      return;
-    }
-
-    mcpServer.server.setRequestHandler(ListToolsRequestSchema, async () => {
-      // Extract user from request (may be undefined if not authenticated or STDIO)
-      // For STDIO transport, httpRequest.raw is undefined, so bypass auth entirely
-      const user = httpRequest.raw
-        ? (httpRequest.raw as McpRequestWithUser).user
-        : undefined;
-
-      // Get all tools and filter based on user permissions
-      // STDIO: If no httpRequest.raw, disable guards (local dev mode)
-      const allTools = this.registry.getTools(this.mcpModuleId);
-      const effectiveModuleHasGuards = httpRequest.raw
-        ? this.moduleHasGuards
-        : false;
-      const allowUnauthenticatedAccess =
-        this.options.allowUnauthenticatedAccess ?? false;
-
-      // Filter by JWT-based authorization (scopes, roles, public)
-      const jwtAuthorizedTools = allTools.filter((tool) =>
-        this.authService.canAccessTool(
-          user,
-          tool,
-          effectiveModuleHasGuards,
-          allowUnauthenticatedAccess,
-        ),
-      );
-
-      // Filter by @ToolGuards() - evaluate each tool's guards
-      const authorizedTools: typeof jwtAuthorizedTools = [];
-      for (const tool of jwtAuthorizedTools) {
-        if (await this.checkToolGuards(tool, httpRequest)) {
-          authorizedTools.push(tool);
-        }
-      }
-
-      const tools = authorizedTools.map((tool) => {
-        // Create base schema
-        const toolSchema = {
-          name: tool.metadata.name,
-          description: tool.metadata.description,
-          annotations: tool.metadata.annotations,
-          _meta: tool.metadata._meta,
-        };
-
-        // Add security schemes
-        const securitySchemes = this.authService.generateSecuritySchemes(
-          tool,
-          effectiveModuleHasGuards,
-        );
-        if (securitySchemes.length > 0) {
-          toolSchema['securitySchemes'] = securitySchemes;
-          // Note: Currently securitySchemes are not supported in MCP sdk, adding to _meta as workaround
-          // (see https://developers.openai.com/apps-sdk/reference/)
-          toolSchema._meta = {
-            ...toolSchema._meta,
-            securitySchemes,
-          };
-        }
-
-        // Add input schema if defined
-        const normalizedInputParameters = normalizeObjectSchema(
-          tool.metadata.parameters,
-        );
-        if (normalizedInputParameters) {
-          toolSchema['inputSchema'] = toJsonSchemaCompat(
-            normalizedInputParameters,
-          );
-        }
-
-        // Add output schema if defined, ensuring it has type: 'object'
-        const normalizedOutputSchema = normalizeObjectSchema(
-          tool.metadata.outputSchema,
-        );
-        if (normalizedOutputSchema) {
-          const outputSchema = toJsonSchemaCompat(normalizedOutputSchema);
-
-          // Create a new object that explicitly includes type: 'object'
-          const jsonSchema = {
-            ...outputSchema,
-            type: 'object',
-          };
-
-          toolSchema['outputSchema'] = jsonSchema;
-        }
-
-        return toolSchema;
-      });
-
-      return {
-        tools,
-      };
-    });
-
-    mcpServer.server.setRequestHandler(
-      CallToolRequestSchema,
-      async (request) => {
-        this.logger.debug('CallToolRequestSchema is being called');
-
-        const toolInfo = this.registry.findTool(
-          this.mcpModuleId,
-          request.params.name,
-        );
-
-        if (!toolInfo) {
-          throw new McpError(
-            ErrorCode.MethodNotFound,
-            `Unknown tool: ${request.params.name}`,
-          );
-        }
-
-        // Validate authorization before execution
-        // For STDIO transport, bypass auth entirely (local dev mode)
-        const user = httpRequest.raw
-          ? (httpRequest.raw as McpRequestWithUser).user
-          : undefined;
-        const effectiveModuleHasGuards = httpRequest.raw
-          ? this.moduleHasGuards
-          : false;
-        const allowUnauthenticatedAccess =
-          this.options.allowUnauthenticatedAccess ?? false;
-        this.authService.validateToolAccess(
-          user,
-          toolInfo,
-          effectiveModuleHasGuards,
-          allowUnauthenticatedAccess,
-        );
-
-        // Validate @ToolGuards()
-        const guardsPassed = await this.checkToolGuards(toolInfo, httpRequest, request.params.arguments as Record<string, unknown>);
-        if (!guardsPassed) {
-          throw new McpError(
-            ErrorCode.InvalidRequest,
-            `Access denied: insufficient permissions for tool '${request.params.name}'`,
-          );
-        }
-
-        try {
-          // Validate input parameters against the tool's schema
-          if (toolInfo.metadata.parameters) {
-            const validation = toolInfo.metadata.parameters.safeParse(
-              request.params.arguments || {},
-            );
-            if (!validation.success) {
-              const issues = validation.error.issues
-                .map((issue) => {
-                  const path =
-                    issue.path.length > 0 ? issue.path.join('.') : '';
-                  const location = path ? `[${path}]: ` : '';
-                  return `${location}${issue.message}`;
-                })
-                .join('; ');
-              return {
-                content: [
-                  {
-                    type: 'text',
-                    text: `Invalid parameters: ${issues}`,
-                  },
-                ],
-                isError: true,
-              };
-            }
-            // Use validated arguments to ensure defaults and transformations are applied
-            request.params.arguments = validation.data as Record<
-              string,
-              unknown
-            >;
-          }
-
-          const contextId = ContextIdFactory.getByRequest(httpRequest);
-          this.moduleRef.registerRequestByContextId(httpRequest, contextId);
-
-          const context = this.createContext(mcpServer, request);
-          let result: any;
-
-          // Check if this is a dynamic tool (registered via McpRegistryService)
-          if (toolInfo.providerClass === DYNAMIC_TOOL_HANDLER_TOKEN) {
-            // Dynamic tool - get handler using static method with the correct moduleId
-            const handler = McpRegistryService.getHandlerByModuleId(
-              this.mcpModuleId,
-              request.params.name,
-            );
-
-            if (!handler) {
-              throw new McpError(
-                ErrorCode.MethodNotFound,
-                `Handler not found for dynamic tool: ${request.params.name}`,
-              );
-            }
-
-            result = await handler(
-              request.params.arguments || {},
-              context,
-              httpRequest.raw as McpRequestWithUser,
-            );
-          } else {
-            // Decorator-based tool - resolve provider instance and call method
-            const toolInstance = await this.moduleRef.resolve(
-              toolInfo.providerClass,
-              contextId,
-              { strict: false },
-            );
-
-            if (!toolInstance) {
-              throw new McpError(
-                ErrorCode.MethodNotFound,
-                `Unknown tool: ${request.params.name}`,
-              );
-            }
-
-            result = await toolInstance[toolInfo.methodName].call(
-              toolInstance,
-              request.params.arguments,
-              context,
-              httpRequest.raw as McpRequestWithUser,
-            );
-          }
-
-          const transformedResult = this.formatToolResult(
-            result,
-            toolInfo.metadata.outputSchema,
-          );
-
-          this.logger.debug('CallToolRequestSchema result', transformedResult);
-
-          // eslint-disable-next-line @typescript-eslint/no-unsafe-return
-          return transformedResult;
-        } catch (error) {
-          // We are assuming error as at least a message property
-          return this.handleError(error as Error, toolInfo, httpRequest);
-        }
-      },
-    );
-  }
-}

package/src/mcp/services/mcp-dynamic-registry.service.ts

@@ -1,236 +0,0 @@
-import { Injectable, Inject, Logger } from '@nestjs/common';
-import { z } from 'zod';
-import {
-  DynamicToolDefinition,
-  DynamicToolHandler,
-} from '../interfaces/dynamic-tool.interface';
-import {
-  DynamicResourceDefinition,
-  DynamicResourceHandler,
-} from '../interfaces/dynamic-resource.interface';
-import {
-  DynamicPromptDefinition,
-  DynamicPromptHandler,
-} from '../interfaces/dynamic-prompt.interface';
-import { McpRegistryDiscoveryService } from './mcp-registry-discovery.service';
-import type { McpOptions } from '../interfaces';
-import { createMcpLogger } from '../utils/mcp-logger.factory';
-import { ToolMetadata } from '../decorators/tool.decorator';
-import { ResourceMetadata } from '../decorators/resource.decorator';
-import { PromptMetadata } from '../decorators/prompt.decorator';
-
-/**
- * Symbol used to identify dynamic tools in the registry.
- * When a tool's providerClass equals this token, it's a dynamic tool.
- */
-export const DYNAMIC_TOOL_HANDLER_TOKEN = Symbol('DYNAMIC_TOOL_HANDLER');
-export const DYNAMIC_RESOURCE_HANDLER_TOKEN = Symbol(
-  'DYNAMIC_RESOURCE_HANDLER',
-);
-export const DYNAMIC_PROMPT_HANDLER_TOKEN = Symbol('DYNAMIC_PROMPT_HANDLER');
-
-/**
- * Global maps of dynamic capability handlers, scoped by moduleId.
- * Using module-level Maps ensures handlers persist across different
- * McpRegistryService instances that may be created by the DI container.
- */
-const globalHandlers = new Map<string, Map<string, DynamicToolHandler>>();
-const globalResourceHandlers = new Map<
-  string,
-  Map<string, DynamicResourceHandler>
->();
-const globalPromptHandlers = new Map<
-  string,
-  Map<string, DynamicPromptHandler>
->();
-
-/**
- * Service for programmatically registering MCP tools at runtime.
- *
- * Use this to register tools with descriptions/parameters from databases
- * or other dynamic sources during application bootstrap.
- *
- * @example
- * ```typescript
- * @Injectable()
- * export class DynamicToolsService implements OnModuleInit {
- *   constructor(
- *     private readonly capabilityBuilder: McpRegistryService,
- *     private readonly dbService: DatabaseService,
- *   ) {}
- *
- *   async onModuleInit() {
- *     const collections = await this.dbService.getCollections();
- *
- *     this.capabilityBuilder.registerTool({
- *       name: 'search-knowledge',
- *       description: `Search collections: ${collections.join(', ')}`,
- *       parameters: z.object({ query: z.string() }),
- *       handler: async (args, context) => {
- *         const results = await this.dbService.search(args.query);
- *         return { content: [{ type: 'text', text: JSON.stringify(results) }] };
- *       },
- *     });
- *   }
- * }
- * ```
- */
-@Injectable()
-export class McpRegistryService {
-  private readonly logger: Logger;
-
-  constructor(
-    private readonly registry: McpRegistryDiscoveryService,
-    @Inject('MCP_MODULE_ID') private readonly mcpModuleId: string,
-    @Inject('MCP_OPTIONS') private readonly options: McpOptions,
-  ) {
-    this.logger = createMcpLogger(McpRegistryService.name, this.options);
-    [globalHandlers, globalResourceHandlers, globalPromptHandlers].forEach(
-      (store) => {
-        if (!store.has(mcpModuleId)) {
-          store.set(mcpModuleId, new Map());
-        }
-      },
-    );
-  }
-
-  /**
-   * Register a dynamic tool for the current MCP server.
-   *
-   * Tools registered here will appear in the `tools/list` response and
-   * can be called via `tools/call` just like decorator-based tools.
-   *
-   * @param definition - The tool definition including name, description, parameters, and handler
-   *
-   * @example
-   * ```typescript
-   * registry.registerTool({
-   *   name: 'search-knowledge',
-   *   description: await getDescriptionFromDB(),
-   *   parameters: z.object({ query: z.string() }),
-   *   handler: async (args, context) => {
-   *     const results = await searchService.search(args.query);
-   *     return { content: [{ type: 'text', text: JSON.stringify(results) }] };
-   *   },
-   * });
-   * ```
-   */
-  registerTool(definition: DynamicToolDefinition): void {
-    this.logger.debug(`Registering dynamic tool: ${definition.name}`);
-
-    // Store the handler for later execution (scoped by moduleId)
-    const moduleHandlers = globalHandlers.get(this.mcpModuleId)!;
-    moduleHandlers.set(definition.name, definition.handler);
-
-    // Default to empty object schema if no parameters provided (matches @Tool decorator behavior)
-    const parameters = definition.parameters ?? z.object({});
-
-    // Build metadata matching ToolMetadata interface
-    const metadata: ToolMetadata = {
-      name: definition.name,
-      description: definition.description,
-      parameters,
-      outputSchema: definition.outputSchema,
-      annotations: definition.annotations,
-      _meta: definition._meta,
-      isPublic: definition.isPublic,
-      requiredScopes: definition.requiredScopes,
-      requiredRoles: definition.requiredRoles,
-    };
-
-    // Register with the registry
-    this.registry.registerDynamicCapability(this.mcpModuleId, {
-      type: 'tool',
-      metadata,
-      providerClass: DYNAMIC_TOOL_HANDLER_TOKEN,
-      methodName: definition.name,
-    });
-  }
-
-  getHandler(toolName: string): DynamicToolHandler | undefined {
-    return globalHandlers.get(this.mcpModuleId)?.get(toolName);
-  }
-
-  static getHandlerByModuleId(
-    mcpModuleId: string,
-    toolName: string,
-  ): DynamicToolHandler | undefined {
-    return globalHandlers.get(mcpModuleId)?.get(toolName);
-  }
-
-  registerResource(definition: DynamicResourceDefinition): void {
-    this.logger.debug(`Registering dynamic resource: ${definition.uri}`);
-
-    globalResourceHandlers
-      .get(this.mcpModuleId)!
-      .set(definition.uri, definition.handler);
-
-    const metadata: ResourceMetadata = {
-      uri: definition.uri,
-      name: definition.name ?? definition.uri,
-      description: definition.description,
-      mimeType: definition.mimeType,
-      _meta: definition._meta,
-    };
-
-    this.registry.registerDynamicCapability(this.mcpModuleId, {
-      type: 'resource',
-      metadata,
-      providerClass: DYNAMIC_RESOURCE_HANDLER_TOKEN,
-      methodName: definition.uri,
-    });
-  }
-
-  static getResourceHandlerByModuleId(
-    mcpModuleId: string,
-    uri: string,
-  ): DynamicResourceHandler | undefined {
-    return globalResourceHandlers.get(mcpModuleId)?.get(uri);
-  }
-
-  registerPrompt(definition: DynamicPromptDefinition): void {
-    this.logger.debug(`Registering dynamic prompt: ${definition.name}`);
-
-    globalPromptHandlers
-      .get(this.mcpModuleId)!
-      .set(definition.name, definition.handler);
-
-    const metadata: PromptMetadata = {
-      name: definition.name,
-      description: definition.description,
-      parameters: definition.parameters,
-    };
-
-    this.registry.registerDynamicCapability(this.mcpModuleId, {
-      type: 'prompt',
-      metadata,
-      providerClass: DYNAMIC_PROMPT_HANDLER_TOKEN,
-      methodName: definition.name,
-    });
-  }
-
-  static getPromptHandlerByModuleId(
-    mcpModuleId: string,
-    name: string,
-  ): DynamicPromptHandler | undefined {
-    return globalPromptHandlers.get(mcpModuleId)?.get(name);
-  }
-
-  removeTool(name: string): void {
-    this.logger.debug(`Removing dynamic tool: ${name}`);
-    globalHandlers.get(this.mcpModuleId)?.delete(name);
-    this.registry.removeDynamicCapability(this.mcpModuleId, 'tool', name);
-  }
-
-  removeResource(uri: string): void {
-    this.logger.debug(`Removing dynamic resource: ${uri}`);
-    globalResourceHandlers.get(this.mcpModuleId)?.delete(uri);
-    this.registry.removeDynamicCapability(this.mcpModuleId, 'resource', uri);
-  }
-
-  removePrompt(name: string): void {
-    this.logger.debug(`Removing dynamic prompt: ${name}`);
-    globalPromptHandlers.get(this.mcpModuleId)?.delete(name);
-    this.registry.removeDynamicCapability(this.mcpModuleId, 'prompt', name);
-  }
-}