@democratize-quality/mcp-server 1.0.0

package/src/tools/api/api-session-status.js

@@ -0,0 +1,395 @@
+const ToolBase = require('../base/ToolBase');
+
+/**
+ * API Session Status Tool - Query API test session status and results
+ */
+class ApiSessionStatusTool extends ToolBase {
+    static definition = {
+        name: "api_session_status",
+        description: "Query API test session status, logs, and results by sessionId. Provides detailed information about request history and validation results.",
+        input_schema: {
+            type: "object",
+            properties: {
+                sessionId: {
+                    type: "string",
+                    description: "The session ID to query"
+                },
+                includeDetails: {
+                    type: "boolean",
+                    default: true,
+                    description: "Whether to include detailed request/response data"
+                },
+                filterByType: {
+                    type: "string",
+                    enum: ["single", "request", "chain", "all"],
+                    default: "all",
+                    description: "Filter logs by request type"
+                },
+                limit: {
+                    type: "number",
+                    default: 50,
+                    description: "Maximum number of log entries to return"
+                }
+            },
+            required: ["sessionId"]
+        },
+        output_schema: {
+            type: "object",
+            properties: {
+                success: { type: "boolean", description: "Whether the session was found" },
+                found: { type: "boolean", description: "Whether the session exists" },
+                session: {
+                    type: "object",
+                    properties: {
+                        sessionId: { type: "string" },
+                        status: { type: "string" },
+                        startTime: { type: "string" },
+                        endTime: { type: "string" },
+                        executionTime: { type: "number" },
+                        error: { type: "string" }
+                    },
+                    description: "Session metadata"
+                },
+                summary: {
+                    type: "object",
+                    properties: {
+                        totalRequests: { type: "number" },
+                        successfulRequests: { type: "number" },
+                        failedRequests: { type: "number" },
+                        chainSteps: { type: "number" },
+                        logEntries: { type: "number" }
+                    },
+                    description: "Session summary statistics"
+                },
+                logs: {
+                    type: "array",
+                    description: "Session log entries (filtered and limited)"
+                },
+                validationSummary: {
+                    type: "object",
+                    properties: {
+                        passedValidations: { type: "number" },
+                        failedValidations: { type: "number" },
+                        validationRate: { type: "number" }
+                    },
+                    description: "Validation statistics"
+                }
+            },
+            required: ["success", "found"]
+        }
+    };
+
+    constructor() {
+        super();
+        // Access the global session store
+        if (!global.__API_SESSION_STORE__) {
+            global.__API_SESSION_STORE__ = new Map();
+        }
+        this.sessionStore = global.__API_SESSION_STORE__;
+    }
+
+    async execute(parameters) {
+        const {
+            sessionId,
+            includeDetails = true,
+            filterByType = "all",
+            limit = 50
+        } = parameters;
+
+        const session = this.sessionStore.get(sessionId);
+        
+        if (!session) {
+            return {
+                success: false,
+                found: false,
+                message: `Session not found: ${sessionId}`,
+                availableSessions: Array.from(this.sessionStore.keys())
+            };
+        }
+
+        // Filter logs by type
+        let filteredLogs = session.logs || [];
+        if (filterByType !== "all") {
+            filteredLogs = filteredLogs.filter(log => log.type === filterByType);
+        }
+
+        // Apply limit
+        const logs = filteredLogs.slice(-limit);
+
+        // Generate summary statistics
+        const summary = this.generateSummary(session.logs || []);
+        const validationSummary = this.generateValidationSummary(session.logs || []);
+
+        // Prepare session metadata (without sensitive details if not requested)
+        const sessionMetadata = {
+            sessionId: session.sessionId,
+            status: session.status,
+            startTime: session.startTime,
+            endTime: session.endTime,
+            executionTime: session.executionTime,
+            error: session.error
+        };
+
+        // Optionally strip detailed request/response data
+        const processedLogs = includeDetails 
+            ? logs 
+            : logs.map(log => this.stripSensitiveData(log));
+
+        return {
+            success: true,
+            found: true,
+            session: sessionMetadata,
+            summary,
+            validationSummary,
+            logs: processedLogs,
+            logCount: logs.length,
+            totalLogCount: (session.logs || []).length
+        };
+    }
+
+    /**
+     * Generate summary statistics for the session
+     */
+    generateSummary(logs) {
+        const summary = {
+            totalRequests: 0,
+            successfulRequests: 0,
+            failedRequests: 0,
+            chainSteps: 0,
+            singleRequests: 0,
+            logEntries: logs.length
+        };
+
+        for (const log of logs) {
+            switch (log.type) {
+                case 'single':
+                    summary.totalRequests++;
+                    summary.singleRequests++;
+                    if (this.isRequestSuccessful(log)) {
+                        summary.successfulRequests++;
+                    } else {
+                        summary.failedRequests++;
+                    }
+                    break;
+                    
+                case 'request':
+                    summary.totalRequests++;
+                    summary.chainSteps++;
+                    if (this.isRequestSuccessful(log)) {
+                        summary.successfulRequests++;
+                    } else {
+                        summary.failedRequests++;
+                    }
+                    break;
+                    
+                case 'chain':
+                    // Chain logs contain summary of multiple steps
+                    if (log.steps) {
+                        summary.chainSteps += log.steps.length;
+                    }
+                    break;
+            }
+        }
+
+        return summary;
+    }
+
+    /**
+     * Generate validation summary statistics
+     */
+    generateValidationSummary(logs) {
+        let passedValidations = 0;
+        let failedValidations = 0;
+        let totalValidations = 0;
+
+        for (const log of logs) {
+            if (log.validation && log.bodyValidation) {
+                totalValidations++;
+                
+                const isValid = log.validation.status && 
+                               log.validation.contentType && 
+                               log.bodyValidation.matched;
+                
+                if (isValid) {
+                    passedValidations++;
+                } else {
+                    failedValidations++;
+                }
+            }
+            
+            // Also check chain steps
+            if (log.type === 'chain' && log.steps) {
+                for (const step of log.steps) {
+                    if (step.validation && step.bodyValidation) {
+                        totalValidations++;
+                        
+                        const isValid = step.validation.status && 
+                                       step.validation.contentType && 
+                                       step.bodyValidation.matched;
+                        
+                        if (isValid) {
+                            passedValidations++;
+                        } else {
+                            failedValidations++;
+                        }
+                    }
+                }
+            }
+        }
+
+        return {
+            passedValidations,
+            failedValidations,
+            totalValidations,
+            validationRate: totalValidations > 0 
+                ? Math.round((passedValidations / totalValidations) * 100) / 100 
+                : 0
+        };
+    }
+
+    /**
+     * Check if a request was successful based on validation
+     */
+    isRequestSuccessful(log) {
+        return log.validation && 
+               log.bodyValidation &&
+               log.validation.status && 
+               log.validation.contentType && 
+               log.bodyValidation.matched;
+    }
+
+    /**
+     * Remove sensitive data from logs when details are not requested
+     */
+    stripSensitiveData(log) {
+        const stripped = {
+            type: log.type,
+            timestamp: log.timestamp
+        };
+
+        if (log.request) {
+            stripped.request = {
+                method: log.request.method,
+                url: log.request.url,
+                hasHeaders: !!(log.request.headers && Object.keys(log.request.headers).length > 0),
+                hasData: !!log.request.data
+            };
+        }
+
+        if (log.response) {
+            stripped.response = {
+                status: log.response.status,
+                contentType: log.response.contentType,
+                hasBody: !!log.response.body
+            };
+        }
+
+        if (log.validation) {
+            stripped.validation = log.validation;
+        }
+
+        if (log.bodyValidation) {
+            stripped.bodyValidation = {
+                matched: log.bodyValidation.matched,
+                reason: log.bodyValidation.reason
+            };
+        }
+
+        // Handle chain steps
+        if (log.steps) {
+            stripped.steps = log.steps.map(step => this.stripSensitiveData({
+                type: 'request',
+                request: step.request || {
+                    method: step.method,
+                    url: step.url,
+                    headers: step.headers,
+                    data: step.data
+                },
+                response: {
+                    status: step.status,
+                    contentType: step.contentType,
+                    body: step.body
+                },
+                validation: step.validation,
+                bodyValidation: step.bodyValidation
+            }));
+        }
+
+        return stripped;
+    }
+
+    /**
+     * Get detailed analysis of a specific request by index
+     */
+    getRequestDetails(sessionId, requestIndex) {
+        const session = this.sessionStore.get(sessionId);
+        if (!session || !session.logs) {
+            return null;
+        }
+
+        const requestLogs = session.logs.filter(log => 
+            log.type === 'single' || log.type === 'request'
+        );
+
+        if (requestIndex >= requestLogs.length) {
+            return null;
+        }
+
+        return requestLogs[requestIndex];
+    }
+
+    /**
+     * Get session timing analysis
+     */
+    getTimingAnalysis(sessionId) {
+        const session = this.sessionStore.get(sessionId);
+        if (!session || !session.logs) {
+            return null;
+        }
+
+        const requests = session.logs.filter(log => 
+            log.type === 'single' || log.type === 'request'
+        );
+
+        if (requests.length === 0) {
+            return { message: 'No requests found for timing analysis' };
+        }
+
+        // Calculate request intervals
+        const timings = [];
+        for (let i = 0; i < requests.length; i++) {
+            const current = new Date(requests[i].timestamp);
+            const previous = i > 0 ? new Date(requests[i - 1].timestamp) : new Date(session.startTime);
+            
+            timings.push({
+                requestIndex: i,
+                timestamp: requests[i].timestamp,
+                intervalMs: current.getTime() - previous.getTime()
+            });
+        }
+
+        return {
+            totalRequests: requests.length,
+            sessionDuration: session.executionTime || 0,
+            averageInterval: timings.reduce((sum, t) => sum + t.intervalMs, 0) / timings.length,
+            timings
+        };
+    }
+
+    /**
+     * List all available sessions
+     */
+    listAllSessions() {
+        return Array.from(this.sessionStore.entries()).map(([id, session]) => ({
+            sessionId: id,
+            status: session.status,
+            startTime: session.startTime,
+            requestCount: (session.logs || []).filter(log => 
+                log.type === 'single' || log.type === 'request'
+            ).length,
+            logCount: (session.logs || []).length
+        }));
+    }
+}
+
+module.exports = ApiSessionStatusTool;

package/src/tools/base/ToolBase.js

@@ -0,0 +1,230 @@
+/**
+ * Base class for all MCP tools
+ * Provides common functionality and enforces a consistent interface
+ */
+class ToolBase {
+    constructor() {
+        if (this.constructor === ToolBase) {
+            throw new Error("ToolBase is an abstract class and cannot be instantiated directly");
+        }
+        
+        // Validate that required static properties are defined
+        if (!this.constructor.definition) {
+            throw new Error(`Tool ${this.constructor.name} must define a static 'definition' property`);
+        }
+        
+        this.validateDefinition(this.constructor.definition);
+        
+        // Initialize configuration
+        this.config = require('../../config');
+        this.toolConfig = this._getToolConfig();
+    }
+
+    /**
+     * Get tool-specific configuration
+     * @returns {object} - Tool configuration
+     */
+    _getToolConfig() {
+        const toolName = this.constructor.definition.name;
+        const category = this._getToolCategory(toolName);
+        
+        // Get configuration in order of precedence:
+        // 1. Tool-specific config
+        // 2. Category config
+        // 3. Default config
+        return {
+            ...this.config.getToolConfig('default', {}),
+            ...this.config.getToolConfig(category, {}),
+            ...this.config.getToolConfig(category, toolName)
+        };
+    }
+
+    /**
+     * Get tool category from tool name
+     * @param {string} toolName - The tool name
+     * @returns {string} - The tool category
+     */
+    _getToolCategory(toolName) {
+        if (toolName.startsWith('browser_')) return 'browser';
+        if (toolName.startsWith('file_')) return 'file';
+        if (toolName.startsWith('network_')) return 'network';
+        return 'other';
+    }
+
+    /**
+     * Get a configuration value for this tool
+     * @param {string} key - Configuration key
+     * @param {any} defaultValue - Default value
+     * @returns {any} - Configuration value
+     */
+    getConfig(key, defaultValue = undefined) {
+        return this.toolConfig[key] !== undefined ? this.toolConfig[key] : defaultValue;
+    }
+
+    /**
+     * Validates the tool definition schema
+     * @param {object} definition - The tool definition object
+     */
+    validateDefinition(definition) {
+        const required = ['name', 'description', 'input_schema'];
+        for (const field of required) {
+            if (!definition[field]) {
+                throw new Error(`Tool definition missing required field: ${field}`);
+            }
+        }
+        
+        if (!definition.input_schema.type || definition.input_schema.type !== 'object') {
+            throw new Error("Tool input_schema must be of type 'object'");
+        }
+    }
+
+    /**
+     * Validates input parameters against the tool's schema
+     * @param {object} parameters - The input parameters to validate
+     */
+    validateParameters(parameters) {
+        const schema = this.constructor.definition.input_schema;
+        
+        // Check required parameters
+        if (schema.required) {
+            for (const required of schema.required) {
+                if (parameters[required] === undefined || parameters[required] === null) {
+                    throw new Error(`Missing required parameter: ${required}`);
+                }
+            }
+        }
+        
+        // Basic type checking for defined properties
+        if (schema.properties) {
+            for (const [key, value] of Object.entries(parameters)) {
+                if (schema.properties[key]) {
+                    const expectedType = schema.properties[key].type;
+                    const actualType = typeof value;
+                    
+                    if (expectedType === 'string' && actualType !== 'string') {
+                        throw new Error(`Parameter '${key}' must be a string, got ${actualType}`);
+                    }
+                    if (expectedType === 'number' && actualType !== 'number') {
+                        throw new Error(`Parameter '${key}' must be a number, got ${actualType}`);
+                    }
+                    if (expectedType === 'boolean' && actualType !== 'boolean') {
+                        throw new Error(`Parameter '${key}' must be a boolean, got ${actualType}`);
+                    }
+                    if (expectedType === 'object' && (actualType !== 'object' || Array.isArray(value))) {
+                        throw new Error(`Parameter '${key}' must be an object, got ${actualType}`);
+                    }
+                }
+            }
+        }
+    }
+
+    /**
+     * Executes the tool with the given parameters
+     * This method must be implemented by subclasses
+     * @param {object} parameters - The input parameters
+     * @returns {Promise<any>} - The tool execution result
+     */
+    async execute(parameters) {
+        throw new Error("execute() method must be implemented by subclasses");
+    }
+
+    /**
+     * Wrapper method that handles validation, execution, and error handling
+     * @param {object} parameters - The input parameters
+     * @returns {Promise<object>} - Formatted MCP response
+     */
+    async run(parameters = {}) {
+        const toolName = this.constructor.definition.name;
+        const enableDebug = this.config.isFeatureEnabled('enableDebugMode');
+        
+        try {
+            if (enableDebug) {
+                console.error(`[Tool:${toolName}] Executing with parameters:`, JSON.stringify(parameters));
+            }
+            
+            // Validate input parameters if validation is enabled
+            if (this.getConfig('enableInputValidation', true)) {
+                this.validateParameters(parameters);
+            }
+            
+            // Execute the tool with timeout if configured
+            const timeout = this.getConfig('timeout', 30000);
+            const result = await this._executeWithTimeout(parameters, timeout);
+            
+            if (enableDebug) {
+                console.error(`[Tool:${toolName}] Execution successful`);
+            }
+            
+            // Return formatted MCP response
+            return {
+                content: [{
+                    type: "text",
+                    text: JSON.stringify(result)
+                }]
+            };
+            
+        } catch (error) {
+            const enableDetailedErrors = this.getConfig('enableDetailedErrors', true);
+            
+            if (enableDetailedErrors || enableDebug) {
+                console.error(`[Tool:${toolName}] Error during execution:`, error.message);
+            }
+            
+            // Throw properly formatted MCP error
+            throw {
+                code: -32000,
+                message: `Tool '${toolName}' execution failed: ${error.message}`,
+                data: enableDetailedErrors ? {
+                    tool_name: toolName,
+                    parameters: parameters,
+                    original_error: error.message,
+                    config: this.toolConfig
+                } : {
+                    tool_name: toolName,
+                    original_error: error.message
+                }
+            };
+        }
+    }
+
+    /**
+     * Execute the tool with a timeout
+     * @param {object} parameters - The input parameters
+     * @param {number} timeout - Timeout in milliseconds
+     * @returns {Promise<any>} - Execution result
+     */
+    async _executeWithTimeout(parameters, timeout) {
+        return new Promise(async (resolve, reject) => {
+            const timeoutId = setTimeout(() => {
+                reject(new Error(`Tool execution timed out after ${timeout}ms`));
+            }, timeout);
+            
+            try {
+                const result = await this.execute(parameters);
+                clearTimeout(timeoutId);
+                resolve(result);
+            } catch (error) {
+                clearTimeout(timeoutId);
+                reject(error);
+            }
+        });
+    }
+
+    /**
+     * Gets the tool definition
+     * @returns {object} - The tool definition
+     */
+    static getDefinition() {
+        return this.definition;
+    }
+
+    /**
+     * Gets the tool name from the definition
+     * @returns {string} - The tool name
+     */
+    static getName() {
+        return this.definition.name;
+    }
+}
+
+module.exports = ToolBase;