@vfarcic/dot-ai 0.90.0 → 0.91.0

package/dist/interfaces/openapi-generator.js

@@ -0,0 +1,468 @@
+"use strict";
+/**
+ * OpenAPI 3.0 Specification Generator
+ *
+ * Automatically generates OpenAPI 3.0 documentation from the tool registry.
+ * Creates comprehensive API documentation with proper schemas and examples.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpenApiGenerator = void 0;
+/**
+ * OpenAPI 3.0 specification generator
+ */
+class OpenApiGenerator {
+    registry;
+    logger;
+    config;
+    specCache;
+    lastCacheUpdate = 0;
+    cacheValidityMs = 60000; // 1 minute
+    constructor(registry, logger, config = {}) {
+        this.registry = registry;
+        this.logger = logger;
+        this.config = {
+            title: 'DevOps AI Toolkit REST API',
+            description: 'REST API gateway for DevOps AI Toolkit MCP tools - provides HTTP access to all AI-powered DevOps automation capabilities',
+            version: '1.0.0',
+            basePath: '/api',
+            apiVersion: 'v1',
+            serverUrl: 'http://localhost:3456',
+            ...config
+        };
+    }
+    /**
+     * Generate complete OpenAPI 3.0 specification
+     */
+    generateSpec() {
+        // Check cache validity
+        const now = Date.now();
+        if (this.specCache && (now - this.lastCacheUpdate) < this.cacheValidityMs) {
+            this.logger.debug('Returning cached OpenAPI specification');
+            return this.specCache;
+        }
+        this.logger.info('Generating OpenAPI 3.0 specification', {
+            toolCount: this.registry.getToolCount(),
+            cacheExpired: !this.specCache || (now - this.lastCacheUpdate) >= this.cacheValidityMs
+        });
+        const tools = this.registry.getAllTools();
+        const categories = this.registry.getCategories();
+        const spec = {
+            openapi: '3.0.0',
+            info: this.generateInfo(),
+            servers: this.generateServers(),
+            paths: this.generatePaths(tools),
+            components: this.generateComponents(tools),
+            tags: this.generateTags(categories)
+        };
+        // Cache the generated spec
+        this.specCache = spec;
+        this.lastCacheUpdate = now;
+        this.logger.info('OpenAPI specification generated successfully', {
+            pathCount: Object.keys(spec.paths).length,
+            componentCount: Object.keys(spec.components?.schemas || {}).length,
+            tagCount: spec.tags?.length || 0
+        });
+        return spec;
+    }
+    /**
+     * Generate API info section
+     */
+    generateInfo() {
+        const info = {
+            title: this.config.title,
+            description: this.config.description,
+            version: this.config.version,
+            contact: {
+                name: 'Viktor Farcic',
+                url: 'https://devopstoolkit.live/',
+                email: 'viktor@farcic.com'
+            },
+            license: {
+                name: 'MIT',
+                url: 'https://github.com/vfarcic/dot-ai/blob/main/LICENSE'
+            }
+        };
+        return info;
+    }
+    /**
+     * Generate server definitions
+     */
+    generateServers() {
+        return [
+            {
+                url: this.config.serverUrl || 'http://localhost:3456',
+                description: 'DevOps AI Toolkit MCP Server'
+            }
+        ];
+    }
+    /**
+     * Generate paths for all endpoints
+     */
+    generatePaths(tools) {
+        const paths = {};
+        const basePath = `${this.config.basePath}/${this.config.apiVersion}`;
+        // Tool discovery endpoint
+        paths[`${basePath}/tools`] = {
+            get: {
+                summary: 'Discover available tools',
+                description: 'Get a list of all available tools with their schemas and metadata',
+                tags: ['Tool Discovery'],
+                parameters: [
+                    {
+                        name: 'category',
+                        in: 'query',
+                        description: 'Filter tools by category',
+                        required: false,
+                        schema: { type: 'string' }
+                    },
+                    {
+                        name: 'tag',
+                        in: 'query',
+                        description: 'Filter tools by tag',
+                        required: false,
+                        schema: { type: 'string' }
+                    },
+                    {
+                        name: 'search',
+                        in: 'query',
+                        description: 'Search tools by name or description',
+                        required: false,
+                        schema: { type: 'string' }
+                    }
+                ],
+                responses: {
+                    200: {
+                        description: 'List of available tools',
+                        content: {
+                            'application/json': {
+                                schema: { $ref: '#/components/schemas/ToolDiscoveryResponse' }
+                            }
+                        }
+                    }
+                }
+            }
+        };
+        // Individual tool execution endpoints
+        for (const tool of tools) {
+            paths[`${basePath}/tools/${tool.name}`] = {
+                post: {
+                    summary: `Execute ${tool.name} tool`,
+                    description: tool.description,
+                    tags: [tool.category || 'Tools'],
+                    requestBody: {
+                        required: true,
+                        content: {
+                            'application/json': {
+                                schema: { $ref: `#/components/schemas/${tool.name}Request` },
+                                example: this.generateExampleForTool(tool)
+                            }
+                        }
+                    },
+                    responses: {
+                        200: {
+                            description: 'Tool execution result',
+                            content: {
+                                'application/json': {
+                                    schema: { $ref: '#/components/schemas/ToolExecutionResponse' }
+                                }
+                            }
+                        },
+                        400: {
+                            description: 'Bad request - invalid parameters',
+                            content: {
+                                'application/json': {
+                                    schema: { $ref: '#/components/schemas/ErrorResponse' }
+                                }
+                            }
+                        },
+                        404: {
+                            description: 'Tool not found',
+                            content: {
+                                'application/json': {
+                                    schema: { $ref: '#/components/schemas/ErrorResponse' }
+                                }
+                            }
+                        },
+                        500: {
+                            description: 'Internal server error',
+                            content: {
+                                'application/json': {
+                                    schema: { $ref: '#/components/schemas/ErrorResponse' }
+                                }
+                            }
+                        }
+                    }
+                }
+            };
+        }
+        // OpenAPI specification endpoint
+        paths[`${basePath}/openapi`] = {
+            get: {
+                summary: 'Get OpenAPI specification',
+                description: 'Returns the complete OpenAPI 3.0 specification for this API',
+                tags: ['Documentation'],
+                responses: {
+                    200: {
+                        description: 'OpenAPI specification',
+                        content: {
+                            'application/json': {
+                                schema: {
+                                    type: 'object',
+                                    description: 'OpenAPI 3.0 specification'
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        };
+        return paths;
+    }
+    /**
+     * Generate component schemas
+     */
+    generateComponents(tools) {
+        const schemas = {};
+        // Base response schemas
+        schemas.RestApiResponse = {
+            type: 'object',
+            properties: {
+                success: { type: 'boolean', description: 'Whether the request was successful' },
+                data: { type: 'object', description: 'Response data' },
+                error: {
+                    type: 'object',
+                    properties: {
+                        code: { type: 'string', description: 'Error code' },
+                        message: { type: 'string', description: 'Error message' },
+                        details: { type: 'object', description: 'Additional error details' }
+                    }
+                },
+                meta: {
+                    type: 'object',
+                    properties: {
+                        timestamp: { type: 'string', format: 'date-time', description: 'Response timestamp' },
+                        requestId: { type: 'string', description: 'Unique request identifier' },
+                        version: { type: 'string', description: 'API version' }
+                    }
+                }
+            },
+            required: ['success']
+        };
+        schemas.ToolExecutionResponse = {
+            allOf: [
+                { $ref: '#/components/schemas/RestApiResponse' },
+                {
+                    type: 'object',
+                    properties: {
+                        data: {
+                            type: 'object',
+                            properties: {
+                                result: { type: 'object', description: 'Tool execution result' },
+                                tool: { type: 'string', description: 'Name of the executed tool' },
+                                executionTime: { type: 'number', description: 'Execution time in milliseconds' }
+                            }
+                        }
+                    }
+                }
+            ]
+        };
+        schemas.ToolDiscoveryResponse = {
+            allOf: [
+                { $ref: '#/components/schemas/RestApiResponse' },
+                {
+                    type: 'object',
+                    properties: {
+                        data: {
+                            type: 'object',
+                            properties: {
+                                tools: {
+                                    type: 'array',
+                                    items: { $ref: '#/components/schemas/ToolInfo' }
+                                },
+                                total: { type: 'number', description: 'Total number of tools' },
+                                categories: {
+                                    type: 'array',
+                                    items: { type: 'string' },
+                                    description: 'Available tool categories'
+                                },
+                                tags: {
+                                    type: 'array',
+                                    items: { type: 'string' },
+                                    description: 'Available tool tags'
+                                }
+                            }
+                        }
+                    }
+                }
+            ]
+        };
+        schemas.ToolInfo = {
+            type: 'object',
+            properties: {
+                name: { type: 'string', description: 'Tool name' },
+                description: { type: 'string', description: 'Tool description' },
+                schema: { type: 'object', description: 'Tool input schema' },
+                category: { type: 'string', description: 'Tool category' },
+                tags: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Tool tags'
+                }
+            },
+            required: ['name', 'description', 'schema']
+        };
+        schemas.ErrorResponse = {
+            allOf: [
+                { $ref: '#/components/schemas/RestApiResponse' },
+                {
+                    type: 'object',
+                    properties: {
+                        success: { type: 'boolean', enum: [false] },
+                        error: {
+                            type: 'object',
+                            properties: {
+                                code: { type: 'string' },
+                                message: { type: 'string' },
+                                details: { type: 'object' }
+                            },
+                            required: ['code', 'message']
+                        }
+                    },
+                    required: ['error']
+                }
+            ]
+        };
+        // Individual tool request schemas
+        for (const tool of tools) {
+            schemas[`${tool.name}Request`] = tool.schema;
+        }
+        return {
+            schemas
+        };
+    }
+    /**
+     * Generate tags for grouping endpoints
+     */
+    generateTags(categories) {
+        const tags = [
+            {
+                name: 'Tool Discovery',
+                description: 'Endpoints for discovering available tools and their capabilities'
+            },
+            {
+                name: 'Documentation',
+                description: 'API documentation and specification endpoints'
+            }
+        ];
+        // Add category-based tags
+        for (const category of categories) {
+            tags.push({
+                name: category,
+                description: `${category} tools and operations`
+            });
+        }
+        // Add generic tools tag for uncategorized tools
+        if (this.registry.getAllTools().some(tool => !tool.category)) {
+            tags.push({
+                name: 'Tools',
+                description: 'General purpose tools and utilities'
+            });
+        }
+        return tags;
+    }
+    /**
+     * Generate example request body for a tool
+     */
+    generateExampleForTool(tool) {
+        const example = {};
+        try {
+            const schema = tool.schema;
+            if (schema.properties) {
+                for (const [propName, propSchema] of Object.entries(schema.properties)) {
+                    example[propName] = this.generateExampleValue(propSchema, propName);
+                }
+            }
+        }
+        catch (error) {
+            this.logger.warn('Failed to generate example for tool', {
+                toolName: tool.name,
+                error: error instanceof Error ? error.message : String(error)
+            });
+        }
+        return example;
+    }
+    /**
+     * Generate example value for a property schema
+     */
+    generateExampleValue(propSchema, propName) {
+        if (propSchema.example !== undefined) {
+            return propSchema.example;
+        }
+        switch (propSchema.type) {
+            case 'string':
+                if (propSchema.enum) {
+                    return propSchema.enum[0];
+                }
+                if (propName.toLowerCase().includes('email')) {
+                    return 'user@example.com';
+                }
+                if (propName.toLowerCase().includes('url')) {
+                    return 'https://example.com';
+                }
+                if (propName.toLowerCase().includes('name')) {
+                    return `example ${propName}`;
+                }
+                if (propName.toLowerCase().includes('intent')) {
+                    return 'deploy web application with PostgreSQL database';
+                }
+                return `example ${propName}`;
+            case 'number':
+            case 'integer':
+                if (propName.toLowerCase().includes('port')) {
+                    return 8080;
+                }
+                if (propName.toLowerCase().includes('timeout')) {
+                    return 30;
+                }
+                return 42;
+            case 'boolean':
+                return false;
+            case 'array':
+                return [this.generateExampleValue(propSchema.items, 'item')];
+            case 'object': {
+                const objExample = {};
+                if (propSchema.properties) {
+                    for (const [subPropName, subPropSchema] of Object.entries(propSchema.properties)) {
+                        objExample[subPropName] = this.generateExampleValue(subPropSchema, subPropName);
+                    }
+                }
+                return objExample;
+            }
+            default:
+                return `example ${propName}`;
+        }
+    }
+    /**
+     * Invalidate the specification cache
+     */
+    invalidateCache() {
+        this.specCache = undefined;
+        this.lastCacheUpdate = 0;
+        this.logger.debug('OpenAPI specification cache invalidated');
+    }
+    /**
+     * Update configuration
+     */
+    updateConfig(newConfig) {
+        this.config = { ...this.config, ...newConfig };
+        this.invalidateCache();
+        this.logger.info('OpenAPI generator configuration updated');
+    }
+    /**
+     * Get current configuration
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+}
+exports.OpenApiGenerator = OpenApiGenerator;

package/dist/interfaces/rest-api.d.ts

@@ -0,0 +1,124 @@
+/**
+ * REST API Router for MCP Tools
+ *
+ * Provides HTTP REST endpoints for all registered MCP tools.
+ * Handles routing, validation, execution, and response formatting.
+ */
+import { IncomingMessage, ServerResponse } from 'node:http';
+import { RestToolRegistry, ToolInfo } from './rest-registry';
+import { Logger } from '../core/error-handling';
+import { DotAI } from '../core/index';
+/**
+ * HTTP status codes for REST responses
+ */
+export declare enum HttpStatus {
+    OK = 200,
+    BAD_REQUEST = 400,
+    NOT_FOUND = 404,
+    METHOD_NOT_ALLOWED = 405,
+    INTERNAL_SERVER_ERROR = 500
+}
+/**
+ * Standard REST API response format
+ */
+export interface RestApiResponse {
+    success: boolean;
+    data?: any;
+    error?: {
+        code: string;
+        message: string;
+        details?: any;
+    };
+    meta?: {
+        timestamp: string;
+        requestId?: string;
+        version: string;
+    };
+}
+/**
+ * Tool execution response format
+ */
+export interface ToolExecutionResponse extends RestApiResponse {
+    data?: {
+        result: any;
+        tool: string;
+        executionTime?: number;
+    };
+}
+/**
+ * Tool discovery response format
+ */
+export interface ToolDiscoveryResponse extends RestApiResponse {
+    data?: {
+        tools: ToolInfo[];
+        total: number;
+        categories?: string[];
+        tags?: string[];
+    };
+}
+/**
+ * REST API router configuration
+ */
+export interface RestApiConfig {
+    basePath: string;
+    version: string;
+    enableCors: boolean;
+    requestTimeout: number;
+}
+/**
+ * REST API Router for MCP tools
+ */
+export declare class RestApiRouter {
+    private registry;
+    private logger;
+    private dotAI;
+    private config;
+    private openApiGenerator;
+    private requestCounter;
+    constructor(registry: RestToolRegistry, dotAI: DotAI, logger: Logger, config?: Partial<RestApiConfig>);
+    /**
+     * Handle incoming HTTP requests for REST API
+     */
+    handleRequest(req: IncomingMessage, res: ServerResponse, body?: any): Promise<void>;
+    /**
+     * Parse API path and extract route information
+     */
+    private parseApiPath;
+    /**
+     * Handle tool discovery requests
+     */
+    private handleToolDiscovery;
+    /**
+     * Handle tool execution requests
+     */
+    private handleToolExecution;
+    /**
+     * Handle OpenAPI specification requests
+     */
+    private handleOpenApiSpec;
+    /**
+     * Set CORS headers
+     */
+    private setCorsHeaders;
+    /**
+     * Send JSON response
+     */
+    private sendJsonResponse;
+    /**
+     * Send error response
+     */
+    private sendErrorResponse;
+    /**
+     * Generate unique request ID
+     */
+    private generateRequestId;
+    /**
+     * Check if the given path matches the REST API pattern
+     */
+    isApiRequest(pathname: string): boolean;
+    /**
+     * Get API configuration
+     */
+    getConfig(): RestApiConfig;
+}
+//# sourceMappingURL=rest-api.d.ts.map

package/dist/interfaces/rest-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rest-api.d.ts","sourceRoot":"","sources":["../../src/interfaces/rest-api.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAE5D,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAE7D,OAAO,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAChD,OAAO,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAEtC;;GAEG;AACH,oBAAY,UAAU;IACpB,EAAE,MAAM;IACR,WAAW,MAAM;IACjB,SAAS,MAAM;IACf,kBAAkB,MAAM;IACxB,qBAAqB,MAAM;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,GAAG,CAAC;IACX,KAAK,CAAC,EAAE;QACN,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,CAAC,EAAE,GAAG,CAAC;KACf,CAAC;IACF,IAAI,CAAC,EAAE;QACL,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,qBAAsB,SAAQ,eAAe;IAC5D,IAAI,CAAC,EAAE;QACL,MAAM,EAAE,GAAG,CAAC;QACZ,IAAI,EAAE,MAAM,CAAC;QACb,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,qBAAsB,SAAQ,eAAe;IAC5D,IAAI,CAAC,EAAE;QACL,KAAK,EAAE,QAAQ,EAAE,CAAC;QAClB,KAAK,EAAE,MAAM,CAAC;QACd,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;QACtB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;KACjB,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,OAAO,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAmB;IACnC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,KAAK,CAAQ;IACrB,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,gBAAgB,CAAmB;IAC3C,OAAO,CAAC,cAAc,CAAa;gBAGjC,QAAQ,EAAE,gBAAgB,EAC1B,KAAK,EAAE,KAAK,EACZ,MAAM,EAAE,MAAM,EACd,MAAM,GAAE,OAAO,CAAC,aAAa,CAAM;IAoBrC;;OAEG;IACG,aAAa,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,cAAc,EAAE,IAAI,CAAC,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;IA+EzF;;OAEG;IACH,OAAO,CAAC,YAAY;IAmCpB;;OAEG;YACW,mBAAmB;IA2CjC;;OAEG;YACW,mBAAmB;IA8FjC;;OAEG;YACW,iBAAiB;IA8B/B;;OAEG;IACH,OAAO,CAAC,cAAc;IAOtB;;OAEG;YACW,gBAAgB;IAK9B;;OAEG;YACW,iBAAiB;IAyB/B;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAIzB;;OAEG;IACH,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAIvC;;OAEG;IACH,SAAS,IAAI,aAAa;CAG3B"}