@leanmcp/core 0.1.2 → 0.3.0

package/README.md

@@ -75,25 +75,70 @@ export class SentimentService {
 
 ### 2. Create and Start Server
 
+#### Option A: Zero-Config Auto-Discovery (Recommended)
+
+The simplest way to create an HTTP server with auto-discovery:
+
+```typescript
+import { createHTTPServer } from "@leanmcp/core";
+
+// Create and start HTTP server with auto-discovery
+await createHTTPServer({
+  name: "my-mcp-server",
+  version: "1.0.0",
+  port: 3000,
+  cors: true,
+  logging: true
+});
+
+console.log('\nMCP Server running');
+console.log('HTTP endpoint: http://localhost:3000/mcp');
+console.log('Health check: http://localhost:3000/health');
+```
+
+**What happens automatically:**
+- Services are discovered from `./mcp` directory
+- HTTP server is created and started
+- Session management is configured
+- CORS is enabled (if specified)
+
+**Directory Structure:**
+```
+your-project/
+├── main.ts
+└── mcp/
+    ├── sentiment/
+    │   └── index.ts    # export class SentimentService
+    ├── weather/
+    │   └── index.ts    # export class WeatherService
+    └── database/
+        └── index.ts    # export class DatabaseService
+```
+
+#### Option B: Factory Pattern (Advanced)
+
+For advanced use cases requiring manual service registration or custom configuration:
+
 ```typescript
 import { createHTTPServer, MCPServer } from "@leanmcp/core";
 import { SentimentService } from "./services/sentiment";
 
-// Create MCP server
-const serverFactory = () => {
+// Create MCP server with factory function
+const serverFactory = async () => {
   const server = new MCPServer({
     name: "my-mcp-server",
     version: "1.0.0",
-    logging: true
+    logging: true,
+    autoDiscover: false  // Disable auto-discovery for manual registration
   });
 
-  // Register services
+  // Register services manually
   server.registerService(new SentimentService());
 
   return server.getServer();
 };
 
-// Start HTTP server
+// Start HTTP server with factory
 await createHTTPServer(serverFactory, {
   port: 3000,
   cors: true,
@@ -220,30 +265,186 @@ Main server class for registering services.
 
 ```typescript
 const server = new MCPServer({
-  name: string;        // Server name
-  version: string;     // Server version
-  logging?: boolean;   // Enable logging (default: false)
+  name: string;           // Server name
+  version: string;        // Server version
+  logging?: boolean;      // Enable logging (default: false)
+  debug?: boolean;        // Enable verbose debug logs (default: false)
+  autoDiscover?: boolean; // Enable auto-discovery (default: true)
+  mcpDir?: string;        // Custom mcp directory path (optional)
 });
 
+// Manual registration
 server.registerService(instance: any): void;
-server.getServer(): Server;  // Get underlying MCP SDK server
+
+// Get underlying MCP SDK server
+server.getServer(): Server;
+```
+
+**Options:**
+
+- **`logging`**: Enable basic logging for server operations
+- **`debug`**: Enable verbose debug logs showing detailed service registration (requires `logging: true`)
+- **`autoDiscover`**: Automatically discover and register services from `./mcp` directory (default: `true`)
+- **`mcpDir`**: Custom path to the mcp directory (default: auto-detected `./mcp`)
+
+#### Zero-Config Auto-Discovery
+
+Services are automatically discovered and registered from the `./mcp` directory when the server is created:
+
+**Basic Usage (Simplified API):**
+```typescript
+import { createHTTPServer } from "@leanmcp/core";
+
+await createHTTPServer({
+  name: "my-server",
+  version: "1.0.0",
+  port: 3000,
+  logging: true  // Enable logging
+});
+```
+
+**With Debug Logging:**
+```typescript
+await createHTTPServer({
+  name: "my-server",
+  version: "1.0.0",
+  port: 3000,
+  logging: true,
+  debug: true  // Show detailed service registration logs
+});
+```
+
+**With Shared Dependencies:**
+
+For services that need shared dependencies, create a `config.ts` (example) file in your `mcp` directory:
+
+```typescript
+// mcp/config.ts
+import { AuthProvider } from "@leanmcp/auth";
+
+if (!process.env.COGNITO_USER_POOL_ID || !process.env.COGNITO_CLIENT_ID) {
+  throw new Error('Missing required Cognito configuration');
+}
+
+export const authProvider = new AuthProvider('cognito', {
+  region: process.env.AWS_REGION || 'us-east-1',
+  userPoolId: process.env.COGNITO_USER_POOL_ID,
+  clientId: process.env.COGNITO_CLIENT_ID,
+  clientSecret: process.env.COGNITO_CLIENT_SECRET
+});
+
+await authProvider.init();
+```
+
+Then import in your services:
+
+```typescript
+// mcp/slack/index.ts
+import { Tool } from "@leanmcp/core";
+import { Authenticated } from "@leanmcp/auth";
+import { authProvider } from "../config.js";
+
+@Authenticated(authProvider)
+export class SlackService {
+  constructor() {
+    // No parameters needed - use environment or imported config
+  }
+
+  @Tool({ description: 'Send a message' })
+  async sendMessage(args: any) {
+    // Implementation
+  }
+}
+```
+
+Your main file stays clean:
+
+```typescript
+import { createHTTPServer } from "@leanmcp/core";
+
+await createHTTPServer({
+  name: "my-server",
+  version: "1.0.0",
+  port: 3000,
+  logging: true
+});
+
+// Services are automatically discovered and registered
+```
+
+**How It Works:**
+- Automatically discovers and registers services from the `./mcp` directory during server initialization
+- Recursively scans for `index.ts` or `index.js` files
+- Dynamically imports each file and looks for exported classes
+- Instantiates services with no-args constructors
+- Registers all discovered services with their decorated methods
+
+**Directory Structure:**
+```
+your-project/
+├── main.ts
+└── mcp/
+    ├── config.ts      # Optional: shared dependencies
+    ├── slack/
+    │   └── index.ts   # export class SlackService
+    ├── database/
+    │   └── index.ts   # export class DatabaseService
+    └── auth/
+        └── index.ts   # export class AuthService
 ```
 
 ### createHTTPServer
 
 Create and start an HTTP server with streamable transport.
 
+**Simplified API (Recommended):**
+```typescript
+await createHTTPServer({
+  name: string;              // Server name (required)
+  version: string;           // Server version (required)
+  port?: number;             // Port number (default: 3001)
+  cors?: boolean | object;   // Enable CORS (default: false)
+  logging?: boolean;         // Enable logging (default: false)
+  debug?: boolean;           // Enable debug logs (default: false)
+  autoDiscover?: boolean;    // Auto-discover services (default: true)
+  mcpDir?: string;           // Custom mcp directory path (optional)
+  sessionTimeout?: number;   // Session timeout in ms (optional)
+});
+```
+
+**Factory Pattern (Advanced):**
 ```typescript
 await createHTTPServer(
-  serverFactory: () => Server,
+  serverFactory: () => Server | Promise<Server>,
   options: {
-    port?: number;      // Port number (default: 3000)
-    cors?: boolean;     // Enable CORS (default: false)
-    logging?: boolean;  // Enable logging (default: true)
+    port?: number;             // Port number (default: 3001)
+    cors?: boolean | object;   // Enable CORS (default: false)
+    logging?: boolean;         // Enable HTTP request logging (default: false)
+    sessionTimeout?: number;   // Session timeout in ms (optional)
   }
 );
 ```
 
+**CORS Configuration:**
+```typescript
+// Simple CORS (allow all origins - not recommended for production)
+await createHTTPServer({
+  name: "my-server",
+  version: "1.0.0",
+  cors: true
+});
+
+// Advanced CORS configuration
+await createHTTPServer({
+  name: "my-server",
+  version: "1.0.0",
+  cors: {
+    origin: 'https://example.com',  // Specific origin
+    credentials: true                // Allow credentials
+  }
+});
+```
+
 ### Schema Generation
 
 Generate JSON Schema from TypeScript classes:

package/dist/index.d.mts

@@ -223,10 +223,15 @@ interface HTTPServerOptions {
 interface MCPServerFactory {
     (): Server | Promise<Server>;
 }
+type HTTPServerInput = MCPServerFactory | MCPServerConstructorOptions;
 /**
  * Create an HTTP server for MCP with Streamable HTTP transport
+ * Returns the HTTP server instance to keep the process alive
+ *
+ * @param serverInput - Either MCPServerConstructorOptions or a factory function that returns a Server
+ * @param options - HTTP server options (only used when serverInput is a factory function)
  */
-declare function createHTTPServer(serverFactory: MCPServerFactory, options?: HTTPServerOptions): Promise<void>;
+declare function createHTTPServer(serverInput: HTTPServerInput, options?: HTTPServerOptions): Promise<any>;
 
 /**
  * Input validation utilities for LeanMCP
@@ -315,6 +320,21 @@ interface MCPServerOptions {
     cors?: boolean;
     logging?: boolean;
 }
+interface MCPServerConstructorOptions {
+    name: string;
+    version: string;
+    logging?: boolean;
+    debug?: boolean;
+    autoDiscover?: boolean;
+    mcpDir?: string;
+    serviceFactories?: Record<string, () => any>;
+    port?: number;
+    cors?: boolean | {
+        origin?: string | string[];
+        credentials?: boolean;
+    };
+    sessionTimeout?: number;
+}
 interface RegisteredTool {
     name: string;
     description: string;
@@ -352,18 +372,63 @@ declare class MCPServer {
     private resources;
     private logging;
     private logger;
-    constructor(options: {
-        name: string;
-        version: string;
-        logging?: boolean;
-    });
+    private options;
+    private initPromise;
+    private autoDiscovered;
+    constructor(options: MCPServerConstructorOptions);
+    /**
+     * Internal initialization - runs automatically in constructor
+     */
+    private autoInit;
+    /**
+     * Wait for initialization to complete
+     * This is called internally by createHTTPServer
+     */
+    waitForInit(): Promise<void>;
+    /**
+     * Automatically discover and register services from the mcp directory
+     * Called by init() unless autoDiscover is set to false
+     */
+    private autoDiscoverServices;
+    /**
+     * Get the file path of the caller (the file that instantiated MCPServer)
+     */
+    private getCallerFile;
     private setupHandlers;
+    /**
+     * Auto-register all services from the mcp directory
+     * Scans the directory recursively and registers all exported classes
+     *
+     * @param mcpDir - Path to the mcp directory containing service files
+     * @param serviceFactories - Optional map of service class names to factory functions for dependency injection
+     *
+     * @example
+     * // Auto-register services with no dependencies
+     * await server.autoRegisterServices('./mcp');
+     *
+     * @example
+     * // Auto-register with dependency injection
+     * await server.autoRegisterServices('./mcp', {
+     *   SlackService: () => new SlackService(process.env.SLACK_TOKEN),
+     *   AuthService: () => new AuthService(authProvider)
+     * });
+     */
+    autoRegisterServices(mcpDir: string, serviceFactories?: Record<string, () => any>): Promise<void>;
+    /**
+     * Recursively find all index.ts/index.js files in the mcp directory
+     */
+    private findServiceFiles;
+    /**
+     * Load a service file and register all exported classes
+     */
+    private loadAndRegisterService;
     /**
      * Register a service instance with decorated methods
      */
     registerService(instance: any): void;
     /**
      * Get the underlying MCP SDK Server instance
+     * Attaches waitForInit method for HTTP server initialization
      */
     getServer(): Server<{
         method: string;
@@ -432,4 +497,4 @@ declare class MCPServerRuntime {
  */
 declare function startMCPServer(options: MCPServerOptions): Promise<MCPServerRuntime>;
 
-export { Auth, type AuthOptions, Deprecated, type HTTPServerOptions, LogLevel, Logger, type LoggerOptions, MCPServer, type MCPServerFactory, type MCPServerOptions, MCPServerRuntime, Optional, Prompt, type PromptOptions, Render, Resource, type ResourceOptions, SchemaConstraint, Tool, type ToolOptions, UI, UserEnvs, classToJsonSchema, classToJsonSchemaWithConstraints, createHTTPServer, defaultLogger, getDecoratedMethods, getMethodMetadata, startMCPServer, validateNonEmpty, validatePath, validatePort, validateServiceName, validateUrl };
+export { Auth, type AuthOptions, Deprecated, type HTTPServerInput, type HTTPServerOptions, LogLevel, Logger, type LoggerOptions, MCPServer, type MCPServerConstructorOptions, type MCPServerFactory, type MCPServerOptions, MCPServerRuntime, Optional, Prompt, type PromptOptions, Render, Resource, type ResourceOptions, SchemaConstraint, Tool, type ToolOptions, UI, UserEnvs, classToJsonSchema, classToJsonSchemaWithConstraints, createHTTPServer, defaultLogger, getDecoratedMethods, getMethodMetadata, startMCPServer, validateNonEmpty, validatePath, validatePort, validateServiceName, validateUrl };

package/dist/index.d.ts

@@ -223,10 +223,15 @@ interface HTTPServerOptions {
 interface MCPServerFactory {
     (): Server | Promise<Server>;
 }
+type HTTPServerInput = MCPServerFactory | MCPServerConstructorOptions;
 /**
  * Create an HTTP server for MCP with Streamable HTTP transport
+ * Returns the HTTP server instance to keep the process alive
+ *
+ * @param serverInput - Either MCPServerConstructorOptions or a factory function that returns a Server
+ * @param options - HTTP server options (only used when serverInput is a factory function)
  */
-declare function createHTTPServer(serverFactory: MCPServerFactory, options?: HTTPServerOptions): Promise<void>;
+declare function createHTTPServer(serverInput: HTTPServerInput, options?: HTTPServerOptions): Promise<any>;
 
 /**
  * Input validation utilities for LeanMCP
@@ -315,6 +320,21 @@ interface MCPServerOptions {
     cors?: boolean;
     logging?: boolean;
 }
+interface MCPServerConstructorOptions {
+    name: string;
+    version: string;
+    logging?: boolean;
+    debug?: boolean;
+    autoDiscover?: boolean;
+    mcpDir?: string;
+    serviceFactories?: Record<string, () => any>;
+    port?: number;
+    cors?: boolean | {
+        origin?: string | string[];
+        credentials?: boolean;
+    };
+    sessionTimeout?: number;
+}
 interface RegisteredTool {
     name: string;
     description: string;
@@ -352,18 +372,63 @@ declare class MCPServer {
     private resources;
     private logging;
     private logger;
-    constructor(options: {
-        name: string;
-        version: string;
-        logging?: boolean;
-    });
+    private options;
+    private initPromise;
+    private autoDiscovered;
+    constructor(options: MCPServerConstructorOptions);
+    /**
+     * Internal initialization - runs automatically in constructor
+     */
+    private autoInit;
+    /**
+     * Wait for initialization to complete
+     * This is called internally by createHTTPServer
+     */
+    waitForInit(): Promise<void>;
+    /**
+     * Automatically discover and register services from the mcp directory
+     * Called by init() unless autoDiscover is set to false
+     */
+    private autoDiscoverServices;
+    /**
+     * Get the file path of the caller (the file that instantiated MCPServer)
+     */
+    private getCallerFile;
     private setupHandlers;
+    /**
+     * Auto-register all services from the mcp directory
+     * Scans the directory recursively and registers all exported classes
+     *
+     * @param mcpDir - Path to the mcp directory containing service files
+     * @param serviceFactories - Optional map of service class names to factory functions for dependency injection
+     *
+     * @example
+     * // Auto-register services with no dependencies
+     * await server.autoRegisterServices('./mcp');
+     *
+     * @example
+     * // Auto-register with dependency injection
+     * await server.autoRegisterServices('./mcp', {
+     *   SlackService: () => new SlackService(process.env.SLACK_TOKEN),
+     *   AuthService: () => new AuthService(authProvider)
+     * });
+     */
+    autoRegisterServices(mcpDir: string, serviceFactories?: Record<string, () => any>): Promise<void>;
+    /**
+     * Recursively find all index.ts/index.js files in the mcp directory
+     */
+    private findServiceFiles;
+    /**
+     * Load a service file and register all exported classes
+     */
+    private loadAndRegisterService;
     /**
      * Register a service instance with decorated methods
      */
     registerService(instance: any): void;
     /**
      * Get the underlying MCP SDK Server instance
+     * Attaches waitForInit method for HTTP server initialization
      */
     getServer(): Server<{
         method: string;
@@ -432,4 +497,4 @@ declare class MCPServerRuntime {
  */
 declare function startMCPServer(options: MCPServerOptions): Promise<MCPServerRuntime>;
 
-export { Auth, type AuthOptions, Deprecated, type HTTPServerOptions, LogLevel, Logger, type LoggerOptions, MCPServer, type MCPServerFactory, type MCPServerOptions, MCPServerRuntime, Optional, Prompt, type PromptOptions, Render, Resource, type ResourceOptions, SchemaConstraint, Tool, type ToolOptions, UI, UserEnvs, classToJsonSchema, classToJsonSchemaWithConstraints, createHTTPServer, defaultLogger, getDecoratedMethods, getMethodMetadata, startMCPServer, validateNonEmpty, validatePath, validatePort, validateServiceName, validateUrl };
+export { Auth, type AuthOptions, Deprecated, type HTTPServerInput, type HTTPServerOptions, LogLevel, Logger, type LoggerOptions, MCPServer, type MCPServerConstructorOptions, type MCPServerFactory, type MCPServerOptions, MCPServerRuntime, Optional, Prompt, type PromptOptions, Render, Resource, type ResourceOptions, SchemaConstraint, Tool, type ToolOptions, UI, UserEnvs, classToJsonSchema, classToJsonSchemaWithConstraints, createHTTPServer, defaultLogger, getDecoratedMethods, getMethodMetadata, startMCPServer, validateNonEmpty, validatePath, validatePort, validateServiceName, validateUrl };