@nestia/core 14.0.0 → 14.0.2

package/src/adaptors/McpAdaptor.ts

@@ -3,9 +3,19 @@ import {
   HttpException,
   INestApplication,
 } from "@nestjs/common";
-import { NestContainer } from "@nestjs/core";
+import { RouteParamtypes } from "@nestjs/common/enums/route-paramtypes.enum";
+import { ContextId, NestContainer } from "@nestjs/core";
+import { ExternalContextCreator } from "@nestjs/core/helpers/external-context-creator";
+import { Injector } from "@nestjs/core/injector/injector";
+import { InstanceWrapper } from "@nestjs/core/injector/instance-wrapper";
+import { Module } from "@nestjs/core/injector/module";
 
 import { IMcpRouteReflect } from "../decorators/internal/IMcpRouteReflect";
+import { resolve_request_body } from "../decorators/internal/validate_request_body";
+import {
+  create_external_context_creator,
+  get_request_context_id,
+} from "./internal/external_context";
 
 /**
  * MCP (Model Context Protocol) adaptor.
@@ -23,6 +33,11 @@ import { IMcpRouteReflect } from "../decorators/internal/IMcpRouteReflect";
  * registration API of `McpServer` is bypassed by accessing the low-level
  * `.server` handler.
  *
+ * A tool call passes the guards, interceptors, pipes, and exception filters
+ * NestJS applies to an HTTP route on the same method, with the MCP HTTP request
+ * as the execution context. The endpoint is mounted at `path` as given, outside
+ * the application's global prefix.
+ *
  * Error mapping follows the MCP specification:
  *
  * - Unknown tool name: JSON-RPC `-32601`.
@@ -33,14 +48,12 @@ import { IMcpRouteReflect } from "../decorators/internal/IMcpRouteReflect";
  *
  * @author wildduck - https://github.com/wildduck2
  * @example
- *   ```typescript
  *   import core from "@nestia/core";
  *   import { NestFactory } from "@nestjs/core";
  *
  *   const app = await NestFactory.create(AppModule);
  *   await core.McpAdaptor.upgrade(app, { path: "/mcp" });
  *   await app.listen(3000);
- *   ```;
  */
 export class McpAdaptor {
   /**
@@ -57,6 +70,11 @@ export class McpAdaptor {
    *
    * @param app Running Nest application instance.
    * @param options Transport and identity overrides.
+   * @evidence contracts/common.md#principled-implementation Tools are collected once from the prototype chain of every controller instance by the `nestia/McpRoute` metadata, with the first definition of a property name winning and accessors skipped without execution, duplicates by tool name refused before serving, and each call runs through NestJS's `ExternalContextCreator` so guards, interceptors, pipes, and exception filters apply as for an HTTP route; every request gets a fresh MCP server and Streamable HTTP transport, which stateless mode requires, and both are closed in a `finally`.
+   * @evidence contracts/common.md#clear-and-simple-design One entry point does discovery and registration; the per-tool call (`createHandler`), the duplicate check, the SDK loader, and the per-request response facade are separate module-private functions.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Reading the module graph goes through the internal `app.container`, because `INestApplication` exposes no public accessor for it, `create_external_context_creator` constructs an owned subclass through the Nest constructor and overrides module selection on that type, because the default looks for provider classes while controllers belong to the controller collection, and `get_request_context_id` registers the request provider on the request object as NestJS's router does for an HTTP route, and a per-request response facade forwards native state, events and method receivers without replacing raw methods. After a tool or its exception filter has sent headers, only the facade suppresses subsequent transport writes and preserves callbacks and chaining. Native transport writes do not themselves activate takeover. The remaining foreign-internal reads are the application container and Nest request context registration; the MCP SDK uses its public Node response injection boundary.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the stateless mode, what is discovered, and that the SDK is an optional dependency; the options documentation states the path and server information.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation MCP tool discovery and HTTP transport callbacks carry protocol values; optional SDK imports use Node module resolution and no native file identity or child process is defined here.
    */
   public static async upgrade(
     app: INestApplication,
@@ -69,7 +87,12 @@ export class McpAdaptor {
 
     const tools: McpAdaptor.ITool[] = [];
     const container = (app as any).container as NestContainer;
-    for (const module of container.getModules().values()) {
+    const injector: Injector = new Injector();
+    for (const [moduleKey, module] of container.getModules()) {
+      const creator: ExternalContextCreator = create_external_context_creator(
+        container,
+        moduleKey,
+      );
       for (const wrapper of module.controllers.values()) {
         const instance = wrapper.instance;
         if (!instance) continue;
@@ -82,7 +105,8 @@ export class McpAdaptor {
           for (const key of Object.getOwnPropertyNames(proto)) {
             if (key === "constructor" || visited.has(key)) continue;
             visited.add(key);
-            const method = proto[key];
+            // Route discovery inspects data descriptors without invoking accessors.
+            const method = Object.getOwnPropertyDescriptor(proto, key)?.value;
             if (typeof method !== "function") continue;
 
             const meta: IMcpRouteReflect | undefined = Reflect.getMetadata(
@@ -94,15 +118,18 @@ export class McpAdaptor {
             const params: IMcpRouteReflect.IArgument[] =
               Reflect.getMetadata("nestia/McpRoute/Parameters", proto, key) ??
               [];
-            const paramValidator = params.find(
-              (p) => p.category === "params",
-            )?.validate;
-
             tools.push({
               meta,
               source: `${wrapper.metatype?.name ?? proto.constructor?.name ?? "UnknownController"}.${String(key)}`,
-              validateArgs: paramValidator,
-              handler: async (args) => method.call(instance, args),
+              handler: createHandler({
+                container,
+                injector,
+                creator,
+                module,
+                wrapper,
+                key,
+                argument: params.find((p) => p.category === "params"),
+              }),
             });
           }
         }
@@ -132,6 +159,7 @@ export class McpAdaptor {
         capabilities: { tools: {} },
       });
       const server = mcp.server;
+      const relay = transportResponse(res.raw ?? res);
 
       server.setRequestHandler(ListToolsRequestSchema, async () => ({
         tools: tools.map((t) => ({
@@ -153,25 +181,14 @@ export class McpAdaptor {
           );
 
         const args = reqMsg.params.arguments ?? {};
-        if (tool.validateArgs) {
-          const err: Error | null = tool.validateArgs(args);
-          if (err !== null) {
-            const body =
-              err instanceof BadRequestException
-                ? (err.getResponse() as any)
-                : undefined;
-            throw new McpError(ErrorCode.InvalidParams, err.message, {
-              errors: body?.errors,
-              path: body?.path,
-              expected: body?.expected,
-              value: body?.value,
-              reason: body?.reason,
-            });
-          }
-        }
-
         try {
-          const result = await tool.handler(args);
+          const result = await tool.handler({
+            request: req,
+            response: res,
+            args,
+          });
+          if (relay.takeOver()) return { content: [] };
+          if (result instanceof Error) throw result;
           if (result === undefined) return { content: [] };
           return {
             content: [
@@ -183,6 +200,17 @@ export class McpAdaptor {
             ],
           };
         } catch (e) {
+          if (relay.takeOver()) return { content: [] };
+          if (INVALID_ARGUMENTS.has(e as object)) {
+            const body = (e as BadRequestException).getResponse() as any;
+            throw new McpError(ErrorCode.InvalidParams, (e as Error).message, {
+              errors: body?.errors,
+              path: body?.path,
+              expected: body?.expected,
+              value: body?.value,
+              reason: body?.reason,
+            });
+          }
           if (e instanceof HttpException) {
             return {
               content: [{ type: "text" as const, text: e.message }],
@@ -202,7 +230,7 @@ export class McpAdaptor {
       });
       try {
         await mcp.connect(transport);
-        await transport.handleRequest(req.raw ?? req, res.raw ?? res, req.body);
+        await transport.handleRequest(req.raw ?? req, relay.response, req.body);
       } finally {
         await transport.close().catch(() => {});
         await mcp.close().catch(() => {});
@@ -211,6 +239,139 @@ export class McpAdaptor {
   }
 }
 
+/**
+ * The tool's call through the enhancers NestJS applies to a route of the same
+ * method: guards, interceptors, pipes, and exception filters, bound to the
+ * method, its controller, or globally. The MCP HTTP request is the execution
+ * context, so a guard reading `switchToHttp().getRequest()` works unchanged.
+ *
+ * The arguments reach the method through the pipes as its body would, validated
+ * by typia at that stage: after the guards, as `@TypedBody()` is. An invalid
+ * argument is thrown as the validator's `BadRequestException`, which an
+ * exception filter may map; unmapped, it becomes JSON-RPC `-32602`. Successful
+ * resolver data becomes the argument before pipes execute. Legacy error-only
+ * metadata callbacks retain raw input on null success.
+ *
+ * A controller that is request-scoped, itself or through an enhancer or a
+ * dependency, is built per request with its enhancers, as NestJS builds it for
+ * an HTTP route; the static instance is only a placeholder without them.
+ */
+const createHandler = (props: {
+  container: NestContainer;
+  injector: Injector;
+  creator: ExternalContextCreator;
+  module: Module;
+  wrapper: InstanceWrapper;
+  key: string;
+  argument: IMcpRouteReflect.IArgument | undefined;
+}): McpAdaptor.ITool["handler"] => {
+  // the arguments stand at the params' position, or first when undecorated
+  const index: number = props.argument?.index ?? 0;
+  Reflect.defineMetadata(
+    PARAMS_METADATA,
+    { [`${RouteParamtypes.BODY}:${index}`]: { index, data: undefined } },
+    props.wrapper.instance.constructor,
+    props.key,
+  );
+  const validate = props.argument?.validate;
+  const create = (instance: any, contextId?: ContextId) =>
+    props.creator.create(
+      instance,
+      instance[props.key],
+      props.key,
+      PARAMS_METADATA,
+      {
+        // [request, response, next] as an HTTP route has, then the arguments
+        exchangeKeyForValue: (_type, _data, [, , , args]) => {
+          if (!validate) return args;
+          const result = resolve_request_body(validate, args);
+          if (result.success) return result.data;
+          INVALID_ARGUMENTS.add(result.error);
+          throw result.error;
+        },
+      },
+      contextId,
+      contextId && props.wrapper.id,
+    );
+  let target: ((...args: any[]) => Promise<unknown>) | undefined;
+  return async (input) => {
+    const call = (fn: (...args: any[]) => Promise<unknown>) =>
+      fn(input.request, input.response, undefined, input.args);
+    // resolved at the first call, so global enhancers init() registers count
+    if (props.wrapper.isDependencyTreeStatic())
+      return call((target ??= create(props.wrapper.instance)));
+    const contextId: ContextId = get_request_context_id(
+      props.container,
+      input.request as object,
+      props.wrapper.isDependencyTreeDurable(),
+    );
+    const instance: object = await props.injector.loadPerContext(
+      props.wrapper.instance,
+      props.module,
+      props.module.controllers,
+      contextId,
+    );
+    return call(create(instance, contextId));
+  };
+};
+
+/**
+ * The transport's response view. Native state, events and method receivers stay
+ * on the real response; only this view's writes stop after a tool's exception
+ * filter has already answered. Normal transport writes never activate
+ * takeover.
+ */
+const transportResponse = (
+  raw: any,
+): { response: any; takeOver: () => boolean } => {
+  let takenOver = false;
+  const respond = (key: string, args: unknown[]): unknown => {
+    if (takenOver) {
+      const callback = args.find((arg) => typeof arg === "function");
+      if ((key === "write" || key === "end") && typeof callback === "function")
+        queueMicrotask(() => callback());
+      return key === "write"
+        ? true
+        : key === "flushHeaders"
+          ? undefined
+          : response;
+    }
+    const result = Reflect.apply(raw[key], raw, args);
+    return result === raw ? response : result;
+  };
+  const writes = new Map<PropertyKey, (...args: unknown[]) => unknown>(
+    ["writeHead", "flushHeaders", "write", "end"].map((key) => [
+      key,
+      (...args: unknown[]) => respond(key, args),
+    ]),
+  );
+  const response: any = new Proxy(raw, {
+    get: (target, key) => {
+      const write = writes.get(key);
+      if (write !== undefined) return write;
+      const value = Reflect.get(target, key, target);
+      if (typeof value !== "function") return value;
+      return (...args: unknown[]) => {
+        const result = Reflect.apply(value, target, args);
+        return result === target ? response : result;
+      };
+    },
+    set: (target, key, value) => Reflect.set(target, key, value, target),
+  });
+  return {
+    response,
+    takeOver: () => {
+      takenOver ||= raw.headersSent === true;
+      return takenOver;
+    },
+  };
+};
+
+const PARAMS_METADATA = "nestia/McpRoute/ExternalParameters";
+
+/** The validators' exceptions, told apart from a handler's own. */
+const INVALID_ARGUMENTS: WeakSet<object> = new WeakSet();
+
 const assertUniqueTools = (tools: McpAdaptor.ITool[]): void => {
   const dict: Map<string, McpAdaptor.ITool[]> = new Map();
   for (const tool of tools) {
@@ -255,8 +416,26 @@ const loadMcpSdk = async () => {
   }
 };
 
+/**
+ * Types of {@link McpAdaptor}: the options of `upgrade` and the record of a
+ * registered tool.
+ *
+ * @evidence contracts/common.md#principled-implementation The class exposes one static entry point, so the adapter has no instance state: the tool list is closed over by the registered route handler.
+ * @evidence contracts/common.md#clear-and-simple-design One static method and two nested types.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts It has no fixture or tool name, and the MCP SDK is loaded lazily so an application that never enables MCP does not need it.
+ * @evidence contracts/common.md#meaningful-documentation The class comment explains what an MCP route is and how to enable it.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation MCP tool discovery and HTTP transport callbacks carry protocol values; optional SDK imports use Node module resolution and no native file identity or child process is defined here.
+ */
 export namespace McpAdaptor {
-  /** Configuration options for {@link McpAdaptor.upgrade}. */
+  /**
+   * Configuration options for {@link McpAdaptor.upgrade}.
+   *
+   * @evidence contracts/common.md#principled-implementation The two options are the route path, with `/mcp` as the default, and the server information reported to clients, with a default name and version.
+   * @evidence contracts/common.md#clear-and-simple-design A flat record of two optional values.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type; the defaults are stated in the code that reads them.
+   * @evidence contracts/common.md#meaningful-documentation Each option documents its meaning.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation MCP tool discovery and HTTP transport callbacks carry protocol values; optional SDK imports use Node module resolution and no native file identity or child process is defined here.
+   */
   export interface IOptions {
     /**
      * HTTP path where the MCP endpoint will be mounted.
@@ -278,7 +457,10 @@ export namespace McpAdaptor {
   export interface ITool {
     meta: IMcpRouteReflect;
     source: string;
-    handler: (args: unknown) => Promise<unknown>;
-    validateArgs?: (input: any) => Error | null;
+    handler: (input: {
+      request: unknown;
+      response: unknown;
+      args: unknown;
+    }) => Promise<unknown>;
   }
 }