@agentica/core 0.16.8 → 0.16.9

package/lib/structures/mcp/IMcpLlmFunction.d.ts

@@ -0,0 +1,17 @@
+/**
+ * MCP LLM function.
+ */
+export interface IMcpLlmFunction {
+    /**
+     * Name of the function.
+     */
+    name: string;
+    /**
+     * Description of the function.
+     */
+    description?: string;
+    /**
+     * Parameters of the function.
+     */
+    parameters: object;
+}

package/lib/structures/mcp/IMcpLlmFunction.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=IMcpLlmFunction.js.map

package/lib/structures/mcp/IMcpLlmFunction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IMcpLlmFunction.js","sourceRoot":"","sources":["../../../src/structures/mcp/IMcpLlmFunction.ts"],"names":[],"mappings":""}

package/lib/structures/mcp/IMcpLlmTransportProps.d.ts

@@ -0,0 +1,11 @@
+import type { SSEClientTransportOptions } from "@modelcontextprotocol/sdk/client/sse.d.ts";
+import type { StdioServerParameters } from "@modelcontextprotocol/sdk/client/stdio.d.ts";
+export type IMcpLlmTransportProps = IMcpLlmTransportPropsHttp | IMcpLlmTransportPropsStdio;
+export interface IMcpLlmTransportPropsHttp extends IMcpLlmTransportPropsBase<"sse">, SSEClientTransportOptions {
+    url: URL;
+}
+export interface IMcpLlmTransportPropsStdio extends IMcpLlmTransportPropsBase<"stdio">, StdioServerParameters {
+}
+export interface IMcpLlmTransportPropsBase<T extends string> {
+    type: T;
+}

package/lib/structures/mcp/IMcpLlmTransportProps.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=IMcpLlmTransportProps.js.map

package/lib/structures/mcp/IMcpLlmTransportProps.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IMcpLlmTransportProps.js","sourceRoot":"","sources":["../../../src/structures/mcp/IMcpLlmTransportProps.ts"],"names":[],"mappings":""}

package/lib/structures/mcp/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./IMcpLlmApplication";
+export * from "./IMcpLlmFunction";
+export * from "./IMcpLlmTransportProps";

package/lib/structures/mcp/index.js

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./IMcpLlmApplication"), exports);
+__exportStar(require("./IMcpLlmFunction"), exports);
+__exportStar(require("./IMcpLlmTransportProps"), exports);
+//# sourceMappingURL=index.js.map

package/lib/structures/mcp/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/structures/mcp/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,uDAAqC;AACrC,oDAAkC;AAClC,0DAAwC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentica/core",
-  "version": "0.16.8",
+  "version": "0.16.9",
   "description": "Agentic AI Library specialized in LLM Function Calling",
   "author": "Wrtn Technologies",
   "license": "MIT",
@@ -36,9 +36,10 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@samchon/openapi": ">=4.0.0 <5.0.0",
-    "openai": ">=4.80.0",
-    "typia": ">=9.0.1 <10.0.0"
+    "@modelcontextprotocol/sdk": "^1.9.0",
+    "@samchon/openapi": "^4.0.0",
+    "openai": "^4.80.0",
+    "typia": "^9.0.1"
   },
   "dependencies": {
     "@samchon/openapi": "^4.0.0",
@@ -46,9 +47,11 @@
     "uuid": "^11.0.4"
   },
   "devDependencies": {
+    "@modelcontextprotocol/sdk": "^1.9.0",
     "@nestia/e2e": "^6.0.1",
     "@rollup/plugin-terser": "^0.4.4",
     "@rollup/plugin-typescript": "^12.1.2",
+    "@ryoppippi/unplugin-typia": "^2.1.4",
     "@types/node": "^22.13.4",
     "@types/uuid": "^10.0.0",
     "openai": "^4.80.0",
@@ -57,14 +60,16 @@
     "ts-node": "^10.9.2",
     "ts-patch": "^3.3.0",
     "typedoc": "^0.27.7",
-    "typescript": "~5.8.3"
+    "typescript": "~5.8.3",
+    "vitest": "^3.0.9"
   },
   "scripts": {
     "build": "rimraf lib && pnpm build:prompt && tsc && rollup -c",
     "build:prompt": "node build/prompt.js",
     "dev": "rimraf lib && tsc --watch",
     "lint": "eslint .",
-    "format": "eslint --fix ."
+    "format": "eslint --fix .",
+    "test": "vitest"
   },
   "module": "lib/index.mjs",
   "typings": "lib/index.d.ts"

package/src/context/AgenticaOperation.ts

@@ -2,6 +2,7 @@ import type { IHttpLlmFunction, ILlmFunction, ILlmSchema } from "@samchon/openap
 
 import type { IAgenticaOperationJson } from "../json/IAgenticaOperationJson";
 import type { IAgenticaController } from "../structures/IAgenticaController";
+import type { IMcpLlmFunction } from "../structures/mcp/IMcpLlmFunction";
 
 /**
  * Operation information in the Agentica Agent.
@@ -20,7 +21,8 @@ import type { IAgenticaController } from "../structures/IAgenticaController";
  */
 export type AgenticaOperation<Model extends ILlmSchema.Model> =
   | AgenticaOperation.Class<Model>
-  | AgenticaOperation.Http<Model>;
+  | AgenticaOperation.Http<Model>
+  | AgenticaOperation.Mcp;
 export namespace AgenticaOperation {
   export type Class<Model extends ILlmSchema.Model> = Base<
     "class",
@@ -32,9 +34,14 @@ export namespace AgenticaOperation {
     IAgenticaController.IHttp<Model>,
     IHttpLlmFunction<Model>
   >;
+  export type Mcp = Base<
+    "mcp",
+    IAgenticaController.IMcp,
+    IMcpLlmFunction
+  >;
 
   interface Base<
-    Protocol extends "http" | "class",
+    Protocol extends "http" | "class" | "mcp",
     Controller extends object,
     Function extends object,
   > {

package/src/context/internal/AgenticaOperationComposer.spec.ts

@@ -0,0 +1,314 @@
+import type { IHttpLlmFunction, ILlmFunction, IValidation } from "@samchon/openapi";
+
+import type { IAgenticaConfig } from "../../structures/IAgenticaConfig";
+import type { IAgenticaController } from "../../structures/IAgenticaController";
+import type { IMcpLlmFunction } from "../../structures/mcp/IMcpLlmFunction";
+
+import { compose, divide, getOperations, toClassOperations, toHttpOperations, toMcpOperations } from "./AgenticaOperationComposer";
+
+// test helper functions
+function createMockHttpFunction(name: string, method: "get" | "post" | "patch" | "put" | "delete", path: string): IHttpLlmFunction<any> {
+  return {
+    name,
+    method,
+    path,
+    validate: () => ({ success: true, data: {} } as IValidation<unknown>),
+    operation: () => ({}),
+    route: () => ({
+      method,
+      path,
+      emendedPath: path,
+      accessor: [name],
+      body: null,
+      query: null,
+      parameters: [],
+      headers: null,
+      success: null,
+      exceptions: {},
+      comment: () => "OK",
+      operation: () => ({}),
+    }),
+    parameters: {},
+    output: {},
+  };
+}
+
+function createMockHttpController(name: string, functions: IHttpLlmFunction<any>[]): IAgenticaController.IHttp<any> {
+  return {
+    name,
+    protocol: "http",
+    connection: { host: "https://example.com" },
+    application: {
+      model: "chatgpt",
+      options: {},
+      functions,
+      errors: [],
+    },
+  };
+}
+
+function createMockClassController(name: string, functions: ILlmFunction<any>[]): IAgenticaController.IClass<any> {
+  return {
+    name,
+    protocol: "class",
+    application: {
+      model: "chatgpt",
+      options: {},
+      functions,
+    },
+    execute: {},
+  };
+}
+
+function createMockMcpController(name: string, functions: IMcpLlmFunction[]): IAgenticaController.IMcp {
+  return {
+    name,
+    protocol: "mcp",
+    application: {
+      transport: {
+        type: "sse",
+        url: new URL("https://example.com"),
+      },
+      functions,
+    },
+  };
+}
+
+describe("a AgenticaOperationComposer", () => {
+  describe("compose", () => {
+    it("should compose operations from controllers", () => {
+      // Mock controllers
+      const mockHttpController = createMockHttpController("httpController", [
+        createMockHttpFunction("function1", "get", "/api/function1"),
+        createMockHttpFunction("function2", "post", "/api/function2"),
+      ]);
+
+      const mockClassController = createMockClassController("classController", [
+        {
+          name: "function3",
+          validate: () => ({ success: true, data: {} } as IValidation<unknown>),
+          parameters: {},
+          output: {},
+        },
+      ]);
+
+      const mockMcpController = createMockMcpController("mcpController", [
+        {
+          name: "function4",
+          parameters: {},
+        },
+      ]);
+
+      const controllers = [mockHttpController, mockClassController, mockMcpController];
+
+      const result = compose({ controllers });
+
+      expect(result.array).toHaveLength(4);
+      expect(result.flat).toBeInstanceOf(Map);
+      expect(result.group).toBeInstanceOf(Map);
+      expect(result.divided).toBeUndefined();
+    });
+
+    it("should divide operations when capacity is provided", () => {
+      // Mock controllers
+      const mockController = createMockHttpController("httpController", [
+        createMockHttpFunction("function1", "get", "/api/function1"),
+        createMockHttpFunction("function2", "post", "/api/function2"),
+        createMockHttpFunction("function3", "put", "/api/function3"),
+        createMockHttpFunction("function4", "delete", "/api/function4"),
+        createMockHttpFunction("function5", "patch", "/api/function5"),
+      ]);
+
+      const config: IAgenticaConfig<any> = {
+        capacity: 2,
+      };
+
+      const result = compose({ controllers: [mockController], config });
+
+      expect(result.array).toHaveLength(5);
+      expect(result.divided).toBeDefined();
+      expect(result.divided).toHaveLength(3); // 5 items with capacity 2 should be divided into 3 groups
+    });
+  });
+
+  describe("getOperations", () => {
+    it("should get operations from http controllers", () => {
+      const mockController = createMockHttpController("httpController", [
+        createMockHttpFunction("function1", "get", "/api/function1"),
+        createMockHttpFunction("function2", "post", "/api/function2"),
+      ]);
+
+      const result = getOperations({ controllers: [mockController], naming: (func, idx) => `_${idx}_${func}` });
+
+      expect(result).toHaveLength(2);
+      expect(result[0]?.protocol).toBe("http");
+      expect(result[0]?.name).toBe("_0_function1");
+      expect(result[1]?.name).toBe("_0_function2");
+    });
+
+    it("should get operations from class controllers", () => {
+      const mockController = createMockClassController("classController", [
+        {
+          name: "function1",
+          validate: () => ({ success: true, data: {} } as IValidation<unknown>),
+          parameters: {},
+          output: {},
+        },
+      ]);
+
+      const result = getOperations({ controllers: [mockController], naming: (func, idx) => `_${idx}_${func}` });
+
+      expect(result).toHaveLength(1);
+      expect(result[0]?.protocol).toBe("class");
+      expect(result[0]?.name).toBe("_0_function1");
+    });
+
+    it("should get operations from mcp controllers", () => {
+      const mockController = createMockMcpController("mcpController", [
+        {
+          name: "function1",
+          parameters: {},
+        },
+      ]);
+
+      const result = getOperations({ controllers: [mockController], naming: (func, idx) => `_${idx}_${func}` });
+
+      expect(result).toHaveLength(1);
+      expect(result[0]?.protocol).toBe("mcp");
+      expect(result[0]?.name).toBe("_0_function1");
+    });
+
+    it("should throw error for unsupported protocol", () => {
+      const mockController: IAgenticaController.IHttp<any> = {
+        name: "unsupportedController",
+        protocol: "unsupported" as unknown as "http",
+        connection: { host: "https://example.com" },
+        application: { } as unknown as IAgenticaController.IHttp<any>["application"],
+      };
+
+      expect(() => getOperations({ controllers: [mockController], naming: (func, idx) => `_${idx}_${func}` })).toThrow("Unsupported protocol: unsupported");
+    });
+  });
+
+  describe("toHttpOperations", () => {
+    it("should convert http controller to operations", () => {
+      const mockController = createMockHttpController("httpController", [
+        createMockHttpFunction("function1", "get", "/api/function1"),
+        createMockHttpFunction("function2", "post", "/api/function2"),
+      ]);
+
+      const result = toHttpOperations({ controller: mockController, index: 0, naming: (func, idx) => `_${idx}_${func}` });
+
+      expect(result).toHaveLength(2);
+      expect(result[0]?.protocol).toBe("http");
+      expect(result[0]?.name).toBe("_0_function1");
+      expect(result[1]?.name).toBe("_0_function2");
+    });
+  });
+
+  describe("toClassOperations", () => {
+    it("should convert class controller to operations", () => {
+      const mockController = createMockClassController("classController", [
+        {
+          name: "function1",
+          validate: () => ({ success: true, data: {} } as IValidation<unknown>),
+          parameters: {},
+          output: {},
+        },
+      ]);
+
+      const result = toClassOperations({ controller: mockController, index: 0, naming: (func, idx) => `_${idx}_${func}` });
+
+      expect(result).toHaveLength(1);
+      expect(result[0]?.protocol).toBe("class");
+      expect(result[0]?.name).toBe("_0_function1");
+    });
+  });
+
+  describe("toMcpOperations", () => {
+    it("should convert mcp controller to operations", () => {
+      const mockController = createMockMcpController("mcpController", [
+        {
+          name: "function1",
+          parameters: {},
+        },
+      ]);
+
+      const result = toMcpOperations({ controller: mockController, index: 0, naming: (func, idx) => `_${idx}_${func}` });
+
+      expect(result).toHaveLength(1);
+      expect(result[0]?.protocol).toBe("mcp");
+      expect(result[0]?.name).toBe("_0_function1");
+    });
+  });
+  describe("divide with invalid capacity", () => {
+    it("should throw error when capacity is 0", () => {
+      const array = [1, 2, 3, 4, 5];
+      const capacity = 0;
+
+      expect(() => divide({ array, capacity })).toThrow("Capacity must be a positive integer");
+    });
+
+    it("should throw error when capacity is negative", () => {
+      const array = [1, 2, 3, 4, 5];
+      const capacity = -3;
+
+      expect(() => divide({ array, capacity })).toThrow("Capacity must be a positive integer");
+    });
+
+    it("should throw error when capacity is decimal", () => {
+      const array = [1, 2, 3, 4, 5];
+      const capacity = 2.5;
+      const result = divide({ array, capacity });
+      expect(result).toEqual([[1, 2, 3], [4, 5]]);
+    });
+
+    it("should throw error when capacity is Infinity", () => {
+      const array = [1, 2, 3, 4, 5];
+      const capacity = Infinity;
+
+      expect(() => divide({ array, capacity })).toThrow("Capacity must be a positive integer");
+    });
+
+    it("should throw error when capacity is NaN", () => {
+      const array = [1, 2, 3, 4, 5];
+      const capacity = Number.NaN;
+
+      expect(() => divide({ array, capacity })).toThrow("Capacity must be a positive integer");
+    });
+  });
+
+  describe("divide", () => {
+    it("should divide array into chunks based on capacity", () => {
+      const array = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
+      const capacity = 3;
+
+      const result = divide({ array, capacity });
+
+      expect(result).toHaveLength(4); // 10 items with capacity 3 should be divided into 4 groups
+      expect(result[0]).toEqual([1, 2, 3]);
+      expect(result[1]).toEqual([4, 5, 6]);
+      expect(result[2]).toEqual([7, 8, 9]);
+      expect(result[3]).toEqual([10]);
+    });
+
+    it("should handle empty array", () => {
+      const array: number[] = [];
+      const capacity = 3;
+
+      const result = divide({ array, capacity });
+
+      expect(result).toHaveLength(0);
+    });
+
+    it("should handle array smaller than capacity", () => {
+      const array = [1, 2];
+      const capacity = 3;
+
+      const result = divide({ array, capacity });
+
+      expect(result).toHaveLength(1);
+      expect(result[0]).toEqual([1, 2]);
+    });
+  });
+});

package/src/context/internal/AgenticaOperationComposer.ts

@@ -8,59 +8,27 @@ import type { AgenticaOperationCollection } from "../AgenticaOperationCollection
 
 import { __map_take } from "../../utils/__map_take";
 
+/**
+ * Compose the agentica operation collection.
+ *
+ * Compose the {@link AgenticaOperationCollection} from the given
+ * controllers and config.
+ *
+ * @internal
+ */
 export function compose<Model extends ILlmSchema.Model>(props: {
   controllers: IAgenticaController<Model>[];
   config?: IAgenticaConfig<Model> | IMicroAgenticaConfig<Model> | undefined;
 }): AgenticaOperationCollection<Model> {
-  const unique: boolean
-      = props.controllers.length === 1
-        || (() => {
-          const names: string[] = props.controllers
-            .map(controller =>
-              controller.application.functions.map(func => func.name),
-            )
-            .flat();
-          return new Set(names).size === names.length;
-        })();
-  const naming = (func: string, ci: number) =>
-    unique ? func : `_${ci}_${func}`;
-
-  const array: AgenticaOperation<Model>[] = props.controllers
-    .map((controller, ci) =>
-      controller.protocol === "http"
-        ? controller.application.functions.map(
-            func =>
-                ({
-                  protocol: "http",
-                  controller,
-                  function: func,
-                  name: naming(func.name, ci),
-                  toJSON: () => ({
-                    protocol: "http",
-                    controller: controller.name,
-                    function: func.name,
-                    name: naming(func.name, ci),
-                  }),
-                }) satisfies AgenticaOperation.Http<Model>,
-          )
-        : controller.application.functions.map(
-            func =>
-                ({
-                  protocol: "class",
-                  controller,
-                  function: func,
-                  name: naming(func.name, ci),
-                  toJSON: () => ({
-                    protocol: "class",
-                    controller: controller.name,
-                    function: func.name,
-                    name: naming(func.name, ci),
-                  }),
-                }) satisfies AgenticaOperation.Class<Model>,
-          ),
-    )
-    .flat();
+  const unique: boolean = (props.controllers.length === 1 || (() => {
+    const names = props.controllers.map(controllers => controllers.application.functions.map(func => func.name)).flat();
+    return new Set(names).size === names.length;
+  })());
 
+  const array: AgenticaOperation<Model>[] = getOperations({
+    controllers: props.controllers,
+    naming: (func: string, controllerIndex: number) => unique ? func : `_${controllerIndex}_${func}`,
+  });
   const capacity: number | undefined = (props.config as IAgenticaConfig<Model>)?.capacity;
   const divided: AgenticaOperation<Model>[][] | undefined
       = capacity !== undefined && array.length > capacity
@@ -87,10 +55,112 @@ export function compose<Model extends ILlmSchema.Model>(props: {
   };
 }
 
-function divide<T>(props: {
+/**
+ * @internal
+ */
+export function getOperations<Model extends ILlmSchema.Model>(props: {
+  controllers: IAgenticaController<Model>[];
+  naming: (func: string, controllerIndex: number) => string;
+}): AgenticaOperation<Model>[] {
+  return props.controllers.flatMap((controller, idx) => {
+    switch (controller.protocol) {
+      case "http":{
+        return toHttpOperations({ controller, index: idx, naming: props.naming }); }
+      case "class":{
+        return toClassOperations({ controller, index: idx, naming: props.naming }); }
+      case "mcp": {
+        return toMcpOperations({ controller, index: idx, naming: props.naming });
+      }
+      default:
+        controller satisfies never;
+        throw new Error(`Unsupported protocol: ${(controller as { protocol: string }).protocol}`);
+    }
+  });
+}
+
+/**
+ * @internal
+ */
+export function toHttpOperations<Model extends ILlmSchema.Model>(props: {
+  controller: IAgenticaController.IHttp<Model>;
+  index: number;
+  naming: (func: string, controllerIndex: number) => string;
+}): AgenticaOperation<Model>[] {
+  return props.controller.application.functions.map(func => ({
+    protocol: "http",
+    controller: props.controller,
+    function: func,
+    name: props.naming(func.name, props.index),
+    toJSON: () => ({
+      protocol: "http",
+      controller: props.controller.name,
+      function: func.name,
+      name: props.naming(func.name, props.index),
+    }),
+  }));
+}
+
+/**
+ * @internal
+ */
+export function toClassOperations<Model extends ILlmSchema.Model>(props: {
+  controller: IAgenticaController.IClass<Model>;
+  index: number;
+  naming: (func: string, controllerIndex: number) => string;
+}): AgenticaOperation<Model>[] {
+  return props.controller.application.functions.map(func => ({
+    protocol: "class",
+    controller: props.controller,
+    function: func,
+    name: props.naming(func.name, props.index),
+    toJSON: () => ({
+      protocol: "class",
+      controller: props.controller.name,
+      function: func.name,
+      name: props.naming(func.name, props.index),
+    }),
+  }));
+}
+
+/**
+ * @internal
+ */
+export function toMcpOperations<Model extends ILlmSchema.Model>(props: {
+  controller: IAgenticaController.IMcp;
+  index: number;
+  naming: (func: string, controllerIndex: number) => string;
+}): AgenticaOperation<Model>[] {
+  return props.controller.application.functions.map(func => ({
+    protocol: "mcp",
+    controller: props.controller,
+    function: func,
+    name: props.naming(func.name, props.index),
+    toJSON: () => ({
+      protocol: "mcp",
+      controller: props.controller.name,
+      function: func.name,
+      name: props.naming(func.name, props.index),
+    }),
+  }));
+}
+
+/**
+ * @internal
+ */
+export function divide<T>(props: {
   array: T[];
   capacity: number;
 }): T[][] {
+  if (props.capacity <= 0) {
+    throw new Error("Capacity must be a positive integer");
+  }
+  if (Number.isNaN(props.capacity)) {
+    throw new TypeError("Capacity must be a positive integer");
+  }
+  if (props.capacity === Infinity) {
+    throw new Error("Capacity must be a positive integer");
+  }
+
   const size: number = Math.ceil(props.array.length / props.capacity);
   const capacity: number = Math.ceil(props.array.length / size);
   const replica: T[] = props.array.slice();