@nitrostack/core 1.0.0

package/dist/core/prompt.js

@@ -0,0 +1,76 @@
+import { ValidationError } from './errors.js';
+/**
+ * Prompt class provides a clean abstraction for defining and executing prompts
+ */
+export class Prompt {
+    definition;
+    constructor(definition) {
+        this.definition = definition;
+    }
+    /**
+     * Get prompt name
+     */
+    get name() {
+        return this.definition.name;
+    }
+    /**
+     * Get prompt description
+     */
+    get description() {
+        return this.definition.description;
+    }
+    /**
+     * Get prompt arguments
+     */
+    get arguments() {
+        return this.definition.arguments || [];
+    }
+    /**
+     * Execute the prompt with provided arguments
+     */
+    async execute(args, context) {
+        // Validate required arguments
+        this.validateArguments(args);
+        context.logger.info(`Executing prompt: ${this.name}`, { args: args });
+        try {
+            const messages = await this.definition.handler(args, context);
+            context.logger.info(`Prompt executed successfully: ${this.name}`, {
+                messageCount: messages.length,
+            });
+            return messages;
+        }
+        catch (error) {
+            context.logger.error(`Error executing prompt: ${this.name}`, { error: error instanceof Error ? error.message : String(error) });
+            throw error;
+        }
+    }
+    /**
+     * Validate prompt arguments
+     */
+    validateArguments(args) {
+        if (!this.definition.arguments)
+            return;
+        for (const arg of this.definition.arguments) {
+            if (arg.required && !(arg.name in args)) {
+                throw new ValidationError(`Missing required argument '${arg.name}' for prompt '${this.name}'`);
+            }
+        }
+    }
+    /**
+     * Create prompt metadata for MCP protocol
+     */
+    toMcpPrompt() {
+        return {
+            name: this.name,
+            description: this.description,
+            arguments: this.arguments,
+        };
+    }
+}
+/**
+ * Helper function to create a prompt
+ */
+export function createPrompt(definition) {
+    return new Prompt(definition);
+}
+//# sourceMappingURL=prompt.js.map

package/dist/core/prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt.js","sourceRoot":"","sources":["../../src/core/prompt.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAW9C;;GAEG;AACH,MAAM,OAAO,MAAM;IACT,UAAU,CAAmB;IAErC,YAAY,UAA4B;QACtC,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;IAED;;OAEG;IACH,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;IAC9B,CAAC;IAED;;OAEG;IACH,IAAI,WAAW;QACb,OAAO,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC;IACrC,CAAC;IAED;;OAEG;IACH,IAAI,SAAS;QACX,OAAO,IAAI,CAAC,UAAU,CAAC,SAAS,IAAI,EAAE,CAAC;IACzC,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,OAAO,CAAC,IAAyC,EAAE,OAAyB;QAChF,8BAA8B;QAC9B,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC;QAE7B,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,qBAAqB,IAAI,CAAC,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,IAA6B,EAAE,CAAC,CAAC;QAE/F,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;YAE9D,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,iCAAiC,IAAI,CAAC,IAAI,EAAE,EAAE;gBAChE,YAAY,EAAE,QAAQ,CAAC,MAAM;aAC9B,CAAC,CAAC;YAEH,OAAO,QAAQ,CAAC;QAClB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,2BAA2B,IAAI,CAAC,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;YAChI,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IAED;;OAEG;IACK,iBAAiB,CAAC,IAAyC;QACjE,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,SAAS;YAAE,OAAO;QAEvC,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,UAAU,CAAC,SAAS,EAAE,CAAC;YAC5C,IAAI,GAAG,CAAC,QAAQ,IAAI,CAAC,CAAC,GAAG,CAAC,IAAI,IAAI,IAAI,CAAC,EAAE,CAAC;gBACxC,MAAM,IAAI,eAAe,CACvB,8BAA8B,GAAG,CAAC,IAAI,iBAAiB,IAAI,CAAC,IAAI,GAAG,CACpE,CAAC;YACJ,CAAC;QACH,CAAC;IACH,CAAC;IAED;;OAEG;IACH,WAAW;QACT,OAAO;YACL,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,SAAS,EAAE,IAAI,CAAC,SAAS;SAC1B,CAAC;IACJ,CAAC;CACF;AAED;;GAEG;AACH,MAAM,UAAU,YAAY,CAAC,UAA4B;IACvD,OAAO,IAAI,MAAM,CAAC,UAAU,CAAC,CAAC;AAChC,CAAC"}

package/dist/core/resource.d.ts

@@ -0,0 +1,47 @@
+import { ResourceDefinition, ExecutionContext, ResourceContent } from './types.js';
+/**
+ * Resource class provides a clean abstraction for defining and serving resources
+ */
+export declare class Resource {
+    private definition;
+    private cache?;
+    constructor(definition: ResourceDefinition);
+    /**
+     * Get resource URI
+     */
+    get uri(): string;
+    /**
+     * Get resource name
+     */
+    get name(): string;
+    /**
+     * Get resource description
+     */
+    get description(): string;
+    /**
+     * Get resource MIME type
+     */
+    get mimeType(): string | undefined;
+    /**
+     * Fetch the resource content
+     */
+    fetch(context: ExecutionContext): Promise<ResourceContent>;
+    /**
+     * Clear cached content
+     */
+    clearCache(): void;
+    /**
+     * MCP Resource metadata structure
+     */
+    toMcpResource(): {
+        uri: string;
+        name: string;
+        description: string;
+        mimeType?: string;
+    };
+}
+/**
+ * Helper function to create a resource
+ */
+export declare function createResource(definition: ResourceDefinition): Resource;
+//# sourceMappingURL=resource.d.ts.map

package/dist/core/resource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource.d.ts","sourceRoot":"","sources":["../../src/core/resource.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAEnF;;GAEG;AACH,qBAAa,QAAQ;IACnB,OAAO,CAAC,UAAU,CAAqB;IACvC,OAAO,CAAC,KAAK,CAAC,CAGZ;gBAEU,UAAU,EAAE,kBAAkB;IAI1C;;OAEG;IACH,IAAI,GAAG,IAAI,MAAM,CAEhB;IAED;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;OAEG;IACH,IAAI,WAAW,IAAI,MAAM,CAExB;IAED;;OAEG;IACH,IAAI,QAAQ,IAAI,MAAM,GAAG,SAAS,CAEjC;IAED;;OAEG;IACG,KAAK,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC;IAkChE;;OAEG;IACH,UAAU,IAAI,IAAI;IAIlB;;OAEG;IACH,aAAa,IAAI;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE;CAQvF;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,UAAU,EAAE,kBAAkB,GAAG,QAAQ,CAEvE"}

package/dist/core/resource.js

@@ -0,0 +1,90 @@
+/**
+ * Resource class provides a clean abstraction for defining and serving resources
+ */
+export class Resource {
+    definition;
+    cache;
+    constructor(definition) {
+        this.definition = definition;
+    }
+    /**
+     * Get resource URI
+     */
+    get uri() {
+        return this.definition.uri;
+    }
+    /**
+     * Get resource name
+     */
+    get name() {
+        return this.definition.name;
+    }
+    /**
+     * Get resource description
+     */
+    get description() {
+        return this.definition.description;
+    }
+    /**
+     * Get resource MIME type
+     */
+    get mimeType() {
+        return this.definition.mimeType;
+    }
+    /**
+     * Fetch the resource content
+     */
+    async fetch(context) {
+        const cacheable = this.definition.metadata?.cacheable;
+        const cacheMaxAge = this.definition.metadata?.cacheMaxAge || 60000; // 1 minute default
+        // Check cache
+        if (cacheable && this.cache) {
+            const age = Date.now() - this.cache.timestamp;
+            if (age < cacheMaxAge) {
+                context.logger.debug(`Serving cached resource: ${this.uri}`);
+                return this.cache.content;
+            }
+        }
+        context.logger.info(`Fetching resource: ${this.uri}`);
+        try {
+            const content = await this.definition.handler(this.uri, context);
+            // Update cache
+            if (cacheable) {
+                this.cache = {
+                    content,
+                    timestamp: Date.now(),
+                };
+            }
+            context.logger.info(`Resource fetched successfully: ${this.uri}`);
+            return content;
+        }
+        catch (error) {
+            context.logger.error(`Error fetching resource: ${this.uri}`, { error: error instanceof Error ? error.message : String(error) });
+            throw error;
+        }
+    }
+    /**
+     * Clear cached content
+     */
+    clearCache() {
+        this.cache = undefined;
+    }
+    /**
+     * MCP Resource metadata structure
+     */
+    toMcpResource() {
+        return {
+            uri: this.uri,
+            name: this.name,
+            description: this.description,
+            mimeType: this.mimeType,
+        };
+    }
+}
+/**
+ * Helper function to create a resource
+ */
+export function createResource(definition) {
+    return new Resource(definition);
+}
+//# sourceMappingURL=resource.js.map

package/dist/core/resource.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource.js","sourceRoot":"","sources":["../../src/core/resource.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,OAAO,QAAQ;IACX,UAAU,CAAqB;IAC/B,KAAK,CAGX;IAEF,YAAY,UAA8B;QACxC,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;IAED;;OAEG;IACH,IAAI,GAAG;QACL,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;IAC7B,CAAC;IAED;;OAEG;IACH,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;IAC9B,CAAC;IAED;;OAEG;IACH,IAAI,WAAW;QACb,OAAO,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC;IACrC,CAAC;IAED;;OAEG;IACH,IAAI,QAAQ;QACV,OAAO,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC;IAClC,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,KAAK,CAAC,OAAyB;QACnC,MAAM,SAAS,GAAG,IAAI,CAAC,UAAU,CAAC,QAAQ,EAAE,SAAS,CAAC;QACtD,MAAM,WAAW,GAAG,IAAI,CAAC,UAAU,CAAC,QAAQ,EAAE,WAAW,IAAI,KAAK,CAAC,CAAC,mBAAmB;QAEvF,cAAc;QACd,IAAI,SAAS,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YAC5B,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC;YAC9C,IAAI,GAAG,GAAG,WAAW,EAAE,CAAC;gBACtB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,4BAA4B,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;gBAC7D,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC;YAC5B,CAAC;QACH,CAAC;QAED,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,sBAAsB,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;QAEtD,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;YAEjE,eAAe;YACf,IAAI,SAAS,EAAE,CAAC;gBACd,IAAI,CAAC,KAAK,GAAG;oBACX,OAAO;oBACP,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;iBACtB,CAAC;YACJ,CAAC;YAED,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,kCAAkC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;YAClE,OAAO,OAAO,CAAC;QACjB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,4BAA4B,IAAI,CAAC,GAAG,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;YAChI,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IAED;;OAEG;IACH,UAAU;QACR,IAAI,CAAC,KAAK,GAAG,SAAS,CAAC;IACzB,CAAC;IAED;;OAEG;IACH,aAAa;QACX,OAAO;YACL,GAAG,EAAE,IAAI,CAAC,GAAG;YACb,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,QAAQ,EAAE,IAAI,CAAC,QAAQ;SACxB,CAAC;IACJ,CAAC;CACF;AAED;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,UAA8B;IAC3D,OAAO,IAAI,QAAQ,CAAC,UAAU,CAAC,CAAC;AAClC,CAAC"}

package/dist/core/server.d.ts

@@ -0,0 +1,129 @@
+import { Tool } from './tool.js';
+import { Resource } from './resource.js';
+import { Prompt } from './prompt.js';
+import { McpServerConfig, ServerStats, ClassConstructor } from './types.js';
+/**
+ * HTTP Transport interface
+ */
+interface HttpTransport {
+    start(): Promise<void>;
+    close(): Promise<void>;
+    send(message: JsonRpcResponse): Promise<void>;
+    onmessage?: (message: JsonRpcRequest) => Promise<void>;
+    setToolsCallback?(callback: () => Promise<unknown[]>): void;
+    setServerConfig?(config: {
+        name: string;
+        version: string;
+        description?: string;
+    }): void;
+}
+/**
+ * JSON-RPC request structure
+ */
+interface JsonRpcRequest {
+    jsonrpc: '2.0';
+    id?: string | number | null;
+    method?: string;
+    params?: Record<string, unknown>;
+}
+/**
+ * JSON-RPC response structure
+ */
+interface JsonRpcResponse {
+    jsonrpc: '2.0';
+    id: string | number | null;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+}
+/**
+ * NitroStackServer - Main server class
+ */
+export declare class NitroStackServer {
+    private mcpServer;
+    private tools;
+    private resources;
+    private prompts;
+    private modules;
+    private config;
+    private logger;
+    private stats;
+    private pendingComponentRegistrations;
+    /** Transport type used by the server */
+    private _transportType?;
+    /** HTTP transport instance (when using http or dual mode) */
+    private _httpTransport?;
+    constructor(config?: McpServerConfig);
+    /**
+     * Add a tool to the server
+     */
+    tool(tool: Tool): this;
+    /**
+     * Register a component as an MCP resource
+     */
+    private registerComponentResource;
+    /**
+     * Add a resource to the server
+     */
+    resource(resource: Resource): this;
+    /**
+     * Add a prompt to the server
+     */
+    prompt(prompt: Prompt): this;
+    /**
+     * Register a module with all its controllers
+     * Automatically extracts and registers all tools, resources, and prompts
+     *
+     * @example
+     * ```typescript
+     * server.module(AuthModule);
+     * server.module(ProductsModule);
+     * ```
+     */
+    module(moduleClass: ClassConstructor): this;
+    /**
+     * Get server statistics
+     */
+    getStats(): ServerStats;
+    /**
+     * Create execution context
+     */
+    private createContext;
+    /**
+     * Setup MCP protocol handlers
+     */
+    private setupHandlers;
+    /**
+     * Start the server
+     * Automatically determines the transport based on NODE_ENV
+     *
+     * Transport determination:
+     * - MCP_TRANSPORT_TYPE env var takes precedence (for explicit control)
+     * - NODE_ENV=development or unset → stdio mode
+     * - NODE_ENV=production → dual mode (STDIO + HTTP)
+     */
+    start(): Promise<void>;
+    /**
+     * Start the server with specified transport
+     * @param transportType - 'stdio', 'http', or 'dual' (default: 'stdio')
+     * @param transportOptions - Transport-specific options
+     */
+    private startWithTransport;
+    /**
+     * Stop the server
+     */
+    stop(): Promise<void>;
+    /**
+     * Get the HTTP transport (for modules that need to register endpoints)
+     */
+    getHttpTransport(): HttpTransport | undefined;
+}
+/**
+ * Helper function to create a server
+ */
+export declare function createServer(config: McpServerConfig): NitroStackServer;
+export {};
+//# sourceMappingURL=server.d.ts.map

package/dist/core/server.d.ts.map

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