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

package/src/generates/internal/SdkImportWizard.ts

@@ -1,62 +1,62 @@
-import { ImportDictionary } from "./ImportDictionary";
-
-export namespace SdkImportWizard {
-  export const Fetcher = (encrypted: boolean) =>
-    encrypted ? EncryptedFetcher : PlainFetcher;
-
-  export const HttpError = (importer: ImportDictionary) =>
-    importer.external({
-      declaration: true,
-      file: "@nestia/fetcher",
-      type: "element",
-      name: "HttpError",
-    });
-
-  export const IConnection = (importer: ImportDictionary) =>
-    importer.external({
-      declaration: true,
-      file: "@nestia/fetcher",
-      type: "element",
-      name: "IConnection",
-    });
-
-  export const Primitive = (importer: ImportDictionary) =>
-    importer.external({
-      declaration: true,
-      file: "typia",
-      type: "element",
-      name: "Primitive",
-    });
-
-  export const Resolved = (importer: ImportDictionary) =>
-    importer.external({
-      declaration: true,
-      file: "typia",
-      type: "element",
-      name: "Resolved",
-    });
-
-  export const typia = (importer: ImportDictionary) =>
-    importer.external({
-      declaration: false,
-      file: "typia",
-      type: "default",
-      name: "typia",
-    });
-}
-
-const PlainFetcher = (importer: ImportDictionary) =>
-  importer.external({
-    declaration: false,
-    file: "@nestia/fetcher",
-    type: "element",
-    name: "PlainFetcher",
-  });
-
-const EncryptedFetcher = (importer: ImportDictionary) =>
-  importer.external({
-    declaration: false,
-    file: "@nestia/fetcher/lib/EncryptedFetcher",
-    type: "element",
-    name: "EncryptedFetcher",
-  });
+import { ImportDictionary } from "./ImportDictionary";
+
+export namespace SdkImportWizard {
+  export const Fetcher = (encrypted: boolean) =>
+    encrypted ? EncryptedFetcher : PlainFetcher;
+
+  export const HttpError = (importer: ImportDictionary) =>
+    importer.external({
+      declaration: true,
+      file: "@nestia/fetcher",
+      type: "element",
+      name: "HttpError",
+    });
+
+  export const IConnection = (importer: ImportDictionary) =>
+    importer.external({
+      declaration: true,
+      file: "@nestia/fetcher",
+      type: "element",
+      name: "IConnection",
+    });
+
+  export const Primitive = (importer: ImportDictionary) =>
+    importer.external({
+      declaration: true,
+      file: "typia",
+      type: "element",
+      name: "Primitive",
+    });
+
+  export const Resolved = (importer: ImportDictionary) =>
+    importer.external({
+      declaration: true,
+      file: "typia",
+      type: "element",
+      name: "Resolved",
+    });
+
+  export const typia = (importer: ImportDictionary) =>
+    importer.external({
+      declaration: false,
+      file: "typia",
+      type: "default",
+      name: "typia",
+    });
+}
+
+const PlainFetcher = (importer: ImportDictionary) =>
+  importer.external({
+    declaration: false,
+    file: "@nestia/fetcher",
+    type: "element",
+    name: "PlainFetcher",
+  });
+
+const EncryptedFetcher = (importer: ImportDictionary) =>
+  importer.external({
+    declaration: false,
+    file: "@nestia/fetcher/lib/EncryptedFetcher",
+    type: "element",
+    name: "EncryptedFetcher",
+  });

package/src/generates/internal/SdkMcpRouteProgrammer.ts

@@ -0,0 +1,447 @@
+import {
+  type Expression,
+  type Node,
+  NodeFlags,
+  type ObjectLiteralElement,
+  type ParameterDeclaration,
+  type Statement,
+  SyntaxKind,
+  factory,
+} from "@ttsc/factory";
+
+import { IdentifierFactory } from "../../factories/IdentifierFactory";
+import { INestiaProject } from "../../structures/INestiaProject";
+import { ITypedMcpRoute } from "../../structures/ITypedMcpRoute";
+import { FilePrinter } from "./FilePrinter";
+import { ImportDictionary } from "./ImportDictionary";
+
+/**
+ * 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>`.
+ *
+ * @author wildduck - https://github.com/wildduck2
+ */
+export namespace SdkMcpRouteProgrammer {
+  export const write =
+    (project: INestiaProject) =>
+    (importer: ImportDictionary) =>
+    (route: ITypedMcpRoute): Node[] => [
+      FilePrinter.description(
+        writeFunction(project)(importer)(route),
+        writeDescription(route),
+      ),
+      writeNamespace(project)(importer)(route),
+    ];
+
+  const writeFunction =
+    (_project: INestiaProject) =>
+    (importer: ImportDictionary) =>
+    (route: ITypedMcpRoute): Node => {
+      const clientType = factory.createTypeReferenceNode(
+        importer.external({
+          declaration: true,
+          file: "@modelcontextprotocol/sdk/client/index.js",
+          type: "element",
+          name: "Client",
+          alias: "McpClient",
+        }),
+      );
+      const callToolResultTypeName = importer.external({
+        declaration: true,
+        file: "@modelcontextprotocol/sdk/types.js",
+        type: "element",
+        name: "CallToolResult",
+        alias: "McpCallToolResult",
+      });
+      const isVoid = isVoidReturn(route);
+      if (!isVoid)
+        importer.external({
+          declaration: true,
+          file: "typia",
+          type: "element",
+          name: "Primitive",
+        });
+
+      const inputRef: Node = route.input
+        ? factory.createTypeReferenceNode(`${route.name}.Input`)
+        : factory.createTypeLiteralNode([]);
+      const outputRef: Node = factory.createTypeReferenceNode(
+        `${route.name}.Output`,
+      );
+
+      const params: ParameterDeclaration[] = [
+        factory.createParameterDeclaration(
+          undefined,
+          undefined,
+          "client",
+          undefined,
+          clientType,
+          undefined,
+        ),
+      ];
+      if (route.input)
+        params.push(
+          factory.createParameterDeclaration(
+            undefined,
+            undefined,
+            "args",
+            undefined,
+            inputRef,
+            undefined,
+          ),
+        );
+
+      const toolNameExpr = factory.createPropertyAccessExpression(
+        factory.createPropertyAccessExpression(
+          factory.createIdentifier(route.name),
+          "METADATA",
+        ),
+        "tool",
+      );
+
+      const callToolParams: ObjectLiteralElement[] = [
+        factory.createPropertyAssignment("name", toolNameExpr),
+      ];
+      if (route.input)
+        callToolParams.push(
+          factory.createPropertyAssignment(
+            "arguments",
+            factory.createAsExpression(
+              factory.createAsExpression(
+                factory.createIdentifier("args"),
+                factory.createKeywordTypeNode(SyntaxKind.AnyKeyword),
+              ),
+              factory.createTypeReferenceNode("Record", [
+                factory.createKeywordTypeNode(SyntaxKind.StringKeyword),
+                factory.createKeywordTypeNode(SyntaxKind.AnyKeyword),
+              ]),
+            ),
+          ),
+        );
+
+      const body = factory.createBlock(
+        [
+          factory.createVariableStatement(
+            undefined,
+            factory.createVariableDeclarationList(
+              [
+                factory.createVariableDeclaration(
+                  "raw",
+                  undefined,
+                  undefined,
+                  factory.createAwaitExpression(
+                    factory.createCallExpression(
+                      factory.createPropertyAccessExpression(
+                        factory.createIdentifier("client"),
+                        "callTool",
+                      ),
+                      undefined,
+                      [
+                        factory.createObjectLiteralExpression(
+                          callToolParams,
+                          true,
+                        ),
+                      ],
+                    ),
+                  ),
+                ),
+              ],
+              NodeFlags.Const,
+            ),
+          ),
+          factory.createIfStatement(
+            factory.createCallExpression(
+              factory.createPropertyAccessExpression(
+                factory.createPropertyAccessExpression(
+                  factory.createPropertyAccessExpression(
+                    factory.createIdentifier("Object"),
+                    "prototype",
+                  ),
+                  "hasOwnProperty",
+                ),
+                "call",
+              ),
+              undefined,
+              [
+                factory.createIdentifier("raw"),
+                factory.createStringLiteral("toolResult"),
+              ],
+            ),
+            throwToolError(
+              toolNameExpr,
+              '" returned a legacy (pre-2024-11-05) compatibility result',
+            ),
+          ),
+          factory.createVariableStatement(
+            undefined,
+            factory.createVariableDeclarationList(
+              [
+                factory.createVariableDeclaration(
+                  "result",
+                  undefined,
+                  factory.createTypeReferenceNode(callToolResultTypeName),
+                  factory.createAsExpression(
+                    factory.createIdentifier("raw"),
+                    factory.createTypeReferenceNode(callToolResultTypeName),
+                  ),
+                ),
+              ],
+              NodeFlags.Const,
+            ),
+          ),
+          factory.createIfStatement(
+            factory.createBinaryExpression(
+              factory.createPropertyAccessExpression(
+                factory.createIdentifier("result"),
+                "isError",
+              ),
+              factory.createToken(SyntaxKind.EqualsEqualsEqualsToken),
+              factory.createTrue(),
+            ),
+            throwToolError(toolNameExpr, '" returned isError'),
+          ),
+          ...(isVoid
+            ? [factory.createReturnStatement()]
+            : [
+                factory.createVariableStatement(
+                  undefined,
+                  factory.createVariableDeclarationList(
+                    [
+                      factory.createVariableDeclaration(
+                        "first",
+                        undefined,
+                        undefined,
+                        factory.createCallExpression(
+                          factory.createPropertyAccessExpression(
+                            factory.createPropertyAccessExpression(
+                              factory.createIdentifier("result"),
+                              "content",
+                            ),
+                            "find",
+                          ),
+                          undefined,
+                          [
+                            factory.createArrowFunction(
+                              undefined,
+                              undefined,
+                              [IdentifierFactory.parameter("entry")],
+                              undefined,
+                              undefined,
+                              factory.createBinaryExpression(
+                                factory.createPropertyAccessExpression(
+                                  factory.createIdentifier("entry"),
+                                  "type",
+                                ),
+                                factory.createToken(
+                                  SyntaxKind.EqualsEqualsEqualsToken,
+                                ),
+                                factory.createStringLiteral("text"),
+                              ),
+                            ),
+                          ],
+                        ),
+                      ),
+                    ],
+                    NodeFlags.Const,
+                  ),
+                ),
+                factory.createIfStatement(
+                  factory.createBinaryExpression(
+                    factory.createIdentifier("first"),
+                    factory.createToken(SyntaxKind.EqualsEqualsEqualsToken),
+                    factory.createIdentifier("undefined"),
+                  ),
+                  throwToolError(toolNameExpr, '" returned no text content'),
+                ),
+                factory.createIfStatement(
+                  factory.createBinaryExpression(
+                    factory.createPropertyAccessExpression(
+                      factory.createIdentifier("first"),
+                      "type",
+                    ),
+                    factory.createToken(SyntaxKind.EqualsEqualsEqualsToken),
+                    factory.createStringLiteral("text"),
+                  ),
+                  factory.createReturnStatement(
+                    factory.createAsExpression(
+                      factory.createCallExpression(
+                        factory.createPropertyAccessExpression(
+                          factory.createIdentifier("JSON"),
+                          "parse",
+                        ),
+                        undefined,
+                        [
+                          factory.createPropertyAccessExpression(
+                            factory.createIdentifier("first"),
+                            "text",
+                          ),
+                        ],
+                      ),
+                      outputRef,
+                    ),
+                  ),
+                ),
+                throwToolError(toolNameExpr, '" returned no text content'),
+              ]),
+        ],
+        true,
+      );
+
+      return factory.createFunctionDeclaration(
+        [
+          factory.createModifier(SyntaxKind.ExportKeyword),
+          factory.createModifier(SyntaxKind.AsyncKeyword),
+        ],
+        undefined,
+        route.name,
+        undefined,
+        params,
+        factory.createTypeReferenceNode("Promise", [outputRef]),
+        body,
+      );
+    };
+
+  const writeNamespace =
+    (_project: INestiaProject) =>
+    (importer: ImportDictionary) =>
+    (route: ITypedMcpRoute): Node => {
+      const statements: Statement[] = [];
+
+      if (route.input)
+        statements.push(
+          factory.createTypeAliasDeclaration(
+            [factory.createModifier(SyntaxKind.ExportKeyword)],
+            "Input",
+            undefined,
+            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),
+                ),
+              ],
+            )
+          : factory.createKeywordTypeNode(SyntaxKind.VoidKeyword);
+      statements.push(
+        factory.createTypeAliasDeclaration(
+          [factory.createModifier(SyntaxKind.ExportKeyword)],
+          "Output",
+          undefined,
+          outputType,
+        ),
+      );
+
+      statements.push(
+        factory.createVariableStatement(
+          [factory.createModifier(SyntaxKind.ExportKeyword)],
+          factory.createVariableDeclarationList(
+            [
+              factory.createVariableDeclaration(
+                "METADATA",
+                undefined,
+                undefined,
+                factory.createAsExpression(
+                  factory.createObjectLiteralExpression(
+                    [
+                      factory.createPropertyAssignment(
+                        "protocol",
+                        factory.createStringLiteral("mcp"),
+                      ),
+                      factory.createPropertyAssignment(
+                        "tool",
+                        factory.createStringLiteral(route.toolName),
+                      ),
+                      factory.createPropertyAssignment(
+                        "title",
+                        route.title === null
+                          ? factory.createNull()
+                          : factory.createStringLiteral(route.title),
+                      ),
+                      factory.createPropertyAssignment(
+                        "description",
+                        route.toolDescription === null
+                          ? factory.createNull()
+                          : factory.createStringLiteral(route.toolDescription),
+                      ),
+                    ],
+                    true,
+                  ),
+                  factory.createTypeReferenceNode("const"),
+                ),
+              ),
+            ],
+            NodeFlags.Const,
+          ),
+        ),
+      );
+
+      return factory.createModuleDeclaration(
+        [factory.createModifier(SyntaxKind.ExportKeyword)],
+        factory.createIdentifier(route.name),
+        factory.createModuleBlock(statements),
+        NodeFlags.Namespace,
+      );
+    };
+
+  const writeDescription = (route: ITypedMcpRoute): string => {
+    const lines: string[] = [];
+    if (route.toolDescription) lines.push(...route.toolDescription.split("\n"));
+    else if (route.description) lines.push(...route.description.split("\n"));
+    if (lines.length) lines.push("");
+    lines.push(
+      `@controller ${route.controller.class.name}.${route.function.name || route.name}`,
+      `@tool ${route.toolName}`,
+      `@accessor ${["api", "functional", ...route.accessor].join(".")}`,
+      `@protocol mcp`,
+      `@nestia Generated by Nestia - https://github.com/samchon/nestia`,
+    );
+    return lines.join("\n");
+  };
+
+  const unwrapPromise = (name: string): string => {
+    const m = /^Promise<(.+)>$/.exec(name);
+    return m ? m[1]! : name;
+  };
+
+  const isVoidReturn = (route: ITypedMcpRoute): boolean =>
+    route.returnType === null ||
+    isVoidName(unwrapPromise(route.returnType.name));
+
+  const isVoidName = (name: string): boolean =>
+    name === "void" || name === "undefined";
+
+  const throwToolError = (
+    toolNameExpr: Expression,
+    suffix: string,
+  ): Statement =>
+    factory.createThrowStatement(
+      factory.createNewExpression(
+        factory.createIdentifier("Error"),
+        undefined,
+        [
+          factory.createTemplateExpression(
+            factory.createTemplateHead('MCP tool "'),
+            [
+              factory.createTemplateSpan(
+                toolNameExpr,
+                factory.createTemplateTail(suffix),
+              ),
+            ],
+          ),
+        ],
+      ),
+    );
+}

package/src/generates/internal/SdkRouteDirectory.ts

@@ -1,18 +1,21 @@
-import { ITypedHttpRoute } from "../../structures/ITypedHttpRoute";
-import { ITypedWebSocketRoute } from "../../structures/ITypedWebSocketRoute";
-
-export class SdkRouteDirectory {
-  public readonly module: string;
-  public readonly children: Map<string, SdkRouteDirectory>;
-  public readonly routes: Array<ITypedHttpRoute | ITypedWebSocketRoute>;
-
-  public constructor(
-    readonly parent: SdkRouteDirectory | null,
-    readonly name: string,
-  ) {
-    this.children = new Map();
-    this.routes = [];
-    this.module =
-      this.parent !== null ? `${this.parent.module}.${name}` : `api.${name}`;
-  }
-}
+import { ITypedHttpRoute } from "../../structures/ITypedHttpRoute";
+import { ITypedMcpRoute } from "../../structures/ITypedMcpRoute";
+import { ITypedWebSocketRoute } from "../../structures/ITypedWebSocketRoute";
+
+export class SdkRouteDirectory {
+  public readonly module: string;
+  public readonly children: Map<string, SdkRouteDirectory>;
+  public readonly routes: Array<
+    ITypedHttpRoute | ITypedWebSocketRoute | ITypedMcpRoute
+  >;
+
+  public constructor(
+    readonly parent: SdkRouteDirectory | null,
+    readonly name: string,
+  ) {
+    this.children = new Map();
+    this.routes = [];
+    this.module =
+      this.parent !== null ? `${this.parent.module}.${name}` : `api.${name}`;
+  }
+}