@agentica/core 0.16.8 → 0.16.9

package/src/functional/assertMcpLlmApplication.ts

@@ -0,0 +1,48 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { ListToolsResultSchema } from "@modelcontextprotocol/sdk/types.js";
+
+import type { IMcpLlmApplication, IMcpLlmTransportProps } from "../structures/mcp";
+/**
+ * Create an MCP LLM application instance with type assertion.
+ *
+ * Create an {@link IMcpLlmApplication} instance which represents
+ * an MCP (Model Context Protocol) LLM application.
+ *
+ * @param props Properties to create the MCP LLM application instance
+ * @param props.name Name of the MCP implementation.
+ * @param props.url URL of the MCP server.
+ * @param props.version Describes version of an MCP implementation.
+ * @returns MCP LLM application instance
+ * @author Samchon
+ */
+export async function assertMcpLlmApplication(props: IMcpLlmTransportProps): Promise<IMcpLlmApplication> {
+  const client = new Client({
+    name: "get_tool_list",
+    version: "1.0.0",
+  });
+
+  const transport = (() => {
+    switch (props.type) {
+      case "sse":
+        return new SSEClientTransport(props.url);
+      case "stdio":
+        return new StdioClientTransport(props);
+      default:
+        props satisfies never;
+        throw new Error("Invalid transport type");
+    }
+  })();
+  await client.connect(transport);
+
+  const toolList = await client.request({ method: "tools/list" }, ListToolsResultSchema);
+  return {
+    functions: toolList.tools.map(tool => ({
+      name: tool.name,
+      description: tool.description,
+      parameters: tool.inputSchema,
+    })),
+    transport: props,
+  };
+}

package/src/index.ts

@@ -6,9 +6,9 @@ export * from "./context/AgenticaOperation";
 export * from "./context/AgenticaOperationCollection";
 export * from "./context/AgenticaOperationSelection";
 export * from "./context/AgenticaTokenUsage";
+
 export * from "./events/AgenticaCallEvent";
 export * from "./events/AgenticaCancelEvent";
-
 export * from "./events/AgenticaDescribeEvent";
 export * from "./events/AgenticaEvent";
 export * from "./events/AgenticaEventSource";
@@ -19,10 +19,14 @@ export * from "./events/AgenticaSelectEvent";
 export * from "./events/AgenticaTextEvent";
 export * from "./events/AgenticaValidateEvent";
 export * from "./events/MicroAgenticaEvent";
+
 export * as factory from "./factory";
-export * from "./functional/assertHttpLlmApplication";
 
+export * from "./functional/assertHttpLlmApplication";
+export * from "./functional/assertMcpLlmApplication";
 export * from "./functional/validateHttpLlmApplication";
+// @TODO: implement validateMcpLlmApplication
+
 export * from "./histories/AgenticaCancelHistory";
 export * from "./histories/AgenticaDescribeHistory";
 export * from "./histories/AgenticaExecuteHistory";

package/src/json/IAgenticaOperationJson.ts

@@ -17,7 +17,7 @@ export interface IAgenticaOperationJson {
   /**
    * Protocol discriminator.
    */
-  protocol: "class" | "http";
+  protocol: "class" | "http" | "mcp";
 
   /**
    * Belonged controller of the target function.

package/src/orchestrate/call.ts

@@ -73,16 +73,18 @@ export async function call<Model extends ILlmSchema.Model>(
           function: {
             name: s.name,
             description: s.function.description,
-            parameters: (s.function.separated !== undefined
-              ? (s.function.separated.llm
-                ?? ({
-                  type: "object",
-                  properties: {},
-                  required: [],
-                  additionalProperties: false,
-                  $defs: {},
-                } satisfies IChatGptSchema.IParameters))
-              : s.function.parameters) as Record<string, any>,
+            parameters: (
+              "separated" in s.function
+              && s.function.separated !== undefined
+                ? (s.function.separated.llm
+                  ?? ({
+                    type: "object",
+                    properties: {},
+                    required: [],
+                    additionalProperties: false,
+                    $defs: {},
+                  } satisfies IChatGptSchema.IParameters))
+                : s.function.parameters) as Record<string, any>,
           },
         }) as OpenAI.ChatCompletionTool,
     ),
@@ -200,126 +202,93 @@ async function propagate<Model extends ILlmSchema.Model>(
   call: AgenticaCallEvent<Model>,
   retry: number,
 ): Promise<AgenticaExecuteHistory<Model>> {
-  if (call.operation.protocol === "http") {
-    // ----
-    // HTTP PROTOCOL
-    // ----
-    // NESTED VALIDATOR
-    const check: IValidation<unknown> = call.operation.function.validate(
-      call.arguments,
-    );
-    if (check.success === false) {
-      ctx.dispatch(
-        createValidateEvent({
-          id: call.id,
-          operation: call.operation,
-          result: check,
-        }),
-      ).catch(() => {});
-      if (retry++ < (ctx.config?.retry ?? AgenticaConstant.RETRY)) {
-        const trial: AgenticaExecuteHistory<Model> | null = await correct(
-          ctx,
-          call,
-          retry,
-          check.errors,
-        );
-        if (trial !== null) {
-          return trial;
-        }
+  switch (call.operation.protocol) {
+    case "http": {
+      return propagateHttp({ ctx, operation: call.operation, call, retry });
+    }
+    case "class": {
+      return propagateClass({ ctx, operation: call.operation, call, retry });
+    }
+    case "mcp": {
+      return propagateMcp({ ctx, operation: call.operation, call, retry });
+    }
+    default: {
+      call.operation satisfies never;
+      throw new Error("Unsupported protocol");
+    }
+  }
+}
+
+async function propagateHttp<Model extends ILlmSchema.Model>(
+  props: {
+    ctx: AgenticaContext<Model> | MicroAgenticaContext<Model>;
+    operation: AgenticaOperation.Http<Model>;
+    call: AgenticaCallEvent<Model>;
+    retry: number;
+  },
+): Promise<AgenticaExecuteHistory<Model>> {
+  // ----
+  // HTTP PROTOCOL
+  // ----
+  // NESTED VALIDATOR
+  const check: IValidation<unknown> = props.operation.function.validate(
+    props.call.arguments,
+  );
+  if (check.success === false) {
+    props.ctx.dispatch(
+      createValidateEvent({
+        id: props.call.id,
+        operation: props.operation,
+        result: check,
+      }),
+    ).catch(() => {});
+
+    if (props.retry++ < (props.ctx.config?.retry ?? AgenticaConstant.RETRY)) {
+      const trial: AgenticaExecuteHistory<Model> | null = await correct(
+        props.ctx,
+        props.call,
+        props.retry,
+        check.errors,
+      );
+      if (trial !== null) {
+        return trial;
       }
     }
-    try {
-      // CALL HTTP API
-      const response: IHttpResponse = await executeHttpOperation(call.operation, call.arguments);
-      // CHECK STATUS
-      const success: boolean
+  }
+
+  try {
+    // CALL HTTP API
+    const response: IHttpResponse = await executeHttpOperation(props.operation, props.call.arguments);
+    // CHECK STATUS
+    const success: boolean
           = ((response.status === 400
             || response.status === 404
             || response.status === 422)
-          && retry++ < (ctx.config?.retry ?? AgenticaConstant.RETRY)
+          && props.retry++ < (props.ctx.config?.retry ?? AgenticaConstant.RETRY)
           && typeof response.body) === false;
-        // DISPATCH EVENT
-      return (
-        (success === false
-          ? await correct(ctx, call, retry, response.body)
-          : null)
-        ?? createExecuteHistory({
-          operation: call.operation,
-          id: call.id,
-          arguments: call.arguments,
-          value: response,
-        })
-      );
-    }
-    catch (error) {
-      // DISPATCH ERROR
-      return createExecuteHistory({
-        operation: call.operation,
-        id: call.id,
-        arguments: call.arguments,
-        value: {
-          status: 500,
-          headers: {},
-          body:
-              error instanceof Error
-                ? {
-                    ...error,
-                    name: error.name,
-                    message: error.message,
-                  }
-                : error,
-        },
-      });
-    }
-  }
-  else {
-    // ----
-    // CLASS FUNCTION
-    // ----
-    // VALIDATE FIRST
-    const check: IValidation<unknown> = call.operation.function.validate(
-      call.arguments,
+      // DISPATCH EVENT
+    return (
+      (success === false
+        ? await correct(props.ctx, props.call, props.retry, response.body)
+        : null)
+      ?? createExecuteHistory({
+        operation: props.call.operation,
+        id: props.call.id,
+        arguments: props.call.arguments,
+        value: response,
+      })
     );
-    if (check.success === false) {
-      ctx.dispatch(
-        createValidateEvent({
-          id: call.id,
-          operation: call.operation,
-          result: check,
-        }),
-      ).catch(() => {});
-      return (
-        (retry++ < (ctx.config?.retry ?? AgenticaConstant.RETRY)
-          ? await correct(ctx, call, retry, check.errors)
-          : null)
-        ?? createExecuteHistory({
-          id: call.id,
-          operation: call.operation,
-          arguments: call.arguments,
-          value: {
-            name: "TypeGuardError",
-            message: "Invalid arguments.",
-            errors: check.errors,
-          },
-        })
-      );
-    }
-    // EXECUTE FUNCTION
-    try {
-      const value = await executeClassOperation(call.operation, call.arguments);
-      return createExecuteHistory({
-        id: call.id,
-        operation: call.operation,
-        arguments: call.arguments,
-        value,
-      });
-    }
-    catch (error) {
-      return createExecuteHistory({
-        id: call.id,
-        operation: call.operation,
-        arguments: call.arguments,
-        value:
+  }
+  catch (error) {
+    // DISPATCH ERROR
+    return createExecuteHistory({
+      operation: props.call.operation,
+      id: props.call.id,
+      arguments: props.call.arguments,
+      value: {
+        status: 500,
+        headers: {},
+        body:
           error instanceof Error
             ? {
                 ...error,
@@ -327,8 +296,109 @@ async function propagate<Model extends ILlmSchema.Model>(
                 message: error.message,
               }
             : error,
-      });
-    }
+      },
+    });
+  }
+}
+
+async function propagateClass<Model extends ILlmSchema.Model>(props: {
+  ctx: AgenticaContext<Model> | MicroAgenticaContext<Model>;
+  operation: AgenticaOperation.Class<Model>;
+  call: AgenticaCallEvent<Model>;
+  retry: number;
+}): Promise<AgenticaExecuteHistory<Model>> {
+// ----
+  // CLASS FUNCTION
+  // ----
+  // VALIDATE FIRST
+  const check: IValidation<unknown> = props.operation.function.validate(
+    props.call.arguments,
+  );
+
+  if (check.success === false) {
+    props.ctx.dispatch(
+      createValidateEvent({
+        id: props.call.id,
+        operation: props.call.operation,
+        result: check,
+      }),
+    ).catch(() => {});
+    return (
+      (props.retry++ < (props.ctx.config?.retry ?? AgenticaConstant.RETRY)
+        ? await correct(props.ctx, props.call, props.retry, check.errors)
+        : null)
+      ?? createExecuteHistory({
+        id: props.call.id,
+        operation: props.call.operation,
+        arguments: props.call.arguments,
+        value: {
+          name: "TypeGuardError",
+          message: "Invalid arguments.",
+          errors: check.errors,
+        },
+      })
+    );
+  }
+  // EXECUTE FUNCTION
+  try {
+    const value = await executeClassOperation(props.operation, props.call.arguments);
+    return createExecuteHistory({
+      id: props.call.id,
+      operation: props.call.operation,
+      arguments: props.call.arguments,
+      value,
+    });
+  }
+  catch (error) {
+    return createExecuteHistory({
+      id: props.call.id,
+      operation: props.call.operation,
+      arguments: props.call.arguments,
+      value:
+        error instanceof Error
+          ? {
+              ...error,
+              name: error.name,
+              message: error.message,
+            }
+          : error,
+    });
+  }
+}
+
+async function propagateMcp<Model extends ILlmSchema.Model>(props: {
+  ctx: AgenticaContext<Model> | MicroAgenticaContext<Model>;
+  operation: AgenticaOperation.Mcp;
+  call: AgenticaCallEvent<Model>;
+  retry: number;
+}): Promise<AgenticaExecuteHistory<Model>> {
+  // ----
+  // MCP PROTOCOL
+  // ----
+  // @TODO: implement argument validation logic
+  try {
+    const value = await executeMcpOperation(props.operation, props.call.arguments);
+    return createExecuteHistory({
+      id: props.call.id,
+      operation: props.call.operation,
+      arguments: props.call.arguments,
+      value,
+    });
+  }
+  catch (error) {
+    return createExecuteHistory({
+      id: props.call.id,
+      operation: props.call.operation,
+      arguments: props.call.arguments,
+      value:
+        error instanceof Error
+          ? {
+              ...error,
+              name: error.name,
+              message: error.message,
+            }
+          : error,
+    });
   }
 }
 
@@ -365,6 +435,36 @@ async function executeClassOperation<Model extends ILlmSchema.Model>(operation:
   return ((execute as Record<string, unknown>)[operation.function.name] as (...args: unknown[]) => Promise<unknown>)(operationArguments);
 }
 
+async function executeMcpOperation(operation: AgenticaOperation.Mcp, operationArguments: Record<string, unknown>): Promise<unknown> {
+  // for peerDependencies
+  const { Client } = await import("@modelcontextprotocol/sdk/client/index.js");
+  const { SSEClientTransport } = await import("@modelcontextprotocol/sdk/client/sse.js");
+  const { StdioClientTransport } = await import("@modelcontextprotocol/sdk/client/stdio.js");
+
+  const client = new Client({
+    name: operation.name,
+    version: "1.0.0",
+  });
+
+  const transport = (() => {
+    switch (operation.controller.application.transport.type) {
+      case "sse":
+        return new SSEClientTransport(operation.controller.application.transport.url);
+      case "stdio":
+        // @TODO: implement StdioClientTransport cache
+        // StdioClientTransport and connects a new child process every time it is initialized and connected.
+        // This results in significant latency and resource waste.
+        return new StdioClientTransport(operation.controller.application.transport);
+      default:
+        operation.controller.application.transport satisfies never;
+        throw new Error("Unsupported transport type");
+    }
+  })();
+  await client.connect(transport);
+  const result = await client.callTool({ method: operation.function.name, name: operation.function.name, arguments: operationArguments });
+  return result.content;
+}
+
 async function correct<Model extends ILlmSchema.Model>(
   ctx: AgenticaContext<Model> | MicroAgenticaContext<Model>,
   call: AgenticaCallEvent<Model>,
@@ -436,16 +536,18 @@ async function correct<Model extends ILlmSchema.Model>(
            * @TODO fix it
            * The property and value have a type mismatch, but it works.
            */
-          parameters: (call.operation.function.separated !== undefined
-            ? (call.operation.function.separated?.llm
-              ?? ({
-                $defs: {},
-                type: "object",
-                properties: {},
-                additionalProperties: false,
-                required: [],
-              } satisfies IChatGptSchema.IParameters))
-            : call.operation.function.parameters) as unknown as Record<string, unknown>,
+          parameters: (
+            "separated" in call.operation.function
+            && call.operation.function.separated !== undefined
+              ? (call.operation.function.separated?.llm
+                ?? ({
+                  $defs: {},
+                  type: "object",
+                  properties: {},
+                  additionalProperties: false,
+                  required: [],
+                } satisfies IChatGptSchema.IParameters))
+              : call.operation.function.parameters) as unknown as Record<string, unknown>,
         },
       },
     ],

package/src/structures/IAgenticaController.ts

@@ -8,6 +8,8 @@ import type {
   ILlmSchema,
 } from "@samchon/openapi";
 
+import type { IMcpLlmApplication } from "./mcp/IMcpLlmApplication";
+
 /**
  * Controller of the Agentica Agent.
  *
@@ -18,14 +20,17 @@ import type {
  * Also, `IAgenticaController` is an union type which can specify
  * a subtype by checking the {@link protocol} property.
  *
- * - HTTP server: {@link IAgenticaController..IHttp}
+ * - HTTP server: {@link IAgenticaController.IHttp}
  * - TypeScript class: {@link IAgenticaController.IClass}
+ * - MCP Server: {@link IAgenticaController.IMcp}
  *
  * @author Samchon
  */
 export type IAgenticaController<Model extends ILlmSchema.Model> =
   | IAgenticaController.IHttp<Model>
-  | IAgenticaController.IClass<Model>;
+  | IAgenticaController.IClass<Model>
+  | IAgenticaController.IMcp;
+
 export namespace IAgenticaController {
   /**
    * HTTP controller.
@@ -114,6 +119,11 @@ export namespace IAgenticaController {
       }) => Promise<unknown>);
   }
 
+  /**
+   * MCP Server controller.
+   */
+  export interface IMcp extends IBase<"mcp", IMcpLlmApplication> { }
+
   interface IBase<Protocol, Application> {
     /**
      * Protocol discrminator.

package/src/structures/mcp/IMcpLlmApplication.ts

@@ -0,0 +1,17 @@
+import type { IMcpLlmFunction } from "./IMcpLlmFunction";
+import type { IMcpLlmTransportProps } from "./IMcpLlmTransportProps";
+
+/**
+ * MCP LLM application.
+ */
+export interface IMcpLlmApplication {
+  /**
+   * Functions of the MCP server.
+   */
+  functions: IMcpLlmFunction[];
+
+  /**
+   * Transport properties of the MCP server.
+   */
+  transport: IMcpLlmTransportProps;
+}

package/src/structures/mcp/IMcpLlmFunction.ts

@@ -0,0 +1,19 @@
+/**
+ * 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/src/structures/mcp/IMcpLlmTransportProps.ts

@@ -0,0 +1,13 @@
+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/src/structures/mcp/index.ts

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