@nestia/sdk 11.2.1 → 11.3.0

package/src/analyses/ReflectMcpOperationAnalyzer.ts

@@ -0,0 +1,124 @@
+import { INestiaProject } from "../structures/INestiaProject";
+import { IReflectController } from "../structures/IReflectController";
+import { IReflectImport } from "../structures/IReflectImport";
+import { IReflectMcpOperation } from "../structures/IReflectMcpOperation";
+import { IReflectMcpOperationParameter } from "../structures/IReflectMcpOperationParameter";
+import { IOperationMetadata } from "../transformers/IOperationMetadata";
+import { ImportAnalyzer } from "./ImportAnalyzer";
+
+/**
+ * Reflects controller methods carrying `"nestia/McpRoute"` metadata into
+ * {@link IReflectMcpOperation} structures consumed by the SDK generator.
+ *
+ * @author wildduck - https://github.com/wildduck2
+ */
+export namespace ReflectMcpOperationAnalyzer {
+  export interface IProps {
+    project: Omit<INestiaProject, "config">;
+    controller: IReflectController;
+    function: Function;
+    name: string;
+    metadata: IOperationMetadata;
+  }
+
+  export const analyze = (ctx: IProps): IReflectMcpOperation | null => {
+    const route:
+      | {
+          name: string;
+          title?: string;
+          description?: string;
+          inputSchema: object;
+          outputSchema?: object;
+          annotations?: IReflectMcpOperation.IAnnotations;
+        }
+      | undefined = Reflect.getMetadata("nestia/McpRoute", ctx.function);
+    if (route === undefined) return null;
+
+    const errors: string[] = [];
+
+    const preconfigured: IReflectMcpOperationParameter.IPreconfigured[] = (
+      (Reflect.getMetadata(
+        "nestia/McpRoute/Parameters",
+        ctx.controller.class.prototype,
+        ctx.name,
+      ) ?? []) as IReflectMcpOperationParameter.IPreconfigured[]
+    ).sort((a, b) => a.index - b.index);
+
+    if (preconfigured.length !== 1)
+      errors.push(
+        "@McpRoute tools must declare exactly one @McpRoute.Params() parameter.",
+      );
+    if (ctx.metadata.parameters.length !== 1)
+      errors.push(
+        "@McpRoute tools must have exactly one parameter (the MCP arguments object).",
+      );
+    else if (preconfigured[0]?.index !== 0)
+      errors.push(
+        "@McpRoute tools must decorate their only parameter with @McpRoute.Params().",
+      );
+
+    const imports: IReflectImport[] = [];
+    const parameters: IReflectMcpOperationParameter[] = preconfigured
+      .map((p) => {
+        const matched: IOperationMetadata.IParameter | undefined =
+          ctx.metadata.parameters.find((m) => p.index === m.index);
+        if (matched === undefined) {
+          errors.push(
+            `Unable to find parameter type of the ${p.index} (th) argument.`,
+          );
+          return null;
+        }
+        if (matched.type === null) {
+          errors.push(
+            `Failed to analyze the parameter type of ${JSON.stringify(matched.name)}.`,
+          );
+          return null;
+        }
+        imports.push(...matched.imports);
+        return {
+          category: "params" as const,
+          name: matched.name,
+          index: p.index,
+          type: matched.type,
+          imports: matched.imports,
+          description: matched.description,
+          jsDocTags: matched.jsDocTags,
+        };
+      })
+      .filter((p): p is IReflectMcpOperationParameter => !!p);
+
+    if (ctx.metadata.success?.imports?.length)
+      imports.push(...ctx.metadata.success.imports);
+
+    if (errors.length) {
+      ctx.project.errors.push({
+        file: ctx.controller.file,
+        class: ctx.controller.class.name,
+        function: ctx.function.name,
+        from: ctx.name,
+        contents: errors,
+      });
+      return null;
+    }
+    // Prefer the decorator's explicit config. Fall back to the JSDoc-derived
+    // description captured by SdkOperationTransformer, so users who only
+    // document their method with a JSDoc comment still get it surfaced on
+    // the `tools/list` wire + the generated SDK metadata.
+    return {
+      protocol: "mcp",
+      name: ctx.name,
+      toolName: route.name,
+      title: route.title ?? null,
+      toolDescription: route.description ?? ctx.metadata.description ?? null,
+      inputSchema: route.inputSchema,
+      outputSchema: route.outputSchema ?? null,
+      annotations: route.annotations ?? null,
+      function: ctx.function,
+      parameters,
+      returnType: ctx.metadata.success?.type ?? null,
+      imports: ImportAnalyzer.merge(imports),
+      description: ctx.metadata.description ?? null,
+      jsDocTags: ctx.metadata.jsDocTags,
+    };
+  };
+}

package/src/analyses/TypedMcpRouteAnalyzer.ts

@@ -0,0 +1,40 @@
+import { IReflectController } from "../structures/IReflectController";
+import { IReflectMcpOperation } from "../structures/IReflectMcpOperation";
+import { ITypedMcpRoute } from "../structures/ITypedMcpRoute";
+
+/**
+ * Builds {@link ITypedMcpRoute} entries from a reflected MCP operation,
+ * assigning a stable `["mcp", toolName]` accessor for SDK file emission.
+ *
+ * @author wildduck - https://github.com/wildduck2
+ */
+export namespace TypedMcpRouteAnalyzer {
+  export const analyze = (props: {
+    controller: IReflectController;
+    operation: IReflectMcpOperation;
+  }): ITypedMcpRoute[] => [
+    {
+      protocol: "mcp",
+      controller: props.controller,
+      name: props.operation.name,
+      toolName: props.operation.toolName,
+      title: props.operation.title,
+      toolDescription: props.operation.toolDescription,
+      accessor: accessor(props.operation.toolName),
+      function: props.operation.function,
+      input: props.operation.parameters[0] ?? null,
+      returnType: props.operation.returnType,
+      inputSchema: props.operation.inputSchema,
+      outputSchema: props.operation.outputSchema,
+      annotations: props.operation.annotations,
+      imports: props.operation.imports,
+      description: props.operation.description,
+      jsDocTags: props.operation.jsDocTags,
+    },
+  ];
+
+  const accessor = (toolName: string): string[] => {
+    const safe = toolName.replace(/[^A-Za-z0-9_$]/g, "_");
+    return ["mcp", safe];
+  };
+}

package/src/generates/SdkGenerator.ts

@@ -7,6 +7,7 @@ import { IReflectOperationError } from "../structures/IReflectOperationError";
 import { IReflectType } from "../structures/IReflectType";
 import { ITypedApplication } from "../structures/ITypedApplication";
 import { ITypedHttpRoute } from "../structures/ITypedHttpRoute";
+import { ITypedMcpRoute } from "../structures/ITypedMcpRoute";
 import { CloneGenerator } from "./CloneGenerator";
 import { SdkDistributionComposer } from "./internal/SdkDistributionComposer";
 import { SdkFileProgrammer } from "./internal/SdkFileProgrammer";
@@ -55,6 +56,7 @@ export namespace SdkGenerator {
     if (app.project.config.distribute !== undefined)
       await SdkDistributionComposer.compose({
         config: app.project.config,
+        mcp: app.routes.some((r) => r.protocol === "mcp"),
         websocket: app.routes.some((r) => r.protocol === "websocket"),
       });
   };
@@ -63,6 +65,8 @@ export namespace SdkGenerator {
     app: ITypedApplication,
   ): IReflectOperationError[] => {
     const errors: IReflectOperationError[] = [];
+    validateMcpDuplicates(errors)(app.routes);
+    validateMcpAccessors(errors)(app.routes);
     if (app.project.config.clone === true) return errors;
     for (const route of app.routes)
       if (route.protocol === "http")
@@ -74,6 +78,57 @@ export namespace SdkGenerator {
     return errors;
   };
 
+  const validateMcpDuplicates =
+    (errors: IReflectOperationError[]) =>
+    (routes: ITypedApplication["routes"]): void => {
+      const dict: Map<string, ITypedMcpRoute[]> = new Map();
+      for (const route of routes)
+        if (route.protocol === "mcp") {
+          const array = dict.get(route.toolName) ?? [];
+          array.push(route);
+          dict.set(route.toolName, array);
+        }
+
+      for (const [toolName, list] of dict)
+        if (list.length > 1)
+          for (const route of list)
+            errors.push({
+              file: route.controller.file,
+              class: route.controller.class.name,
+              function: route.function.name || route.name,
+              from: `@McpRoute(${JSON.stringify(toolName)})`,
+              contents: [
+                `Duplicate MCP tool name ${JSON.stringify(toolName)} is not allowed.`,
+              ],
+            });
+    };
+
+  const validateMcpAccessors =
+    (errors: IReflectOperationError[]) =>
+    (routes: ITypedApplication["routes"]): void => {
+      const dict: Map<string, ITypedMcpRoute[]> = new Map();
+      for (const route of routes)
+        if (route.protocol === "mcp") {
+          const accessor = route.accessor.join(".");
+          const array = dict.get(accessor) ?? [];
+          array.push(route);
+          dict.set(accessor, array);
+        }
+
+      for (const [accessor, list] of dict)
+        if (list.length > 1)
+          for (const route of list)
+            errors.push({
+              file: route.controller.file,
+              class: route.controller.class.name,
+              function: route.function.name || route.name,
+              from: `@McpRoute(${JSON.stringify(route.toolName)})`,
+              contents: [
+                `MCP tool name ${JSON.stringify(route.toolName)} conflicts on generated SDK accessor "api.functional.${accessor}".`,
+              ],
+            });
+    };
+
   const validateImplicit = (props: {
     config: INestiaConfig;
     errors: IReflectOperationError[];

package/src/generates/internal/ImportDictionary.ts

@@ -1,5 +1,5 @@
 import path from "path";
-import { HashMap, TreeSet, hash } from "tstl";
+import { HashMap, TreeMap, hash } from "tstl";
 import ts from "typescript";
 
 import { ImportAnalyzer } from "../../analyses/ImportAnalyzer";
@@ -78,10 +78,11 @@ export class ImportDictionary {
     };
     const value: ICompositeValue = this.components_.take(key, () => ({
       ...key,
-      elements: new TreeSet<string>(),
+      elements: new TreeMap<string, string | null>(),
     }));
-    if (props.type === "element") value.elements.insert(props.name);
-    return props.name;
+    if (props.type === "element")
+      value.elements.set(props.name, props.alias ?? null);
+    return props.type === "element" ? (props.alias ?? props.name) : props.name;
   }
 
   public toStatements(outDir: string): ts.Statement[] {
@@ -149,11 +150,11 @@ export class ImportDictionary {
       c.default !== null ? ts.factory.createIdentifier(c.default) : undefined,
       c.elements.size() !== 0
         ? ts.factory.createNamedImports(
-            Array.from(c.elements).map((elem) =>
+            Array.from(c.elements).map(({ first: name, second: alias }) =>
               ts.factory.createImportSpecifier(
                 false,
-                undefined,
-                ts.factory.createIdentifier(elem),
+                alias !== null ? ts.factory.createIdentifier(name) : undefined,
+                ts.factory.createIdentifier(alias ?? name),
               ),
             ),
           )
@@ -166,6 +167,7 @@ export namespace ImportDictionary {
     type: "default" | "element" | "asterisk";
     file: string;
     name: string;
+    alias?: string;
     declaration: boolean;
   }
 }
@@ -177,7 +179,7 @@ interface ICompositeKey {
   default: string | null;
 }
 interface ICompositeValue extends ICompositeKey {
-  elements: TreeSet<string>;
+  elements: TreeMap<string, string | null>;
 }
 
 const NODE_MODULES = "node_modules/";

package/src/generates/internal/SdkDistributionComposer.ts

@@ -8,6 +8,7 @@ import { INestiaConfig } from "../../INestiaConfig";
 export namespace SdkDistributionComposer {
   export const compose = async (props: {
     config: INestiaConfig;
+    mcp: boolean;
     websocket: boolean;
   }) => {
     if (!fs.existsSync(props.config.distribute!))
@@ -34,6 +35,10 @@ export namespace SdkDistributionComposer {
     execute("npm install --save-dev rimraf");
     execute(`npm install --save @nestia/fetcher@${v.version}`);
     execute(`npm install --save typia@${v.typia}`);
+    if (props.mcp)
+      execute(
+        `npm install --save @modelcontextprotocol/sdk@${v["@modelcontextprotocol/sdk"]}`,
+      );
     if (props.websocket) execute(`npm install --save tgrid@${v.tgrid}`);
     execute("npx typia setup --manager npm");
 
@@ -96,6 +101,7 @@ export namespace SdkDistributionComposer {
 }
 
 interface IDependencies {
+  "@modelcontextprotocol/sdk": string;
   version: string;
   typia: string;
   tgrid: string;

package/src/generates/internal/SdkFileProgrammer.ts

@@ -4,11 +4,13 @@ import ts from "typescript";
 import { INestiaProject } from "../../structures/INestiaProject";
 import { ITypedApplication } from "../../structures/ITypedApplication";
 import { ITypedHttpRoute } from "../../structures/ITypedHttpRoute";
+import { ITypedMcpRoute } from "../../structures/ITypedMcpRoute";
 import { ITypedWebSocketRoute } from "../../structures/ITypedWebSocketRoute";
 import { MapUtil } from "../../utils/MapUtil";
 import { FilePrinter } from "./FilePrinter";
 import { ImportDictionary } from "./ImportDictionary";
 import { SdkHttpRouteProgrammer } from "./SdkHttpRouteProgrammer";
+import { SdkMcpRouteProgrammer } from "./SdkMcpRouteProgrammer";
 import { SdkRouteDirectory } from "./SdkRouteDirectory";
 import { SdkWebSocketRouteProgrammer } from "./SdkWebSocketRouteProgrammer";
 
@@ -27,7 +29,7 @@ export namespace SdkFileProgrammer {
 
   const emplace =
     (directory: SdkRouteDirectory) =>
-    (route: ITypedHttpRoute | ITypedWebSocketRoute): void => {
+    (route: ITypedHttpRoute | ITypedWebSocketRoute | ITypedMcpRoute): void => {
       // OPEN DIRECTORIES
       for (const key of route.accessor.slice(0, -1)) {
         directory = MapUtil.take(
@@ -80,7 +82,9 @@ export namespace SdkFileProgrammer {
         statements.push(
           ...(route.protocol === "http"
             ? SdkHttpRouteProgrammer.write(project)(importer)(route)
-            : SdkWebSocketRouteProgrammer.write(project)(importer)(route)),
+            : route.protocol === "websocket"
+              ? SdkWebSocketRouteProgrammer.write(project)(importer)(route)
+              : SdkMcpRouteProgrammer.write(project)(importer)(route)),
         );
         if (i !== directory.routes.length - 1)
           statements.push(FilePrinter.enter());