@democratize-quality/mcp-server 1.1.8 → 1.2.0

package/src/services/browserService.js

@@ -1,325 +0,0 @@
-const CDP = require('chrome-remote-interface');
-//const launchChrome = require('chrome-launcher').launch;
-const fs = require('fs');
-const path = require('path');
-const { findNodeBySelector, getElementClickCoordinates } = require('../utils/browserHelpers'); // Import helpers
-const config = require('../config');
-
-// A private in-memory store for our browser instances within the service
-// Each key will be a unique browserId, value will be { chromeInstance, cdpClient, userDataDir }
-const activeBrowsers = {};
-
-/**
- * Ensures a user data directory exists.
- * @param {string} dirPath - The absolute path to the user data directory.
- */
-function ensureUserDataDir(dirPath) {
-    if (!fs.existsSync(dirPath)) {
-        fs.mkdirSync(dirPath, { recursive: true });
-        console.log(`[BrowserService] Created user data directory: ${dirPath}`);
-    } else {
-        console.log(`[BrowserService] Using existing user data directory: ${dirPath}`);
-    }
-}
-
-/**
- * Retrieves a browser instance by ID.
- * @param {string} browserId - The ID of the browser instance.
- * @returns {object|null} - The browser instance object or null if not found.
- */
-function getBrowserInstance(browserId) {
-    return activeBrowsers[browserId];
-}
-
-/**
- * Launches a new Chrome instance.
- * @param {boolean} headless - Whether to run Chrome in headless mode.
- * @param {number} port - The port for remote debugging.
- * @param {string|null} userDataDir - Path to the user data directory for persistent profiles.
- * @returns {Promise<object>} - Object containing browserId, port, and resolvedUserDataDir.
- */
-async function launchBrowser(headless, port, userDataDir) {
-    let chrome;
-    let client;
-    const { launch: launchChrome } = await import('chrome-launcher');
-    let resolvedUserDataDir = null;
-
-    try {
-        if (userDataDir) {
-            resolvedUserDataDir = path.resolve(process.cwd(), userDataDir);
-            ensureUserDataDir(resolvedUserDataDir);
-        }
-
-        console.log(`[BrowserService] Launching Chrome (headless: ${headless}, userDataDir: ${resolvedUserDataDir || 'temporary'})...`);
-
-        const launchOptions = {
-            port: port,
-            userDataDir: resolvedUserDataDir, // Set userDataDir if provided
-            chromeFlags: [
-                headless ? '--headless=new' : '',
-                '--disable-gpu',
-                '--disable-setuid-sandbox',
-                '--no-sandbox'
-            ].filter(Boolean)
-        };
-
-        chrome = await launchChrome(launchOptions);
-
-        // Generate browserId: profile-name if userDataDir is used, otherwise a unique timestamped ID
-        const browserId = userDataDir ? `profile-${path.basename(resolvedUserDataDir)}` : `browser-${Date.now()}-${Math.random().toString(36).substring(2, 9)}`;
-
-        if (activeBrowsers[browserId]) {
-            console.warn(`[BrowserService] Warning: Browser ID '${browserId}' already exists. Overwriting.`);
-            // In a real scenario, you might want more sophisticated handling here,
-            // e.g., error if ID exists, or try to attach to existing.
-            // For now, we're assuming a new launch means a fresh start or overwrite.
-            try { // Attempt to clean up old instance if it exists
-                if (activeBrowsers[browserId].cdpClient) activeBrowsers[browserId].cdpClient.close();
-                if (activeBrowsers[browserId].chromeInstance) await activeBrowsers[browserId].chromeInstance.kill();
-            } catch (cleanupErr) {
-                console.error(`[BrowserService] Error cleaning up old instance for ${browserId}:`, cleanupErr.message);
-            }
-        }
-
-        activeBrowsers[browserId] = { chromeInstance: chrome, cdpClient: null, userDataDir: resolvedUserDataDir };
-        console.log(`[BrowserService] Chrome launched on port ${chrome.port} with ID: ${browserId}`);
-
-        client = await CDP({ port: chrome.port });
-        activeBrowsers[browserId].cdpClient = client;
-
-        const { Page, Runtime, DOM, Network, Security, Input } = client; // Enable Input domain here
-        await Page.enable();
-        await Runtime.enable();
-        await DOM.enable();
-        await Network.enable();
-        await Security.enable();
-        //await Input.enable(); // Enable Input domain
-
-        console.log(`[BrowserService] CDP client connected and domains enabled for ${browserId}.`);
-
-        return { browserId, port: chrome.port, userDataDir: resolvedUserDataDir };
-
-    } catch (error) {
-        console.error(`[BrowserService] Error launching browser:`, error);
-        if (chrome && !client) { // If chrome launched but CDP connection failed
-            try {
-                await chrome.kill();
-                console.log(`[BrowserService] Partially launched Chrome instance killed due to error.`);
-            } catch (killError) {
-                console.error(`[BrowserService] Error killing partially launched Chrome:`, killError);
-            }
-        }
-        throw error; // Re-throw to be caught by the route handler
-    }
-}
-
-/**
- * Navigates a specific browser instance to a URL.
- * @param {string} browserId - The ID of the browser instance.
- * @param {string} url - The URL to navigate to.
- * @returns {Promise<void>}
- */
-async function navigateBrowser(browserId, url) {
-    const instance = getBrowserInstance(browserId);
-    if (!instance) throw new Error(`Browser instance with ID '${browserId}' not found.`);
-
-    const { cdpClient } = instance;
-    console.log(`[BrowserService] Browser ${browserId} navigating to: ${url}`);
-    await cdpClient.Page.navigate({ url: url });
-    await cdpClient.Page.loadEventFired(); // Wait for page to load
-    console.log(`[BrowserService] Browser ${browserId} successfully navigated to ${url}.`);
-}
-
-/**
- * Takes a screenshot of a specific browser page and can save it to disk.
- * @param {string} browserId - The ID of the browser instance.
- * @param {string} [fileName='screenshot.png'] - Optional: The name of the file to save the screenshot as.
- * @param {boolean} [saveToDisk=true] - Optional: Whether to save the screenshot to disk.
- * @returns {Promise<string>} - Base64 encoded screenshot data.
- */
-async function takeScreenshot(browserId, fileName = 'screenshot.png', saveToDisk = true) { // Added fileName and saveToDisk params
-    const instance = getBrowserInstance(browserId);
-    if (!instance) throw new Error(`Browser instance with ID '${browserId}' not found.`);
-
-    const { cdpClient } = instance;
-    console.log(`[BrowserService] Taking screenshot for browser ${browserId}...`);
-    const screenshot = await cdpClient.Page.captureScreenshot({ format: 'png', quality: 80 });
-
-    if (saveToDisk) {
-        const screenshotBuffer = Buffer.from(screenshot.data, 'base64');
-        // Ensure the output directory exists
-        if (!fs.existsSync(config.OUTPUT_DIR)) {
-            fs.mkdirSync(config.OUTPUT_DIR, { recursive: true });
-        }
-        const filePath = path.join(config.OUTPUT_DIR, fileName);
-        fs.writeFileSync(filePath, screenshotBuffer);
-        console.log(`[BrowserService] Screenshot saved to ${filePath}`);
-    }
-
-    console.log(`[BrowserService] Screenshot captured for browser ${browserId}.`);
-    return screenshot.data; // Always return base64 data to the caller (e.g., AI agent)
-}
-
-/**
- * Gets the current DOM content of a specific browser page.
- * @param {string} browserId - The ID of the browser instance.
- * @returns {Promise<string>} - The outer HTML of the document.
- */
-async function getDomContent(browserId) {
-    const instance = getBrowserInstance(browserId);
-    if (!instance) throw new Error(`Browser instance with ID '${browserId}' not found.`);
-
-    const { cdpClient } = instance;
-    console.log(`[BrowserService] Getting DOM for browser ${browserId}...`);
-    const documentNode = await cdpClient.DOM.getDocument({ depth: -1 });
-    const outerHTML = await cdpClient.DOM.getOuterHTML({ nodeId: documentNode.root.nodeId });
-    console.log(`[BrowserService] DOM content retrieved for browser ${browserId}.`);
-    return outerHTML.outerHTML;
-}
-
-/**
- * Clicks an element identified by a locator.
- * @param {string} browserId - The ID of the browser instance.
- * @param {object} locator - { type: 'css'|'xpath', value: 'selector' }
- * @returns {Promise<object>} - Coordinates of the click.
- */
-async function clickElement(browserId, locator) {
-    const instance = getBrowserInstance(browserId);
-    if (!instance) throw new Error(`Browser instance with ID '${browserId}' not found.`);
-
-    const { cdpClient } = instance;
-    const { Input } = cdpClient;
-
-    console.log(`[BrowserService] Browser ${browserId}: Attempting to click element with locator:`, locator);
-
-    const nodeId = await findNodeBySelector(cdpClient, locator.type, locator.value);
-    if (!nodeId) {
-        throw new Error(`Element not found for locator: ${JSON.stringify(locator)}`);
-    }
-
-    const coords = await getElementClickCoordinates(cdpClient, nodeId);
-    if (!coords) {
-        throw new Error(`Could not determine click coordinates for element: ${JSON.stringify(locator)}`);
-    }
-
-    await Input.dispatchMouseEvent({
-        type: 'mousePressed',
-        button: 'left',
-        x: coords.x,
-        y: coords.y,
-        clickCount: 1
-    });
-    await Input.dispatchMouseEvent({
-        type: 'mouseReleased',
-        button: 'left',
-        x: coords.x,
-        y: coords.y,
-        clickCount: 1
-    });
-
-    console.log(`[BrowserService] Browser ${browserId}: Clicked element at x: ${coords.x}, y: ${coords.y}`);
-    return coords;
-}
-
-/**
- * Types text into an element identified by a locator.
- * @param {string} browserId - The ID of the browser instance.
- * @param {object} locator - { type: 'css'|'xpath', value: 'selector' }
- * @param {string} text - The text to type.
- * @returns {Promise<void>}
- */
-async function typeIntoElement(browserId, locator, text) {
-    const instance = getBrowserInstance(browserId);
-    if (!instance) throw new Error(`Browser instance with ID '${browserId}' not found.`);
-
-    const { cdpClient } = instance;
-    const { DOM, Input } = cdpClient;
-
-    console.log(`[BrowserService] Browser ${browserId}: Attempting to type "${text}" into element with locator:`, locator);
-
-    const nodeId = await findNodeBySelector(cdpClient, locator.type, locator.value);
-    if (!nodeId) {
-        throw new Error(`Element not found for locator: ${JSON.stringify(locator)}`);
-    }
-
-    await DOM.focus({ nodeId: nodeId });
-    await new Promise(resolve => setTimeout(resolve, 50)); // Small delay for focus
-
-    // Clear existing text: Cmd/Ctrl+A then Backspace
-    await Input.dispatchKeyEvent({ type: 'keyDown', text: 'a', modifiers: (process.platform === 'darwin' ? 4 : 2) }); // 4 for Meta (Cmd), 2 for Control
-    await Input.dispatchKeyEvent({ type: 'keyUp', text: 'a', modifiers: (process.platform === 'darwin' ? 4 : 2) });
-    await Input.dispatchKeyEvent({ type: 'keyDown', key: 'Backspace' });
-    await Input.dispatchKeyEvent({ type: 'keyUp', key: 'Backspace' });
-    await new Promise(resolve => setTimeout(resolve, 50)); // Small delay for clear
-
-    for (const char of text) {
-        await Input.dispatchKeyEvent({ type: 'keyDown', text: char, key: char });
-        await Input.dispatchKeyEvent({ type: 'keyUp', text: char, key: char });
-        await new Promise(resolve => setTimeout(resolve, 10)); // Small delay for realism
-    }
-
-    console.log(`[BrowserService] Browser ${browserId}: Typed "${text}" into element.`);
-}
-
-/**
- * Closes a specific browser instance.
- * @param {string} browserId - The ID of the browser instance.
- * @returns {Promise<void>}
- */
-async function closeBrowser(browserId) {
-    const instance = getBrowserInstance(browserId);
-    if (!instance) throw new Error(`Browser instance with ID '${browserId}' not found.`);
-
-    const { chromeInstance, cdpClient, userDataDir } = instance;
-
-    console.log(`[BrowserService] Closing browser ${browserId} (profile: ${userDataDir || 'temporary'})...`);
-    if (cdpClient) {
-        try {
-            cdpClient.close();
-            console.log(`[BrowserService] CDP client disconnected for ${browserId}.`);
-        } catch (err) {
-            console.warn(`[BrowserService] Error during CDP client close for ${browserId}:`, err.message);
-        }
-    }
-    if (chromeInstance) {
-        try {
-            await chromeInstance.kill();
-            console.log(`[BrowserService] Chrome instance ${browserId} killed.`);
-        } catch (err) {
-            console.warn(`[BrowserService] Error during Chrome instance kill for ${browserId}:`, err.message);
-        }
-    }
-    delete activeBrowsers[browserId]; // Remove from our store
-    console.log(`[BrowserService] Browser ${browserId} removed from active list.`);
-}
-
-/**
- * Shuts down all active browser instances. Used for graceful server shutdown.
- * @returns {Promise<void>}
- */
-async function shutdownAllBrowsers() {
-    const browserIds = Object.keys(activeBrowsers);
-    if (browserIds.length === 0) {
-        console.log('[BrowserService] No active browsers to shut down.');
-        return;
-    }
-    console.log(`[BrowserService] Shutting down ${browserIds.length} active browser(s)...`);
-    await Promise.all(browserIds.map(id => closeBrowser(id).catch(err => {
-        console.error(`[BrowserService] Failed to gracefully close browser ${id}:`, err.message);
-        // Continue with other shutdowns even if one fails
-    })));
-    console.log('[BrowserService] All active browsers shut down.');
-}
-
-
-module.exports = {
-    launchBrowser,
-    navigateBrowser,
-    getBrowserInstance,
-    takeScreenshot,
-    getDomContent,
-    clickElement,
-    typeIntoElement,
-    closeBrowser,
-    shutdownAllBrowsers // Export for server.js to use
-};

package/src/skills/api-planning/SKILL.md

@@ -1,224 +0,0 @@
----
-name: api-planning
-description: Analyze API schemas (OpenAPI, Swagger, GraphQL) and create comprehensive test plans with realistic sample data and optional endpoint validation. Use when user mentions API testing, test plans, test coverage, API documentation, schema analysis, REST APIs, GraphQL APIs, test scenarios, or needs to plan API test strategy.
----
-
-# API Test Planning Skill
-
-Use this skill to analyze API schemas and generate comprehensive test plans with realistic, context-aware sample data.
-
-## When to Use This Skill
-
-- User provides an API schema URL or file path
-- User mentions creating test plans for APIs
-- User needs to analyze API documentation
-- User wants to validate API endpoints
-- User requests test coverage analysis for REST or GraphQL APIs
-
-## Core Workflow
-
-### Step 1: Generate Test Plan with Realistic Samples
-
-When user provides a schema URL or file path, use the `api_planner` tool from the democratize-quality MCP server:
-
-```javascript
-await tools.api_planner({
-  schemaUrl: "https://api.example.com/swagger.json",
-  // OR schemaPath: "./schema.graphql" for local files
-  apiBaseUrl: "https://api.example.com",
-  includeAuth: true,
-  includeSecurity: true,
-  includeErrorHandling: true,
-  outputPath: "./api-test-plan.md",
-  testCategories: ["functional", "security", "performance", "integration", "edge-cases"],
-  validateEndpoints: false  // Set to true for live validation
-})
-```
-
-**Important Workflow Rules:**
-1. Call `api_planner` tool ONCE to generate the test plan
-2. Review the results and explain what was generated to the user
-3. Answer questions based on the generated output
-4. Only call api_planner again if user explicitly requests a new/different test plan
-
-### Step 2: Optional Endpoint Validation
-
-When API is accessible, enable validation to verify schemas match reality:
-
-```javascript
-await tools.api_planner({
-  schemaUrl: "https://api.example.com/swagger.json",
-  validateEndpoints: true,
-  validationSampleSize: 3,  // Default: 3, use -1 for all endpoints
-  validationTimeout: 5000   // 5 seconds per request
-})
-```
-
-**Validation Features:**
-- Real API testing with actual responses
-- Response time metrics
-- Success/failure indicators (✅/❌)
-- Validation summary with success rate
-- Graceful error handling
-
-## What You Get
-
-### Without Validation (Fast):
-- Test plan with realistic sample data
-- Context-aware field values (names, emails, dates)
-- Ready-to-use test data
-
-### With Validation (Comprehensive):
-- Test plan with realistic samples
-- Validation summary (success rate, statistics)
-- Per-endpoint validation results
-- Actual API responses captured
-- Response time metrics for each endpoint
-
-## Working with Schema Files
-
-### GraphQL SDL Files (.graphql, .gql)
-**ALWAYS use `schemaPath` parameter for SDL files:**
-
-```javascript
-await tools.api_planner({
-  schemaPath: "./schema.graphql",  // Tool reads full file, converts SDL to introspection
-  outputPath: "./test-plan.md"
-})
-```
-
-**What happens:**
-- Tool reads full file (no truncation)
-- Automatically converts SDL → Introspection JSON
-- Saves `schema.json` alongside `schema.graphql`
-- Generates test plan from introspection
-
-### OpenAPI/Swagger Files
-- Use `schemaPath` for local files (`.json`, `.yaml`, `.yml`)
-- Use `schemaUrl` for remote URLs
-
-## Realistic Sample Data Generation
-
-The tool generates context-aware sample data automatically:
-
-**50+ Field Patterns:**
-- Personal info: `firstName` → "John", `email` → "john.doe@example.com"
-- Contact: `phoneNumber` → "+1-555-0123", `city` → "New York"
-- Business: `company` → "Acme Corp", `jobTitle` → "Engineer"
-- Identifiers: `uuid` → valid UUID, `token` → realistic token
-- Content: `title` → "Report Title", `description` → meaningful text
-- Numeric: `price` → 19.99, `age` → 25, `rating` → 4.5
-- Dates: `createdAt` → "2026-02-15T10:30:00Z"
-
-## Advanced Scenarios
-
-### Scenario 1: Local Schema File
-```javascript
-await tools.api_planner({
-  schemaPath: "./openapi.json",
-  apiBaseUrl: "https://staging-api.example.com",
-  validateEndpoints: true
-})
-```
-
-### Scenario 2: GraphQL API
-```javascript
-await tools.api_planner({
-  schemaUrl: "https://api.example.com/graphql",
-  schemaType: "graphql",
-  testCategories: ["functional", "edge-cases"]
-})
-```
-
-### Scenario 3: Multiple Related Services
-```javascript
-const services = [
-  { url: "https://api1.example.com/swagger.json", name: "auth-service" },
-  { url: "https://api2.example.com/swagger.json", name: "user-service" }
-]
-
-for (const service of services) {
-  await tools.api_planner({
-    schemaUrl: service.url,
-    outputPath: `./${service.name}-test-plan.md`
-  })
-}
-```
-
-## Best Practices
-
-### DO:
-- Use api_planner once per schema
-- Enable validation when API is accessible
-- Use schemaPath for local files (especially GraphQL SDL)
-- Review validation results for API issues
-- Save plans to files using outputPath parameter
-- Include security and edge case testing
-
-### DON'T:
-- Don't call api_planner multiple times without user request
-- Don't regenerate plans just to answer questions
-- Don't skip validation if API is accessible
-- Don't ignore failed validations
-- Don't validate all endpoints for large APIs (use validationSampleSize)
-
-## Parameter Reference
-
-**Required (one of):**
-- `schemaUrl` - URL to fetch schema
-- `schemaPath` - Local file path
-
-**Common Optional:**
-- `apiBaseUrl` - Override base URL from schema
-- `outputPath` - Save test plan to file
-- `includeAuth` - Include auth scenarios (default: false)
-- `includeSecurity` - Include security scenarios (default: false)
-- `includeErrorHandling` - Include error scenarios (default: false)
-- `testCategories` - Array of test types
-
-**Validation Optional:**
-- `validateEndpoints` - Enable actual API testing (default: false)
-- `validationSampleSize` - Number to validate (default: 3, -1 = all)
-- `validationTimeout` - Timeout in ms (default: 5000)
-
-## Troubleshooting
-
-### Issue: Validation Not Running
-- Ensure `validateEndpoints: true` is set explicitly
-
-### Issue: All Validations Fail with 401/403
-- API requires authentication
-- Use api_request tool to test with proper auth headers
-- Document auth requirements in manual review
-
-### Issue: Validation Timeout
-- Increase `validationTimeout` parameter (e.g., 10000 for 10s)
-
-### Issue: Schema Parse Errors
-- Verify schema URL is accessible
-- Check schema format compatibility
-- Try using `schemaPath` for local files
-
-## Additional Validation Tools
-
-If you need to validate specific endpoints manually:
-
-```javascript
-await tools.api_request({
-  sessionId: "validation-session",
-  method: "GET",
-  url: "https://api.example.com/endpoint",
-  expect: { status: 200 }
-})
-
-// Check session status
-await tools.api_session_status({
-  sessionId: "validation-session"
-})
-
-// Generate report
-await tools.api_session_report({
-  sessionId: "validation-session",
-  outputPath: "./validation-report.html"
-})
-```