@nestia/core/lib/adaptors/McpAdaptor.d.ts

Super-fast validation decorators of NestJS

import { INestApplication } from "@nestjs/common";
/**
 * MCP (Model Context Protocol) adaptor.
 *
 * `McpAdaptor` exposes every method decorated with {@link McpRoute} as an MCP
 * tool, reachable by LLM clients through a stateless Streamable HTTP endpoint.
 *
 * At bootstrap the adaptor walks the {@link NestContainer}, collects every
 * controller method carrying `"nestia/McpRoute"` metadata, and caches a tool
 * registry. A fresh MCP server and transport pair is spun up per incoming HTTP
 * request, following MCP stateless Streamable HTTP mode. This adaptor
 * intentionally does not manage `Mcp-Session-Id` state.
 *
 * Typia-generated JSON Schemas flow through unchanged; the Zod-based high-level
 * registration API of `McpServer` is bypassed by accessing the low-level
 * `.server` handler.
 *
 * Error mapping follows the MCP specification:
 *
 * - Unknown tool name: JSON-RPC `-32601`.
 * - Typia validation failure: JSON-RPC `-32602` with structured diagnostics.
 * - Handler throws {@link HttpException}: success response with `isError: true`,
 *   so the LLM can read the message and recover.
 * - Any other throw: JSON-RPC `-32603`.
 *
 * @author wildduck - https://github.com/wildduck2
 * @example
 *   ```typescript
 *   import core from "@nestia/core";
 *   import { NestFactory } from "@nestjs/core";
 *
 *   const app = await NestFactory.create(AppModule);
 *   await core.McpAdaptor.upgrade(app, { path: "/mcp" });
 *   await app.listen(3000);
 *   ```;
 */
export declare class McpAdaptor {
    /**
     * Upgrade a running Nest application with a stateless MCP endpoint.
     *
     * Scans the application container for methods decorated with {@link McpRoute},
     * then registers a catch-all HTTP route at the configured path. Each incoming
     * request builds a fresh MCP server + transport on demand, wires the
     * registered tools into it, and delegates handling.
     *
     * Must be called after `NestFactory.create(...)` but before `app.listen(...)`
     * if you want the MCP endpoint to be reachable alongside your regular HTTP
     * routes.
     *
     * @param app Running Nest application instance.
     * @param options Transport and identity overrides.
     */
    static upgrade(app: INestApplication, options?: McpAdaptor.IOptions): Promise<void>;
}
export declare namespace McpAdaptor {
    /** Configuration options for {@link McpAdaptor.upgrade}. */
    interface IOptions {
        /**
         * HTTP path where the MCP endpoint will be mounted.
         *
         * @default "/mcp"
         */
        path?: string;
        /**
         * Identity advertised to MCP clients during the initialize handshake. Shows
         * up in Claude Desktop / Cursor's MCP panel.
         *
         * @default { name: "nestia-mcp", version: "1.0.0" }
         */
        serverInfo?: {
            name: string;
            version: string;
        };
    }
}