@leanmcp/core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,435 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+
+interface ToolOptions {
+    description?: string;
+    inputClass?: any;
+}
+interface PromptOptions {
+    description?: string;
+    inputClass?: any;
+}
+interface ResourceOptions {
+    description?: string;
+    mimeType?: string;
+    inputClass?: any;
+}
+/**
+ * Marks a method as an MCP tool (callable function)
+ * - Tool name is automatically derived from function name
+ * - Input schema is explicitly defined via inputClass
+ * - Full type safety at compile time
+ *
+ * @example
+ * class AnalyzeSentimentInput {
+ *   @SchemaConstraint({ description: 'Text to analyze' })
+ *   text!: string;
+ *
+ *   @Optional()
+ *   language?: string;
+ * }
+ *
+ * @Tool({
+ *   description: 'Analyze sentiment of text',
+ *   inputClass: AnalyzeSentimentInput
+ * })
+ * async analyzeSentiment(args: AnalyzeSentimentInput): Promise<AnalyzeSentimentOutput> {
+ *   // Tool name will be: "analyzeSentiment"
+ * }
+ */
+declare function Tool(options?: ToolOptions): MethodDecorator;
+/**
+ * Marks a method as an MCP prompt template
+ * - Prompt name is automatically derived from function name
+ * - Input schema can be explicitly defined via inputClass or inferred from parameter type
+ *
+ * @example
+ * class PromptInput {
+ *   @SchemaConstraint({ description: 'Auth token' })
+ *   token!: string;
+ * }
+ *
+ * @Prompt({
+ *   description: 'Generate sentiment analysis prompt',
+ *   inputClass: PromptInput
+ * })
+ * sentimentPrompt(args: PromptInput) {
+ *   // Prompt name will be: "sentimentPrompt"
+ * }
+ */
+declare function Prompt(options?: PromptOptions): MethodDecorator;
+/**
+ * Marks a method as an MCP resource (data source/endpoint)
+ * - Resource URI is automatically derived from function name (e.g., "myservice://functionName")
+ * - Can be customized with description, mimeType, and input schema
+ *
+ * @example
+ * class ResourceInput {
+ *   @SchemaConstraint({ description: 'Auth token' })
+ *   token!: string;
+ * }
+ *
+ * @Resource({
+ *   description: 'Service statistics',
+ *   mimeType: 'application/json',
+ *   inputClass: ResourceInput
+ * })
+ * getStats(args: ResourceInput) {
+ *   // Resource URI will be: "servicename://getStats"
+ *   return { stats: '...' };
+ * }
+ */
+declare function Resource(options?: ResourceOptions): MethodDecorator;
+interface AuthOptions {
+    provider: string;
+}
+/**
+ * Adds authentication requirements using a specified provider
+ * @example
+ * @Auth({ provider: 'clerk' })
+ * export class MyService { }
+ *
+ * @Tool({ description: 'Premium feature' })
+ * @Auth({ provider: 'stripe' })
+ * async premiumAction() { }
+ */
+declare function Auth(options: AuthOptions): ClassDecorator & MethodDecorator;
+/**
+ * Injects environment variables or user-level configuration into the tool instance
+ */
+declare function UserEnvs(): PropertyDecorator;
+/**
+ * Property decorator to mark a field as optional in JSON Schema
+ *
+ * @example
+ * class MyInput {
+ *   required!: string;
+ *
+ *   @Optional()
+ *   optional?: string;
+ * }
+ */
+/**
+ * Links a UI component or frontend visualization to a tool or resource
+ * @param component - UI component name
+ */
+declare function UI(component: string): ClassDecorator & MethodDecorator;
+/**
+ * Specifies how output should be rendered
+ * @param format - Render format ('markdown', 'html', 'json', 'chart', 'table')
+ */
+declare function Render(format: 'markdown' | 'html' | 'json' | 'chart' | 'table' | string): MethodDecorator;
+/**
+ * Marks a tool, prompt, or resource as deprecated
+ * @param message - Optional deprecation message
+ */
+declare function Deprecated(message?: string): ClassDecorator & MethodDecorator;
+/**
+ * Get metadata for a specific method
+ */
+declare function getMethodMetadata(method: Function): {
+    toolName: any;
+    toolDescription: any;
+    promptName: any;
+    promptDescription: any;
+    resourceUri: any;
+    resourceName: any;
+    resourceDescription: any;
+    inputSchema: any;
+    outputSchema: any;
+    authProvider: any;
+    authRequired: any;
+    uiComponent: any;
+    renderFormat: any;
+    deprecated: any;
+    deprecationMessage: any;
+};
+/**
+ * Get all methods with a specific decorator from a class
+ */
+declare function getDecoratedMethods(target: any, metadataKey: string): Array<{
+    method: Function;
+    propertyKey: string;
+    metadata: any;
+}>;
+
+/**
+ * Converts a TypeScript class to JSON Schema
+ * Uses reflect-metadata and TypeScript design:type metadata
+ */
+declare function classToJsonSchema(classConstructor: new () => any): any;
+/**
+ * Property decorator to mark a field as optional in JSON Schema
+ */
+declare function Optional(): PropertyDecorator;
+/**
+ * Property decorator to add JSON Schema constraints
+ */
+declare function SchemaConstraint(constraints: {
+    minLength?: number;
+    maxLength?: number;
+    minimum?: number;
+    maximum?: number;
+    pattern?: string;
+    enum?: any[];
+    description?: string;
+    default?: any;
+}): PropertyDecorator;
+/**
+ * Enhanced schema generator that includes constraints
+ */
+declare function classToJsonSchemaWithConstraints(classConstructor: new () => any): any;
+
+/**
+ * Simple configurable logger for LeanMCP SDK
+ */
+declare enum LogLevel {
+    DEBUG = 0,
+    INFO = 1,
+    WARN = 2,
+    ERROR = 3,
+    NONE = 4
+}
+interface LoggerOptions {
+    level?: LogLevel;
+    prefix?: string;
+    timestamps?: boolean;
+}
+declare class Logger {
+    private level;
+    private prefix;
+    private timestamps;
+    constructor(options?: LoggerOptions);
+    private format;
+    private shouldLog;
+    debug(message: string, ...args: any[]): void;
+    info(message: string, ...args: any[]): void;
+    warn(message: string, ...args: any[]): void;
+    error(message: string, ...args: any[]): void;
+    setLevel(level: LogLevel): void;
+    getLevel(): LogLevel;
+}
+declare const defaultLogger: Logger;
+
+interface HTTPServerOptions {
+    port?: number;
+    cors?: boolean | {
+        origin?: string | string[];
+        credentials?: boolean;
+    };
+    logging?: boolean;
+    logger?: Logger;
+    sessionTimeout?: number;
+}
+interface MCPServerFactory {
+    (): Server | Promise<Server>;
+}
+/**
+ * Create an HTTP server for MCP with Streamable HTTP transport
+ */
+declare function createHTTPServer(serverFactory: MCPServerFactory, options?: HTTPServerOptions): Promise<void>;
+
+/**
+ * Input validation utilities for LeanMCP
+ * Provides secure validation for common input types
+ */
+/**
+ * Validates that a port number is within valid range (1-65535)
+ *
+ * @param port - Port number to validate
+ * @throws {Error} If port is invalid
+ *
+ * @example
+ * ```typescript
+ * validatePort(3000); // OK
+ * validatePort(0);    // Throws error
+ * validatePort(70000); // Throws error
+ * ```
+ */
+declare function validatePort(port: number): void;
+/**
+ * Validates that a file path doesn't contain directory traversal patterns
+ * Prevents path traversal attacks by checking for '..' and '~'
+ *
+ * @param path - File path to validate
+ * @throws {Error} If path contains unsafe patterns
+ *
+ * @example
+ * ```typescript
+ * validatePath('./services'); // OK
+ * validatePath('../etc/passwd'); // Throws error
+ * validatePath('~/secrets'); // Throws error
+ * ```
+ */
+declare function validatePath(path: string): void;
+/**
+ * Validates that a service name contains only safe characters
+ * Allows alphanumeric, hyphens, and underscores only
+ *
+ * @param name - Service name to validate
+ * @throws {Error} If name contains unsafe characters
+ *
+ * @example
+ * ```typescript
+ * validateServiceName('my-service'); // OK
+ * validateServiceName('my_service_123'); // OK
+ * validateServiceName('my service'); // Throws error
+ * validateServiceName('../malicious'); // Throws error
+ * ```
+ */
+declare function validateServiceName(name: string): void;
+/**
+ * Validates that a string is not empty or only whitespace
+ *
+ * @param value - String to validate
+ * @param fieldName - Name of the field for error message
+ * @throws {Error} If string is empty or only whitespace
+ *
+ * @example
+ * ```typescript
+ * validateNonEmpty('hello', 'name'); // OK
+ * validateNonEmpty('', 'name'); // Throws error
+ * validateNonEmpty('   ', 'name'); // Throws error
+ * ```
+ */
+declare function validateNonEmpty(value: string, fieldName: string): void;
+/**
+ * Validates that a URL is well-formed and uses allowed protocols
+ *
+ * @param url - URL to validate
+ * @param allowedProtocols - Array of allowed protocols (default: ['http:', 'https:'])
+ * @throws {Error} If URL is invalid or uses disallowed protocol
+ *
+ * @example
+ * ```typescript
+ * validateUrl('https://example.com'); // OK
+ * validateUrl('http://localhost:3000'); // OK
+ * validateUrl('file:///etc/passwd'); // Throws error
+ * validateUrl('javascript:alert(1)'); // Throws error
+ * ```
+ */
+declare function validateUrl(url: string, allowedProtocols?: string[]): void;
+
+interface MCPServerOptions {
+    servicesDir: string;
+    port?: number;
+    cors?: boolean;
+    logging?: boolean;
+}
+interface RegisteredTool {
+    name: string;
+    description: string;
+    inputSchema: any;
+    method: Function;
+    instance: any;
+    propertyKey: string;
+}
+interface RegisteredPrompt {
+    name: string;
+    description: string;
+    arguments: any[];
+    method: Function;
+    instance: any;
+    propertyKey: string;
+}
+interface RegisteredResource {
+    uri: string;
+    name: string;
+    description: string;
+    mimeType: string;
+    inputSchema?: any;
+    method: Function;
+    instance: any;
+    propertyKey: string;
+}
+/**
+ * MCPServer - A simplified server class for manually registering services
+ * Use this when you want to explicitly instantiate and register your services
+ */
+declare class MCPServer {
+    private server;
+    private tools;
+    private prompts;
+    private resources;
+    private logging;
+    private logger;
+    constructor(options: {
+        name: string;
+        version: string;
+        logging?: boolean;
+    });
+    private setupHandlers;
+    /**
+     * Register a service instance with decorated methods
+     */
+    registerService(instance: any): void;
+    /**
+     * Get the underlying MCP SDK Server instance
+     */
+    getServer(): Server<{
+        method: string;
+        params?: {
+            [x: string]: unknown;
+            _meta?: {
+                [x: string]: unknown;
+                progressToken?: string | number | undefined;
+            } | undefined;
+        } | undefined;
+    }, {
+        method: string;
+        params?: {
+            [x: string]: unknown;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+        } | undefined;
+    }, {
+        [x: string]: unknown;
+        _meta?: {
+            [x: string]: unknown;
+        } | undefined;
+    }>;
+}
+declare class MCPServerRuntime {
+    private server;
+    private tools;
+    private prompts;
+    private resources;
+    private options;
+    private logger;
+    constructor(options: MCPServerOptions);
+    private setupHandlers;
+    loadServices(): Promise<void>;
+    start(): Promise<void>;
+    getServer(): Server<{
+        method: string;
+        params?: {
+            [x: string]: unknown;
+            _meta?: {
+                [x: string]: unknown;
+                progressToken?: string | number | undefined;
+            } | undefined;
+        } | undefined;
+    }, {
+        method: string;
+        params?: {
+            [x: string]: unknown;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+        } | undefined;
+    }, {
+        [x: string]: unknown;
+        _meta?: {
+            [x: string]: unknown;
+        } | undefined;
+    }>;
+    getTools(): RegisteredTool[];
+    getPrompts(): RegisteredPrompt[];
+    getResources(): RegisteredResource[];
+}
+/**
+ * Start MCP server with tools from services directory
+ */
+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 };