@nestia/core 11.2.0 → 11.3.0

package/src/adaptors/McpAdaptor.ts

@@ -0,0 +1,276 @@
+import {
+  BadRequestException,
+  HttpException,
+  INestApplication,
+} from "@nestjs/common";
+import { NestContainer } from "@nestjs/core";
+
+import { IMcpRouteReflect } from "../decorators/internal/IMcpRouteReflect";
+
+/**
+ * MCP (Model Context Protocol) adaptor.
+ *
+ * `McpAdaptor` exposes every method decorated with {@link McpRoute} as an MCP
+ * tool, reachable by LLM clients through a stateless Streamable HTTP endpoint.
+ *
+ * At bootstrap the adaptor walks the {@link NestContainer}, collects every
+ * controller method carrying `"nestia/McpRoute"` metadata, and caches a tool
+ * registry. A fresh MCP server and transport pair is spun up per incoming HTTP
+ * request, following MCP stateless Streamable HTTP mode. This adaptor
+ * intentionally does not manage `Mcp-Session-Id` state.
+ *
+ * Typia-generated JSON Schemas flow through unchanged; the Zod-based high-level
+ * registration API of `McpServer` is bypassed by accessing the low-level
+ * `.server` handler.
+ *
+ * Error mapping follows the MCP specification:
+ *
+ * - Unknown tool name: JSON-RPC `-32601`.
+ * - Typia validation failure: JSON-RPC `-32602` with structured diagnostics.
+ * - Handler throws {@link HttpException}: success response with `isError: true`,
+ *   so the LLM can read the message and recover.
+ * - Any other throw: JSON-RPC `-32603`.
+ *
+ * @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 {
+  /**
+   * Upgrade a running Nest application with a stateless MCP endpoint.
+   *
+   * Scans the application container for methods decorated with {@link McpRoute},
+   * then registers a catch-all HTTP route at the configured path. Each incoming
+   * request builds a fresh MCP server + transport on demand, wires the
+   * registered tools into it, and delegates handling.
+   *
+   * Must be called after `NestFactory.create(...)` but before `app.listen(...)`
+   * if you want the MCP endpoint to be reachable alongside your regular HTTP
+   * routes.
+   *
+   * @param app Running Nest application instance.
+   * @param options Transport and identity overrides.
+   */
+  public static async upgrade(
+    app: INestApplication,
+    options: McpAdaptor.IOptions = {},
+  ): Promise<void> {
+    if ("sessioned" in (options as Record<string, unknown>))
+      throw new Error(
+        "McpAdaptor.upgrade() supports stateless Streamable HTTP only; sessioned mode is not implemented.",
+      );
+
+    const tools: McpAdaptor.ITool[] = [];
+    const container = (app as any).container as NestContainer;
+    for (const module of container.getModules().values()) {
+      for (const wrapper of module.controllers.values()) {
+        const instance = wrapper.instance;
+        if (!instance) continue;
+        const proto = Object.getPrototypeOf(instance);
+        for (const key of Object.getOwnPropertyNames(proto)) {
+          if (key === "constructor") continue;
+          const method = proto[key];
+          if (typeof method !== "function") continue;
+
+          const meta: IMcpRouteReflect | undefined = Reflect.getMetadata(
+            "nestia/McpRoute",
+            method,
+          );
+          if (!meta) continue;
+
+          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),
+          });
+        }
+      }
+    }
+    assertUniqueTools(tools);
+
+    const serverInfo = options.serverInfo ?? {
+      name: "nestia-mcp",
+      version: "1.0.0",
+    };
+    const {
+      CallToolRequestSchema,
+      ErrorCode,
+      ListToolsRequestSchema,
+      McpError,
+      McpServer,
+      StreamableHTTPServerTransport,
+    } = await loadMcpSdk();
+
+    const http = app.getHttpAdapter();
+    const route = options.path ?? "/mcp";
+    http.all(route, async (req: any, res: any) => {
+      // Stateless mode requires a fresh transport per request; sharing one
+      // across clients races on internal initialization and request IDs.
+      const mcp = new McpServer(serverInfo, {
+        capabilities: { tools: {} },
+      });
+      const server = mcp.server;
+
+      server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: tools.map((t) => ({
+          name: t.meta.name,
+          title: t.meta.title,
+          description: t.meta.description,
+          inputSchema: t.meta.inputSchema,
+          outputSchema: t.meta.outputSchema,
+          annotations: t.meta.annotations,
+        })),
+      }));
+
+      server.setRequestHandler(CallToolRequestSchema, async (reqMsg) => {
+        const tool = tools.find((t) => t.meta.name === reqMsg.params.name);
+        if (!tool)
+          throw new McpError(
+            ErrorCode.MethodNotFound,
+            `Tool not found: ${reqMsg.params.name}`,
+          );
+
+        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);
+          if (result === undefined) return { content: [] };
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text:
+                  typeof result === "string" ? result : JSON.stringify(result),
+              },
+            ],
+          };
+        } catch (e) {
+          if (e instanceof HttpException) {
+            return {
+              content: [{ type: "text" as const, text: e.message }],
+              isError: true,
+            };
+          }
+          throw new McpError(
+            ErrorCode.InternalError,
+            e instanceof Error ? e.message : "Internal error",
+          );
+        }
+      });
+
+      const transport = new StreamableHTTPServerTransport({
+        sessionIdGenerator: undefined,
+        enableJsonResponse: true,
+      });
+      try {
+        await mcp.connect(transport);
+        await transport.handleRequest(req.raw ?? req, res.raw ?? res, req.body);
+      } finally {
+        await transport.close().catch(() => {});
+        await mcp.close().catch(() => {});
+      }
+    });
+  }
+}
+
+const assertUniqueTools = (tools: McpAdaptor.ITool[]): void => {
+  const dict: Map<string, McpAdaptor.ITool[]> = new Map();
+  for (const tool of tools) {
+    const array = dict.get(tool.meta.name) ?? [];
+    array.push(tool);
+    dict.set(tool.meta.name, array);
+  }
+  const duplicated = Array.from(dict.entries()).filter(
+    ([, list]) => list.length > 1,
+  );
+  if (duplicated.length === 0) return;
+  throw new Error(
+    [
+      "Duplicated MCP tool names are not allowed.",
+      ...duplicated.map(
+        ([name, list]) =>
+          `  - ${JSON.stringify(name)}: ${list.map((tool) => tool.source).join(", ")}`,
+      ),
+    ].join("\n"),
+  );
+};
+
+const loadMcpSdk = async () => {
+  try {
+    const [server, transport, types] = await Promise.all([
+      import("@modelcontextprotocol/sdk/server/mcp.js"),
+      import("@modelcontextprotocol/sdk/server/streamableHttp.js"),
+      import("@modelcontextprotocol/sdk/types.js"),
+    ]);
+    return {
+      McpServer: server.McpServer,
+      StreamableHTTPServerTransport: transport.StreamableHTTPServerTransport,
+      CallToolRequestSchema: types.CallToolRequestSchema,
+      ErrorCode: types.ErrorCode,
+      ListToolsRequestSchema: types.ListToolsRequestSchema,
+      McpError: types.McpError,
+    };
+  } catch {
+    throw new Error(
+      "McpAdaptor.upgrade() requires @modelcontextprotocol/sdk. Install it before enabling MCP routes.",
+    );
+  }
+};
+
+export namespace McpAdaptor {
+  /** Configuration options for {@link McpAdaptor.upgrade}. */
+  export interface IOptions {
+    /**
+     * HTTP path where the MCP endpoint will be mounted.
+     *
+     * @default "/mcp"
+     */
+    path?: string;
+
+    /**
+     * Identity advertised to MCP clients during the initialize handshake. Shows
+     * up in Claude Desktop / Cursor's MCP panel.
+     *
+     * @default { name: "nestia-mcp", version: "1.0.0" }
+     */
+    serverInfo?: { name: string; version: string };
+  }
+
+  /** @internal */
+  export interface ITool {
+    meta: IMcpRouteReflect;
+    source: string;
+    handler: (args: unknown) => Promise<unknown>;
+    validateArgs?: (input: any) => Error | null;
+  }
+}

package/src/decorators/McpRoute.ts

@@ -0,0 +1,159 @@
+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 (Claude Desktop, Cursor, OpenAI function calling,
+ * etc.) 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 (powered by
+ * typia) and the JSON Schema attached to `inputSchema` in `tools/list`
+ * responses.
+ *
+ * For the MCP endpoint to actually be served, you must 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 do not write this directly; they call `@McpRoute("name")` and the
+   * transformer rewrites the call to `@McpRoute({ name, description, title,
+   * inputSchema, ... })` after parsing the method's 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 (no `Record<string,
+   * X>`, no index signatures); the nestia transformer enforces this through
+   * `LlmSchemaProgrammer.validate`.
+   *
+   * @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,
+      );
+  };
+}

package/src/decorators/internal/IMcpRouteReflect.ts

@@ -0,0 +1,41 @@
+/**
+ * Reflection metadata stored by the {@link McpRoute} decorator.
+ *
+ * Every method decorated with `@McpRoute()` carries an `IMcpRouteReflect`
+ * object under the `"nestia/McpRoute"` key on its function value. The
+ * {@link McpAdaptor} reads these at bootstrap to build the MCP tool registry.
+ *
+ * @author wildduck - https://github.com/wildduck2
+ * @internal
+ */
+export interface IMcpRouteReflect {
+  name: string;
+  title?: string;
+  description?: string;
+  inputSchema: object;
+  outputSchema?: object;
+  annotations?: {
+    readOnlyHint?: boolean;
+    destructiveHint?: boolean;
+    idempotentHint?: boolean;
+    openWorldHint?: boolean;
+  };
+}
+
+export namespace IMcpRouteReflect {
+  /**
+   * Per-parameter reflection entry stored under `"nestia/McpRoute/Parameters"`
+   * on the owning prototype + property key.
+   *
+   * `validate` is the closure returned by `validate_request_body(...)`;
+   * runtime callers receive `null` for valid input or an `Error` for invalid
+   * input.
+   *
+   * @internal
+   */
+  export interface IArgument {
+    category: "params";
+    index: number;
+    validate: (input: any) => Error | null;
+  }
+}

package/src/module.ts

@@ -20,4 +20,6 @@ export * from "./decorators/SwaggerExample";
 
 export * from "./adaptors/WebSocketAdaptor";
 export * from "./decorators/WebSocketRoute";
+export * from "./adaptors/McpAdaptor";
+export * from "./decorators/McpRoute";
 export * from "./decorators/doNotThrowTransformError";

package/src/programmers/McpRouteProgrammer.ts

@@ -0,0 +1,75 @@
+import {
+  LlmParametersProgrammer,
+  MetadataCollection,
+  MetadataFactory,
+  MetadataSchema,
+  TransformerError,
+} from "@typia/core";
+import { ValidationPipe } from "@typia/interface";
+import ts from "typescript";
+
+import { INestiaTransformContext } from "../options/INestiaTransformProject";
+import { check_mcp_object } from "./internal/check_mcp_object";
+
+/**
+ * Compile-time JSON Schema emitter for `@McpRoute.Params<T>()` types.
+ *
+ * Mirrors {@link TypedBodyProgrammer} for runtime validators, but instead of
+ * emitting a `typia.assert` closure it emits a literal JSON Schema object.
+ * The MCP specification requires `inputSchema` to be a single static object
+ * type — no primitives, no unions, no dynamic-key records — so this
+ * programmer rejects anything else with a {@link TransformerError}.
+ *
+ * The emitted shape is `LlmParametersProgrammer`'s parameters block —
+ * `{ type: "object", properties, required, $defs }` — which is exactly what
+ * the MCP `tools/list` response requires for `inputSchema`. Plain
+ * `JsonSchemaProgrammer.write` cannot be used here because it may produce a
+ * top-level `$ref` to a `$defs` entry, which MCP clients reject.
+ *
+ * @author wildduck - https://github.com/wildduck2
+ */
+export namespace McpRouteProgrammer {
+  export const generate = (props: {
+    context: INestiaTransformContext;
+    modulo: ts.LeftHandSideExpression;
+    type: ts.Type;
+  }): ts.Expression => {
+    const result: ValidationPipe<MetadataSchema, MetadataFactory.IError> =
+      MetadataFactory.analyze({
+        checker: props.context.checker,
+        transformer: props.context.transformer,
+        options: {
+          escape: true,
+          constant: true,
+          absorb: true,
+        },
+        components: new MetadataCollection(),
+        type: props.type,
+      });
+    if (result.success === false)
+      throw TransformerError.from({
+        code: "@nestia.core.McpRoute.Params",
+        errors: result.errors,
+      });
+
+    const violations: string[] = check_mcp_object("params")(result.data);
+    if (violations.length)
+      throw new Error(
+        `[@nestia.core.McpRoute.Params] ${violations.join(" ")}`,
+      );
+
+    return LlmParametersProgrammer.write({
+      context: {
+        ...props.context,
+        options: {
+          numeric: false,
+          finite: false,
+          functional: false,
+        },
+      },
+      config: { strict: false },
+      metadata: result.data,
+    });
+  };
+
+}

package/src/programmers/McpRouteReturnProgrammer.ts

@@ -0,0 +1,77 @@
+import {
+  MetadataCollection,
+  MetadataFactory,
+  MetadataSchema,
+  TransformerError,
+} from "@typia/core";
+import { ValidationPipe } from "@typia/interface";
+import ts from "typescript";
+
+import { INestiaTransformContext } from "../options/INestiaTransformProject";
+import { check_mcp_object } from "./internal/check_mcp_object";
+
+/**
+ * Compile-time validator for the return type of an `@McpRoute()` method.
+ *
+ * Mirrors {@link TypedRouteProgrammer} but adapted to MCP's structured-output
+ * rules. The MCP specification requires every tool's output to be a single
+ * object value or nothing at all. To enforce that:
+ *
+ * - `void` returns short-circuit (nothing emitted).
+ * - Object returns are inspected directly on the analyzed metadata to reject
+ *   primitives, unions, and dynamic-key records.
+ * - Mixed unions of `void` and a value type are rejected outright; MCP has no
+ *   way to model "sometimes returns nothing, sometimes returns X".
+ *
+ * @author wildduck - https://github.com/wildduck2
+ */
+export namespace McpRouteReturnProgrammer {
+  export const generate = (props: {
+    context: INestiaTransformContext;
+    modulo: ts.LeftHandSideExpression;
+    type: ts.Type;
+  }): void => {
+    const inner: ts.Type =
+      props.context.checker.getAwaitedType(props.type) ?? props.type;
+    if (inner.isUnion()) {
+      const hasVoid = inner.types.some((t) => isVoidLike(t));
+      const hasValue = inner.types.some((t) => !isVoidLike(t));
+      if (hasVoid && hasValue)
+        throw new Error(
+          "[@nestia.core.McpRoute] tool return type must be either `void` or a single object type. Mixed unions of `void` and an object type are not supported.",
+        );
+    }
+    if (isVoidLike(inner)) return;
+
+    const result: ValidationPipe<MetadataSchema, MetadataFactory.IError> =
+      MetadataFactory.analyze({
+        checker: props.context.checker,
+        transformer: props.context.transformer,
+        options: {
+          escape: true,
+          constant: true,
+          absorb: true,
+        },
+        components: new MetadataCollection(),
+        type: inner,
+      });
+    if (result.success === false)
+      throw TransformerError.from({
+        code: "@nestia.core.McpRoute.Return",
+        errors: result.errors,
+      });
+
+    if (result.data.size() === 0) return;
+    const violations: string[] = check_mcp_object("return")(result.data);
+    if (violations.length)
+      throw new Error(
+        `[@nestia.core.McpRoute.Return] ${violations.join(" ")}`,
+      );
+  };
+
+  const isVoidLike = (t: ts.Type): boolean =>
+    Boolean(
+      t.flags &
+        (ts.TypeFlags.Void | ts.TypeFlags.Undefined | ts.TypeFlags.Never),
+    );
+}

package/src/programmers/internal/check_mcp_object.ts

@@ -0,0 +1,37 @@
+import { MetadataSchema } from "@typia/core";
+
+/**
+ * Shared object-only constraint check for MCP parameter and return schemas.
+ *
+ * MCP requires both `inputSchema` and `outputSchema` (when present) to be a
+ * single, static object type — no primitives, no unions, no dynamic-key
+ * records. Parameter types additionally cannot be empty (a tool must accept
+ * an object); return types may be empty (`void` short-circuited upstream).
+ *
+ * @internal
+ * @author wildduck - https://github.com/wildduck2
+ */
+export const check_mcp_object =
+  (kind: "params" | "return") =>
+  (metadata: MetadataSchema): string[] => {
+    const errors: string[] = [];
+    if (metadata.objects.length === 0)
+      errors.push(
+        kind === "return"
+          ? "MCP tool return type must be an object type or `void`."
+          : "MCP tool parameters must be an object type.",
+      );
+    else if (metadata.objects.length > 1 || metadata.size() > 1)
+      errors.push(
+        `MCP tool ${kind === "return" ? "return type" : "parameters"} must be a single object type.`,
+      );
+    else if (
+      metadata.objects[0]!.type.properties.some(
+        (p) => p.key.isSoleLiteral() === false,
+      )
+    )
+      errors.push(
+        `MCP tool ${kind === "return" ? "return type" : "parameters"} must not declare dynamic keys (Record<string, X>, index signatures).`,
+      );
+    return errors;
+  };