mcp-server-framework 1.0.0

package/build/logger/writers/file-writer.d.ts

@@ -0,0 +1,160 @@
+/**
+ * File Log Writer Module
+ *
+ * Writes log entries to files organized by component.
+ * Handles stream creation, directory management, and graceful shutdown.
+ *
+ * @module logger/writers/file-writer
+ */
+import type { LogLevel } from "../core/types.js";
+import { BaseLogWriter } from "./base-writer.js";
+/**
+ * Configuration for the file writer.
+ */
+export interface FileWriterConfig {
+    /** Directory to write log files to */
+    logDir: string;
+    /** Component names to create streams for (default: ['server', 'api', 'transport']) */
+    components?: readonly string[];
+    /** File extension for log files (default: '.log') */
+    extension?: string;
+    /** Fallback component when requested component has no stream */
+    fallbackComponent?: string;
+    /**
+     * Maximum file size in bytes before rotation (default: 10 MB).
+     * When a log file exceeds this size, it is renamed to `<component>.1.log`
+     * and a new file is created. Set to 0 to disable rotation.
+     */
+    maxFileSize?: number | undefined;
+    /**
+     * Maximum number of rotated files to keep per component (default: 3).
+     * Older files beyond this count are deleted during rotation.
+     */
+    maxFiles?: number | undefined;
+    /**
+     * Log file retention in days. Files (including rotated) older than this
+     * are deleted automatically. Set to 0 to disable (default: 0).
+     */
+    retentionDays?: number | undefined;
+}
+/**
+ * File Writer class for writing logs to files.
+ *
+ * Features:
+ * - Creates separate log files per component
+ * - Size-based log rotation with configurable limits
+ * - Automatic directory creation
+ * - Graceful stream shutdown
+ * - Fallback to default component when stream not found
+ *
+ * @example
+ * ```typescript
+ * const writer = new FileWriter({
+ *   logDir: '/var/log/app',
+ *   maxFileSize: 5 * 1024 * 1024, // 5 MB
+ *   maxFiles: 5,
+ * });
+ * writer.write('info', 'Server started', 'server');
+ * await writer.close();
+ * ```
+ */
+export declare class FileWriter extends BaseLogWriter {
+    private streams;
+    private logDir;
+    private extension;
+    private fallbackComponent;
+    private initialized;
+    /** Rotation config */
+    private readonly maxFileSize;
+    private readonly maxFiles;
+    private readonly retentionDays;
+    /** Track approximate bytes written per component for rotation checks */
+    private bytesWritten;
+    /** Guard against concurrent rotation */
+    private rotating;
+    /** Retention cleanup interval */
+    private retentionTimer;
+    /** Default max file size: 10 MB */
+    private static readonly DEFAULT_MAX_FILE_SIZE;
+    /** Default max rotated files to keep */
+    private static readonly DEFAULT_MAX_FILES;
+    /** Retention cleanup interval: once per day */
+    private static readonly RETENTION_CHECK_INTERVAL_MS;
+    /**
+     * Create a new FileWriter.
+     * @param config - Writer configuration
+     */
+    constructor(config: FileWriterConfig);
+    /**
+     * Initialize streams for the specified components.
+     */
+    private initialize;
+    /**
+     * Create a write stream for a component.
+     * Includes error handling to prevent unhandled stream errors.
+     * Initializes byte tracking from existing file size for rotation.
+     */
+    private createStream;
+    /**
+     * Write a log message to the appropriate file.
+     * Triggers rotation when the file exceeds `maxFileSize`.
+     *
+     * @param _level - The log level (unused for files)
+     * @param message - The formatted log message
+     * @param component - The component (determines which file)
+     */
+    write(_level: LogLevel, message: string, component: string): void;
+    /**
+     * Rotate the log file for a component.
+     *
+     * Rotation chain: `server.log` → `server.1.log` → `server.2.log` → ...
+     * Files beyond `maxFiles` are deleted. The current stream is replaced.
+     *
+     * Rotation is **synchronous** to guarantee ordering — log writes that arrive
+     * during rotation are safe because Node.js is single-threaded.
+     */
+    private rotateFile;
+    /**
+     * Delete log files older than `retentionDays`.
+     *
+     * Scans the log directory for files matching the configured extension
+     * and removes any whose `mtime` exceeds the retention threshold.
+     * Called once at startup and then once per day.
+     */
+    private cleanExpiredFiles;
+    /** Build the primary log file path for a component. */
+    private getFilePath;
+    /** Build the rotated file path: `<component>.<n><extension>` */
+    private getRotatedPath;
+    /** Rename a file if it exists; ignore errors silently. */
+    private renameSafe;
+    /** Delete a file if it exists; ignore errors silently. */
+    private unlinkSafe;
+    /**
+     * Close all streams gracefully.
+     * Should be called during application shutdown to ensure all logs are flushed.
+     *
+     * @returns Promise that resolves when all streams are closed
+     */
+    close(): Promise<void>;
+    /**
+     * Check if the writer has been initialized successfully.
+     */
+    isAvailable(): boolean;
+    /**
+     * Check if a stream exists for a component.
+     */
+    hasStream(component: string): boolean;
+    /**
+     * Add a new stream for a component.
+     *
+     * @param component - The component name
+     * @returns true if stream was created successfully
+     */
+    addStream(component: string): boolean;
+    /**
+     * Get the number of active streams.
+     */
+    getStreamCount(): number;
+}
+//# sourceMappingURL=file-writer.d.ts.map

package/build/logger/writers/file-writer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-writer.d.ts","sourceRoot":"","sources":["../../../src/logger/writers/file-writer.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAEjD,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEjD;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,sCAAsC;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,sFAAsF;IACtF,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B,qDAAqD;IACrD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gEAAgE;IAChE,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACpC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,UAAW,SAAQ,aAAa;IAC3C,OAAO,CAAC,OAAO,CAA0C;IACzD,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,iBAAiB,CAAS;IAClC,OAAO,CAAC,WAAW,CAAkB;IAErC,sBAAsB;IACtB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,wEAAwE;IACxE,OAAO,CAAC,YAAY,CAAkC;IACtD,wCAAwC;IACxC,OAAO,CAAC,QAAQ,CAA0B;IAC1C,iCAAiC;IACjC,OAAO,CAAC,cAAc,CAA+C;IAErE,mCAAmC;IACnC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,qBAAqB,CAAoB;IACjE,wCAAwC;IACxC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,iBAAiB,CAAK;IAC9C,+CAA+C;IAC/C,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,2BAA2B,CAAuB;IAE1E;;;OAGG;gBACS,MAAM,EAAE,gBAAgB;IAWpC;;OAEG;IACH,OAAO,CAAC,UAAU;IAgClB;;;;OAIG;IACH,OAAO,CAAC,YAAY;IA2CpB;;;;;;;OAOG;IACH,KAAK,CAAC,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;IAyBjE;;;;;;;;OAQG;IACH,OAAO,CAAC,UAAU;IA6ClB;;;;;;OAMG;IACH,OAAO,CAAC,iBAAiB;IA6BzB,uDAAuD;IACvD,OAAO,CAAC,WAAW;IAKnB,gEAAgE;IAChE,OAAO,CAAC,cAAc;IAKtB,0DAA0D;IAC1D,OAAO,CAAC,UAAU;IAUlB,0DAA0D;IAC1D,OAAO,CAAC,UAAU;IAUlB;;;;;OAKG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA2B5B;;OAEG;IACH,WAAW,IAAI,OAAO;IAItB;;OAEG;IACH,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAIrC;;;;;OAKG;IACH,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAIrC;;OAEG;IACH,cAAc,IAAI,MAAM;CAGzB"}

package/build/logger/writers/file-writer.js

@@ -0,0 +1,345 @@
+/**
+ * File Log Writer Module
+ *
+ * Writes log entries to files organized by component.
+ * Handles stream creation, directory management, and graceful shutdown.
+ *
+ * @module logger/writers/file-writer
+ */
+import * as fs from "fs";
+import * as path from "path";
+import { DEFAULT_LOG_COMPONENTS, LOG_FILE_EXTENSION } from "../core/constants.js";
+import { BaseLogWriter } from "./base-writer.js";
+/**
+ * File Writer class for writing logs to files.
+ *
+ * Features:
+ * - Creates separate log files per component
+ * - Size-based log rotation with configurable limits
+ * - Automatic directory creation
+ * - Graceful stream shutdown
+ * - Fallback to default component when stream not found
+ *
+ * @example
+ * ```typescript
+ * const writer = new FileWriter({
+ *   logDir: '/var/log/app',
+ *   maxFileSize: 5 * 1024 * 1024, // 5 MB
+ *   maxFiles: 5,
+ * });
+ * writer.write('info', 'Server started', 'server');
+ * await writer.close();
+ * ```
+ */
+export class FileWriter extends BaseLogWriter {
+    streams = new Map();
+    logDir;
+    extension;
+    fallbackComponent;
+    initialized = false;
+    /** Rotation config */
+    maxFileSize;
+    maxFiles;
+    retentionDays;
+    /** Track approximate bytes written per component for rotation checks */
+    bytesWritten = new Map();
+    /** Guard against concurrent rotation */
+    rotating = new Set();
+    /** Retention cleanup interval */
+    retentionTimer = null;
+    /** Default max file size: 10 MB */
+    static DEFAULT_MAX_FILE_SIZE = 10 * 1024 * 1024;
+    /** Default max rotated files to keep */
+    static DEFAULT_MAX_FILES = 3;
+    /** Retention cleanup interval: once per day */
+    static RETENTION_CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+    /**
+     * Create a new FileWriter.
+     * @param config - Writer configuration
+     */
+    constructor(config) {
+        super();
+        this.logDir = config.logDir;
+        this.extension = config.extension ?? LOG_FILE_EXTENSION;
+        this.fallbackComponent = config.fallbackComponent ?? "server";
+        this.maxFileSize = config.maxFileSize ?? FileWriter.DEFAULT_MAX_FILE_SIZE;
+        this.maxFiles = config.maxFiles ?? FileWriter.DEFAULT_MAX_FILES;
+        this.retentionDays = config.retentionDays ?? 0;
+        this.initialize(config.components ?? DEFAULT_LOG_COMPONENTS);
+    }
+    /**
+     * Initialize streams for the specified components.
+     */
+    initialize(components) {
+        if (this.initialized)
+            return;
+        try {
+            // Ensure log directory exists
+            if (!fs.existsSync(this.logDir)) {
+                fs.mkdirSync(this.logDir, { recursive: true });
+            }
+            // Create streams for each component
+            for (const component of components) {
+                this.createStream(component);
+            }
+            this.initialized = true;
+            // Start retention cleanup if enabled
+            if (this.retentionDays > 0) {
+                // Run once immediately, then periodically
+                this.cleanExpiredFiles();
+                this.retentionTimer = setInterval(() => this.cleanExpiredFiles(), FileWriter.RETENTION_CHECK_INTERVAL_MS);
+                // Allow the process to exit even if the timer is still running
+                this.retentionTimer.unref();
+            }
+        }
+        catch (error) {
+            // File logging is optional — report failure on stderr (stdout reserved for MCP protocol)
+            const message = error instanceof Error ? error.message : String(error);
+            process.stderr.write(`[FileWriter] Initialization failed (file logging disabled): ${message}\n`);
+            this.enabled = false;
+        }
+    }
+    /**
+     * Create a write stream for a component.
+     * Includes error handling to prevent unhandled stream errors.
+     * Initializes byte tracking from existing file size for rotation.
+     */
+    createStream(component) {
+        if (this.streams.has(component)) {
+            return true;
+        }
+        try {
+            const filePath = this.getFilePath(component);
+            const stream = fs.createWriteStream(filePath, { flags: "a" });
+            // Handle stream errors to prevent unhandled exceptions
+            stream.on("error", (err) => {
+                // Log to stderr since our logger might not be available
+                process.stderr.write(`[FileWriter] Stream error for ${component}: ${err.message}\n`);
+                // Remove the broken stream
+                this.streams.delete(component);
+                // If the log directory was deleted externally, attempt recovery
+                if (err.code === "ENOENT") {
+                    try {
+                        fs.mkdirSync(this.logDir, { recursive: true });
+                        this.createStream(component);
+                    }
+                    catch {
+                        process.stderr.write(`[FileWriter] Directory recovery failed for ${component} — file logging disabled\n`);
+                    }
+                }
+            });
+            this.streams.set(component, stream);
+            // Initialize byte counter from existing file size (for rotation accuracy after restart)
+            try {
+                const stats = fs.statSync(filePath);
+                this.bytesWritten.set(component, stats.size);
+            }
+            catch {
+                this.bytesWritten.set(component, 0);
+            }
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Write a log message to the appropriate file.
+     * Triggers rotation when the file exceeds `maxFileSize`.
+     *
+     * @param _level - The log level (unused for files)
+     * @param message - The formatted log message
+     * @param component - The component (determines which file)
+     */
+    write(_level, message, component) {
+        if (!this.enabled || !this.initialized)
+            return;
+        // Resolve effective component (fallback if stream missing)
+        const effectiveComponent = this.streams.has(component) ? component : this.fallbackComponent;
+        const stream = this.streams.get(effectiveComponent);
+        if (!stream)
+            return;
+        const data = message + "\n";
+        stream.write(data);
+        // Track approximate bytes written for rotation
+        const written = (this.bytesWritten.get(effectiveComponent) ?? 0) + Buffer.byteLength(data);
+        this.bytesWritten.set(effectiveComponent, written);
+        // Trigger rotation when file exceeds limit (skip if rotation disabled or already in progress)
+        if (this.maxFileSize > 0 && written >= this.maxFileSize && !this.rotating.has(effectiveComponent)) {
+            this.rotateFile(effectiveComponent);
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Rotation
+    // ---------------------------------------------------------------------------
+    /**
+     * Rotate the log file for a component.
+     *
+     * Rotation chain: `server.log` → `server.1.log` → `server.2.log` → ...
+     * Files beyond `maxFiles` are deleted. The current stream is replaced.
+     *
+     * Rotation is **synchronous** to guarantee ordering — log writes that arrive
+     * during rotation are safe because Node.js is single-threaded.
+     */
+    rotateFile(component) {
+        this.rotating.add(component);
+        try {
+            // 1. Close the current stream synchronously.
+            //    destroy() releases the file descriptor immediately (unlike end()
+            //    which queues async close). This prevents EACCES on Windows when
+            //    renaming the file in step 4.
+            const oldStream = this.streams.get(component);
+            if (oldStream) {
+                oldStream.destroy();
+                this.streams.delete(component);
+            }
+            const basePath = this.getFilePath(component);
+            // 2. Delete oldest file if it exceeds maxFiles
+            const oldestPath = this.getRotatedPath(component, this.maxFiles);
+            this.unlinkSafe(oldestPath);
+            // 3. Shift existing rotated files: .3 → .4, .2 → .3, .1 → .2
+            for (let i = this.maxFiles - 1; i >= 1; i--) {
+                const from = this.getRotatedPath(component, i);
+                const to = this.getRotatedPath(component, i + 1);
+                this.renameSafe(from, to);
+            }
+            // 4. Rename current file to .1
+            this.renameSafe(basePath, this.getRotatedPath(component, 1));
+            // 5. Create a fresh stream and reset byte counter
+            this.bytesWritten.set(component, 0);
+            this.createStream(component);
+        }
+        catch {
+            // Rotation failure must not crash the application
+            process.stderr.write(`[FileWriter] Rotation failed for ${component}\n`);
+        }
+        finally {
+            this.rotating.delete(component);
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Retention
+    // ---------------------------------------------------------------------------
+    /**
+     * Delete log files older than `retentionDays`.
+     *
+     * Scans the log directory for files matching the configured extension
+     * and removes any whose `mtime` exceeds the retention threshold.
+     * Called once at startup and then once per day.
+     */
+    cleanExpiredFiles() {
+        if (this.retentionDays <= 0)
+            return;
+        const cutoff = Date.now() - this.retentionDays * 24 * 60 * 60 * 1000;
+        try {
+            const entries = fs.readdirSync(this.logDir);
+            for (const entry of entries) {
+                if (!entry.endsWith(this.extension))
+                    continue;
+                const filePath = path.join(this.logDir, entry);
+                try {
+                    const stats = fs.statSync(filePath);
+                    if (stats.isFile() && stats.mtimeMs < cutoff) {
+                        fs.unlinkSync(filePath);
+                    }
+                }
+                catch {
+                    // best-effort: individual file errors are non-fatal
+                }
+            }
+        }
+        catch {
+            // best-effort: directory read errors are non-fatal
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Path Helpers
+    // ---------------------------------------------------------------------------
+    /** Build the primary log file path for a component. */
+    getFilePath(component) {
+        const safeName = component.replace(/[^a-zA-Z0-9_-]/g, "_");
+        return path.join(this.logDir, `${safeName}${this.extension}`);
+    }
+    /** Build the rotated file path: `<component>.<n><extension>` */
+    getRotatedPath(component, n) {
+        const safeName = component.replace(/[^a-zA-Z0-9_-]/g, "_");
+        return path.join(this.logDir, `${safeName}.${n}${this.extension}`);
+    }
+    /** Rename a file if it exists; ignore errors silently. */
+    renameSafe(from, to) {
+        try {
+            if (fs.existsSync(from)) {
+                fs.renameSync(from, to);
+            }
+        }
+        catch {
+            // best-effort
+        }
+    }
+    /** Delete a file if it exists; ignore errors silently. */
+    unlinkSafe(filePath) {
+        try {
+            if (fs.existsSync(filePath)) {
+                fs.unlinkSync(filePath);
+            }
+        }
+        catch {
+            // best-effort
+        }
+    }
+    /**
+     * Close all streams gracefully.
+     * Should be called during application shutdown to ensure all logs are flushed.
+     *
+     * @returns Promise that resolves when all streams are closed
+     */
+    async close() {
+        // Stop retention timer
+        if (this.retentionTimer) {
+            clearInterval(this.retentionTimer);
+            this.retentionTimer = null;
+        }
+        const closePromises = [];
+        for (const [, stream] of this.streams.entries()) {
+            closePromises.push(new Promise((resolve) => {
+                stream.end(() => {
+                    stream.close(() => resolve());
+                });
+            }));
+        }
+        await Promise.allSettled(closePromises);
+        this.streams.clear();
+        this.bytesWritten.clear();
+        this.rotating.clear();
+        this.initialized = false;
+        await super.close();
+    }
+    /**
+     * Check if the writer has been initialized successfully.
+     */
+    isAvailable() {
+        return this.enabled && this.initialized;
+    }
+    /**
+     * Check if a stream exists for a component.
+     */
+    hasStream(component) {
+        return this.streams.has(component);
+    }
+    /**
+     * Add a new stream for a component.
+     *
+     * @param component - The component name
+     * @returns true if stream was created successfully
+     */
+    addStream(component) {
+        return this.createStream(component);
+    }
+    /**
+     * Get the number of active streams.
+     */
+    getStreamCount() {
+        return this.streams.size;
+    }
+}
+//# sourceMappingURL=file-writer.js.map

package/build/logger/writers/file-writer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-writer.js","sourceRoot":"","sources":["../../../src/logger/writers/file-writer.ts"],"names":[],"mappings":"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"}

package/build/logger/writers/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Writers Module
+ *
+ * Log output writers for different destinations.
+ * Each writer handles a specific output target (console, file, MCP).
+ *
+ * Note: TransportMode type should be imported from '../core/constants.js'
+ *
+ * @module logger/writers
+ */
+export { BaseLogWriter } from "./base-writer.js";
+export { ConsoleWriter, type ConsoleWriterConfig } from "./console-writer.js";
+export { FileWriter, type FileWriterConfig } from "./file-writer.js";
+export { CompositeWriter } from "./composite-writer.js";
+//# sourceMappingURL=index.d.ts.map

package/build/logger/writers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/logger/writers/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAGjD,OAAO,EAAE,aAAa,EAAE,KAAK,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAG9E,OAAO,EAAE,UAAU,EAAE,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAGrE,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC"}

package/build/logger/writers/index.js

@@ -0,0 +1,19 @@
+/**
+ * Writers Module
+ *
+ * Log output writers for different destinations.
+ * Each writer handles a specific output target (console, file, MCP).
+ *
+ * Note: TransportMode type should be imported from '../core/constants.js'
+ *
+ * @module logger/writers
+ */
+// Base Writer
+export { BaseLogWriter } from "./base-writer.js";
+// Console Writer
+export { ConsoleWriter } from "./console-writer.js";
+// File Writer
+export { FileWriter } from "./file-writer.js";
+// Composite Writer
+export { CompositeWriter } from "./composite-writer.js";
+//# sourceMappingURL=index.js.map

package/build/logger/writers/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/logger/writers/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,cAAc;AACd,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEjD,iBAAiB;AACjB,OAAO,EAAE,aAAa,EAA4B,MAAM,qBAAqB,CAAC;AAE9E,cAAc;AACd,OAAO,EAAE,UAAU,EAAyB,MAAM,kBAAkB,CAAC;AAErE,mBAAmB;AACnB,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC"}

package/build/mcp/capabilities/apps/define-app.d.ts

@@ -0,0 +1,68 @@
+/**
+ * App Definition Factory
+ *
+ * Provides the defineApp() factory function for defining MCP Apps.
+ * An MCP App combines a tool with a UI resource, linked via
+ * `_meta.ui.resourceUri` on the tool definition.
+ *
+ * `defineApp()` internally creates:
+ * 1. A static resource via `defineResource()` (the UI)
+ * 2. A tool via `defineTool()` with `_meta.ui.resourceUri` pointing to the resource
+ *
+ * Both are automatically registered in the global registries.
+ *
+ * @module mcp/capabilities/apps/define-app
+ */
+import type { z } from "zod";
+import type { AppDefinition } from "../../types/index.js";
+/**
+ * Define an MCP App with automatic resource and tool registration.
+ *
+ * Creates a tool linked to a UI resource via `_meta.ui.resourceUri`.
+ * Both the tool and the resource are registered in the global registries,
+ * so they are automatically available when `createServer()` is called.
+ *
+ * @typeParam TInput - Zod schema type for the tool input (inferred)
+ *
+ * @param definition - App definition with resource and tool configuration
+ * @returns The original app definition (for re-export and type inference)
+ *
+ * @example
+ * ```typescript
+ * import { defineApp, text, z } from 'mcp-server-framework';
+ *
+ * export const calculator = defineApp({
+ *   name: 'calculator',
+ *   description: 'An interactive calculator app',
+ *   resource: {
+ *     uri: 'ui://calculator',
+ *     mimeType: 'text/html;profile=mcp-app',
+ *     read: async () => '<html>...calculator UI...</html>',
+ *   },
+ *   input: z.object({ expression: z.string() }),
+ *   handler: async ({ expression }) => text('42'),
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With annotations and custom _meta
+ * export const dashboard = defineApp({
+ *   name: 'dashboard',
+ *   description: 'System monitoring dashboard',
+ *   resource: {
+ *     uri: 'ui://dashboard',
+ *     name: 'Dashboard UI',
+ *     description: 'Interactive system monitoring dashboard',
+ *     mimeType: 'text/html;profile=mcp-app',
+ *     read: async () => generateDashboardHtml(),
+ *   },
+ *   input: z.object({ metric: z.string().optional() }),
+ *   handler: async ({ metric }, ctx) => json(await getMetrics(metric)),
+ *   annotations: { readOnlyHint: true },
+ *   _meta: { version: '2.0' },
+ * });
+ * ```
+ */
+export declare function defineApp<TInput extends z.ZodTypeAny>(definition: AppDefinition<TInput>): AppDefinition<TInput>;
+//# sourceMappingURL=define-app.d.ts.map

package/build/mcp/capabilities/apps/define-app.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-app.d.ts","sourceRoot":"","sources":["../../../../src/mcp/capabilities/apps/define-app.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAW1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,wBAAgB,SAAS,CAAC,MAAM,SAAS,CAAC,CAAC,UAAU,EAAE,UAAU,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,aAAa,CAAC,MAAM,CAAC,CA4D/G"}