@mcp-weave/nestjs 0.1.1 → 0.3.0

package/README.md

@@ -27,6 +27,7 @@ pnpm add @mcp-weave/nestjs reflect-metadata
 - **Method Decorators** - `@McpTool`, `@McpResource`, `@McpPrompt`
 - **Parameter Decorators** - `@McpInput`, `@McpParam`, `@McpPromptArg`
 - **Runtime Server** - Start MCP servers from decorated classes
+- **Multiple Transports** - Stdio (default) and SSE (Server-Sent Events)
 
 ## Quick Start
 
@@ -215,6 +216,46 @@ const server = new McpRuntimeServer(MyServer, {
 await server.start();
 ```
 
+### SSE Transport (Server-Sent Events)
+
+For web-based integrations, use the SSE transport:
+
+```typescript
+import { McpRuntimeServer } from '@mcp-weave/nestjs';
+
+const server = new McpRuntimeServer(MyServer, {
+  transport: 'sse',
+  port: 3000,
+  endpoint: '/sse',
+});
+
+// Starts HTTP server with SSE endpoint
+const httpServer = await server.start();
+
+// Server available at:
+// - SSE endpoint: http://localhost:3000/sse
+// - Health check: http://localhost:3000/health
+```
+
+Or use the `startSSE` method directly:
+
+```typescript
+const server = new McpRuntimeServer(MyServer);
+
+// Start with SSE transport
+const httpServer = await server.startSSE({
+  port: 8080,
+  endpoint: '/mcp',
+});
+```
+
+**SSE Features:**
+
+- CORS enabled by default
+- Health check endpoint at `/health`
+- Session management for multiple clients
+- Automatic cleanup on connection close
+
 ## Metadata Extraction
 
 Extract metadata from decorated classes for code generation:

package/dist/index.d.mts

@@ -1,6 +1,7 @@
 import { ToolInputSchema, PromptArgument, McpParamMetadata, McpPromptMetadata, McpResourceMetadata, McpServerMetadata, McpToolMetadata } from '@mcp-weave/core';
 export { METADATA_KEYS, McpParamMetadata, McpPromptMetadata, McpResourceMetadata, McpServerMetadata, McpToolMetadata, ScannedMetadata, extractMetadata } from '@mcp-weave/core';
-import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { IncomingMessage, ServerResponse, Server } from 'http';
+import { Server as Server$1 } from '@modelcontextprotocol/sdk/server/index.js';
 
 /**
  * Options for @McpServer decorator
@@ -204,14 +205,142 @@ declare function getPromptsMetadata(target: Function): McpPromptMetadata[];
  */
 declare function getParamsMetadata(target: Function): McpParamMetadata[];
 
+/**
+ * @mcp-weave/nestjs - Authentication Module
+ * Provides API key authentication and request tracking
+ */
+
+/**
+ * API Key configuration
+ */
+interface ApiKeyConfig {
+    /** The API key value */
+    key: string;
+    /** Human-readable name for the key (for logging) */
+    name?: string;
+    /** Optional metadata associated with this key */
+    metadata?: Record<string, unknown>;
+    /** Scopes/permissions for this key */
+    scopes?: string[];
+}
+/**
+ * Authentication options for MCP servers
+ */
+interface McpAuthOptions {
+    /**
+     * Enable authentication (default: false)
+     */
+    enabled?: boolean;
+    /**
+     * API keys allowed to access the server
+     * Can be a single key string, array of keys, or array of ApiKeyConfig objects
+     */
+    apiKeys?: string | string[] | ApiKeyConfig[];
+    /**
+     * Header name for the API key (default: 'x-api-key')
+     */
+    headerName?: string;
+    /**
+     * Query parameter name for the API key (default: 'api_key')
+     */
+    queryParamName?: string;
+    /**
+     * Custom authentication function
+     * Return true to allow, false to deny, or an AuthResult object
+     */
+    authenticate?: (token: string | undefined, request: IncomingMessage) => boolean | AuthResult | Promise<boolean | AuthResult>;
+    /**
+     * Called when authentication fails
+     */
+    onAuthFailure?: (request: IncomingMessage, reason: string) => void;
+    /**
+     * Called when authentication succeeds
+     */
+    onAuthSuccess?: (request: IncomingMessage, result: AuthResult) => void;
+}
+/**
+ * Result of authentication
+ */
+interface AuthResult {
+    /** Whether authentication succeeded */
+    success: boolean;
+    /** Client identifier (for tracking) */
+    clientId?: string;
+    /** Client name (for logging) */
+    clientName?: string;
+    /** Scopes/permissions granted */
+    scopes?: string[];
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+    /** Error message if authentication failed */
+    error?: string;
+}
+/**
+ * Request context with authentication info
+ */
+interface AuthenticatedRequest {
+    /** The original request */
+    request: IncomingMessage;
+    /** Authentication result */
+    auth: AuthResult;
+    /** Request ID for tracking */
+    requestId: string;
+    /** Timestamp of the request */
+    timestamp: Date;
+}
+/**
+ * Normalize API keys configuration to ApiKeyConfig array
+ */
+declare function normalizeApiKeys(keys: string | string[] | ApiKeyConfig[] | undefined): ApiKeyConfig[];
+/**
+ * Extract API key from request
+ */
+declare function extractApiKey(req: IncomingMessage, headerName?: string, queryParamName?: string): string | undefined;
+/**
+ * Validate API key against configured keys
+ */
+declare function validateApiKey(token: string | undefined, apiKeys: ApiKeyConfig[]): AuthResult;
+/**
+ * Hash a token for safe logging (shows first 4 and last 4 chars)
+ */
+declare function hashToken(token: string): string;
+/**
+ * Generate a unique request ID
+ */
+declare function generateRequestId(): string;
+/**
+ * Create an authentication middleware for HTTP requests
+ */
+declare function createAuthMiddleware(options?: McpAuthOptions): (req: IncomingMessage, res: ServerResponse) => Promise<AuthenticatedRequest | null>;
+/**
+ * Send unauthorized response
+ */
+declare function sendUnauthorized(res: ServerResponse, message?: string, requestId?: string): void;
+/**
+ * Generate a random API key
+ */
+declare function generateApiKey(prefix?: string): string;
+
 /**
  * Options for MCP runtime server
  */
 interface McpRuntimeOptions {
     /**
-     * Transport type
+     * Transport type: 'stdio' (default), 'sse', or 'websocket'
+     */
+    transport?: 'stdio' | 'sse' | 'websocket';
+    /**
+     * Port for SSE/WebSocket transport (default: 3000)
      */
-    transport?: 'stdio' | 'sse';
+    port?: number;
+    /**
+     * Endpoint path for SSE/WebSocket (default: '/sse' or '/ws')
+     */
+    endpoint?: string;
+    /**
+     * Authentication options
+     */
+    auth?: McpAuthOptions;
 }
 /**
  * Runtime MCP server that wraps a decorated class
@@ -220,7 +349,9 @@ declare class McpRuntimeServer {
     private server;
     private instance;
     private metadata;
-    constructor(target: Function, _options?: McpRuntimeOptions);
+    private authOptions;
+    private authMiddleware;
+    constructor(target: Function, options?: McpRuntimeOptions);
     private setupHandlers;
     private setupToolHandlers;
     private setupResourceHandlers;
@@ -230,19 +361,49 @@ declare class McpRuntimeServer {
     private resolvePromptArgs;
     private extractUriParams;
     /**
-     * Start the MCP server
+     * Start the MCP server with stdio transport
      */
     start(): Promise<void>;
+    /**
+     * Start the MCP server with SSE transport
+     */
+    startSSE(options?: {
+        port?: number;
+        endpoint?: string;
+    }): Promise<Server>;
     /**
      * Get the underlying MCP server instance
      */
-    getServer(): Server;
+    getServer(): Server$1;
+    /**
+     * Start the MCP server with WebSocket transport
+     */
+    startWebSocket(options?: {
+        port?: number;
+        endpoint?: string;
+    }): Promise<Server>;
+    /**
+     * Handle WebSocket JSON-RPC messages
+     */
+    private handleWebSocketMessage;
 }
 /**
  * Create and start an MCP server from a decorated class
+ *
+ * @example
+ * // Stdio transport (default)
+ * await createMcpServer(MyServer);
+ *
+ * @example
+ * // SSE transport
+ * await createMcpServer(MyServer, { transport: 'sse', port: 3000 });
+ *
+ * @example
+ * // WebSocket transport
+ * await createMcpServer(MyServer, { transport: 'websocket', port: 8080 });
  */
 declare function createMcpServer(target: Function, options?: McpRuntimeOptions): Promise<McpRuntimeServer>;
 
 declare const VERSION = "0.1.0";
 
-export { McpInput, McpParam, McpPrompt, McpPromptArg, type McpPromptOptions, McpResource, type McpResourceOptions, type McpRuntimeOptions, McpRuntimeServer, McpServer, type McpServerOptions, McpTool, type McpToolOptions, VERSION, createMcpServer, getMcpServers, getParamsMetadata, getPromptsMetadata, getResourcesMetadata, getServerMetadata, getToolsMetadata, isMcpServer };
+export { type ApiKeyConfig, type AuthResult, type AuthenticatedRequest, type McpAuthOptions, McpInput, McpParam, McpPrompt, McpPromptArg, type McpPromptOptions, McpResource, type McpResourceOptions, type McpRuntimeOptions, McpRuntimeServer, McpServer, type McpServerOptions, McpTool, type McpToolOptions, VERSION, createAuthMiddleware, createMcpServer, extractApiKey, generateApiKey, generateRequestId, getMcpServers, getParamsMetadata, getPromptsMetadata, getResourcesMetadata, getServerMetadata, getToolsMetadata, hashToken, isMcpServer, normalizeApiKeys, sendUnauthorized, validateApiKey };

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import { ToolInputSchema, PromptArgument, McpParamMetadata, McpPromptMetadata, McpResourceMetadata, McpServerMetadata, McpToolMetadata } from '@mcp-weave/core';
 export { METADATA_KEYS, McpParamMetadata, McpPromptMetadata, McpResourceMetadata, McpServerMetadata, McpToolMetadata, ScannedMetadata, extractMetadata } from '@mcp-weave/core';
-import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { IncomingMessage, ServerResponse, Server } from 'http';
+import { Server as Server$1 } from '@modelcontextprotocol/sdk/server/index.js';
 
 /**
  * Options for @McpServer decorator
@@ -204,14 +205,142 @@ declare function getPromptsMetadata(target: Function): McpPromptMetadata[];
  */
 declare function getParamsMetadata(target: Function): McpParamMetadata[];
 
+/**
+ * @mcp-weave/nestjs - Authentication Module
+ * Provides API key authentication and request tracking
+ */
+
+/**
+ * API Key configuration
+ */
+interface ApiKeyConfig {
+    /** The API key value */
+    key: string;
+    /** Human-readable name for the key (for logging) */
+    name?: string;
+    /** Optional metadata associated with this key */
+    metadata?: Record<string, unknown>;
+    /** Scopes/permissions for this key */
+    scopes?: string[];
+}
+/**
+ * Authentication options for MCP servers
+ */
+interface McpAuthOptions {
+    /**
+     * Enable authentication (default: false)
+     */
+    enabled?: boolean;
+    /**
+     * API keys allowed to access the server
+     * Can be a single key string, array of keys, or array of ApiKeyConfig objects
+     */
+    apiKeys?: string | string[] | ApiKeyConfig[];
+    /**
+     * Header name for the API key (default: 'x-api-key')
+     */
+    headerName?: string;
+    /**
+     * Query parameter name for the API key (default: 'api_key')
+     */
+    queryParamName?: string;
+    /**
+     * Custom authentication function
+     * Return true to allow, false to deny, or an AuthResult object
+     */
+    authenticate?: (token: string | undefined, request: IncomingMessage) => boolean | AuthResult | Promise<boolean | AuthResult>;
+    /**
+     * Called when authentication fails
+     */
+    onAuthFailure?: (request: IncomingMessage, reason: string) => void;
+    /**
+     * Called when authentication succeeds
+     */
+    onAuthSuccess?: (request: IncomingMessage, result: AuthResult) => void;
+}
+/**
+ * Result of authentication
+ */
+interface AuthResult {
+    /** Whether authentication succeeded */
+    success: boolean;
+    /** Client identifier (for tracking) */
+    clientId?: string;
+    /** Client name (for logging) */
+    clientName?: string;
+    /** Scopes/permissions granted */
+    scopes?: string[];
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+    /** Error message if authentication failed */
+    error?: string;
+}
+/**
+ * Request context with authentication info
+ */
+interface AuthenticatedRequest {
+    /** The original request */
+    request: IncomingMessage;
+    /** Authentication result */
+    auth: AuthResult;
+    /** Request ID for tracking */
+    requestId: string;
+    /** Timestamp of the request */
+    timestamp: Date;
+}
+/**
+ * Normalize API keys configuration to ApiKeyConfig array
+ */
+declare function normalizeApiKeys(keys: string | string[] | ApiKeyConfig[] | undefined): ApiKeyConfig[];
+/**
+ * Extract API key from request
+ */
+declare function extractApiKey(req: IncomingMessage, headerName?: string, queryParamName?: string): string | undefined;
+/**
+ * Validate API key against configured keys
+ */
+declare function validateApiKey(token: string | undefined, apiKeys: ApiKeyConfig[]): AuthResult;
+/**
+ * Hash a token for safe logging (shows first 4 and last 4 chars)
+ */
+declare function hashToken(token: string): string;
+/**
+ * Generate a unique request ID
+ */
+declare function generateRequestId(): string;
+/**
+ * Create an authentication middleware for HTTP requests
+ */
+declare function createAuthMiddleware(options?: McpAuthOptions): (req: IncomingMessage, res: ServerResponse) => Promise<AuthenticatedRequest | null>;
+/**
+ * Send unauthorized response
+ */
+declare function sendUnauthorized(res: ServerResponse, message?: string, requestId?: string): void;
+/**
+ * Generate a random API key
+ */
+declare function generateApiKey(prefix?: string): string;
+
 /**
  * Options for MCP runtime server
  */
 interface McpRuntimeOptions {
     /**
-     * Transport type
+     * Transport type: 'stdio' (default), 'sse', or 'websocket'
+     */
+    transport?: 'stdio' | 'sse' | 'websocket';
+    /**
+     * Port for SSE/WebSocket transport (default: 3000)
      */
-    transport?: 'stdio' | 'sse';
+    port?: number;
+    /**
+     * Endpoint path for SSE/WebSocket (default: '/sse' or '/ws')
+     */
+    endpoint?: string;
+    /**
+     * Authentication options
+     */
+    auth?: McpAuthOptions;
 }
 /**
  * Runtime MCP server that wraps a decorated class
@@ -220,7 +349,9 @@ declare class McpRuntimeServer {
     private server;
     private instance;
     private metadata;
-    constructor(target: Function, _options?: McpRuntimeOptions);
+    private authOptions;
+    private authMiddleware;
+    constructor(target: Function, options?: McpRuntimeOptions);
     private setupHandlers;
     private setupToolHandlers;
     private setupResourceHandlers;
@@ -230,19 +361,49 @@ declare class McpRuntimeServer {
     private resolvePromptArgs;
     private extractUriParams;
     /**
-     * Start the MCP server
+     * Start the MCP server with stdio transport
      */
     start(): Promise<void>;
+    /**
+     * Start the MCP server with SSE transport
+     */
+    startSSE(options?: {
+        port?: number;
+        endpoint?: string;
+    }): Promise<Server>;
     /**
      * Get the underlying MCP server instance
      */
-    getServer(): Server;
+    getServer(): Server$1;
+    /**
+     * Start the MCP server with WebSocket transport
+     */
+    startWebSocket(options?: {
+        port?: number;
+        endpoint?: string;
+    }): Promise<Server>;
+    /**
+     * Handle WebSocket JSON-RPC messages
+     */
+    private handleWebSocketMessage;
 }
 /**
  * Create and start an MCP server from a decorated class
+ *
+ * @example
+ * // Stdio transport (default)
+ * await createMcpServer(MyServer);
+ *
+ * @example
+ * // SSE transport
+ * await createMcpServer(MyServer, { transport: 'sse', port: 3000 });
+ *
+ * @example
+ * // WebSocket transport
+ * await createMcpServer(MyServer, { transport: 'websocket', port: 8080 });
  */
 declare function createMcpServer(target: Function, options?: McpRuntimeOptions): Promise<McpRuntimeServer>;
 
 declare const VERSION = "0.1.0";
 
-export { McpInput, McpParam, McpPrompt, McpPromptArg, type McpPromptOptions, McpResource, type McpResourceOptions, type McpRuntimeOptions, McpRuntimeServer, McpServer, type McpServerOptions, McpTool, type McpToolOptions, VERSION, createMcpServer, getMcpServers, getParamsMetadata, getPromptsMetadata, getResourcesMetadata, getServerMetadata, getToolsMetadata, isMcpServer };
+export { type ApiKeyConfig, type AuthResult, type AuthenticatedRequest, type McpAuthOptions, McpInput, McpParam, McpPrompt, McpPromptArg, type McpPromptOptions, McpResource, type McpResourceOptions, type McpRuntimeOptions, McpRuntimeServer, McpServer, type McpServerOptions, McpTool, type McpToolOptions, VERSION, createAuthMiddleware, createMcpServer, extractApiKey, generateApiKey, generateRequestId, getMcpServers, getParamsMetadata, getPromptsMetadata, getResourcesMetadata, getServerMetadata, getToolsMetadata, hashToken, isMcpServer, normalizeApiKeys, sendUnauthorized, validateApiKey };