@leanmcp/core 0.3.2 → 0.3.4

package/README.md

@@ -1,555 +1,555 @@
-# @leanmcp/core
-
-Core library for building Model Context Protocol (MCP) servers with TypeScript decorators and declarative schema definition.
-
-## Features
-
-- **Type-safe decorators** - `@Tool`, `@Prompt`, `@Resource` with full TypeScript support
-- **Schema generation** - Define JSON Schema declaratively using `@SchemaConstraint` decorators on class properties
-- **Streamable HTTP transport** - Production-ready HTTP server with session management
-- **Input validation** - Built-in AJV validation for all inputs
-- **Clean API** - Function names automatically become tool/prompt/resource names
-- **MCP compliant** - Built on official `@modelcontextprotocol/sdk`
-
-## Installation
-
-```bash
-npm install @leanmcp/core
-```
-
-### Peer Dependencies
-
-For HTTP server support:
-```bash
-npm install express cors
-```
-
-## Quick Start
-
-### 1. Define Your Service with Class-Based Schema
-
-```typescript
-import { Tool, SchemaConstraint, Optional } from "@leanmcp/core";
-
-// Define input schema as a class
-class AnalyzeSentimentInput {
-  @SchemaConstraint({
-    description: 'Text to analyze',
-    minLength: 1
-  })
-  text!: string;
-
-  @Optional()
-  @SchemaConstraint({
-    description: 'Language code',
-    enum: ['en', 'es', 'fr'],
-    default: 'en'
-  })
-  language?: string;
-}
-
-// Define output schema
-class AnalyzeSentimentOutput {
-  @SchemaConstraint({ enum: ['positive', 'negative', 'neutral'] })
-  sentiment!: string;
-
-  @SchemaConstraint({ minimum: -1, maximum: 1 })
-  score!: number;
-}
-
-export class SentimentService {
-  @Tool({ 
-    description: 'Analyze sentiment of text',
-    inputClass: AnalyzeSentimentInput
-  })
-  async analyzeSentiment(input: AnalyzeSentimentInput): Promise<AnalyzeSentimentOutput> {
-    // Your implementation
-    return {
-      sentiment: 'positive',
-      score: 0.8,
-      confidence: 0.95
-    };
-  }
-}
-```
-
-### 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 with factory function
-const serverFactory = async () => {
-  const server = new MCPServer({
-    name: "my-mcp-server",
-    version: "1.0.0",
-    logging: true,
-    autoDiscover: false  // Disable auto-discovery for manual registration
-  });
-
-  // Register services manually
-  server.registerService(new SentimentService());
-
-  return server.getServer();
-};
-
-// Start HTTP server with factory
-await createHTTPServer(serverFactory, {
-  port: 3000,
-  cors: true,
-  logging: true
-});
-```
-
-## Decorators
-
-### @Tool
-
-Marks a method as an MCP tool (callable function). Use `inputClass` to specify the input schema class.
-
-```typescript
-class CalculateInput {
-  @SchemaConstraint({ description: 'First number' })
-  a!: number;
-  
-  @SchemaConstraint({ description: 'Second number' })
-  b!: number;
-}
-
-@Tool({ 
-  description: 'Calculate sum of two numbers',
-  inputClass: CalculateInput
-})
-async calculate(input: CalculateInput) {
-  return { result: input.a + input.b };
-}
-```
-
-### @Prompt
-
-Marks a method as an MCP prompt template. Input schema is automatically inferred from parameter type.
-
-```typescript
-class CodeReviewInput {
-  @SchemaConstraint({ description: 'Code to review' })
-  code!: string;
-  
-  @SchemaConstraint({ description: 'Programming language' })
-  language!: string;
-}
-
-@Prompt({ description: 'Generate code review prompt' })
-codeReview(input: CodeReviewInput) {
-  return {
-    messages: [{
-      role: "user",
-      content: {
-        type: "text",
-        text: `Review this ${input.language} code:\n\n${input.code}`
-      }
-    }]
-  };
-}
-```
-
-### @Resource
-
-Marks a method as an MCP resource (data source).
-
-```typescript
-@Resource({ description: 'Get system configuration', mimeType: 'application/json' })
-async getConfig() {
-  return {
-    version: "1.0.0",
-    environment: process.env.NODE_ENV
-  };
-}
-```
-
-### @SchemaConstraint
-
-Add validation constraints to class properties for automatic schema generation.
-
-```typescript
-class UserInput {
-  @SchemaConstraint({
-    description: 'User email',
-    format: 'email',
-    minLength: 5,
-    maxLength: 100
-  })
-  email!: string;
-
-  @SchemaConstraint({
-    description: 'User age',
-    minimum: 18,
-    maximum: 120
-  })
-  age!: number;
-
-  @Optional()
-  @SchemaConstraint({
-    description: 'User role',
-    enum: ['admin', 'user', 'guest'],
-    default: 'user'
-  })
-  role?: string;
-}
-```
-
-### @Optional
-
-Marks a property as optional in the schema.
-
-```typescript
-class SearchInput {
-  @SchemaConstraint({ description: 'Search query' })
-  query!: string;
-
-  @Optional()
-  @SchemaConstraint({ description: 'Max results', default: 10 })
-  limit?: number;
-}
-```
-
-## API Reference
-
-### MCPServer
-
-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)
-  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;
-
-// 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 | Promise<Server>,
-  options: {
-    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:
-
-```typescript
-import { classToJsonSchemaWithConstraints } from "@leanmcp/core";
-
-const schema = classToJsonSchemaWithConstraints(MyInputClass);
-```
-
-## HTTP Endpoints
-
-When using `createHTTPServer`, the following endpoints are available:
-
-- `POST /mcp` - MCP protocol endpoint (accepts JSON-RPC 2.0 messages)
-- `GET /health` - Health check endpoint
-- `GET /` - Welcome message
-
-## Environment Variables
-
-```bash
-PORT=3000              # Server port (optional)
-NODE_ENV=production    # Environment (optional)
-```
-
-## Error Handling
-
-All tools automatically handle errors and return them in MCP format:
-
-```typescript
-class DivideInput {
-  @SchemaConstraint({ description: 'Numerator' })
-  a!: number;
-  
-  @SchemaConstraint({ description: 'Denominator' })
-  b!: number;
-}
-
-@Tool({ 
-  description: 'Divide numbers',
-  inputClass: DivideInput
-})
-async divide(input: DivideInput) {
-  if (input.b === 0) {
-    throw new Error("Division by zero");
-  }
-  return { result: input.a / input.b };
-}
-```
-
-Errors are returned as:
-```json
-{
-  "content": [{"type": "text", "text": "Error: Division by zero"}],
-  "isError": true
-}
-```
-
-## TypeScript Support
-
-Full TypeScript support with type inference:
-
-```typescript
-class MyInput {
-  @SchemaConstraint({ description: 'Input field' })
-  field!: string;
-}
-
-class MyOutput {
-  result!: string;
-}
-
-// Input schema defined via inputClass, output type inferred from return type
-@Tool({ 
-  description: 'My tool',
-  inputClass: MyInput
-})
-async myTool(input: MyInput): Promise<MyOutput> {
-  // TypeScript knows the exact types
-  const result: MyOutput = {
-    result: input.field.toUpperCase()
-    // Full autocomplete and type checking
-  };
-  return result;
-}
-```
-
-**Key Points:**
-- Input schema is defined using `inputClass` in the `@Tool` decorator
-- Output schema is inferred from the return type
-- For tools with no input parameters, omit the `inputClass` option
-- Use `@SchemaConstraint` decorators to add validation and documentation to your input classes
-
-## License
-
-MIT
-
-## Related Packages
-
-- [@leanmcp/cli](../cli) - CLI tool for creating new projects
-- [@leanmcp/auth](../auth) - Authentication decorators and providers
-- [@leanmcp/utils](../utils) - Utility functions
-
-## Links
-
-- [GitHub Repository](https://github.com/LeanMCP/leanmcp-sdk)
-- [MCP Specification](https://spec.modelcontextprotocol.io/)
-- [Documentation](https://github.com/LeanMCP/leanmcp-sdk#readme)
+# @leanmcp/core
+
+Core library for building Model Context Protocol (MCP) servers with TypeScript decorators and declarative schema definition.
+
+## Features
+
+- **Type-safe decorators** - `@Tool`, `@Prompt`, `@Resource` with full TypeScript support
+- **Schema generation** - Define JSON Schema declaratively using `@SchemaConstraint` decorators on class properties
+- **Streamable HTTP transport** - Production-ready HTTP server with session management
+- **Input validation** - Built-in AJV validation for all inputs
+- **Clean API** - Function names automatically become tool/prompt/resource names
+- **MCP compliant** - Built on official `@modelcontextprotocol/sdk`
+
+## Installation
+
+```bash
+npm install @leanmcp/core
+```
+
+### Peer Dependencies
+
+For HTTP server support:
+```bash
+npm install express cors
+```
+
+## Quick Start
+
+### 1. Define Your Service with Class-Based Schema
+
+```typescript
+import { Tool, SchemaConstraint, Optional } from "@leanmcp/core";
+
+// Define input schema as a class
+class AnalyzeSentimentInput {
+  @SchemaConstraint({
+    description: 'Text to analyze',
+    minLength: 1
+  })
+  text!: string;
+
+  @Optional()
+  @SchemaConstraint({
+    description: 'Language code',
+    enum: ['en', 'es', 'fr'],
+    default: 'en'
+  })
+  language?: string;
+}
+
+// Define output schema
+class AnalyzeSentimentOutput {
+  @SchemaConstraint({ enum: ['positive', 'negative', 'neutral'] })
+  sentiment!: string;
+
+  @SchemaConstraint({ minimum: -1, maximum: 1 })
+  score!: number;
+}
+
+export class SentimentService {
+  @Tool({ 
+    description: 'Analyze sentiment of text',
+    inputClass: AnalyzeSentimentInput
+  })
+  async analyzeSentiment(input: AnalyzeSentimentInput): Promise<AnalyzeSentimentOutput> {
+    // Your implementation
+    return {
+      sentiment: 'positive',
+      score: 0.8,
+      confidence: 0.95
+    };
+  }
+}
+```
+
+### 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 with factory function
+const serverFactory = async () => {
+  const server = new MCPServer({
+    name: "my-mcp-server",
+    version: "1.0.0",
+    logging: true,
+    autoDiscover: false  // Disable auto-discovery for manual registration
+  });
+
+  // Register services manually
+  server.registerService(new SentimentService());
+
+  return server.getServer();
+};
+
+// Start HTTP server with factory
+await createHTTPServer(serverFactory, {
+  port: 3000,
+  cors: true,
+  logging: true
+});
+```
+
+## Decorators
+
+### @Tool
+
+Marks a method as an MCP tool (callable function). Use `inputClass` to specify the input schema class.
+
+```typescript
+class CalculateInput {
+  @SchemaConstraint({ description: 'First number' })
+  a!: number;
+  
+  @SchemaConstraint({ description: 'Second number' })
+  b!: number;
+}
+
+@Tool({ 
+  description: 'Calculate sum of two numbers',
+  inputClass: CalculateInput
+})
+async calculate(input: CalculateInput) {
+  return { result: input.a + input.b };
+}
+```
+
+### @Prompt
+
+Marks a method as an MCP prompt template. Input schema is automatically inferred from parameter type.
+
+```typescript
+class CodeReviewInput {
+  @SchemaConstraint({ description: 'Code to review' })
+  code!: string;
+  
+  @SchemaConstraint({ description: 'Programming language' })
+  language!: string;
+}
+
+@Prompt({ description: 'Generate code review prompt' })
+codeReview(input: CodeReviewInput) {
+  return {
+    messages: [{
+      role: "user",
+      content: {
+        type: "text",
+        text: `Review this ${input.language} code:\n\n${input.code}`
+      }
+    }]
+  };
+}
+```
+
+### @Resource
+
+Marks a method as an MCP resource (data source).
+
+```typescript
+@Resource({ description: 'Get system configuration', mimeType: 'application/json' })
+async getConfig() {
+  return {
+    version: "1.0.0",
+    environment: process.env.NODE_ENV
+  };
+}
+```
+
+### @SchemaConstraint
+
+Add validation constraints to class properties for automatic schema generation.
+
+```typescript
+class UserInput {
+  @SchemaConstraint({
+    description: 'User email',
+    format: 'email',
+    minLength: 5,
+    maxLength: 100
+  })
+  email!: string;
+
+  @SchemaConstraint({
+    description: 'User age',
+    minimum: 18,
+    maximum: 120
+  })
+  age!: number;
+
+  @Optional()
+  @SchemaConstraint({
+    description: 'User role',
+    enum: ['admin', 'user', 'guest'],
+    default: 'user'
+  })
+  role?: string;
+}
+```
+
+### @Optional
+
+Marks a property as optional in the schema.
+
+```typescript
+class SearchInput {
+  @SchemaConstraint({ description: 'Search query' })
+  query!: string;
+
+  @Optional()
+  @SchemaConstraint({ description: 'Max results', default: 10 })
+  limit?: number;
+}
+```
+
+## API Reference
+
+### MCPServer
+
+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)
+  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;
+
+// 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 | Promise<Server>,
+  options: {
+    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:
+
+```typescript
+import { classToJsonSchemaWithConstraints } from "@leanmcp/core";
+
+const schema = classToJsonSchemaWithConstraints(MyInputClass);
+```
+
+## HTTP Endpoints
+
+When using `createHTTPServer`, the following endpoints are available:
+
+- `POST /mcp` - MCP protocol endpoint (accepts JSON-RPC 2.0 messages)
+- `GET /health` - Health check endpoint
+- `GET /` - Welcome message
+
+## Environment Variables
+
+```bash
+PORT=3000              # Server port (optional)
+NODE_ENV=production    # Environment (optional)
+```
+
+## Error Handling
+
+All tools automatically handle errors and return them in MCP format:
+
+```typescript
+class DivideInput {
+  @SchemaConstraint({ description: 'Numerator' })
+  a!: number;
+  
+  @SchemaConstraint({ description: 'Denominator' })
+  b!: number;
+}
+
+@Tool({ 
+  description: 'Divide numbers',
+  inputClass: DivideInput
+})
+async divide(input: DivideInput) {
+  if (input.b === 0) {
+    throw new Error("Division by zero");
+  }
+  return { result: input.a / input.b };
+}
+```
+
+Errors are returned as:
+```json
+{
+  "content": [{"type": "text", "text": "Error: Division by zero"}],
+  "isError": true
+}
+```
+
+## TypeScript Support
+
+Full TypeScript support with type inference:
+
+```typescript
+class MyInput {
+  @SchemaConstraint({ description: 'Input field' })
+  field!: string;
+}
+
+class MyOutput {
+  result!: string;
+}
+
+// Input schema defined via inputClass, output type inferred from return type
+@Tool({ 
+  description: 'My tool',
+  inputClass: MyInput
+})
+async myTool(input: MyInput): Promise<MyOutput> {
+  // TypeScript knows the exact types
+  const result: MyOutput = {
+    result: input.field.toUpperCase()
+    // Full autocomplete and type checking
+  };
+  return result;
+}
+```
+
+**Key Points:**
+- Input schema is defined using `inputClass` in the `@Tool` decorator
+- Output schema is inferred from the return type
+- For tools with no input parameters, omit the `inputClass` option
+- Use `@SchemaConstraint` decorators to add validation and documentation to your input classes
+
+## License
+
+MIT
+
+## Related Packages
+
+- [@leanmcp/cli](../cli) - CLI tool for creating new projects
+- [@leanmcp/auth](../auth) - Authentication decorators and providers
+- [@leanmcp/utils](../utils) - Utility functions
+
+## Links
+
+- [GitHub Repository](https://github.com/LeanMCP/leanmcp-sdk)
+- [MCP Specification](https://spec.modelcontextprotocol.io/)
+- [Documentation](https://github.com/LeanMCP/leanmcp-sdk#readme)