@nestia/sdk 14.0.0 → 14.0.2

package/src/generates/internal/SdkHttpSimulationProgrammer.ts

@@ -23,7 +23,32 @@ import { SdkAliasCollection } from "./SdkAliasCollection";
 import { SdkHttpParameterProgrammer } from "./SdkHttpParameterProgrammer";
 import { SdkImportWizard } from "./SdkImportWizard";
 
+/**
+ * Writes the mockup functions of an HTTP route.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace prints random for the response type and simulate for structural parameter assertions followed by random response creation. Simulation operates on typed SDK arguments rather than parsing HTTP transport values.
+ * @evidence contracts/common.md#clear-and-simple-design Two public functions and their helpers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Generated validation calls typia.assert through NestiaSimulator's error adapter. It does not reproduce arbitrary server pipes or the server transform's prune and equality modes; simulation rejects structural type violations without contacting a server.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+ * efficient algorithms: Response construction has a fixed AST skeleton; request assertion emission visits significant parameters once and allocates one validator expression per parameter. Type and parameter projection costs belong to the called programmers.
+ * reuse equivalent work: These writers construct route-specific mutable AST nodes and coordinate no completed or in-flight generation across requests.
+ * bound retention and release resources: Returned ASTs transfer to the file writer. The emitted binary random function closes its empty stream during construction; the programmer itself retains no stream or producer task.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkHttpSimulationProgrammer composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+ */
 export namespace SdkHttpSimulationProgrammer {
+  /**
+   * Returns `random`: it makes a value of the response, a closed empty stream
+   * for a binary one. Binary readers receive EOF without waiting for payload.
+   *
+   * @evidence contracts/common.md#principled-implementation Ordinary responses call typia.random of the output type. Binary responses construct a stream with the existing binary chunk type and a start callback that closes its own controller synchronously; no bytes are enqueued, so the first read reports EOF under Streams semantics.
+   * @evidence contracts/common.md#clear-and-simple-design The existing binary versus ordinary expression branch owns response generation. Its inline stream source supplies closure without another runtime helper, import or transport.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The binary case has no random content.
+   * @evidence contracts/common.md#meaningful-documentation The prose states that binary random output is closed and readers receive EOF without waiting for payload.
+   * bound retention and release resources: The emitted binary source queues no bytes or producer task and closes each empty stream during construction. The writer returns its AST without retaining stream handles; runtime readers belong to the generated SDK caller.
+   * efficient algorithms: After response-type projection, either branch allocates a fixed AST skeleton; the binary branch emits one empty stream constructor without traversing or generating payload bytes.
+   * reuse equivalent work: The returned AST belongs to this route and importer. Each generated runtime call needs its own random value or stream, so neither mutable syntax nor runtime response identity is shared.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkHttpSimulationProgrammer.random composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const random =
     (project: INestiaProject) =>
     (importer: ImportDictionary) =>
@@ -47,7 +72,34 @@ export namespace SdkHttpSimulationProgrammer {
             ? factory.createNewExpression(
                 factory.createIdentifier("ReadableStream"),
                 [SdkAliasCollection.binaryChunk() as TypeNode],
-                [],
+                [
+                  factory.createObjectLiteralExpression([
+                    factory.createPropertyAssignment(
+                      "start",
+                      factory.createArrowFunction(
+                        undefined,
+                        undefined,
+                        [
+                          factory.createParameterDeclaration(
+                            undefined,
+                            undefined,
+                            "controller",
+                          ),
+                        ],
+                        undefined,
+                        undefined,
+                        factory.createCallExpression(
+                          IdentifierFactory.access(
+                            factory.createIdentifier("controller"),
+                            "close",
+                          ),
+                          undefined,
+                          [],
+                        ),
+                      ),
+                    ),
+                  ]),
+                ],
               )
             : factory.createCallExpression(
                 IdentifierFactory.access(
@@ -61,10 +113,25 @@ export namespace SdkHttpSimulationProgrammer {
       );
     };
 
+  /**
+   * Returns `simulate`: it asserts the parameters and returns a random output,
+   * wrapped as a propagation when configured.
+   *
+   * @evidence contracts/common.md#principled-implementation The status of the wrapper is the declared one or the method's default. A response without a content type has no Content-Type entry; a declared media type supplies a string header, preserving the propagation header contract.
+   * @evidence contracts/common.md#clear-and-simple-design One function.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The parameters are validated before a response is made.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * efficient algorithms: Parameter declarations and assertion nodes grow linearly with significant route parameters; propagation adds a fixed response wrapper and one catch block. The private assertion writer handles the connection headers separately rather than duplicating every parameter validation.
+   * reuse equivalent work: Simulation syntax contains this route's names, arguments, output type and importer aliases; this operation coordinates no reusable result across generation requests.
+   * bound retention and release resources: This function returns an AST to its caller and owns no retained cache, stream, handle or background task; runtime random response creation is documented by random.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkHttpSimulationProgrammer.simulate composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const simulate =
     (project: INestiaProject) =>
     (importer: ImportDictionary) =>
     (route: ITypedHttpRoute): Node => {
+      const names: SdkHttpParameterProgrammer.INames =
+        SdkHttpParameterProgrammer.getNames({ project, route });
       const output: boolean =
         project.config.propagate === true ||
         route.success.binary === true ||
@@ -82,9 +149,9 @@ export namespace SdkHttpSimulationProgrammer {
           [
             IdentifierFactory.parameter(
               SdkHttpParameterProgrammer.getSignificant(route, true).length !==
-                0
-                ? "connection"
-                : "_connection",
+                0 || route.headerObject !== null
+                ? names.connection
+                : `_${names.connection}`,
               factory.createTypeReferenceNode(
                 SdkImportWizard.IConnection(importer),
                 route.headerObject
@@ -104,7 +171,7 @@ export namespace SdkHttpSimulationProgrammer {
           undefined,
           factory.createBlock(
             [
-              ...assert(project)(importer)(route),
+              ...assert(project)(importer)(route)(names),
               factory.createReturnStatement(
                 project.config.propagate
                   ? factory.createAsExpression(
@@ -123,9 +190,11 @@ export namespace SdkHttpSimulationProgrammer {
                           ),
                           factory.createPropertyAssignment(
                             "headers",
-                            LiteralFactory.write({
-                              "Content-Type": route.success.contentType,
-                            }),
+                            LiteralFactory.write(
+                              route.success.contentType === null
+                                ? {}
+                                : { "Content-Type": route.success.contentType },
+                            ),
                           ),
                           factory.createPropertyAssignment("data", caller()),
                         ],
@@ -145,13 +214,14 @@ export namespace SdkHttpSimulationProgrammer {
   const assert =
     (project: INestiaProject) =>
     (importer: ImportDictionary) =>
-    (route: ITypedHttpRoute): Statement[] => {
+    (route: ITypedHttpRoute) =>
+    (names: SdkHttpParameterProgrammer.INames): Statement[] => {
       const parameters = SdkHttpParameterProgrammer.getSignificant(route, true);
-      if (parameters.length === 0) return [];
+      if (parameters.length === 0 && route.headerObject === null) return [];
 
       const typia = SdkImportWizard.typia(importer);
       const validator = StatementFactory.constant({
-        name: "assert",
+        name: names.assert,
         value: factory.createCallExpression(
           IdentifierFactory.access(
             factory.createIdentifier(
@@ -174,7 +244,10 @@ export namespace SdkHttpSimulationProgrammer {
                 ),
                 factory.createPropertyAssignment(
                   "host",
-                  factory.createIdentifier("connection.host"),
+                  IdentifierFactory.access(
+                    factory.createIdentifier(names.connection),
+                    "host",
+                  ),
                 ),
                 factory.createPropertyAssignment(
                   "path",
@@ -205,7 +278,7 @@ export namespace SdkHttpSimulationProgrammer {
           factory.createCallExpression(
             (() => {
               const base = IdentifierFactory.access(
-                factory.createIdentifier("assert"),
+                factory.createIdentifier(names.assert),
                 p.category,
               );
               if (p.category !== "param") return base;
@@ -227,17 +300,48 @@ export namespace SdkHttpSimulationProgrammer {
                     "assert",
                   ),
                   undefined,
-                  [
-                    project.config.keyword === true
-                      ? factory.createIdentifier(`props.${p.name}`)
-                      : factory.createIdentifier(p.name),
-                  ],
+                  [names.access(p)],
                 ),
               ),
             ],
           ),
         )
         .map(factory.createExpressionStatement);
+      // Headers travel in the connection and receive a structural assertion.
+      if (route.headerObject !== null)
+        individual.push(
+          factory.createExpressionStatement(
+            factory.createCallExpression(
+              IdentifierFactory.access(
+                factory.createIdentifier(names.assert),
+                "headers",
+              ),
+              undefined,
+              [
+                factory.createArrowFunction(
+                  undefined,
+                  undefined,
+                  [],
+                  undefined,
+                  undefined,
+                  factory.createCallExpression(
+                    IdentifierFactory.access(
+                      factory.createIdentifier(typia),
+                      "assert",
+                    ),
+                    [factory.createTypeReferenceNode(`${route.name}.Headers`)],
+                    [
+                      IdentifierFactory.access(
+                        factory.createIdentifier(names.connection),
+                        "headers",
+                      ),
+                    ],
+                  ),
+                ),
+              ],
+            ),
+          ),
+        );
       return [
         validator,
         ...(project.config.propagate !== true

package/src/generates/internal/SdkImportWizard.ts

@@ -1,9 +1,36 @@
 import { ImportDictionary } from "./ImportDictionary";
 
+/**
+ * The imports of the SDK's runtime dependencies.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace names each dependency once so every generator registers it the same way.
+ * @evidence contracts/common.md#clear-and-simple-design Six one-call helpers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Each helper registers one fixed import.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkImportWizard composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+ */
 export namespace SdkImportWizard {
+  /**
+   * Returns the import of the fetcher: the encrypted one or the plain one.
+   *
+   * @evidence contracts/common.md#principled-implementation The choice follows the route.
+   * @evidence contracts/common.md#clear-and-simple-design One conditional.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It returns the registering function.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkImportWizard.Fetcher composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const Fetcher = (encrypted: boolean) =>
     encrypted ? EncryptedFetcher : PlainFetcher;
 
+  /**
+   * Registers `HttpError` of `@nestia/fetcher`.
+   *
+   * @evidence contracts/common.md#principled-implementation It is a type import.
+   * @evidence contracts/common.md#clear-and-simple-design One call.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The import is fixed.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkImportWizard.HttpError composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const HttpError = (importer: ImportDictionary) =>
     importer.external({
       declaration: true,
@@ -12,6 +39,15 @@ export namespace SdkImportWizard {
       name: "HttpError",
     });
 
+  /**
+   * Registers `IConnection` of `@nestia/fetcher`.
+   *
+   * @evidence contracts/common.md#principled-implementation It is a type import.
+   * @evidence contracts/common.md#clear-and-simple-design One call.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The import is fixed.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkImportWizard.IConnection composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const IConnection = (importer: ImportDictionary) =>
     importer.external({
       declaration: true,
@@ -20,6 +56,15 @@ export namespace SdkImportWizard {
       name: "IConnection",
     });
 
+  /**
+   * Registers `Primitive` of `typia`.
+   *
+   * @evidence contracts/common.md#principled-implementation It is a type import.
+   * @evidence contracts/common.md#clear-and-simple-design One call.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The import is fixed.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkImportWizard.Primitive composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const Primitive = (importer: ImportDictionary) =>
     importer.external({
       declaration: true,
@@ -28,6 +73,15 @@ export namespace SdkImportWizard {
       name: "Primitive",
     });
 
+  /**
+   * Registers `Resolved` of `typia`.
+   *
+   * @evidence contracts/common.md#principled-implementation It is a type import.
+   * @evidence contracts/common.md#clear-and-simple-design One call.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The import is fixed.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkImportWizard.Resolved composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const Resolved = (importer: ImportDictionary) =>
     importer.external({
       declaration: true,
@@ -36,6 +90,15 @@ export namespace SdkImportWizard {
       name: "Resolved",
     });
 
+  /**
+   * Registers the default import of `typia`.
+   *
+   * @evidence contracts/common.md#principled-implementation It is a value import.
+   * @evidence contracts/common.md#clear-and-simple-design One call.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The import is fixed.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkImportWizard.typia composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const typia = (importer: ImportDictionary) =>
     importer.external({
       declaration: false,

package/src/generates/internal/SdkMcpRouteProgrammer.ts

@@ -12,18 +12,35 @@ import {
 import { IdentifierFactory } from "../../factories/IdentifierFactory";
 import { INestiaProject } from "../../structures/INestiaProject";
 import { ITypedMcpRoute } from "../../structures/ITypedMcpRoute";
+import { StringUtil } from "../../utils/StringUtil";
 import { FilePrinter } from "./FilePrinter";
 import { ImportDictionary } from "./ImportDictionary";
+import { SdkTypeProgrammer } from "./SdkTypeProgrammer";
 
 /**
  * Emits a typed client wrapper for an MCP tool.
  *
- * Object output types are wrapped in `Primitive<T>` because MCP round-trips
- * values through JSON. Void MCP tools return `Promise<void>`.
+ * Cloned input and output declarations use the native JSON wire graph.
+ * Source-reference output types use `Primitive<T>` for the same JSON
+ * round-trip. Void MCP tools return `Promise<void>`.
  *
  * @author wildduck - https://github.com/wildduck2
+ * @evidence contracts/common.md#principled-implementation The namespace prints the wrapper that calls the tool and its metadata, and turns a tool error into an exception.
+ * @evidence contracts/common.md#clear-and-simple-design One public function and the writers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The function's identifiers yield to the tool's own name.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkMcpRouteProgrammer composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
  */
 export namespace SdkMcpRouteProgrammer {
+  /**
+   * Returns the function and the namespace of an MCP tool.
+   *
+   * @evidence contracts/common.md#principled-implementation The two nodes are composed together so they share names.
+   * @evidence contracts/common.md#clear-and-simple-design One function.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The shape follows the tool metadata.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkMcpRouteProgrammer.write composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const write =
     (project: INestiaProject) =>
     (importer: ImportDictionary) =>
@@ -39,6 +56,16 @@ export namespace SdkMcpRouteProgrammer {
     (_project: INestiaProject) =>
     (importer: ImportDictionary) =>
     (route: ITypedMcpRoute): Node => {
+      // The body reads `<route>.METADATA` next to these, so they yield to a
+      // tool of the same name, as the HTTP and WebSocket SDKs' own do.
+      const own = StringUtil.escapeDuplicate([route.name]);
+      const names = {
+        client: own("client"),
+        args: own("args"),
+        raw: own("raw"),
+        result: own("result"),
+        first: own("first"),
+      };
       const clientType = factory.createTypeReferenceNode(
         importer.external({
           declaration: true,
@@ -56,7 +83,7 @@ export namespace SdkMcpRouteProgrammer {
         alias: "McpCallToolResult",
       });
       const isVoid = isVoidReturn(route);
-      if (!isVoid)
+      if (!isVoid && _project.config.clone !== true)
         importer.external({
           declaration: true,
           file: "typia",
@@ -75,7 +102,7 @@ export namespace SdkMcpRouteProgrammer {
         factory.createParameterDeclaration(
           undefined,
           undefined,
-          "client",
+          names.client,
           undefined,
           clientType,
           undefined,
@@ -86,7 +113,7 @@ export namespace SdkMcpRouteProgrammer {
           factory.createParameterDeclaration(
             undefined,
             undefined,
-            "args",
+            names.args,
             undefined,
             inputRef,
             undefined,
@@ -110,7 +137,7 @@ export namespace SdkMcpRouteProgrammer {
             "arguments",
             factory.createAsExpression(
               factory.createAsExpression(
-                factory.createIdentifier("args"),
+                factory.createIdentifier(names.args),
                 factory.createKeywordTypeNode(SyntaxKind.AnyKeyword),
               ),
               factory.createTypeReferenceNode("Record", [
@@ -128,13 +155,13 @@ export namespace SdkMcpRouteProgrammer {
             factory.createVariableDeclarationList(
               [
                 factory.createVariableDeclaration(
-                  "raw",
+                  names.raw,
                   undefined,
                   undefined,
                   factory.createAwaitExpression(
                     factory.createCallExpression(
                       factory.createPropertyAccessExpression(
-                        factory.createIdentifier("client"),
+                        factory.createIdentifier(names.client),
                         "callTool",
                       ),
                       undefined,
@@ -165,7 +192,7 @@ export namespace SdkMcpRouteProgrammer {
               ),
               undefined,
               [
-                factory.createIdentifier("raw"),
+                factory.createIdentifier(names.raw),
                 factory.createStringLiteral("toolResult"),
               ],
             ),
@@ -179,11 +206,11 @@ export namespace SdkMcpRouteProgrammer {
             factory.createVariableDeclarationList(
               [
                 factory.createVariableDeclaration(
-                  "result",
+                  names.result,
                   undefined,
                   factory.createTypeReferenceNode(callToolResultTypeName),
                   factory.createAsExpression(
-                    factory.createIdentifier("raw"),
+                    factory.createIdentifier(names.raw),
                     factory.createTypeReferenceNode(callToolResultTypeName),
                   ),
                 ),
@@ -194,13 +221,13 @@ export namespace SdkMcpRouteProgrammer {
           factory.createIfStatement(
             factory.createBinaryExpression(
               factory.createPropertyAccessExpression(
-                factory.createIdentifier("result"),
+                factory.createIdentifier(names.result),
                 "isError",
               ),
               factory.createToken(SyntaxKind.EqualsEqualsEqualsToken),
               factory.createTrue(),
             ),
-            throwToolError(toolNameExpr, '" returned isError'),
+            throwToolErrorWithText(toolNameExpr, names.result),
           ),
           ...(isVoid
             ? [factory.createReturnStatement()]
@@ -210,13 +237,13 @@ export namespace SdkMcpRouteProgrammer {
                   factory.createVariableDeclarationList(
                     [
                       factory.createVariableDeclaration(
-                        "first",
+                        names.first,
                         undefined,
                         undefined,
                         factory.createCallExpression(
                           factory.createPropertyAccessExpression(
                             factory.createPropertyAccessExpression(
-                              factory.createIdentifier("result"),
+                              factory.createIdentifier(names.result),
                               "content",
                             ),
                             "find",
@@ -249,7 +276,7 @@ export namespace SdkMcpRouteProgrammer {
                 ),
                 factory.createIfStatement(
                   factory.createBinaryExpression(
-                    factory.createIdentifier("first"),
+                    factory.createIdentifier(names.first),
                     factory.createToken(SyntaxKind.EqualsEqualsEqualsToken),
                     factory.createIdentifier("undefined"),
                   ),
@@ -258,7 +285,7 @@ export namespace SdkMcpRouteProgrammer {
                 factory.createIfStatement(
                   factory.createBinaryExpression(
                     factory.createPropertyAccessExpression(
-                      factory.createIdentifier("first"),
+                      factory.createIdentifier(names.first),
                       "type",
                     ),
                     factory.createToken(SyntaxKind.EqualsEqualsEqualsToken),
@@ -274,7 +301,7 @@ export namespace SdkMcpRouteProgrammer {
                         undefined,
                         [
                           factory.createPropertyAccessExpression(
-                            factory.createIdentifier("first"),
+                            factory.createIdentifier(names.first),
                             "text",
                           ),
                         ],
@@ -304,7 +331,7 @@ export namespace SdkMcpRouteProgrammer {
     };
 
   const writeNamespace =
-    (_project: INestiaProject) =>
+    (project: INestiaProject) =>
     (importer: ImportDictionary) =>
     (route: ITypedMcpRoute): Node => {
       const statements: Statement[] = [];
@@ -315,25 +342,29 @@ export namespace SdkMcpRouteProgrammer {
             [factory.createModifier(SyntaxKind.ExportKeyword)],
             "Input",
             undefined,
-            factory.createTypeReferenceNode(route.input.type.name),
+            project.config.clone === true && route.inputMetadata
+              ? SdkTypeProgrammer.write(project)(importer)(route.inputMetadata)
+              : factory.createTypeReferenceNode(route.input.type.name),
           ),
         );
 
       const outputType: Node =
         !isVoidReturn(route) && route.returnType !== null
-          ? factory.createTypeReferenceNode(
-              importer.external({
-                declaration: true,
-                file: "typia",
-                type: "element",
-                name: "Primitive",
-              }),
-              [
-                factory.createTypeReferenceNode(
-                  unwrapPromise(route.returnType.name),
-                ),
-              ],
-            )
+          ? project.config.clone === true && route.outputMetadata
+            ? SdkTypeProgrammer.write(project)(importer)(route.outputMetadata)
+            : factory.createTypeReferenceNode(
+                importer.external({
+                  declaration: true,
+                  file: "typia",
+                  type: "element",
+                  name: "Primitive",
+                }),
+                [
+                  factory.createTypeReferenceNode(
+                    unwrapPromise(route.returnType.name),
+                  ),
+                ],
+              )
           : factory.createKeywordTypeNode(SyntaxKind.VoidKeyword);
       statements.push(
         factory.createTypeAliasDeclaration(
@@ -423,6 +454,92 @@ export namespace SdkMcpRouteProgrammer {
   const isVoidName = (name: string): boolean =>
     name === "void" || name === "undefined";
 
+  /**
+   * The error of a tool that answered `isError`, carrying the text content the
+   * tool put its reason in, as `McpAdaptor` does an `HttpException`'s message.
+   */
+  const throwToolErrorWithText = (
+    toolNameExpr: Expression,
+    result: string,
+  ): Statement => {
+    const entry = (): Expression => factory.createIdentifier("entry");
+    return factory.createThrowStatement(
+      factory.createNewExpression(
+        factory.createIdentifier("Error"),
+        undefined,
+        [
+          factory.createTemplateExpression(
+            factory.createTemplateHead('MCP tool "'),
+            [
+              factory.createTemplateSpan(
+                toolNameExpr,
+                factory.createTemplateMiddle('" returned isError: '),
+              ),
+              factory.createTemplateSpan(
+                factory.createCallExpression(
+                  factory.createPropertyAccessExpression(
+                    factory.createCallExpression(
+                      factory.createPropertyAccessExpression(
+                        factory.createCallExpression(
+                          factory.createPropertyAccessExpression(
+                            factory.createPropertyAccessExpression(
+                              factory.createIdentifier(result),
+                              "content",
+                            ),
+                            "filter",
+                          ),
+                          undefined,
+                          [
+                            factory.createArrowFunction(
+                              undefined,
+                              undefined,
+                              [IdentifierFactory.parameter("entry")],
+                              undefined,
+                              undefined,
+                              factory.createBinaryExpression(
+                                factory.createPropertyAccessExpression(
+                                  entry(),
+                                  "type",
+                                ),
+                                factory.createToken(
+                                  SyntaxKind.EqualsEqualsEqualsToken,
+                                ),
+                                factory.createStringLiteral("text"),
+                              ),
+                            ),
+                          ],
+                        ),
+                        "map",
+                      ),
+                      undefined,
+                      [
+                        factory.createArrowFunction(
+                          undefined,
+                          undefined,
+                          [IdentifierFactory.parameter("entry")],
+                          undefined,
+                          undefined,
+                          factory.createPropertyAccessExpression(
+                            entry(),
+                            "text",
+                          ),
+                        ),
+                      ],
+                    ),
+                    "join",
+                  ),
+                  undefined,
+                  [factory.createStringLiteral("\n")],
+                ),
+                factory.createTemplateTail(""),
+              ),
+            ],
+          ),
+        ],
+      ),
+    );
+  };
+
   const throwToolError = (
     toolNameExpr: Expression,
     suffix: string,