@nestia/sdk 12.0.0-dev.20260601.1 → 12.0.0-dev.20260619.1

package/src/analyses/ReflectHttpOperationResponseAnalyzer.ts

@@ -1,130 +1,163 @@
-import { SwaggerExample } from "@nestia/core";
-import {
-  HEADERS_METADATA,
-  HTTP_CODE_METADATA,
-  INTERCEPTORS_METADATA,
-} from "@nestjs/common/constants";
-import { HttpQueryProgrammer, JsonMetadataFactory, sizeOf } from "../internal/legacy";
-
-import { IReflectController } from "../structures/IReflectController";
-import { IReflectHttpOperationSuccess } from "../structures/IReflectHttpOperationSuccess";
-import { IReflectOperationError } from "../structures/IReflectOperationError";
-import { IOperationMetadata } from "../structures/IOperationMetadata";
-import { TextPlainValidator } from "../validators/TextPlainValidator";
-
-export namespace ReflectHttpOperationResponseAnalyzer {
-  export interface IContext {
-    controller: IReflectController;
-    function: Function;
-    functionName: string;
-    httpMethod: string;
-    metadata: IOperationMetadata;
-    errors: IReflectOperationError[];
-  }
-
-  export const analyze = (
-    ctx: IContext,
-  ): IReflectHttpOperationSuccess | null => {
-    const errors: Array<string | IOperationMetadata.IError> = [];
-    const report = () => {
-      ctx.errors.push({
-        file: ctx.controller.file,
-        class: ctx.controller.class.name,
-        function: ctx.functionName,
-        from: "return",
-        contents: errors,
-      });
-      return null;
-    };
-
-    const encrypted: boolean = hasInterceptor({
-      name: "EncryptedRouteInterceptor",
-      function: ctx.function,
-    });
-    const contentType: string | null = encrypted
-      ? "text/plain"
-      : hasInterceptor({
-            name: "TypedQueryRouteInterceptor",
-            function: ctx.function,
-          })
-        ? "application/x-www-form-urlencoded"
-        : (Reflect.getMetadata(HEADERS_METADATA, ctx.function)?.find(
-            (h: Record<string, string>) =>
-              typeof h?.name === "string" &&
-              typeof h?.value === "string" &&
-              h.name.toLowerCase() === "content-type",
-          )?.value ??
-          Reflect.getMetadata("swagger/apiProduces", ctx.function)?.[0] ??
-          (ctx.httpMethod === "HEAD" ? null : "application/json"));
-
-    const schema =
-      contentType === "application/json"
-        ? ctx.metadata.success.primitive
-        : ctx.metadata.success.resolved;
-    if (schema.success === false) errors.push(...schema.errors);
-    if (ctx.httpMethod === "HEAD" && contentType !== null)
-      errors.push(`HEAD method must not have a content type.`);
-    if (isContentType(contentType) === false)
-      errors.push(
-        `@nestia/sdk does not support ${JSON.stringify(contentType)} content type.`,
-      );
-
-    if (errors.length) return report();
-    else if (
-      ctx.metadata.success.type === null ||
-      schema.success === false ||
-      !isContentType(contentType)
-    )
-      return null;
-
-    const example: SwaggerExample.IData<any> | undefined = Reflect.getMetadata(
-      "nestia/SwaggerExample/Response",
-      ctx.function,
-    );
-    return {
-      contentType,
-      encrypted,
-      status:
-        getStatus(ctx.function) ?? (ctx.httpMethod === "POST" ? 201 : 200),
-      type: ctx.metadata.success.type,
-      ...schema.data,
-      validate:
-        contentType === "application/json" || encrypted === true
-          ? JsonMetadataFactory.validate
-          : contentType === "application/x-www-form-urlencoded"
-            ? HttpQueryProgrammer.validate
-            : contentType === "text/plain"
-              ? TextPlainValidator.validate
-              : (next) =>
-                  sizeOf(next.metadata) !== 0
-                    ? ["HEAD method must not have any return value."]
-                    : [],
-      example: example?.example,
-      examples: example?.examples,
-    };
-  };
-
-  const getStatus = (func: Function): number | null => {
-    const text = Reflect.getMetadata(HTTP_CODE_METADATA, func);
-    if (text === undefined) return null;
-    const value: number = Number(text);
-    return isNaN(value) ? null : value;
-  };
-
-  const hasInterceptor = (props: {
-    name: string;
-    function: Function;
-  }): boolean => {
-    const meta = Reflect.getMetadata(INTERCEPTORS_METADATA, props.function);
-    if (Array.isArray(meta) === false) return false;
-    return meta.some((elem) => elem?.constructor?.name === props.name);
-  };
-
-  const isContentType = (
-    input: string | null,
-  ): input is IReflectHttpOperationSuccess["contentType"] =>
-    input === null ||
-    input === "application/json" ||
-    input === "text/plain" ||
-    input === "application/x-www-form-urlencoded";
-}
+import { SwaggerExample } from "@nestia/core";
+import {
+  HEADERS_METADATA,
+  HTTP_CODE_METADATA,
+  INTERCEPTORS_METADATA,
+} from "@nestjs/common/constants";
+
+import {
+  HttpQueryProgrammer,
+  JsonMetadataFactory,
+  sizeOf,
+} from "../internal/legacy";
+import { IOperationMetadata } from "../structures/IOperationMetadata";
+import { IReflectController } from "../structures/IReflectController";
+import { IReflectHttpOperationSuccess } from "../structures/IReflectHttpOperationSuccess";
+import { IReflectOperationError } from "../structures/IReflectOperationError";
+import { HttpResponseContentTypeUtil } from "../utils/HttpResponseContentTypeUtil";
+import { TextPlainValidator } from "../validators/TextPlainValidator";
+
+export namespace ReflectHttpOperationResponseAnalyzer {
+  export interface IContext {
+    controller: IReflectController;
+    function: Function;
+    functionName: string;
+    httpMethod: string;
+    metadata: IOperationMetadata;
+    errors: IReflectOperationError[];
+  }
+
+  export const analyze = (
+    ctx: IContext,
+  ): IReflectHttpOperationSuccess | null => {
+    const errors: Array<string | IOperationMetadata.IError> = [];
+    const report = () => {
+      ctx.errors.push({
+        file: ctx.controller.file,
+        class: ctx.controller.class.name,
+        function: ctx.functionName,
+        from: "return",
+        contents: errors,
+      });
+      return null;
+    };
+
+    const encrypted: boolean = hasInterceptor({
+      name: "EncryptedRouteInterceptor",
+      function: ctx.function,
+    });
+    const contentType: string | null = encrypted
+      ? "text/plain"
+      : hasInterceptor({
+            name: "TypedQueryRouteInterceptor",
+            function: ctx.function,
+          })
+        ? "application/x-www-form-urlencoded"
+        : (Reflect.getMetadata(HEADERS_METADATA, ctx.function)?.find(
+            (h: Record<string, string>) =>
+              typeof h?.name === "string" &&
+              typeof h?.value === "string" &&
+              h.name.toLowerCase() === "content-type",
+          )?.value ??
+          Reflect.getMetadata("swagger/apiProduces", ctx.function)?.[0] ??
+          (ctx.httpMethod === "HEAD" ? null : "application/json"));
+
+    const binary: boolean = HttpResponseContentTypeUtil.isBinary(contentType);
+    const schema = binary
+      ? { success: true as const, data: EMPTY_SCHEMA }
+      : contentType === "application/json"
+        ? ctx.metadata.success.primitive
+        : ctx.metadata.success.resolved;
+    if (schema.success === false) errors.push(...schema.errors);
+    if (ctx.httpMethod === "HEAD" && contentType !== null)
+      errors.push(`HEAD method must not have a content type.`);
+    if (HttpResponseContentTypeUtil.isSupported(contentType) === false)
+      errors.push(
+        `@nestia/sdk does not support ${JSON.stringify(contentType)} content type.`,
+      );
+
+    if (errors.length) return report();
+    else if (
+      (binary === false && ctx.metadata.success.type === null) ||
+      schema.success === false ||
+      !HttpResponseContentTypeUtil.isSupported(contentType)
+    )
+      return null;
+
+    const example: SwaggerExample.IData<any> | undefined = Reflect.getMetadata(
+      "nestia/SwaggerExample/Response",
+      ctx.function,
+    );
+    return {
+      contentType,
+      binary,
+      encrypted,
+      status:
+        getStatus(ctx.function) ?? (ctx.httpMethod === "POST" ? 201 : 200),
+      type: ctx.metadata.success.type ?? { name: "ReadableStream" },
+      ...schema.data,
+      validate:
+        binary === true
+          ? () => []
+          : contentType === "application/json" || encrypted === true
+            ? JsonMetadataFactory.validate
+            : contentType === "application/x-www-form-urlencoded"
+              ? HttpQueryProgrammer.validate
+              : contentType === "text/plain"
+                ? TextPlainValidator.validate
+                : (next) =>
+                    sizeOf(next.metadata) !== 0
+                      ? ["HEAD method must not have any return value."]
+                      : [],
+      example: example?.example,
+      examples: example?.examples,
+    };
+  };
+
+  const getStatus = (func: Function): number | null => {
+    const text = Reflect.getMetadata(HTTP_CODE_METADATA, func);
+    if (text === undefined) return null;
+    const value: number = Number(text);
+    return isNaN(value) ? null : value;
+  };
+
+  const hasInterceptor = (props: {
+    name: string;
+    function: Function;
+  }): boolean => {
+    const meta = Reflect.getMetadata(INTERCEPTORS_METADATA, props.function);
+    if (Array.isArray(meta) === false) return false;
+    return meta.some((elem) => elem?.constructor?.name === props.name);
+  };
+
+  const EMPTY_SCHEMA: IOperationMetadata.ISchema = {
+    components: {
+      aliases: [],
+      arrays: [],
+      objects: [],
+      tuples: [],
+    },
+    metadata: {
+      aliases: [],
+      any: false,
+      arrays: [],
+      atomics: [],
+      constants: [],
+      escaped: null,
+      functions: [],
+      maps: [],
+      natives: [],
+      nullable: false,
+      objects: [],
+      optional: false,
+      required: true,
+      rest: null,
+      sets: [],
+      templates: [],
+      tuples: [],
+      size: 0,
+      name: "void",
+      empty: true,
+    } as IOperationMetadata.ISchema["metadata"],
+  };
+}

package/src/analyses/ReflectMcpOperationAnalyzer.ts

@@ -0,0 +1,124 @@
+import { METHOD_METADATA, PATH_METADATA } from "@nestjs/common/constants";
+
+import { INestiaProject } from "../structures/INestiaProject";
+import { IOperationMetadata } from "../structures/IOperationMetadata";
+import { IReflectController } from "../structures/IReflectController";
+import { IReflectImport } from "../structures/IReflectImport";
+import { IReflectMcpOperation } from "../structures/IReflectMcpOperation";
+import { IReflectMcpOperationParameter } from "../structures/IReflectMcpOperationParameter";
+import { ImportAnalyzer } from "./ImportAnalyzer";
+
+export namespace ReflectMcpOperationAnalyzer {
+  export interface IProps {
+    project: Omit<INestiaProject, "config">;
+    controller: IReflectController;
+    function: Function;
+    name: string;
+    metadata: IOperationMetadata;
+  }
+
+  export const analyze = (ctx: IProps): IReflectMcpOperation | null => {
+    const route:
+      | {
+          name: string;
+          title?: string;
+          description?: string;
+          inputSchema: object;
+          outputSchema?: object;
+          annotations?: IReflectMcpOperation.IAnnotations;
+        }
+      | undefined = Reflect.getMetadata("nestia/McpRoute", ctx.function);
+    if (route === undefined) return null;
+
+    const errors: string[] = [];
+    const hasHttpRoute: boolean =
+      Reflect.getMetadata(PATH_METADATA, ctx.function) !== undefined ||
+      Reflect.getMetadata(METHOD_METADATA, ctx.function) !== undefined;
+    const hasWebSocketRoute: boolean =
+      Reflect.getMetadata("nestia/WebSocketRoute", ctx.function) !== undefined;
+
+    if (hasHttpRoute || hasWebSocketRoute)
+      errors.push(
+        "@McpRoute must not be combined with HTTP or WebSocket route decorators on the same method.",
+      );
+
+    const preconfigured: IReflectMcpOperationParameter.IPreconfigured[] = (
+      (Reflect.getMetadata(
+        "nestia/McpRoute/Parameters",
+        ctx.controller.class.prototype,
+        ctx.name,
+      ) ?? []) as IReflectMcpOperationParameter.IPreconfigured[]
+    ).sort((a, b) => a.index - b.index);
+
+    if (preconfigured.length > 1)
+      errors.push(
+        "@McpRoute tools may declare at most one @McpRoute.Params() parameter.",
+      );
+    if (ctx.function.length > 1)
+      errors.push(
+        "@McpRoute tools must have 0 or 1 parameters (the MCP arguments object).",
+      );
+
+    const imports: IReflectImport[] = [];
+    const parameters: IReflectMcpOperationParameter[] = preconfigured
+      .map((p) => {
+        const matched: IOperationMetadata.IParameter | undefined =
+          ctx.metadata.parameters.find(
+            (m: IOperationMetadata.IParameter) => p.index === m.index,
+          );
+        if (matched === undefined) {
+          errors.push(
+            `Unable to find parameter type of the ${p.index} (th) argument.`,
+          );
+          return null;
+        }
+        if (matched.type === null) {
+          errors.push(
+            `Failed to analyze the parameter type of ${JSON.stringify(matched.name)}.`,
+          );
+          return null;
+        }
+        imports.push(...matched.imports);
+        return {
+          category: "params" as const,
+          name: matched.name,
+          index: p.index,
+          type: matched.type,
+          imports: matched.imports,
+          description: matched.description,
+          jsDocTags: matched.jsDocTags,
+        };
+      })
+      .filter((p): p is IReflectMcpOperationParameter => !!p);
+
+    if (ctx.metadata.success?.imports?.length)
+      imports.push(...ctx.metadata.success.imports);
+
+    if (errors.length) {
+      ctx.project.errors.push({
+        file: ctx.controller.file,
+        class: ctx.controller.class.name,
+        function: ctx.function.name,
+        from: ctx.name,
+        contents: errors,
+      });
+      return null;
+    }
+    return {
+      protocol: "mcp",
+      name: ctx.name,
+      toolName: route.name,
+      title: route.title ?? null,
+      toolDescription: route.description ?? null,
+      inputSchema: route.inputSchema,
+      outputSchema: route.outputSchema ?? null,
+      annotations: route.annotations ?? null,
+      function: ctx.function,
+      parameters,
+      returnType: ctx.metadata.success?.type ?? null,
+      imports: ImportAnalyzer.merge(imports),
+      description: ctx.metadata.description ?? null,
+      jsDocTags: ctx.metadata.jsDocTags,
+    };
+  };
+}

package/src/analyses/ReflectMetadataAnalyzer.ts

@@ -1,44 +1,44 @@
-import { VERSION_NEUTRAL } from "@nestjs/common";
-import { PATH_METADATA, VERSION_METADATA } from "@nestjs/common/constants";
-import { VersionValue } from "@nestjs/common/interfaces";
-
-import { SecurityAnalyzer } from "./SecurityAnalyzer";
-
-export namespace ReflectMetadataAnalyzer {
-  export const paths = (target: Function): string[] => {
-    const value: string | string[] = Reflect.getMetadata(PATH_METADATA, target);
-    if (typeof value === "string") return [value];
-    else if (value.length === 0) return [""];
-    else return value;
-  };
-
-  export const extensions = (value: any): Record<string, any> => {
-    const entire: Record<string, any>[] | undefined = Reflect.getMetadata(
-      "swagger/apiExtension",
-      value,
-    );
-    return entire ?? {};
-  };
-
-  export const securities = (value: any): Record<string, string[]>[] => {
-    const entire: Record<string, string[]>[] | undefined = Reflect.getMetadata(
-      "swagger/apiSecurity",
-      value,
-    );
-    return entire ? SecurityAnalyzer.merge(...entire) : [];
-  };
-
-  export const versions = (
-    target: any,
-  ): Array<string | typeof VERSION_NEUTRAL> | undefined => {
-    const value: VersionValue | undefined = Reflect.getMetadata(
-      VERSION_METADATA,
-      target,
-    );
-    return value === undefined
-      ? undefined
-      : Array.isArray(value)
-        ? value
-        : [value];
-  };
-}
+import { VERSION_NEUTRAL } from "@nestjs/common";
+import { PATH_METADATA, VERSION_METADATA } from "@nestjs/common/constants";
+import { VersionValue } from "@nestjs/common/interfaces";
+
+import { SecurityAnalyzer } from "./SecurityAnalyzer";
+
+export namespace ReflectMetadataAnalyzer {
+  export const paths = (target: Function): string[] => {
+    const value: string | string[] = Reflect.getMetadata(PATH_METADATA, target);
+    if (typeof value === "string") return [value];
+    else if (value.length === 0) return [""];
+    else return value;
+  };
+
+  export const extensions = (value: any): Record<string, any> => {
+    const entire: Record<string, any>[] | undefined = Reflect.getMetadata(
+      "swagger/apiExtension",
+      value,
+    );
+    return entire ?? {};
+  };
+
+  export const securities = (value: any): Record<string, string[]>[] => {
+    const entire: Record<string, string[]>[] | undefined = Reflect.getMetadata(
+      "swagger/apiSecurity",
+      value,
+    );
+    return entire ? SecurityAnalyzer.merge(...entire) : [];
+  };
+
+  export const versions = (
+    target: any,
+  ): Array<string | typeof VERSION_NEUTRAL> | undefined => {
+    const value: VersionValue | undefined = Reflect.getMetadata(
+      VERSION_METADATA,
+      target,
+    );
+    return value === undefined
+      ? undefined
+      : Array.isArray(value)
+        ? value
+        : [value];
+  };
+}

package/src/analyses/SecurityAnalyzer.ts

@@ -1,25 +1,25 @@
-import { MapUtil } from "../utils/MapUtil";
-
-export namespace SecurityAnalyzer {
-  export const merge = (...entire: Record<string, string[]>[]) => {
-    const dict: Map<string | typeof none, Set<string>> = new Map();
-    for (const obj of entire) {
-      const entries = Object.entries(obj);
-      for (const [key, value] of entries) {
-        const set = MapUtil.take(dict, key, () => new Set());
-        for (const val of value) set.add(val);
-      }
-      if (entries.length === 0) MapUtil.take(dict, none, () => new Set());
-    }
-    const output: Record<string, string[]>[] = [];
-    for (const [key, set] of dict)
-      key === none
-        ? output.push({})
-        : output.push({
-            [key]: [...set],
-          });
-    return output;
-  };
-
-  const none = Symbol("none");
-}
+import { MapUtil } from "../utils/MapUtil";
+
+export namespace SecurityAnalyzer {
+  export const merge = (...entire: Record<string, string[]>[]) => {
+    const dict: Map<string | typeof none, Set<string>> = new Map();
+    for (const obj of entire) {
+      const entries = Object.entries(obj);
+      for (const [key, value] of entries) {
+        const set = MapUtil.take(dict, key, () => new Set());
+        for (const val of value) set.add(val);
+      }
+      if (entries.length === 0) MapUtil.take(dict, none, () => new Set());
+    }
+    const output: Record<string, string[]>[] = [];
+    for (const [key, set] of dict)
+      key === none
+        ? output.push({})
+        : output.push({
+            [key]: [...set],
+          });
+    return output;
+  };
+
+  const none = Symbol("none");
+}

package/src/analyses/TypedMcpRouteAnalyzer.ts

@@ -0,0 +1,34 @@
+import { IReflectController } from "../structures/IReflectController";
+import { IReflectMcpOperation } from "../structures/IReflectMcpOperation";
+import { ITypedMcpRoute } from "../structures/ITypedMcpRoute";
+
+export namespace TypedMcpRouteAnalyzer {
+  export const analyze = (props: {
+    controller: IReflectController;
+    operation: IReflectMcpOperation;
+  }): ITypedMcpRoute[] => [
+    {
+      protocol: "mcp",
+      controller: props.controller,
+      name: props.operation.name,
+      toolName: props.operation.toolName,
+      title: props.operation.title,
+      toolDescription: props.operation.toolDescription,
+      accessor: accessor(props.operation.toolName),
+      function: props.operation.function,
+      input: props.operation.parameters[0] ?? null,
+      returnType: props.operation.returnType,
+      inputSchema: props.operation.inputSchema,
+      outputSchema: props.operation.outputSchema,
+      annotations: props.operation.annotations,
+      imports: props.operation.imports,
+      description: props.operation.description,
+      jsDocTags: props.operation.jsDocTags,
+    },
+  ];
+
+  const accessor = (toolName: string): string[] => {
+    const safe = toolName.replace(/[^A-Za-z0-9_$]/g, "_");
+    return ["mcp", safe];
+  };
+}

package/src/decorators/OperationMetadata.ts

@@ -1,29 +1,29 @@
-import { IOperationMetadata } from "../structures/IOperationMetadata";
-
-/**
- * Carries the compile-time operation metadata the SDK / Swagger / e2e
- * generators read through `Reflect.getMetadata("nestia/OperationMetadata")`.
- *
- * The `@nestia/sdk` native transform injects this decorator as a synthesized
- * AST node, so its argument is a single JSON string literal rather than an
- * object literal — keeping the constructed node tree minimal. The string is
- * parsed once here at module-evaluation time. A pre-parsed `IOperationMetadata`
- * object is still accepted for hand-written or test usage.
- */
-export function OperationMetadata(
-  metadata: IOperationMetadata | string,
-): MethodDecorator {
-  const parsed: IOperationMetadata =
-    typeof metadata === "string"
-      ? (JSON.parse(metadata) as IOperationMetadata)
-      : metadata;
-  return function OperationMetadata(target, propertyKey, descriptor) {
-    Reflect.defineMetadata(
-      "nestia/OperationMetadata",
-      parsed,
-      target,
-      propertyKey,
-    );
-    return descriptor;
-  };
-}
+import { IOperationMetadata } from "../structures/IOperationMetadata";
+
+/**
+ * Carries the compile-time operation metadata the SDK / Swagger / e2e
+ * generators read through `Reflect.getMetadata("nestia/OperationMetadata")`.
+ *
+ * The `@nestia/sdk` native transform injects this decorator as a synthesized
+ * AST node, so its argument is a single JSON string literal rather than an
+ * object literal — keeping the constructed node tree minimal. The string is
+ * parsed once here at module-evaluation time. A pre-parsed `IOperationMetadata`
+ * object is still accepted for hand-written or test usage.
+ */
+export function OperationMetadata(
+  metadata: IOperationMetadata | string,
+): MethodDecorator {
+  const parsed: IOperationMetadata =
+    typeof metadata === "string"
+      ? (JSON.parse(metadata) as IOperationMetadata)
+      : metadata;
+  return function OperationMetadata(target, propertyKey, descriptor) {
+    Reflect.defineMetadata(
+      "nestia/OperationMetadata",
+      parsed,
+      target,
+      propertyKey,
+    );
+    return descriptor;
+  };
+}