@democratize-quality/mcp-server 1.1.2 → 1.1.3

package/README.md

@@ -13,7 +13,7 @@
 **The fastest way to get started** - Install with intelligent testing agents for GitHub Copilot:
 
 ```bash
-npx @democratize-quality/mcp-server --agents
+npx @democratize-quality/mcp-server@latest --agents
 ```
 
 **What this does:**
@@ -929,6 +929,7 @@ MCP_FEATURES_ENABLEDEBUGMODE=true node mcpServer.js
 - 📖 [Getting Started Guide](docs/getting-started.md) - Complete setup walkthrough
 - 🔧 [Tool Reference](docs/api/tool-reference.md) - Detailed tool documentation
 - 🎯 [API Tools Usage Guide](docs/api_tools_usage.md) - Advanced examples and patterns
+- 🔷 [GraphQL Support Guide](GRAPHQL-SUPPORT.md) - GraphQL testing capabilities and features
 - �‍💻 [Developer Guide](docs/development/adding-tools.md) - Extend the server
 - ⚙️ [Configuration Guide](docs/development/configuration.md) - Advanced settings
 - � [Examples](docs/examples/) - Real-world usage examples

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@democratize-quality/mcp-server",
-  "version": "1.1.2",
+  "version": "1.1.3",
   "main": "mcpServer.js",
   "bin": {
     "democratize-quality-mcp": "cli.js",
@@ -75,6 +75,7 @@
     "chrome-launcher": "^1.2.0",
     "chrome-remote-interface": "^0.33.3",
     "express": "^5.1.0",
+    "graphql": "^16.11.0",
     "json-rpc-2.0": "^1.7.1",
     "yaml": "^2.8.1",
     "zod": "^4.0.10"

package/src/chatmodes//360/237/214/220 api-planner.chatmode.md"

@@ -200,7 +200,106 @@ await tools.api_planner({
 
 ---
 
-## 🔄 Quality Check Loop (Playwright-Style)
+## � Working with Schema Files
+
+### ⚠️ CRITICAL: GraphQL SDL Files (.graphql, .gql)
+
+**For GraphQL Schema Definition Language (SDL) files, ALWAYS use `schemaPath` parameter:**
+
+```javascript
+// ✅ CORRECT: Use schemaPath
+await tools.api_planner({
+  schemaPath: "./schema.graphql",  // File path
+  apiBaseUrl: "https://api.github.com/graphql",
+  outputPath: "./test-plan.md"
+})
+
+// ❌ WRONG: Don't try to read and pass file content
+// The tool ONLY accepts schemaPath or schemaUrl parameters
+```
+
+**Why schemaPath is Required for SDL:**
+1. **Reads full file** - No truncation or summarization issues
+2. **Automatic conversion** - Tool converts SDL → introspection JSON automatically
+3. **Creates reusable file** - Saves `schema.json` alongside `schema.graphql` for future use
+4. **No parse errors** - Full file is read without truncation
+
+**What Happens:**
+```
+User provides: schema.graphql (SDL file)
+      ↓
+Tool reads full file via schemaPath
+      ↓
+Detects SDL format automatically
+      ↓
+Converts SDL → Introspection JSON using graphql library
+      ↓
+Saves as schema.json (same directory)
+      ↓
+Uses introspection to generate test plan
+      ↓
+Both files available for future use
+```
+
+**Example with User:**
+```
+User: "Generate test plan from schema.graphql"
+Assistant: "I'll use schemaPath to read your GraphQL SDL file and convert it automatically."
+
+await tools.api_planner({
+  schemaPath: "./schema.graphql",  // ← Use path, not content!
+  apiBaseUrl: "https://api.github.com/graphql",
+  outputPath: "./github-test-plan.md"
+})
+
+// Tool automatically:
+// ✓ Reads full file (no truncation)
+// ✓ Converts SDL to introspection JSON
+// ✓ Saves schema.json
+// ✓ Generates test plan
+```
+
+### 📂 Other Schema File Types
+
+**OpenAPI/Swagger Files (.json, .yaml, .yml):**
+- Use `schemaPath` for local files
+- Use `schemaUrl` for remote URLs
+
+```javascript
+// Local OpenAPI file:
+await tools.api_planner({
+  schemaPath: "./openapi.json"
+})
+```
+```
+
+### 🔍 Detecting Schema Type
+
+**When user mentions file:**
+- `*.graphql` or `*.gql` → **MUST use schemaPath** (SDL conversion)
+- `*.json` → Use schemaPath (JSON)
+- `*.yaml` or `*.yml` → Use schemaPath (YAML)
+- URL ending in `/graphql` → Use schemaUrl (introspection)
+- URL ending in `.json` or `.yaml` → Use schemaUrl (fetch)
+
+### 🎯 Best Practice Guidelines
+
+**DO:**
+- ✅ Use `schemaPath` for all local schema files
+- ✅ Use `schemaPath` for GraphQL SDL files (`.graphql`, `.gql`)
+- ✅ Use `schemaPath` for large files (>1MB)
+- ✅ Use `schemaUrl` for remote APIs with introspection
+- ✅ Let tool auto-convert SDL to introspection JSON
+- ✅ Reuse generated `.json` files in future runs
+
+**DON'T:**
+- ❌ Try to read file content and pass it to the tool
+- ❌ Manually convert SDL before using tool (tool does it automatically)
+- ❌ Delete generated `.json` files (they're reusable)
+
+---
+
+## �🔄 Quality Check Loop (Playwright-Style)
 
 ### 1. Generate Plan
 ```javascript
@@ -265,14 +364,9 @@ User asks about the output?
 
 ### Scenario 1: Local Schema File
 ```javascript
-// Read schema from file first
-const schemaContent = await tools.readFile({
-  path: "./openapi.json"
-})
-
-// Then pass content to api_planner
+// Use schemaPath for local files
 await tools.api_planner({
-  schemaContent: schemaContent,
+  schemaPath: "./openapi.json",
   apiBaseUrl: "https://api.example.com",
   validateEndpoints: true
 })
@@ -350,8 +444,9 @@ for (const service of services) {
 
 ## 🎯 Parameter Reference
 
-### Required Parameters:
-- `schemaUrl` OR `schemaContent` - OpenAPI/Swagger schema source
+### Required Parameters (One of):
+- `schemaUrl` - URL to fetch schema (e.g., "https://api.example.com/swagger.json")
+- `schemaPath` - Local file path (e.g., "./schema.graphql", "./openapi.json")
 
 ### Optional Parameters (Common):
 - `apiBaseUrl` - **FULL URL** to override base URL from schema (e.g., `"https://api-staging.example.com/v2"` for staging environment)
@@ -403,8 +498,8 @@ for (const service of services) {
 **Symptoms:** "Failed to parse schema" error
 **Solution:**
 1. Verify schema URL is accessible
-2. Check schema format (OpenAPI 3.0/Swagger 2.0)
-3. Try using `schemaContent` with file contents directly
+2. Check schema format (OpenAPI 3.0/Swagger 2.0/GraphQL SDL)
+3. Try using `schemaPath` for local files instead of schemaUrl
 
 ---
 
@@ -842,12 +937,12 @@ await tools.api_planner({
 
 <example>
 Context: Developer wants to create a test plan from API schema content.
-user: 'Generate a test plan from this OpenAPI schema: [schema content]'
+user: 'Generate a test plan from this OpenAPI schema file: openapi.json'
 assistant: 'I'll generate a comprehensive test plan from your OpenAPI schema using the api_planner tool.'
 
-// IMMEDIATE RESPONSE - Generate from schema content:
+// IMMEDIATE RESPONSE - Generate from schema file:
 await tools.api_planner({
-  schemaContent: `[schema content]`,
+  schemaPath: "./openapi.json",
   schemaType: "auto",
   includeAuth: true,
   includeSecurity: true,
@@ -856,4 +951,4 @@ await tools.api_planner({
 })
 </example>
 
-**Key Principle: Use api_planner tool first, always. Only use manual API exploration if schema analysis needs assistance.**
+**Key Principle: Use api_planner tool first, always. Use schemaPath for local files, schemaUrl for remote schemas.**

package/src/tools/api/api-generator.js

@@ -252,7 +252,8 @@ class ApiGeneratorTool extends ToolBase {
             title: '',
             description: '',
             baseUrl: '',
-            sections: []
+            sections: [],
+            isGraphQL: false  // NEW: Track if this is a GraphQL test plan
         };
 
         const lines = content.split('\n');
@@ -371,6 +372,11 @@ class ApiGeneratorTool extends ToolBase {
                 }
             }
         }
+        
+        // NEW: Detect if test plan is GraphQL-based
+        testPlan.isGraphQL = testPlan.sections.some(section => 
+            section.scenarios.some(scenario => scenario.isGraphQL)
+        );
 
         return testPlan;
     }
@@ -379,6 +385,18 @@ class ApiGeneratorTool extends ToolBase {
         try {
             const data = JSON.parse(content);
             
+            // NEW: Detect GraphQL structure
+            if (data.query || data.mutation || data.subscription) {
+                scenario.isGraphQL = true;
+                scenario.graphql = {
+                    query: data.query || data.mutation || data.subscription,
+                    variables: data.variables || {}
+                };
+                // Also store in data for backward compatibility
+                scenario.data = data;
+                return;
+            }
+            
             if (context === 'request') {
                 // This is request body data
                 scenario.data = data;
@@ -439,7 +457,9 @@ class ApiGeneratorTool extends ToolBase {
                     expectedStatus: scenario.expectedStatus,
                     requestBody: scenario.requestBody,
                     expectedBody: scenario.expectedBody,
-                    steps: scenario.steps
+                    steps: scenario.steps,
+                    isGraphQL: scenario.isGraphQL,  // NEW: GraphQL flag
+                    graphql: scenario.graphql        // NEW: GraphQL query/variables
                 })),
                 language: options.language,
                 isTypeScript: isTS,
@@ -516,7 +536,9 @@ class ApiGeneratorTool extends ToolBase {
                     expectedStatus: scenario.expectedStatus,
                     requestBody: scenario.requestBody,
                     expectedBody: scenario.expectedBody,
-                    steps: scenario.steps
+                    steps: scenario.steps,
+                    isGraphQL: scenario.isGraphQL,  // NEW: GraphQL flag
+                    graphql: scenario.graphql        // NEW: GraphQL query/variables
                 })),
                 language: options.language,
                 isTypeScript: isTS,
@@ -699,8 +721,34 @@ ${this._generatePlaywrightScenarioTest(scenario, options, testPlan.baseUrl)}
                 }
                 testCode += '\n';
             });
+        } else if (scenario.isGraphQL) {
+            // NEW: Handle GraphQL requests
+            const endpoint = scenario.endpoint || '/graphql';
+            const fullUrl = endpoint.startsWith('http') ? endpoint : `\${baseUrl}${endpoint}`;
+            
+            testCode += `      // GraphQL Request\n`;
+            testCode += `      const response = await request.post('${fullUrl}', {\n`;
+            testCode += `        headers: ${JSON.stringify(scenario.headers, null, 8)},\n`;
+            testCode += `        data: {\n`;
+            testCode += `          query: \`${scenario.graphql.query.replace(/`/g, '\\`')}\`,\n`;
+            if (scenario.graphql.variables && Object.keys(scenario.graphql.variables).length > 0) {
+                testCode += `          variables: ${JSON.stringify(scenario.graphql.variables, null, 10)}\n`;
+            }
+            testCode += `        }\n`;
+            testCode += `      });\n\n`;
+            
+            // Add validations for GraphQL
+            if (scenario.expect.status) {
+                testCode += `      expect(response.status()).toBe(${scenario.expect.status});\n`;
+            }
+            
+            if (scenario.expect.body) {
+                testCode += `      \n`;
+                testCode += `      const responseData = await response.json();\n`;
+                testCode += `      ${this._generateGraphQLPlaywrightValidation('responseData', scenario.expect.body)}\n`;
+            }
         } else {
-            // Single request
+            // Single REST request
             let endpoint = scenario.endpoint;
             
             // Replace path parameters if any
@@ -776,6 +824,52 @@ ${this._generatePlaywrightScenarioTest(scenario, options, testPlan.baseUrl)}
         return validation.trimEnd(); // Remove trailing newline
     }
 
+    _generateGraphQLPlaywrightValidation(dataVar, expectedBody) {
+        let validation = '';
+        
+        // GraphQL responses have either data or errors
+        validation += `      // GraphQL response structure validation\n`;
+        validation += `      expect(${dataVar}).toBeDefined();\n`;
+        
+        // Check if we're expecting success (data) or error (errors)
+        if (expectedBody && typeof expectedBody === 'object') {
+            if (expectedBody.data !== undefined) {
+                validation += `      expect(${dataVar}).toHaveProperty('data');\n`;
+                validation += `      expect(${dataVar}.errors).toBeUndefined();\n`;
+                
+                // Validate data structure
+                if (typeof expectedBody.data === 'object' && expectedBody.data !== null) {
+                    Object.entries(expectedBody.data).forEach(([key, value]) => {
+                        validation += `      expect(${dataVar}.data).toHaveProperty('${key}');\n`;
+                        
+                        // Type checks for nested values
+                        if (value === 'string') {
+                            validation += `      expect(typeof ${dataVar}.data.${key}).toBe('string');\n`;
+                        } else if (value === 'number') {
+                            validation += `      expect(typeof ${dataVar}.data.${key}).toBe('number');\n`;
+                        } else if (value === 'boolean') {
+                            validation += `      expect(typeof ${dataVar}.data.${key}).toBe('boolean');\n`;
+                        } else if (Array.isArray(value)) {
+                            validation += `      expect(Array.isArray(${dataVar}.data.${key})).toBe(true);\n`;
+                        } else if (typeof value === 'object' && value !== null) {
+                            validation += `      expect(typeof ${dataVar}.data.${key}).toBe('object');\n`;
+                        }
+                    });
+                }
+            } else if (expectedBody.errors !== undefined) {
+                validation += `      expect(${dataVar}).toHaveProperty('errors');\n`;
+                validation += `      expect(Array.isArray(${dataVar}.errors)).toBe(true);\n`;
+                validation += `      expect(${dataVar}.errors.length).toBeGreaterThan(0);\n`;
+            }
+        } else {
+            // Generic validation when no specific expectation
+            validation += `      // Verify GraphQL response has either data or errors\n`;
+            validation += `      expect(${dataVar}.data !== undefined || ${dataVar}.errors !== undefined).toBe(true);\n`;
+        }
+        
+        return validation.trimEnd();
+    }
+
     _generatePlaywrightHelpers(testPlan, options) {
         const isTS = options.language === 'typescript';
         
@@ -1274,8 +1368,33 @@ describe('${testPlan.title} API Tests', () => {
                 }
                 testCode += '\n';
             });
+        } else if (scenario.isGraphQL) {
+            // NEW: Handle GraphQL requests
+            const endpoint = scenario.endpoint || '/graphql';
+            
+            testCode += `      // GraphQL Request\n`;
+            testCode += `      const response = await apiUtils.makeRequest({\n`;
+            testCode += `        method: 'POST',\n`;
+            testCode += `        url: '${endpoint}',\n`;
+            testCode += `        headers: ${JSON.stringify(scenario.headers, null, 8)},\n`;
+            testCode += `        data: {\n`;
+            testCode += `          query: \`${scenario.graphql.query.replace(/`/g, '\\`')}\`,\n`;
+            if (scenario.graphql.variables && Object.keys(scenario.graphql.variables).length > 0) {
+                testCode += `          variables: ${JSON.stringify(scenario.graphql.variables, null, 10)}\n`;
+            }
+            testCode += `        }\n`;
+            testCode += `      });\n\n`;
+
+            // Add validations for GraphQL
+            if (scenario.expect.status) {
+                testCode += `      expect(response.status).toBe(${scenario.expect.status});\n`;
+            }
+            
+            if (scenario.expect.body) {
+                testCode += `      ${this._generateGraphQLJestValidation('response.data', scenario.expect.body)}\n`;
+            }
         } else {
-            // Single request
+            // Single REST request
             testCode += `      const response = await apiUtils.makeRequest({\n`;
             testCode += `        method: '${scenario.method}',\n`;
             testCode += `        url: '${scenario.endpoint}',\n`;
@@ -1323,6 +1442,52 @@ describe('${testPlan.title} API Tests', () => {
         return validation;
     }
 
+    _generateGraphQLJestValidation(dataVar, expectedBody) {
+        let validation = '';
+        
+        // GraphQL responses have either data or errors
+        validation += `      // GraphQL response structure validation\n`;
+        validation += `      expect(${dataVar}).toBeDefined();\n`;
+        
+        // Check if we're expecting success (data) or error (errors)
+        if (expectedBody && typeof expectedBody === 'object') {
+            if (expectedBody.data !== undefined) {
+                validation += `      expect(${dataVar}).toHaveProperty('data');\n`;
+                validation += `      expect(${dataVar}.errors).toBeUndefined();\n`;
+                
+                // Validate data structure
+                if (typeof expectedBody.data === 'object' && expectedBody.data !== null) {
+                    Object.entries(expectedBody.data).forEach(([key, value]) => {
+                        validation += `      expect(${dataVar}.data).toHaveProperty('${key}');\n`;
+                        
+                        // Type checks for nested values
+                        if (value === 'string') {
+                            validation += `      expect(typeof ${dataVar}.data.${key}).toBe('string');\n`;
+                        } else if (value === 'number') {
+                            validation += `      expect(typeof ${dataVar}.data.${key}).toBe('number');\n`;
+                        } else if (value === 'boolean') {
+                            validation += `      expect(typeof ${dataVar}.data.${key}).toBe('boolean');\n`;
+                        } else if (Array.isArray(value)) {
+                            validation += `      expect(Array.isArray(${dataVar}.data.${key})).toBe(true);\n`;
+                        } else if (typeof value === 'object' && value !== null) {
+                            validation += `      expect(typeof ${dataVar}.data.${key}).toBe('object');\n`;
+                        }
+                    });
+                }
+            } else if (expectedBody.errors !== undefined) {
+                validation += `      expect(${dataVar}).toHaveProperty('errors');\n`;
+                validation += `      expect(Array.isArray(${dataVar}.errors)).toBe(true);\n`;
+                validation += `      expect(${dataVar}.errors.length).toBeGreaterThan(0);\n`;
+            }
+        } else {
+            // Generic validation when no specific expectation
+            validation += `      // Verify GraphQL response has either data or errors\n`;
+            validation += `      expect(${dataVar}.data !== undefined || ${dataVar}.errors !== undefined).toBe(true);\n`;
+        }
+        
+        return validation;
+    }
+
     _generateJestUtils(testPlan, options) {
         const isTS = options.language === 'typescript';