@eaperezc/mcpgen 0.1.0

package/dist/types-B9yzEar_.d.cts

@@ -0,0 +1,895 @@
+import { z } from 'zod';
+
+/**
+ * Transport types supported by the framework
+ */
+type TransportType = 'stdio' | 'http' | 'sse';
+/**
+ * Base transport configuration
+ */
+interface BaseTransportConfig {
+    type: TransportType;
+}
+/**
+ * Stdio transport configuration
+ */
+interface StdioTransportConfig extends BaseTransportConfig {
+    type: 'stdio';
+}
+/**
+ * HTTP transport configuration
+ */
+interface HttpTransportConfig extends BaseTransportConfig {
+    type: 'http';
+    /** Port to listen on */
+    port: number;
+    /** Host to bind to */
+    host?: string;
+    /** Base path for MCP endpoints */
+    basePath?: string;
+    /** CORS configuration */
+    cors?: CorsConfig;
+    /** TLS configuration */
+    tls?: TlsConfig;
+}
+/**
+ * SSE transport configuration
+ */
+interface SseTransportConfig extends BaseTransportConfig {
+    type: 'sse';
+    /** Port to listen on */
+    port: number;
+    /** Host to bind to */
+    host?: string;
+    /** Base path for SSE endpoints */
+    basePath?: string;
+    /** CORS configuration */
+    cors?: CorsConfig;
+}
+/**
+ * CORS configuration
+ */
+interface CorsConfig {
+    /** Allowed origins */
+    origin?: string | string[] | boolean;
+    /** Allowed methods */
+    methods?: string[];
+    /** Allowed headers */
+    allowedHeaders?: string[];
+    /** Exposed headers */
+    exposedHeaders?: string[];
+    /** Allow credentials */
+    credentials?: boolean;
+    /** Max age for preflight cache */
+    maxAge?: number;
+}
+/**
+ * TLS configuration
+ */
+interface TlsConfig {
+    /** Path to certificate file */
+    cert: string;
+    /** Path to key file */
+    key: string;
+    /** Path to CA certificate file */
+    ca?: string;
+}
+/**
+ * Union type for all transport configurations
+ */
+type TransportConfig = StdioTransportConfig | HttpTransportConfig | SseTransportConfig;
+/**
+ * Transport interface that all transports must implement
+ */
+interface Transport {
+    /** Start the transport (optionally with an MCP server instance) */
+    start(mcpServer?: unknown): Promise<void>;
+    /** Stop the transport */
+    stop(): Promise<void>;
+    /** Check if transport is running */
+    isRunning(): boolean;
+}
+
+/**
+ * Log levels in order of severity
+ */
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+/**
+ * Log entry structure
+ */
+interface LogEntry {
+    level: LogLevel;
+    message: string;
+    timestamp: Date;
+    correlationId?: string;
+    context?: Record<string, unknown>;
+    error?: Error;
+}
+/**
+ * Logger configuration options
+ */
+interface LoggerConfig {
+    /** Minimum log level to output */
+    level: LogLevel;
+    /** Whether to output in JSON format (for production) */
+    json?: boolean;
+    /** Whether to include timestamps */
+    timestamps?: boolean;
+    /** Custom context to include in all logs */
+    defaultContext?: Record<string, unknown>;
+    /** Pretty print output (for development) */
+    pretty?: boolean;
+}
+/**
+ * Logger transport interface for custom outputs
+ */
+interface LogTransport {
+    log(entry: LogEntry): void;
+}
+
+/**
+ * Server information
+ */
+interface ServerInfo {
+    /** Server name */
+    name: string;
+    /** Server version */
+    version: string;
+    /** Server description */
+    description?: string;
+}
+/**
+ * OAuth configuration
+ */
+interface OAuthConfig {
+    /** OAuth issuer URL */
+    issuer: string;
+    /** Expected audience */
+    audience: string;
+    /** JWKS URI (defaults to issuer/.well-known/jwks.json) */
+    jwksUri?: string;
+    /** Required scopes for all requests */
+    requiredScopes?: string[];
+    /** Token cache TTL in seconds */
+    cacheTtl?: number;
+}
+/**
+ * API Key configuration
+ */
+interface ApiKeyConfig {
+    /** Header name for API key */
+    header?: string;
+    /** Custom validation function */
+    validate: (key: string) => Promise<ApiKeyValidationResult> | ApiKeyValidationResult;
+}
+/**
+ * API Key validation result
+ */
+interface ApiKeyValidationResult {
+    /** Whether the key is valid */
+    valid: boolean;
+    /** Subject/identity for the key */
+    subject?: string;
+    /** Scopes granted by this key */
+    scopes?: string[];
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Authentication configuration
+ */
+interface AuthConfig {
+    /** OAuth 2.1 configuration */
+    oauth?: OAuthConfig;
+    /** API key configuration */
+    apiKey?: ApiKeyConfig;
+    /** Skip auth for these tool/resource names */
+    skipAuth?: string[];
+}
+/**
+ * Server configuration options
+ */
+interface ServerConfig {
+    /** Server name */
+    name: string;
+    /** Server version */
+    version: string;
+    /** Server description */
+    description?: string;
+    /** Transport configuration (default: stdio) */
+    transport?: TransportType | TransportConfig;
+    /** Authentication configuration */
+    auth?: AuthConfig;
+    /** Logging configuration */
+    logging?: {
+        level?: LogLevel;
+        pretty?: boolean;
+    };
+    /** Auto-discovery configuration */
+    discovery?: {
+        /** Enable auto-discovery */
+        enabled?: boolean;
+        /** Directories to scan */
+        directories?: {
+            tools?: string;
+            resources?: string;
+            prompts?: string;
+        };
+    };
+}
+/**
+ * Server capabilities reported to clients
+ */
+interface ServerCapabilities {
+    tools?: boolean;
+    resources?: boolean;
+    prompts?: boolean;
+    logging?: boolean;
+}
+/**
+ * Server lifecycle hooks
+ */
+interface ServerHooks {
+    /** Called before server starts */
+    onBeforeStart?: () => Promise<void> | void;
+    /** Called after server starts */
+    onAfterStart?: () => Promise<void> | void;
+    /** Called before server stops */
+    onBeforeStop?: () => Promise<void> | void;
+    /** Called after server stops */
+    onAfterStop?: () => Promise<void> | void;
+    /** Called on server error */
+    onError?: (error: Error) => Promise<void> | void;
+}
+
+/**
+ * Tool definition interface
+ */
+interface ToolDefinition<TSchema extends z.ZodType = z.ZodType> {
+    /** Unique tool name */
+    name: string;
+    /** Human-readable description */
+    description: string;
+    /** Zod schema for input validation */
+    schema: TSchema;
+    /** Required scopes for this tool (for auth) */
+    scopes?: string[];
+}
+/**
+ * Tool execution result
+ */
+interface ToolResult {
+    /** Result content (can be any JSON-serializable value) */
+    content: unknown;
+    /** Whether the execution was successful */
+    isError?: boolean;
+}
+/**
+ * Tool handler function type
+ */
+type ToolHandler<TInput = unknown> = (input: TInput) => Promise<ToolResult> | ToolResult;
+/**
+ * Inline tool definition for fluent API
+ */
+interface InlineToolDefinition<TSchema extends z.ZodType = z.ZodType> {
+    description: string;
+    schema: TSchema;
+    handler: ToolHandler<z.infer<TSchema>>;
+    scopes?: string[];
+}
+/**
+ * Tool metadata for registration
+ */
+interface ToolMetadata {
+    name: string;
+    description: string;
+    inputSchema: z.ZodType;
+    scopes: string[];
+}
+
+/**
+ * Base class for defining MCP tools
+ *
+ * @example
+ * ```typescript
+ * class GreetTool extends BaseTool {
+ *   name = 'greet';
+ *   description = 'Greets a user';
+ *   schema = z.object({
+ *     name: z.string().describe('Name to greet'),
+ *   });
+ *
+ *   async execute(input: z.infer<typeof this.schema>): Promise<ToolResult> {
+ *     return { content: { greeting: `Hello, ${input.name}!` } };
+ *   }
+ * }
+ * ```
+ */
+declare abstract class BaseTool<TSchema extends z.ZodType = z.ZodType> {
+    /** Unique tool name */
+    abstract readonly name: string;
+    /** Human-readable description of what the tool does */
+    abstract readonly description: string;
+    /** Zod schema for input validation */
+    abstract readonly schema: TSchema;
+    /** Required scopes for this tool (optional) */
+    readonly scopes: string[];
+    /**
+     * Execute the tool with validated input
+     */
+    abstract execute(input: z.infer<TSchema>): Promise<ToolResult> | ToolResult;
+    /**
+     * Validate and execute the tool
+     */
+    run(input: unknown): Promise<ToolResult>;
+    /**
+     * Get tool metadata for registration
+     */
+    getMetadata(): ToolMetadata;
+    /**
+     * Convert schema to JSON Schema format for MCP protocol
+     */
+    getJsonSchema(): Record<string, unknown>;
+}
+
+/**
+ * Registry for managing tools
+ */
+declare class ToolRegistry {
+    private tools;
+    /**
+     * Register a tool instance
+     */
+    register(tool: BaseTool): void;
+    /**
+     * Register an inline tool definition
+     */
+    registerInline<TSchema extends z.ZodType>(name: string, definition: InlineToolDefinition<TSchema>): void;
+    /**
+     * Get a tool by name
+     */
+    get(name: string): BaseTool | undefined;
+    /**
+     * Get a tool by name or throw if not found
+     */
+    getOrThrow(name: string): BaseTool;
+    /**
+     * Check if a tool exists
+     */
+    has(name: string): boolean;
+    /**
+     * Remove a tool
+     */
+    remove(name: string): boolean;
+    /**
+     * Get all registered tools
+     */
+    getAll(): BaseTool[];
+    /**
+     * Get all tool names
+     */
+    getNames(): string[];
+    /**
+     * Get the number of registered tools
+     */
+    get size(): number;
+    /**
+     * Clear all tools
+     */
+    clear(): void;
+}
+
+/**
+ * Resource content types
+ */
+type ResourceContent = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'blob';
+    data: string;
+    mimeType: string;
+};
+/**
+ * Resource definition interface
+ */
+interface ResourceDefinition {
+    /** Unique resource URI */
+    uri: string;
+    /** Human-readable name */
+    name: string;
+    /** Description of the resource */
+    description?: string;
+    /** MIME type of the resource content */
+    mimeType?: string;
+    /** Required scopes for this resource (for auth) */
+    scopes?: string[];
+}
+/**
+ * Resource read result
+ */
+interface ResourceResult {
+    contents: ResourceContent[];
+}
+/**
+ * Resource handler function type
+ */
+type ResourceHandler = () => Promise<ResourceResult> | ResourceResult;
+/**
+ * Inline resource definition for fluent API
+ */
+interface InlineResourceDefinition {
+    name: string;
+    description?: string;
+    mimeType?: string;
+    read: ResourceHandler;
+    scopes?: string[];
+}
+/**
+ * Resource metadata for registration
+ */
+interface ResourceMetadata {
+    uri: string;
+    name: string;
+    description?: string;
+    mimeType?: string;
+    scopes: string[];
+}
+/**
+ * Resource template for dynamic resources
+ */
+interface ResourceTemplate {
+    /** URI template with placeholders (e.g., "file://{path}") */
+    uriTemplate: string;
+    /** Human-readable name */
+    name: string;
+    /** Description of the resource template */
+    description?: string;
+    /** MIME type of resources from this template */
+    mimeType?: string;
+}
+
+/**
+ * Base class for defining MCP resources
+ *
+ * @example
+ * ```typescript
+ * class ConfigResource extends BaseResource {
+ *   uri = 'config://app';
+ *   name = 'App Configuration';
+ *   description = 'Application configuration settings';
+ *
+ *   async read(): Promise<ResourceResult> {
+ *     const config = await loadConfig();
+ *     return {
+ *       contents: [{ type: 'text', text: JSON.stringify(config, null, 2) }]
+ *     };
+ *   }
+ * }
+ * ```
+ */
+declare abstract class BaseResource {
+    /** Unique resource URI */
+    abstract readonly uri: string;
+    /** Human-readable name */
+    abstract readonly name: string;
+    /** Description of the resource */
+    readonly description?: string;
+    /** MIME type of the resource content */
+    readonly mimeType?: string;
+    /** Required scopes for this resource (optional) */
+    readonly scopes: string[];
+    /**
+     * Read the resource content
+     */
+    abstract read(): Promise<ResourceResult> | ResourceResult;
+    /**
+     * Safely read the resource with error handling
+     */
+    safeRead(): Promise<ResourceResult>;
+    /**
+     * Get resource metadata for registration
+     */
+    getMetadata(): ResourceMetadata;
+    /**
+     * Helper to create text content
+     */
+    protected text(content: string): ResourceContent;
+    /**
+     * Helper to create JSON content
+     */
+    protected json(data: unknown): ResourceContent;
+    /**
+     * Helper to create blob content
+     */
+    protected blob(data: string, mimeType: string): ResourceContent;
+}
+
+/**
+ * Registry for managing resources
+ */
+declare class ResourceRegistry {
+    private resources;
+    /**
+     * Register a resource instance
+     */
+    register(resource: BaseResource): void;
+    /**
+     * Register an inline resource definition
+     */
+    registerInline(uri: string, definition: InlineResourceDefinition): void;
+    /**
+     * Get a resource by URI
+     */
+    get(uri: string): BaseResource | undefined;
+    /**
+     * Get a resource by URI or throw if not found
+     */
+    getOrThrow(uri: string): BaseResource;
+    /**
+     * Check if a resource exists
+     */
+    has(uri: string): boolean;
+    /**
+     * Remove a resource
+     */
+    remove(uri: string): boolean;
+    /**
+     * Get all registered resources
+     */
+    getAll(): BaseResource[];
+    /**
+     * Get all resource URIs
+     */
+    getUris(): string[];
+    /**
+     * Get the number of registered resources
+     */
+    get size(): number;
+    /**
+     * Clear all resources
+     */
+    clear(): void;
+}
+
+/**
+ * Prompt message role
+ */
+type PromptRole = 'user' | 'assistant';
+/**
+ * Prompt message content
+ */
+interface PromptMessage {
+    role: PromptRole;
+    content: string;
+}
+/**
+ * Prompt definition interface
+ */
+interface PromptDefinition<TArgs extends z.ZodType = z.ZodType> {
+    /** Unique prompt name */
+    name: string;
+    /** Human-readable description */
+    description?: string;
+    /** Zod schema for arguments validation */
+    arguments?: TArgs;
+    /** Required scopes for this prompt (for auth) */
+    scopes?: string[];
+}
+/**
+ * Prompt render result
+ */
+interface PromptResult {
+    messages: PromptMessage[];
+    description?: string;
+}
+/**
+ * Prompt handler function type
+ */
+type PromptHandler<TArgs = unknown> = (args: TArgs) => Promise<PromptResult> | PromptResult;
+/**
+ * Inline prompt definition for fluent API
+ */
+interface InlinePromptDefinition<TArgs extends z.ZodType = z.ZodType> {
+    description?: string;
+    arguments?: TArgs;
+    render: PromptHandler<z.infer<TArgs>>;
+    scopes?: string[];
+}
+/**
+ * Prompt argument metadata
+ */
+interface PromptArgumentMetadata {
+    name: string;
+    description?: string;
+    required: boolean;
+}
+/**
+ * Prompt metadata for registration
+ */
+interface PromptMetadata {
+    name: string;
+    description?: string;
+    arguments: PromptArgumentMetadata[];
+    scopes: string[];
+}
+
+/**
+ * Base class for defining MCP prompts
+ *
+ * @example
+ * ```typescript
+ * class SummarizePrompt extends BasePrompt {
+ *   name = 'summarize';
+ *   description = 'Summarize a piece of text';
+ *
+ *   arguments = z.object({
+ *     text: z.string().describe('Text to summarize'),
+ *     style: z.enum(['brief', 'detailed']).optional().describe('Summary style'),
+ *   });
+ *
+ *   async render(args: z.infer<typeof this.arguments>): Promise<PromptResult> {
+ *     const style = args.style ?? 'brief';
+ *     return {
+ *       messages: [{
+ *         role: 'user',
+ *         content: `Please provide a ${style} summary of the following text:\n\n${args.text}`
+ *       }]
+ *     };
+ *   }
+ * }
+ * ```
+ */
+declare abstract class BasePrompt<TArgs extends z.ZodType = z.ZodType> {
+    /** Unique prompt name */
+    abstract readonly name: string;
+    /** Human-readable description */
+    readonly description?: string;
+    /** Zod schema for arguments validation */
+    readonly arguments?: TArgs;
+    /** Required scopes for this prompt (optional) */
+    readonly scopes: string[];
+    /**
+     * Render the prompt with given arguments
+     */
+    abstract render(args: z.infer<TArgs>): Promise<PromptResult> | PromptResult;
+    /**
+     * Validate arguments and render the prompt
+     */
+    safeRender(args: unknown): Promise<PromptResult>;
+    /**
+     * Get prompt metadata for registration
+     */
+    getMetadata(): PromptMetadata;
+    /**
+     * Get arguments metadata from schema
+     */
+    private getArgumentsMetadata;
+    /**
+     * Helper to create a user message
+     */
+    protected user(content: string): PromptMessage;
+    /**
+     * Helper to create an assistant message
+     */
+    protected assistant(content: string): PromptMessage;
+}
+
+/**
+ * Registry for managing prompts
+ */
+declare class PromptRegistry {
+    private prompts;
+    /**
+     * Register a prompt instance
+     */
+    register(prompt: BasePrompt): void;
+    /**
+     * Register an inline prompt definition
+     */
+    registerInline<TArgs extends z.ZodType>(name: string, definition: InlinePromptDefinition<TArgs>): void;
+    /**
+     * Get a prompt by name
+     */
+    get(name: string): BasePrompt | undefined;
+    /**
+     * Get a prompt by name or throw if not found
+     */
+    getOrThrow(name: string): BasePrompt;
+    /**
+     * Check if a prompt exists
+     */
+    has(name: string): boolean;
+    /**
+     * Remove a prompt
+     */
+    remove(name: string): boolean;
+    /**
+     * Get all registered prompts
+     */
+    getAll(): BasePrompt[];
+    /**
+     * Get all prompt names
+     */
+    getNames(): string[];
+    /**
+     * Get the number of registered prompts
+     */
+    get size(): number;
+    /**
+     * Clear all prompts
+     */
+    clear(): void;
+}
+
+/**
+ * Structured logger with support for correlation IDs and contextual logging
+ */
+declare class Logger {
+    private pino;
+    private config;
+    private defaultContext;
+    constructor(config?: Partial<LoggerConfig>);
+    /**
+     * Check if a log level should be output
+     */
+    private shouldLog;
+    /**
+     * Create a child logger with additional context
+     */
+    child(context: Record<string, unknown>): Logger;
+    /**
+     * Log a debug message
+     */
+    debug(message: string, context?: Record<string, unknown>): void;
+    /**
+     * Log an info message
+     */
+    info(message: string, context?: Record<string, unknown>): void;
+    /**
+     * Log a warning message
+     */
+    warn(message: string, context?: Record<string, unknown>): void;
+    /**
+     * Log an error message
+     */
+    error(message: string, error?: Error | Record<string, unknown>): void;
+    /**
+     * Log with correlation ID for request tracing
+     */
+    withCorrelationId(correlationId: string): Logger;
+    /**
+     * Set the log level
+     */
+    setLevel(level: LogLevel): void;
+    /**
+     * Get the current log level
+     */
+    getLevel(): LogLevel;
+}
+/**
+ * Default logger instance
+ */
+declare const logger: Logger;
+
+/**
+ * Main MCP Server class
+ *
+ * @example
+ * ```typescript
+ * const server = new McpServer({
+ *   name: 'my-server',
+ *   version: '1.0.0',
+ * });
+ *
+ * server.tool(new GreetTool());
+ * server.resource(new ConfigResource());
+ * await server.start();
+ * ```
+ */
+declare class McpServer {
+    private server;
+    private config;
+    private logger;
+    private running;
+    private httpTransport;
+    private toolRegistry;
+    private resourceRegistry;
+    private promptRegistry;
+    private hooks;
+    constructor(config: ServerConfig);
+    /**
+     * Get server info
+     */
+    getInfo(): ServerInfo;
+    /**
+     * Get server capabilities
+     */
+    private getCapabilities;
+    /**
+     * Set up MCP request handlers
+     */
+    private setupHandlers;
+    /**
+     * Register a tool
+     */
+    tool(tool: BaseTool): this;
+    tool<TSchema extends z.ZodType>(name: string, definition: InlineToolDefinition<TSchema>): this;
+    /**
+     * Register a resource
+     */
+    resource(resource: BaseResource): this;
+    resource(uri: string, definition: InlineResourceDefinition): this;
+    /**
+     * Register a prompt
+     */
+    prompt(prompt: BasePrompt): this;
+    prompt<TArgs extends z.ZodType>(name: string, definition: InlinePromptDefinition<TArgs>): this;
+    /**
+     * Set lifecycle hooks
+     */
+    setHooks(hooks: ServerHooks): this;
+    /**
+     * Start the server
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the server
+     */
+    stop(): Promise<void>;
+    /**
+     * Check if server is running
+     */
+    isRunning(): boolean;
+    /**
+     * Get the logger instance
+     */
+    getLogger(): Logger;
+    /**
+     * Get tool registry (for testing)
+     */
+    getToolRegistry(): ToolRegistry;
+    /**
+     * Get resource registry (for testing)
+     */
+    getResourceRegistry(): ResourceRegistry;
+    /**
+     * Get prompt registry (for testing)
+     */
+    getPromptRegistry(): PromptRegistry;
+}
+
+/**
+ * Request context data available throughout request lifecycle
+ */
+interface RequestContextData {
+    /** Unique ID for request tracing */
+    correlationId: string;
+    /** Request start time */
+    startTime: Date;
+    /** Logger instance with correlation ID */
+    logger: Logger;
+    /** Authenticated user info (if available) */
+    auth?: AuthContext;
+    /** Custom context data */
+    custom: Map<string, unknown>;
+}
+/**
+ * Authentication context
+ */
+interface AuthContext {
+    /** User/client identifier */
+    subject: string;
+    /** Token scopes/permissions */
+    scopes: string[];
+    /** Token expiration */
+    expiresAt?: Date;
+    /** Additional claims */
+    claims?: Record<string, unknown>;
+}
+/**
+ * Type for context store key
+ */
+type ContextKey = string | symbol;
+
+export { type AuthContext as A, BaseTool as B, type PromptDefinition as C, type PromptResult as D, type PromptHandler as E, type PromptArgumentMetadata as F, type PromptMetadata as G, type HttpTransportConfig as H, type InlineToolDefinition as I, logger as J, type LogEntry as K, type LogLevel as L, McpServer as M, type LoggerConfig as N, type OAuthConfig as O, PromptRegistry as P, type LogTransport as Q, type RequestContextData as R, type ServerHooks as S, type TransportConfig as T, type ContextKey as U, type TransportType as V, type StdioTransportConfig as W, type SseTransportConfig as X, type CorsConfig as Y, type TlsConfig as Z, BaseResource as a, BasePrompt as b, type InlineResourceDefinition as c, type InlinePromptDefinition as d, type AuthConfig as e, Logger as f, type Transport as g, type ServerConfig as h, type ServerInfo as i, type ServerCapabilities as j, type ApiKeyConfig as k, type ApiKeyValidationResult as l, ToolRegistry as m, type ToolDefinition as n, type ToolResult as o, type ToolHandler as p, type ToolMetadata as q, ResourceRegistry as r, type ResourceContent as s, type ResourceDefinition as t, type ResourceResult as u, type ResourceHandler as v, type ResourceMetadata as w, type ResourceTemplate as x, type PromptRole as y, type PromptMessage as z };