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

package/native/transform/typia_replacement.go

@@ -1,24 +1,24 @@
-package transform
-
-import (
-	"strings"
-
-	shimast "github.com/microsoft/typescript-go/shim/ast"
-	typiaadapter "github.com/samchon/typia/packages/typia/native/adapter"
-)
-
-func parenthesizeTypiaReplacement(
-	site typiaadapter.CallSite,
-	expr string,
-) string {
-	text := strings.TrimSpace(expr)
-	if strings.HasPrefix(text, "{") == false {
-		return expr
-	}
-	node := site.Call.AsNode()
-	if node == nil || node.Parent == nil ||
-		node.Parent.Kind != shimast.KindExpressionStatement {
-		return expr
-	}
-	return "(" + expr + ")"
-}
+package transform
+
+import (
+	"strings"
+
+	shimast "github.com/microsoft/typescript-go/shim/ast"
+	typiaadapter "github.com/samchon/typia/packages/typia/native/adapter"
+)
+
+func parenthesizeTypiaReplacement(
+	site typiaadapter.CallSite,
+	expr string,
+) string {
+	text := strings.TrimSpace(expr)
+	if strings.HasPrefix(text, "{") == false {
+		return expr
+	}
+	node := site.Call.AsNode()
+	if node == nil || node.Parent == nil ||
+		node.Parent.Kind != shimast.KindExpressionStatement {
+		return expr
+	}
+	return "(" + expr + ")"
+}

package/native/transform.cjs

@@ -1,43 +1,43 @@
-const fs = require("node:fs");
-const path = require("node:path");
-
-// `@nestia/core` ttsc plugin descriptor.
-//
-// `source` is the Go command package of the executable transform host
-// (`cmd/ttsc-nestia`, package `main`).
-//
-// `@nestia/sdk` is NOT a standalone ttsc plugin: its Go transform is declared
-// here as a `contributor`, discovered by resolving `@nestia/sdk` from the
-// project. ttsc statically links a contributor's Go source into this host
-// binary. Consequences:
-//
-//   - A project that depends on `@nestia/core` but not `@nestia/sdk` never
-//     links, compiles, or ships any SDK transform code.
-//   - When the `@nestia/core` plugin itself is disabled, this descriptor is
-//     never evaluated, so the SDK contributor is never linked either.
-function createTtscPlugin(context) {
-  const plugin = {
-    name: "@nestia/core",
-    source: path.resolve(__dirname, "cmd", "ttsc-nestia"),
-    composes: ["typia/lib/transform"],
-  };
-  const sdk = resolveSdkContributorSource(context);
-  if (sdk !== null) plugin.contributors = [{ name: "sdk", source: sdk }];
-  return plugin;
-}
-
-function resolveSdkContributorSource(context) {
-  const paths = [__dirname];
-  if (context && typeof context.projectRoot === "string")
-    paths.push(context.projectRoot);
-  try {
-    const manifest = require.resolve("@nestia/sdk/package.json", { paths });
-    const source = path.resolve(path.dirname(manifest), "native", "sdk");
-    return fs.existsSync(source) ? source : null;
-  } catch {
-    return null;
-  }
-}
-
-module.exports = createTtscPlugin;
-module.exports.createTtscPlugin = createTtscPlugin;
+const fs = require("node:fs");
+const path = require("node:path");
+
+// `@nestia/core` ttsc plugin descriptor.
+//
+// `source` is the Go command package of the executable transform host
+// (`cmd/ttsc-nestia`, package `main`).
+//
+// `@nestia/sdk` is NOT a standalone ttsc plugin: its Go transform is declared
+// here as a `contributor`, discovered by resolving `@nestia/sdk` from the
+// project. ttsc statically links a contributor's Go source into this host
+// binary. Consequences:
+//
+//   - A project that depends on `@nestia/core` but not `@nestia/sdk` never
+//     links, compiles, or ships any SDK transform code.
+//   - When the `@nestia/core` plugin itself is disabled, this descriptor is
+//     never evaluated, so the SDK contributor is never linked either.
+function createTtscPlugin(context) {
+  const plugin = {
+    name: "@nestia/core",
+    source: path.resolve(__dirname, "cmd", "ttsc-nestia"),
+    composes: ["typia/lib/transform"],
+  };
+  const sdk = resolveSdkContributorSource(context);
+  if (sdk !== null) plugin.contributors = [{ name: "sdk", source: sdk }];
+  return plugin;
+}
+
+function resolveSdkContributorSource(context) {
+  const paths = [__dirname];
+  if (context && typeof context.projectRoot === "string")
+    paths.push(context.projectRoot);
+  try {
+    const manifest = require.resolve("@nestia/sdk/package.json", { paths });
+    const source = path.resolve(path.dirname(manifest), "native", "sdk");
+    return fs.existsSync(source) ? source : null;
+  } catch {
+    return null;
+  }
+}
+
+module.exports = createTtscPlugin;
+module.exports.createTtscPlugin = createTtscPlugin;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nestia/core",
-  "version": "12.0.0-dev.20260601.1",
+  "version": "12.0.0-dev.20260612.1",
   "description": "Super-fast validation decorators of NestJS",
   "types": "lib/index.d.ts",
   "main": "lib/index.js",
@@ -46,8 +46,8 @@
   },
   "homepage": "https://nestia.io",
   "dependencies": {
-    "@typia/interface": "13.0.0-dev.20260601.1",
-    "@typia/utils": "13.0.0-dev.20260601.1",
+    "@typia/interface": "13.0.0-dev.20260612.1",
+    "@typia/utils": "13.0.0-dev.20260612.1",
     "get-function-location": "^2.0.0",
     "glob": "^11.0.3",
     "path-parser": "^6.1.0",
@@ -55,19 +55,26 @@
     "reflect-metadata": ">=0.1.12",
     "rxjs": ">=6.0.3",
     "tgrid": "^1.1.0",
-    "typia": "13.0.0-dev.20260601.1",
+    "typia": "13.0.0-dev.20260612.1",
     "ws": "^7.5.3",
-    "@nestia/fetcher": "^12.0.0-dev.20260601.1"
+    "@nestia/fetcher": "^12.0.0-dev.20260612.1"
   },
   "peerDependencies": {
+    "@modelcontextprotocol/sdk": "^1.18.0",
     "@nestjs/common": ">=7.0.1",
     "@nestjs/core": ">=7.0.1",
     "reflect-metadata": ">=0.1.12",
     "rxjs": ">=6.0.3",
-    "typia": "13.0.0-dev.20260601.1",
-    "@nestia/fetcher": "^12.0.0-dev.20260601.1"
+    "typia": "13.0.0-dev.20260612.1",
+    "@nestia/fetcher": "^12.0.0-dev.20260612.1"
+  },
+  "peerDependenciesMeta": {
+    "@modelcontextprotocol/sdk": {
+      "optional": true
+    }
   },
   "devDependencies": {
+    "@modelcontextprotocol/sdk": "^1.18.0",
     "@nestjs/common": "^11.1.6",
     "@nestjs/core": "^11.1.6",
     "@nestjs/platform-express": "^11.1.6",
@@ -77,7 +84,7 @@
     "@types/ws": "^8.5.10",
     "fastify": "^4.28.1",
     "rimraf": "^6.1.3",
-    "ttsc": "^0.14.1",
+    "ttsc": "^0.15.3",
     "tstl": "^3.0.0"
   },
   "files": [

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: any) => {
+        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;
+  }
+}