export function registerMcpControllers(props: {
  server: McpServer | Server;
  controllers: Array<ILlmController | IHttpLlmController>;
  preserve?: boolean | undefined;
}): void;

import { ILlmApplication } from "./ILlmApplication";
 
/**
 * Controller of TypeScript class-based LLM function calling.
 *
 * `ILlmController` is a controller for registering TypeScript class methods as
 * LLM function calling tools. It contains {@link ILlmApplication} with
 * {@link ILlmFunction function calling schemas}, {@link name identifier}, and
 * {@link execute class instance} for method execution.
 *
 * You can create this controller with `typia.llm.controller<Class>()` function,
 * and register it to MCP server with {@link registerMcpControllers}:
 *
 * ```typescript
 * import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 * import { registerMcpControllers } from "@typia/mcp";
 * import typia from "typia";
 *
 * class Calculator {
 *   add(input: { a: number; b: number }): number {
 *     return input.a + input.b;
 *   }
 *   subtract(input: { a: number; b: number }): number {
 *     return input.a - input.b;
 *   }
 * }
 *
 * const server = new McpServer({ name: "my-server", version: "1.0.0" });
 * registerMcpControllers({
 *   server,
 *   controllers: [
 *     typia.llm.controller<Calculator>("calculator", new Calculator()),
 *   ],
 * });
 * ```
 *
 * For OpenAPI/HTTP-based controller, use {@link IHttpLlmController} instead.
 *
 * @author Jeongho Nam - https://github.com/samchon
 * @template Class Class type of the function executor
 */
export interface ILlmController<Class extends object = any> {
  /** Protocol discriminator. */
  protocol: "class";
 
  /** Identifier name of the controller. */
  name: string;
 
  /** Application schema of function calling. */
  application: ILlmApplication<Class>;
 
  /** Target class instance for function execution. */
  execute: Class;
}

import { IHttpConnection } from "./IHttpConnection";
import { IHttpLlmApplication } from "./IHttpLlmApplication";
import { IHttpLlmFunction } from "./IHttpLlmFunction";
import { IHttpResponse } from "./IHttpResponse";
 
/**
 * Controller of HTTP LLM function calling.
 *
 * `IHttpLlmController` is a controller for registering OpenAPI operations as
 * LLM function calling tools. It contains {@link IHttpLlmApplication} with
 * {@link IHttpLlmFunction function calling schemas}, {@link name identifier}, and
 * {@link connection} to the API server.
 *
 * You can create this controller with {@link HttpLlm.controller} function, and
 * register it to MCP server with {@link registerMcpControllers}:
 *
 * ```typescript
 * import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 * import { registerMcpControllers } from "@typia/mcp";
 * import { HttpLlm } from "@typia/utils";
 *
 * const server = new McpServer({ name: "my-server", version: "1.0.0" });
 * registerMcpControllers({
 *   server,
 *   controllers: [
 *     HttpLlm.controller({
 *       name: "shopping",
 *       document: await fetch(
 *         "https://shopping-be.wrtn.io/editor/swagger.json",
 *       ).then((r) => r.json()),
 *       connection: {
 *         host: "https://shopping-be.wrtn.io",
 *         headers: {
 *           Authorization: "Bearer ********",
 *         },
 *       },
 *     }),
 *   ],
 * });
 * ```
 *
 * For TypeScript class-based controller, use {@link ILlmController} instead.
 *
 * @author Jeongho Nam - https://github.com/samchon
 */
export interface IHttpLlmController {
  /** Protocol discriminator. */
  protocol: "http";
 
  /** Identifier name of the controller. */
  name: string;
 
  /** Application schema of function calling. */
  application: IHttpLlmApplication;
 
  /**
   * Connection to the server.
   *
   * Connection to the API server including the URL and headers.
   */
  connection: IHttpConnection;
 
  /**
   * Executor of the API function.
   *
   * Default executor is {@link HttpLlm.execute} function, and you can override
   * it with your own function.
   *
   * @param props Properties of the API function call
   * @returns HTTP response of the API function call
   */
  execute?:
    | undefined
    | ((props: {
        /** Connection to the server. */
        connection: IHttpConnection;
 
        /** Application schema. */
        application: IHttpLlmApplication;
 
        /** Function schema. */
        function: IHttpLlmFunction;
 
        /**
         * Arguments of the function calling.
         *
         * It is an object of key-value pairs of the API function's parameters.
         * The property keys are composed by below rules:
         *
         * - Parameter names
         * - Query parameter as an object type if exists
         * - Body parameter if exists
         */
        arguments: object;
      }) => Promise<IHttpResponse>);
}

import {
  IHttpConnection,
  IHttpLlmApplication,
  IHttpLlmController,
  IHttpLlmFunction,
  IHttpMigrateApplication,
  IHttpResponse,
  OpenApi,
  OpenApiV3,
  OpenApiV3_1,
  OpenApiV3_2,
  SwaggerV2,
} from "@typia/interface";
 
import { HttpMigration } from "./HttpMigration";
import { HttpLlmApplicationComposer } from "./internal/HttpLlmApplicationComposer";
import { HttpLlmFunctionFetcher } from "./internal/HttpLlmFunctionFetcher";
 
/**
 * LLM function calling utilities for OpenAPI documents.
 *
 * `HttpLlm` converts OpenAPI documents into LLM function calling applications
 * and executes them. Supports all OpenAPI versions (Swagger 2.0, OpenAPI 3.0,
 * 3.1) through automatic conversion to {@link OpenApi} format.
 *
 * Main functions:
 *
 * - {@link controller}: Create {@link IHttpLlmController} from OpenAPI document
 * - {@link application}: Convert OpenAPI document to {@link IHttpLlmApplication}
 * - {@link execute}: Call an LLM function and return the response body
 * - {@link propagate}: Call an LLM function and return full HTTP response
 * - {@link mergeParameters}: Merge LLM-filled and human-filled parameters
 *
 * Typical workflow:
 *
 * 1. Load OpenAPI document (JSON/YAML)
 * 2. Call `HttpLlm.application()` to get function schemas
 * 3. Send function schemas to LLM for function selection
 * 4. Call `HttpLlm.execute()` with LLM's chosen function and arguments
 *
 * @author Jeongho Nam - https://github.com/samchon
 */
export namespace HttpLlm {
  /* -----------------------------------------------------------
    COMPOSERS
  ----------------------------------------------------------- */
  /**
   * Create HTTP LLM controller from OpenAPI document.
   *
   * Composes {@link IHttpLlmController} from OpenAPI document with connection
   * info. The controller can be used with {@link registerMcpControllers} to
   * register all API operations as MCP tools at once.
   *
   * @param props Controller properties
   * @returns HTTP LLM controller
   */
  export const controller = (props: {
    /** Identifier name of the controller. */
    name: string;
 
    /** OpenAPI document to convert. */
    document:
      | OpenApi.IDocument
      | SwaggerV2.IDocument
      | OpenApiV3.IDocument
      | OpenApiV3_1.IDocument
      | OpenApiV3_2.IDocument;
 
    /** Connection to the API server. */
    connection: IHttpConnection;
 
    /** LLM schema conversion configuration. */
    config?: Partial<IHttpLlmApplication.IConfig>;
 
    /**
     * Custom executor of the API function.
     *
     * Default executor is {@link HttpLlm.execute} function.
     */
    execute?: IHttpLlmController["execute"];
  }): IHttpLlmController => ({
    protocol: "http",
    name: props.name,
    application: application({
      document: props.document,
      config: props.config,
    }),
    connection: props.connection,
    execute: props.execute,
  });
 
  /**
   * Convert OpenAPI document to LLM function calling application.
   *
   * Converts API operations to LLM-callable functions.
   *
   * @param props Composition properties
   * @returns LLM function calling application
   */
  export const application = (props: {
    /** OpenAPI document to convert. */
    document:
      | OpenApi.IDocument
      | SwaggerV2.IDocument
      | OpenApiV3.IDocument
      | OpenApiV3_1.IDocument
      | OpenApiV3_2.IDocument;
 
    /** LLM schema conversion configuration. */
    config?: Partial<IHttpLlmApplication.IConfig>;
  }): IHttpLlmApplication => {
    // MIGRATE
    const migrate: IHttpMigrateApplication = HttpMigration.application(
      props.document,
    );
    return HttpLlmApplicationComposer.application({
      migrate,
      config: {
        strict: props.config?.strict ?? false,
        maxLength: props.config?.maxLength ?? 64,
        equals: props.config?.equals ?? false,
      },
    });
  };
 
  /* -----------------------------------------------------------
    FETCHERS
  ----------------------------------------------------------- */
  /** Properties for LLM function call. */
  export interface IFetchProps {
    /** LLM function calling application. */
    application: IHttpLlmApplication;
 
    /** Function to call. */
    function: IHttpLlmFunction;
 
    /** HTTP connection info. */
    connection: IHttpConnection;
 
    /** Function arguments. */
    input: object;
  }
 
  /**
   * Execute LLM function call.
   *
   * Calls API endpoint and returns response body. Throws {@link HttpError} on
   * non-2xx status.
   *
   * @param props Function call properties
   * @returns Response body
   * @throws HttpError on non-2xx status
   */
  export const execute = (props: IFetchProps): Promise<unknown> =>
    HttpLlmFunctionFetcher.execute(props);
 
  /**
   * Propagate LLM function call.
   *
   * Calls API endpoint and returns full response including non-2xx. Use when
   * you need to handle error responses yourself.
   *
   * @param props Function call properties
   * @returns Full HTTP response
   * @throws Error only on connection failure
   */
  export const propagate = (props: IFetchProps): Promise<IHttpResponse> =>
    HttpLlmFunctionFetcher.propagate(props);
}

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { registerMcpControllers } from "@typia/mcp";
import typia from "typia";
 
import { BbsArticleService } from "./BbsArticleService";
import { Calculator } from "./Calculator";
 
const server: McpServer = new McpServer({
  name: "my-server",
  version: "1.0.0",
});
registerMcpControllers({
  server,
  controllers: [
    typia.llm.controller<Calculator>("calculator", new Calculator()),
    typia.llm.controller<BbsArticleService>(
      "bbs",
      new BbsArticleService(),
    ),
  ],
});

export class Calculator {
  /**
   * Add two numbers.
   *
   * @param p The input containing two numbers to add
   * @returns The sum of a and b
   */
  add(p: Calculator.IProps): Calculator.IResult {
    return { value: p.x + p.y };
  }
 
  /**
   * Subtract two numbers.
   *
   * @param p The input containing two numbers to subtract
   * @returns The difference of a and b
   */
  subtract(p: Calculator.IProps): Calculator.IResult {
    return { value: p.x - p.y };
  }
 
  /**
   * Multiply two numbers.
   *
   * @param p The input containing two numbers to multiply
   * @returns The product of a and b
   */
  multiply(p: Calculator.IProps): Calculator.IResult {
    return { value: p.x * p.y };
  }
 
  /**
   * Divide two numbers.
   *
   * @param p The input containing two numbers to divide
   * @returns The quotient of a and b
   */
  divide(p: Calculator.IProps): Calculator.IResult {
    if (p.y === 0) {
      throw new Error("Division by zero is not allowed");
    }
    return { value: p.x / p.y };
  }
}
export namespace Calculator {
  export interface IProps {
    /** First operand */
    x: number;
 
    /** Second operand */
    y: number;
  }
 
  /** Result of a calculation. */
  export interface IResult {
    /** Calculated value */
    value: number;
  }
}

import { tags } from "typia";
 
import { IBbsArticle } from "./IBbsArticle";
 
export declare class BbsArticleService {
  /**
   * Get all articles.
   *
   * List up every articles archived in the BBS DB.
   *
   * @returns List of every articles
   */
  public index(): IBbsArticle.IPage;
 
  /**
   * Create a new article.
   *
   * Writes a new article and archives it into the DB.
   *
   * @param props Properties of create function
   * @returns Newly created article
   */
  public create(props: {
    /** Information of the article to create */
    input: IBbsArticle.ICreate;
  }): IBbsArticle;
 
  /**
   * Update an article.
   *
   * Updates an article with new content.
   *
   * @param props Properties of update function
   * @param input New content to update
   */
  public update(props: {
    /** Target article's {@link IBbsArticle.id}. */
    id: string & tags.Format<"uuid">;
 
    /** New content to update. */
    input: IBbsArticle.IUpdate;
  }): void;
 
  /**
   * Erase an article.
   *
   * Erases an article from the DB.
   *
   * @param props Properties of erase function
   */
  public erase(props: {
    /** Target article's {@link IBbsArticle.id}. */
    id: string & tags.Format<"uuid">;
  }): void;
}

import { tags } from "typia";
 
/**
 * Article entity.
 *
 * `IBbsArticle` is an entity representing an article in the BBS (Bulletin Board
 * System).
 */
export interface IBbsArticle extends IBbsArticle.ICreate {
  /** Primary Key. */
  id: string & tags.Format<"uuid">;
 
  /** Creation time of the article. */
  created_at: string & tags.Format<"date-time">;
 
  /** Last updated time of the article. */
  updated_at: string & tags.Format<"date-time">;
}
export namespace IBbsArticle {
  /** Information of the article to create. */
  export interface ICreate {
    /**
     * Title of the article.
     *
     * Representative title of the article.
     */
    title: string;
 
    /**
     * Content body.
     *
     * Content body of the article written in the markdown format.
     */
    body: string;
 
    /**
     * Thumbnail image URI.
     *
     * Thumbnail image URI which can represent the article.
     *
     * If configured as `null`, it means that no thumbnail image in the article.
     */
    thumbnail:
      | null
      | (string & tags.Format<"uri"> & tags.ContentMediaType<"image/*">);
  }
 
  /**
   * Information of the article to update.
   *
   * Only the filled properties will be updated.
   */
  export type IUpdate = Partial<ICreate>;
 
  /** Page of articles. */
  export interface IPage {
    /** List of articles. */
    articles: IBbsArticle[];
  }
}

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { TestValidator } from "@nestia/e2e";
import { ILlmController } from "@typia/interface";
import { registerMcpControllers } from "@typia/mcp";
import typia from "typia";
import { z } from "zod";
 
import { Calculator } from "../structures/Calculator";
 
export const test_mcp_class_controller_preserve = async (): Promise<void> => {
  // 1. Create class-based controller using typia.llm.controller
  const controller: ILlmController<Calculator> =
    typia.llm.controller<Calculator>("calculator", new Calculator());
 
  // 2. Create McpServer with tools capability
  const mcpServer: McpServer = new McpServer(
    {
      name: "test-server",
      version: "1.0.0",
    },
    {
      capabilities: {
        tools: {},
      },
    },
  );
 
  // 3. Register existing tool via McpServer.registerTool() with zod schema
  const inputSchema: z.ZodObject<{ message: z.ZodString }> = z.object({
    message: z.string().describe("Message to echo"),
  });
  (mcpServer.registerTool as Function)(
    "echo",
    {
      description: "Echo a message",
      inputSchema,
    },
    async (args: z.infer<typeof inputSchema>) => ({
      content: [
        {
          type: "text",
          text: args.message,
        },
      ],
    }),
  );
 
  // 4. Register with preserve: true
  registerMcpControllers({
    server: mcpServer,
    controllers: [controller],
    preserve: true,
  });
 
  // 5. Verify private API IS used
  const registeredTools: Record<string, unknown> =
    (mcpServer as any)._registeredTools ?? {};
  const handlersInitialized: boolean = (mcpServer as any)
    ._toolHandlersInitialized;
 
  TestValidator.equals(
    "existing echo tool should be present",
    Object.keys(registeredTools).includes("echo"),
    true,
  );
  TestValidator.equals(
    "_toolHandlersInitialized should be true",
    handlersInitialized,
    true,
  );
 
  // 6. Call tools/list to verify all tools (echo + calculator)
  const rawServer: Server = mcpServer.server;
  const requestHandlers: Map<string, Function> = (rawServer as any)
    ._requestHandlers;
  const listHandler: Function = requestHandlers.get("tools/list")!;
  const result: { tools: { name: string }[] } = await listHandler(
    {
      method: "tools/list",
      params: {},
    },
    {
      signal: new AbortController().signal,
    },
  );
 
  const toolNames: string[] = result.tools.map((t) => t.name).sort();
 
  // Should have 5 tools: echo + add, subtract, multiply, divide
  TestValidator.equals("should have 5 tools total", result.tools.length, 5);
  TestValidator.predicate(
    "should include echo tool",
    toolNames.includes("echo"),
  );
  TestValidator.predicate("should include add tool", toolNames.includes("add"));
  TestValidator.predicate(
    "should include subtract tool",
    toolNames.includes("subtract"),
  );
  TestValidator.predicate(
    "should include multiply tool",
    toolNames.includes("multiply"),
  );
  TestValidator.predicate(
    "should include divide tool",
    toolNames.includes("divide"),
  );
};

export class Calculator {
  /**
   * Add two numbers.
   *
   * @param p The input containing two numbers to add
   * @returns The sum of a and b
   */
  add(p: Calculator.IProps): Calculator.IResult {
    return { value: p.x + p.y };
  }
 
  /**
   * Subtract two numbers.
   *
   * @param p The input containing two numbers to subtract
   * @returns The difference of a and b
   */
  subtract(p: Calculator.IProps): Calculator.IResult {
    return { value: p.x - p.y };
  }
 
  /**
   * Multiply two numbers.
   *
   * @param p The input containing two numbers to multiply
   * @returns The product of a and b
   */
  multiply(p: Calculator.IProps): Calculator.IResult {
    return { value: p.x * p.y };
  }
 
  /**
   * Divide two numbers.
   *
   * @param p The input containing two numbers to divide
   * @returns The quotient of a and b
   */
  divide(p: Calculator.IProps): Calculator.IResult {
    if (p.y === 0) {
      throw new Error("Division by zero is not allowed");
    }
    return { value: p.x / p.y };
  }
}
export namespace Calculator {
  export interface IProps {
    /** First operand */
    x: number;
 
    /** Second operand */
    y: number;
  }
 
  /** Result of a calculation. */
  export interface IResult {
    /** Calculated value */
    value: number;
  }
}