@nestia/core 12.0.0-dev.20260601.1 → 12.0.0-dev.20260612.2

package/src/decorators/EncryptedRoute.ts

@@ -1,213 +1,213 @@
-import { IEncryptionPassword } from "@nestia/fetcher";
-import { AesPkcs5 } from "@nestia/fetcher/lib/AesPkcs5";
-import {
-  CallHandler,
-  Delete,
-  ExecutionContext,
-  Get,
-  NestInterceptor,
-  Patch,
-  Post,
-  Put,
-  UseInterceptors,
-  applyDecorators,
-} from "@nestjs/common";
-import { HttpArgumentsHost } from "@nestjs/common/interfaces";
-import express from "express";
-import { catchError, map } from "rxjs/operators";
-import typia from "typia";
-
-import { IResponseBodyStringifier } from "../options/IResponseBodyStringifier";
-import { Singleton } from "../utils/Singleton";
-import { TypedRoute } from "./TypedRoute";
-import { ENCRYPTION_METADATA_KEY } from "./internal/EncryptedConstant";
-import { get_path_and_stringify } from "./internal/get_path_and_stringify";
-import { headers_to_object } from "./internal/headers_to_object";
-import { route_error } from "./internal/route_error";
-
-/**
- * Encrypted router decorator functions.
- *
- * `EncryptedRoute` is a module containing router decorator functions which
- * encrypts response body data through AES-128/256 encryption. Furthermore, they
- * can boost up JSON string conversion speed about 50x times faster than
- * `class-transformer`, even type safe through
- * [typia](https://github.com/samchon/typia).
- *
- * For reference, if you try to invalid data that is not following the promised
- * type `T`, 500 internal server error would be thrown. Also, as
- * `EncryptedRoute` composes JSON string through `typia.assertStringify<T>()`
- * function, it is not possible to modify response data through interceptors.
- *
- * - AES-128/256
- * - CBC mode
- * - PKCS #5 Padding
- * - Base64 Encoding
- *
- * @author Jeongho Nam - https://github.com/samchon
- */
-export namespace EncryptedRoute {
-  /**
-   * Encrypted router decorator function for the GET method.
-   *
-   * @param paths Path(s) of the HTTP request
-   * @returns Method decorator
-   */
-  export const Get = Generator("Get");
-
-  /**
-   * Encrypted router decorator function for the GET method.
-   *
-   * @param paths Path(s) of the HTTP request
-   * @returns Method decorator
-   */
-  export const Post = Generator("Post");
-
-  /**
-   * Encrypted router decorator function for the PATCH method.
-   *
-   * @param path Path of the HTTP request
-   * @returns Method decorator
-   */
-  export const Patch = Generator("Patch");
-
-  /**
-   * Encrypted router decorator function for the PUT method.
-   *
-   * @param path Path of the HTTP request
-   * @returns Method decorator
-   */
-  export const Put = Generator("Put");
-
-  /**
-   * Encrypted router decorator function for the DELETE method.
-   *
-   * @param path Path of the HTTP request
-   * @returns Method decorator
-   */
-  export const Delete = Generator("Delete");
-
-  /**
-   * Set the logger function for the response validation failure.
-   *
-   * If you've configured the transformation option to `validate.log` in the
-   * `tsconfig.json` file, then the error log information of the response
-   * validation failure would be logged through this function instead of
-   * throwing the 400 bad request error.
-   *
-   * By the way, be careful. If you've configured the response transformation
-   * option to be `validate.log`, client may get wrong response data. Therefore,
-   * this way is not recommended in the common backend server case.
-   *
-   * @default console.log
-   * @param func Logger function
-   */
-  export function setValidateErrorLogger(
-    func: (log: IValidateErrorLog) => void,
-  ): void {
-    TypedRoute.setValidateErrorLogger(func);
-  }
-
-  export import IValidateErrorLog = TypedRoute.IValidateErrorLog;
-
-  /** @internal */
-  function Generator(method: "Get" | "Post" | "Put" | "Patch" | "Delete") {
-    function route(path?: string | string[]): MethodDecorator;
-    function route<T>(
-      stringify?: IResponseBodyStringifier<T> | null,
-    ): MethodDecorator;
-    function route<T>(
-      path: string | string[],
-      stringify?: IResponseBodyStringifier<T> | null,
-    ): MethodDecorator;
-
-    function route(...args: any[]): MethodDecorator {
-      const [path, stringify] = get_path_and_stringify(
-        () => TypedRoute.__logger,
-      )(`EncryptedRoute.${method}`)(...args);
-      return applyDecorators(
-        ROUTERS[method](path),
-        UseInterceptors(new EncryptedRouteInterceptor(method, stringify)),
-      );
-    }
-    return route;
-  }
-}
-
-for (const method of [
-  typia.json.isStringify,
-  typia.json.assertStringify,
-  typia.json.validateStringify,
-  typia.json.stringify,
-])
-  for (const [key, value] of Object.entries(method))
-    for (const deco of [
-      EncryptedRoute.Get,
-      EncryptedRoute.Delete,
-      EncryptedRoute.Post,
-      EncryptedRoute.Put,
-      EncryptedRoute.Patch,
-    ])
-      (deco as any)[key] = value;
-
-/** @internal */
-class EncryptedRouteInterceptor implements NestInterceptor {
-  public constructor(
-    private readonly method: string,
-    private readonly stringify: (
-      input: any,
-      method: string,
-      path: string,
-    ) => string,
-  ) {}
-
-  public intercept(context: ExecutionContext, next: CallHandler) {
-    const http: HttpArgumentsHost = context.switchToHttp();
-    return next.handle().pipe(
-      map((value) => {
-        const param:
-          | IEncryptionPassword
-          | IEncryptionPassword.Closure
-          | undefined = Reflect.getMetadata(
-          ENCRYPTION_METADATA_KEY,
-          context.getClass(),
-        );
-        if (!param)
-          return Error(
-            `Error on EncryptedRoute.${this.method}(): no password found.`,
-          );
-
-        const request: express.Request = http.getRequest();
-        const headers: Singleton<Record<string, string>> = new Singleton(() =>
-          headers_to_object(request.headers),
-        );
-        const body: string | undefined = this.stringify(
-          value,
-          request.method,
-          request.url,
-        );
-        const password: IEncryptionPassword =
-          typeof param === "function"
-            ? param({
-                headers: headers.get(),
-                body,
-                direction: "encode",
-              })
-            : param;
-
-        if (body === undefined) return body;
-        return AesPkcs5.encrypt(body, password.key, password.iv);
-      }),
-      catchError((err) => route_error(http.getRequest(), err)),
-    );
-  }
-}
-
-/** @internal */
-const ROUTERS = {
-  Get,
-  Post,
-  Put,
-  Patch,
-  Delete,
-};
+import { IEncryptionPassword } from "@nestia/fetcher";
+import { AesPkcs5 } from "@nestia/fetcher/lib/AesPkcs5";
+import {
+  CallHandler,
+  Delete,
+  ExecutionContext,
+  Get,
+  NestInterceptor,
+  Patch,
+  Post,
+  Put,
+  UseInterceptors,
+  applyDecorators,
+} from "@nestjs/common";
+import { HttpArgumentsHost } from "@nestjs/common/interfaces";
+import express from "express";
+import { catchError, map } from "rxjs/operators";
+import typia from "typia";
+
+import { IResponseBodyStringifier } from "../options/IResponseBodyStringifier";
+import { Singleton } from "../utils/Singleton";
+import { TypedRoute } from "./TypedRoute";
+import { ENCRYPTION_METADATA_KEY } from "./internal/EncryptedConstant";
+import { get_path_and_stringify } from "./internal/get_path_and_stringify";
+import { headers_to_object } from "./internal/headers_to_object";
+import { route_error } from "./internal/route_error";
+
+/**
+ * Encrypted router decorator functions.
+ *
+ * `EncryptedRoute` is a module containing router decorator functions which
+ * encrypts response body data through AES-128/256 encryption. Furthermore, they
+ * can boost up JSON string conversion speed about 50x times faster than
+ * `class-transformer`, even type safe through
+ * [typia](https://github.com/samchon/typia).
+ *
+ * For reference, if you try to invalid data that is not following the promised
+ * type `T`, 500 internal server error would be thrown. Also, as
+ * `EncryptedRoute` composes JSON string through `typia.assertStringify<T>()`
+ * function, it is not possible to modify response data through interceptors.
+ *
+ * - AES-128/256
+ * - CBC mode
+ * - PKCS #5 Padding
+ * - Base64 Encoding
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export namespace EncryptedRoute {
+  /**
+   * Encrypted router decorator function for the GET method.
+   *
+   * @param paths Path(s) of the HTTP request
+   * @returns Method decorator
+   */
+  export const Get = Generator("Get");
+
+  /**
+   * Encrypted router decorator function for the GET method.
+   *
+   * @param paths Path(s) of the HTTP request
+   * @returns Method decorator
+   */
+  export const Post = Generator("Post");
+
+  /**
+   * Encrypted router decorator function for the PATCH method.
+   *
+   * @param path Path of the HTTP request
+   * @returns Method decorator
+   */
+  export const Patch = Generator("Patch");
+
+  /**
+   * Encrypted router decorator function for the PUT method.
+   *
+   * @param path Path of the HTTP request
+   * @returns Method decorator
+   */
+  export const Put = Generator("Put");
+
+  /**
+   * Encrypted router decorator function for the DELETE method.
+   *
+   * @param path Path of the HTTP request
+   * @returns Method decorator
+   */
+  export const Delete = Generator("Delete");
+
+  /**
+   * Set the logger function for the response validation failure.
+   *
+   * If you've configured the transformation option to `validate.log` in the
+   * `tsconfig.json` file, then the error log information of the response
+   * validation failure would be logged through this function instead of
+   * throwing the 400 bad request error.
+   *
+   * By the way, be careful. If you've configured the response transformation
+   * option to be `validate.log`, client may get wrong response data. Therefore,
+   * this way is not recommended in the common backend server case.
+   *
+   * @default console.log
+   * @param func Logger function
+   */
+  export function setValidateErrorLogger(
+    func: (log: IValidateErrorLog) => void,
+  ): void {
+    TypedRoute.setValidateErrorLogger(func);
+  }
+
+  export import IValidateErrorLog = TypedRoute.IValidateErrorLog;
+
+  /** @internal */
+  function Generator(method: "Get" | "Post" | "Put" | "Patch" | "Delete") {
+    function route(path?: string | string[]): MethodDecorator;
+    function route<T>(
+      stringify?: IResponseBodyStringifier<T> | null,
+    ): MethodDecorator;
+    function route<T>(
+      path: string | string[],
+      stringify?: IResponseBodyStringifier<T> | null,
+    ): MethodDecorator;
+
+    function route(...args: any[]): MethodDecorator {
+      const [path, stringify] = get_path_and_stringify(
+        () => TypedRoute.__logger,
+      )(`EncryptedRoute.${method}`)(...args);
+      return applyDecorators(
+        ROUTERS[method](path),
+        UseInterceptors(new EncryptedRouteInterceptor(method, stringify)),
+      );
+    }
+    return route;
+  }
+}
+
+for (const method of [
+  typia.json.isStringify,
+  typia.json.assertStringify,
+  typia.json.validateStringify,
+  typia.json.stringify,
+])
+  for (const [key, value] of Object.entries(method))
+    for (const deco of [
+      EncryptedRoute.Get,
+      EncryptedRoute.Delete,
+      EncryptedRoute.Post,
+      EncryptedRoute.Put,
+      EncryptedRoute.Patch,
+    ])
+      (deco as any)[key] = value;
+
+/** @internal */
+class EncryptedRouteInterceptor implements NestInterceptor {
+  public constructor(
+    private readonly method: string,
+    private readonly stringify: (
+      input: any,
+      method: string,
+      path: string,
+    ) => string,
+  ) {}
+
+  public intercept(context: ExecutionContext, next: CallHandler) {
+    const http: HttpArgumentsHost = context.switchToHttp();
+    return next.handle().pipe(
+      map((value) => {
+        const param:
+          | IEncryptionPassword
+          | IEncryptionPassword.Closure
+          | undefined = Reflect.getMetadata(
+          ENCRYPTION_METADATA_KEY,
+          context.getClass(),
+        );
+        if (!param)
+          return Error(
+            `Error on EncryptedRoute.${this.method}(): no password found.`,
+          );
+
+        const request: express.Request = http.getRequest();
+        const headers: Singleton<Record<string, string>> = new Singleton(() =>
+          headers_to_object(request.headers),
+        );
+        const body: string | undefined = this.stringify(
+          value,
+          request.method,
+          request.url,
+        );
+        const password: IEncryptionPassword =
+          typeof param === "function"
+            ? param({
+                headers: headers.get(),
+                body,
+                direction: "encode",
+              })
+            : param;
+
+        if (body === undefined) return body;
+        return AesPkcs5.encrypt(body, password.key, password.iv);
+      }),
+      catchError((err) => route_error(http.getRequest(), err)),
+    );
+  }
+}
+
+/** @internal */
+const ROUTERS = {
+  Get,
+  Post,
+  Put,
+  Patch,
+  Delete,
+};

package/src/decorators/HumanRoute.ts

@@ -1,21 +1,21 @@
-import { SwaggerCustomizer } from "./SwaggerCustomizer";
-
-/**
- * Human only API marking.
- *
- * This decorator marks the API for human only, so that LLM function calling
- * schema composer excludes the API.
- *
- * In other words, if you adjust the `@HumanRoute()` decorator to the API, the
- * API never participates in the LLM function calling. When calling the
- * {@link HttpLlm.application} function, matched {@link IHttpLlmFunction} data
- * never be composed.
- *
- * @author Jeongho Nam - https://github.com/samchon
- * @returns Method decorator
- */
-export function HumanRoute(): MethodDecorator {
-  return SwaggerCustomizer((props) => {
-    props.route["x-samchon-human"] = true;
-  });
-}
+import { SwaggerCustomizer } from "./SwaggerCustomizer";
+
+/**
+ * Human only API marking.
+ *
+ * This decorator marks the API for human only, so that LLM function calling
+ * schema composer excludes the API.
+ *
+ * In other words, if you adjust the `@HumanRoute()` decorator to the API, the
+ * API never participates in the LLM function calling. When calling the
+ * {@link HttpLlm.application} function, matched {@link IHttpLlmFunction} data
+ * never be composed.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @returns Method decorator
+ */
+export function HumanRoute(): MethodDecorator {
+  return SwaggerCustomizer((props) => {
+    props.route["x-samchon-human"] = true;
+  });
+}

package/src/decorators/McpRoute.ts

@@ -0,0 +1,154 @@
+import { IRequestBodyValidator } from "../options/IRequestBodyValidator";
+import { IMcpRouteReflect } from "./internal/IMcpRouteReflect";
+import { validate_request_body } from "./internal/validate_request_body";
+
+/**
+ * MCP (Model Context Protocol) route decorator.
+ *
+ * `@McpRoute()` marks a controller method as a callable MCP tool. When the
+ * application bootstraps, every method annotated with this decorator is
+ * registered on the MCP server built by {@link McpAdaptor.upgrade}, making it
+ * reachable by LLM clients through the standard Streamable HTTP transport.
+ *
+ * The public form takes only the tool's `name` (string). Human-readable
+ * `description` and `title` are read from the method's JSDoc:
+ *
+ * - `description`: the JSDoc comment body.
+ * - `title`: the value of an optional `@title` JSDoc tag.
+ *
+ * For type-safe tool inputs, decorate exactly one parameter of the method with
+ * {@link McpRoute.Params}. The parameter type `T` is analyzed at compile time by
+ * the nestia transformer, which generates both a runtime validator and the JSON
+ * Schema attached to `inputSchema` in `tools/list` responses.
+ *
+ * For the MCP endpoint to actually be served, call {@link McpAdaptor.upgrade} on
+ * the {@link INestApplication} instance at bootstrap. The decorator alone only
+ * stores reflection metadata.
+ *
+ * @author wildduck - https://github.com/wildduck2
+ * @example
+ *   ```typescript
+ *   import core from "@nestia/core";
+ *
+ *   @Controller()
+ *   export class WeatherController {
+ *     /**
+ *      * Return current weather for a city.
+ *      *
+ *      * @title Get weather
+ *      *\/
+ *     @core.McpRoute("get_weather")
+ *     public async get(
+ *       @core.McpRoute.Params() params: { city: string },
+ *     ): Promise<{ temp: number }> {
+ *       return { temp: 22 };
+ *     }
+ *   }
+ *   ```;
+ *
+ * @param name Unique tool identifier exposed to MCP clients via `tools/list`.
+ * @returns Method decorator.
+ */
+export function McpRoute(name: string): MethodDecorator;
+
+/** @internal */
+export function McpRoute(config: McpRoute.IConfig): MethodDecorator;
+
+export function McpRoute(input: string | McpRoute.IConfig): MethodDecorator {
+  const config: McpRoute.IConfig =
+    typeof input === "string" ? { name: input } : input;
+  return function McpRoute(
+    _target: Object,
+    _propertyKey: string | symbol,
+    descriptor: TypedPropertyDescriptor<any>,
+  ): TypedPropertyDescriptor<any> {
+    Reflect.defineMetadata(
+      "nestia/McpRoute",
+      {
+        name: config.name,
+        title: config.title,
+        description: config.description,
+        inputSchema: config.inputSchema ?? { type: "object", properties: {} },
+        outputSchema: config.outputSchema,
+        annotations: config.annotations,
+      } satisfies IMcpRouteReflect,
+      descriptor.value,
+    );
+    return descriptor;
+  };
+}
+
+export namespace McpRoute {
+  /**
+   * Configuration object emitted by the nestia transformer at compile time.
+   *
+   * Users call `@McpRoute("name")`; the transformer rewrites the call to
+   * `@McpRoute({ name, description, title, inputSchema, ... })` after parsing
+   * method JSDoc and analyzing the `@McpRoute.Params<T>()` parameter type.
+   *
+   * @internal
+   */
+  export interface IConfig {
+    name: string;
+    title?: string;
+    description?: string;
+    inputSchema?: object;
+    outputSchema?: object;
+    annotations?: IMcpRouteReflect["annotations"];
+  }
+
+  /**
+   * Parameter decorator for an MCP tool's input arguments.
+   *
+   * `@McpRoute.Params<T>()` validates the `arguments` object from a
+   * `tools/call` request against the TypeScript type `T` using typia. A failed
+   * validation surfaces to the client as a JSON-RPC `-32602` (`InvalidParams`)
+   * error with structured diagnostics, giving the LLM precise feedback to
+   * self-correct.
+   *
+   * MCP tools accept exactly one arguments object; applying this decorator more
+   * than once on a single method is a compile-time error. The decorated type
+   * `T` must be an object type without dynamic properties.
+   *
+   * @author wildduck - https://github.com/wildduck2
+   * @param validator Optional custom validator. Default is `typia.assert()`.
+   * @returns Parameter decorator.
+   */
+  export function Params<T>(
+    validator?: IRequestBodyValidator<T>,
+  ): ParameterDecorator {
+    const validate = validate_request_body("McpRoute.Params")(validator);
+    return function McpRouteParams(
+      target: Object,
+      propertyKey: string | symbol | undefined,
+      parameterIndex: number,
+    ) {
+      emplace(target, propertyKey ?? "", {
+        category: "params",
+        index: parameterIndex,
+        validate,
+      });
+    };
+  }
+
+  /** @internal */
+  const emplace = (
+    target: Object,
+    propertyKey: string | symbol,
+    value: IMcpRouteReflect.IArgument,
+  ) => {
+    const array: IMcpRouteReflect.IArgument[] | undefined = Reflect.getMetadata(
+      "nestia/McpRoute/Parameters",
+      target,
+      propertyKey,
+    );
+    if (array !== undefined) array.push(value);
+    else
+      Reflect.defineMetadata(
+        "nestia/McpRoute/Parameters",
+        [value],
+        target,
+        propertyKey,
+      );
+  };
+}