@democratize-quality/mcp-server 1.1.0 → 1.1.2

package/README.md

@@ -1,640 +1,1111 @@
 # 🎯 Democratize Quality MCP Server
 
-A comprehensive **Model Context Protocol (MCP)** server that democratizes quality through comprehensive API testing capabilities.
+**Intelligent API Testing Made Simple** - A comprehensive Model Context Protocol (MCP) server that brings professional-grade API testing capabilities to everyone, from QA engineers to developers.
 
-## 🤖 API Testing Agents for GitHub Copilot
+> Transform your API testing workflow with AI-powered agents that plan, generate, and heal your tests automatically.
 
-Introducing **intelligent API testing agents** that work seamlessly with GitHub Copilot Chat to automate your API testing workflow - from planning to generation to healing.
+---
+
+## 📦 Quick Installation
+
+### Option 1: Agent Mode Installation (Recommended)
 
-### 🚀 One-Click Installation
+**The fastest way to get started** - Install with intelligent testing agents for GitHub Copilot:
 
-Get started instantly with our VS Code integration:
+```bash
+npx @democratize-quality/mcp-server --agents
+```
+
+**What this does:**
+- ✅ Installs the MCP server
+- ✅ Sets up 3 AI-powered testing agents
+- ✅ Configures VS Code integration automatically
+- ✅ Creates project folders (`.github/chatmodes/`, `.vscode/`)
+
+**One-Click Alternative:**
 
 [<img src="https://img.shields.io/badge/VS_Code-VS_Code?style=flat-square&label=Install%20Server&color=0098FF" alt="Install in VS Code">](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522democratize-quality%2522%252C%2522type%2522%253A%2522stdio%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522%2540democratize-quality%252Fmcp-server%2522%255D%252C%2522cwd%2522%253A%2522%2524%257BworkspaceFolder%257D%2522%252C%2522env%2522%253A%257B%2522NODE_ENV%2522%253A%2522production%2522%252C%2522OUTPUT_DIR%2522%253A%2522.%252Fapi-test-reports%2522%257D%257D) [<img alt="Install in VS Code Insiders" src="https://img.shields.io/badge/VS_Code_Insiders-VS_Code_Insiders?style=flat-square&label=Install%20Server&color=24bfa5">](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522democratize-quality%2522%252C%2522type%2522%253A%2522stdio%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522%2540democratize-quality%252Fmcp-server%2522%255D%252C%2522cwd%2522%253A%2522%2524%257BworkspaceFolder%257D%2522%252C%2522env%2522%253A%257B%2522NODE_ENV%2522%253A%2522production%2522%252C%2522OUTPUT_DIR%2522%253A%2522.%252Fapi-test-reports%2522%257D%257D)
 
+**Prerequisites:**
+- Node.js 14+ installed
+- VS Code with GitHub Copilot extension (for agents)
+- Active internet connection
 
-> **Choose your installation:** Install the core server for direct tool access. Agent button installs chatmode files for GitHub Copilot Chat integration.
+### Option 2: Manual Installation
 
-Run following command in your project:
+**For Claude Desktop or other MCP clients:**
 
+Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+
+```json
+{
+  "mcpServers": {
+    "democratize-quality": {
+      "command": "npx",
+      "args": ["@democratize-quality/mcp-server"],
+      "env": {
+        "NODE_ENV": "production",
+        "OUTPUT_DIR": "./api-test-reports"
+      }
+    }
+  }
+}
+```
+
+**Global installation option:**
 ```bash
-# Install MCP Server + Agents (Recommended)
-npx @democratize-quality/mcp-server --agents
+npm install -g @democratize-quality/mcp-server
+
+# Then use anywhere
+democratize-quality-mcp --help
 ```
 
-### 🎭 Meet Your API Testing Agents
+---
 
-Once installed, these agents become available in GitHub Copilot Chat:
+## 🛠️ Available Tools
 
-| Agent | Purpose | Example Usage |
-|-------|---------|---------------|
-| **🌐 @api-planner** | Analyze API schemas and create comprehensive test plans | `@🌐 api-planner analyze the OpenAPI spec at https://api.example.com/swagger.json` |
-| **🌐 @api-generator** | Generate executable tests from test plans | `@🌐 api-generator create Jest tests from ./api-test-plan.md` |
-| **🌐 @api-healer** | Debug and automatically fix failing API tests | `@🌐 api-healer fix the failing tests in ./tests/api.test.js` |
+This MCP server provides **7 powerful tools** for comprehensive API testing:
 
-### 🔄 Complete API Testing Workflow
+### 🤖 AI-Powered Testing Tools
 
-**1. Plan** → **2. Generate** → **3. Heal** → **Repeat**
+| Tool | Purpose | When to Use |
+|------|---------|-------------|
+| **`api_planner`** | Analyzes API schemas (OpenAPI/Swagger, GraphQL) and creates comprehensive test plans with realistic sample data | Starting a new API testing project, documenting API behavior, validating API endpoints |
+| **`api_generator`** | Generates executable tests (Jest, Playwright, Postman) from test plans using AI-powered code generation | Converting test plans to runnable code in TypeScript or JavaScript |
+| **`api_healer`** | Debugs and automatically fixes failing tests by analyzing errors and applying healing strategies | Tests break after API changes, schema updates, or authentication issues |
+| **`api_project_setup`** | Detects project configuration (framework and language) for smart test generation | Before using `api_generator` - auto-detects Playwright/Jest and TypeScript/JavaScript |
 
-```bash
-# 1. Analyze your API and create a comprehensive test plan
-@🌐 api-planner analyze our REST API using the OpenAPI spec at /docs/api-spec.yaml
+### 🔧 Core API Testing Tools
 
-# 2. Generate executable tests from the plan
-@🌐 api-generator create Playwright tests from the generated test plan
+| Tool | Purpose | When to Use |
+|------|---------|-------------|
+| **`api_request`** | Executes HTTP requests with validation and request chaining | Making individual API calls, testing specific endpoints, chaining multiple requests |
+| **`api_session_status`** | Queries test session status and logs | Checking progress of test sequences, viewing request history |
+| **`api_session_report`** | Generates comprehensive HTML test reports | Creating shareable test documentation with detailed analytics |
 
-# 3. If tests fail, automatically heal them
-@🌐 api-healer fix any failing tests and update assertions to match current API behavior
-```
+**Key Capabilities:**
+- ✅ **Smart Validation**: Automatic "expected vs actual" comparison with detailed failure messages
+- 🔗 **Request Chaining**: Extract data from one response and use in subsequent requests
+- 📊 **Session Tracking**: Monitor multi-step API workflows across multiple requests
+- 📈 **Visual Reports**: Interactive HTML reports with timing analysis and validation results
+- 🎯 **All HTTP Methods**: GET, POST, PUT, DELETE, PATCH, OPTIONS, HEAD
+- 🔒 **Authentication**: Support for Bearer tokens, API keys, custom headers
+- 🎨 **Realistic Sample Data**: Auto-generates context-aware test data (names, emails, dates, etc.)
+- 🔍 **Optional Validation**: Validate endpoints by making actual API calls with response time metrics
 
-### ✨ Key Agent Capabilities
 
-- **🔍 Schema Analysis**: Automatically parse OpenAPI/Swagger specs and GraphQL schemas
-- **📋 Intelligent Planning**: Generate comprehensive test scenarios covering functional, security, and edge cases
-- **⚡ Multi-Format Generation**: Create Jest, Playwright, and Postman tests from the same plan
-- **🛠️ Automatic Healing**: Detect and fix common test failures like changed endpoints, updated schemas, and authentication issues
-- **🔗 Workflow Integration**: Seamlessly work together to maintain your API test suite
+## 🌐 Chat Modes (AI Agents)
 
-### 🎬 See It In Action
+When you install with `--agents`, you get 3 intelligent testing assistants:
 
-> *Coming soon: Video demonstration of the complete API testing workflow*
+### 1. 🌐 @api-planner - The Strategist
 
----
+**What it does:** Analyzes your API and creates comprehensive test strategies
 
-## 📋 Overview
+**Best for:**
+- Starting new testing projects
+- Documenting API behavior
+- Creating test scenarios for complex workflows
+- Security and edge case planning
 
-This MCP server offers **6 powerful API testing tools** for comprehensive API quality assurance:
+**Example: Analyze a Real API**
+```
+1. Select the "🌐 api-planner" chatmode from GitHub Copilot Chat window and enter following prompt:
 
-### 🤖 AI-Powered API Testing Tools
-- **`api_planner`**: Analyze API schemas and generate comprehensive test plans
-- **`api_generator`**: Generate executable tests (Jest, Playwright, Postman) from test plans
-- **`api_healer`**: Debug and automatically fix failing API tests
+2. Analyze this API and create a comprehensive test plan: 
+https://fakerestapi.azurewebsites.net/swagger/v1/swagger.json
 
-### 🔗 Core API Testing Tools
-- **`api_request`**: HTTP requests with validation and session management
-- **`api_session_status`**: Query API test session status and logs  
-- **`api_session_report`**: Generate comprehensive HTML test reports
+3. Agent: I'll call the API planner once to analyze the OpenAPI schema at the provided URL and generate a comprehensive test plan with realistic sample data plus live validation of 5 endpoints; expected outcome: a saved test plan in ./api-test-reports/fakerest-test-plan.md and a validation summary. I'll run the planner now. 
 
-**Key Features:**
-- 🤖 **AI-Powered Agents**: Intelligent test planning, generation, and healing
-- ✅ **Enhanced Validation**: Shows "expected vs actual" values in validation failures
-- 🔗 **Request Chaining**: Use response data in subsequent requests
-- 📊 **Session Management**: Track API test sequences across multiple requests
-- 📈 **HTML Reports**: Beautiful, interactive test reports with detailed validation results
-- 🎯 **Comprehensive Testing**: Support for all HTTP methods with advanced validation options
+4. When prompted to allow the tool call " Run api_plannerdemocratize-quality (MCP Server)". 
 
-## ⚡️ Installation & Setup
+```
 
-### Prerequisites
-- Node.js 14+ 
-- VS Code with GitHub Copilot extension (for agents)
-- MCP-compatible client (Claude Desktop, VS Code, etc.)
+**What you get:**
+- Comprehensive markdown test plan with 40+ test scenarios
+- Realistic sample requests for each endpoint
+- Expected response structures
+- Error scenarios and edge cases
+- Ready for test generation
 
-### 🎭 Agent Installation (Recommended)
+### 2. 🌐 @api-generator - The Builder
 
-**For GitHub Copilot Users:**
+**What it does:** Converts test plans into executable code
 
-The fastest way to get started with API testing agents:
+**Best for:**
+- Generating Jest test suites
+- Creating Playwright automation scripts
+- Building Postman collections
 
-```bash
-# Install agents in your VS Code project
-npx @democratize-quality/mcp-server --agents
+**Example: Generate Tests from Plan**
 ```
+1. Once you have the test plan generated as part of API Planner mode, now change the chatmode to : "🌐 api-generator", open the test plan MD file created in previous step (so that it can be in context) and enter following prompt
+Create Playwright tests in TypeScript for the Books API section
 
-This will:
-- 📁 Copy chatmode files to `.github/chatmodes/`
-- ⚙️ Set up MCP configuration in `.vscode/mcp.json`
-- 🎯 Enable `@🌐 api-planner`, `@🌐 api-generator`, and `@🌐 api-healer` agents
+2. Agent: I'm going to detect the project's test framework/language (required first step) so I can generate Playwright TypeScript tests in the correct layout; expected outcome: detection result with suggested framework/language. Then ask you to allow the another tool "Run api_project_setupdemocratize-quality (MCP Server)" for capturing the project info e.g. if you have an empty project then it will ask to select the framework/language otherwise if your project is playwright typescript it will create playwright test(s) accordingly.
 
-**Alternative one-click installation:**
+3. After you answer, it invoke tool "Run api_generatordemocratize-quality (MCP Server)" which will actually generate your tests, click "Allow"
 
-[<img src="https://img.shields.io/badge/VS_Code-VS_Code?style=flat-square&label=Install%20Server&color=0098FF" alt="Install in VS Code">](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522democratize-quality%2522%252C%2522type%2522%253A%2522stdio%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522%2540democratize-quality%252Fmcp-server%2522%255D%252C%2522cwd%2522%253A%2522%2524%257BworkspaceFolder%257D%2522%252C%2522env%2522%253A%257B%2522NODE_ENV%2522%253A%2522production%2522%252C%2522OUTPUT_DIR%2522%253A%2522.%252Fapi-test-reports%2522%257D%257D) [<img alt="Install in VS Code Insiders" src="https://img.shields.io/badge/VS_Code_Insiders-VS_Code_Insiders?style=flat-square&label=Install%20Server&color=24bfa5">](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522democratize-quality%2522%252C%2522type%2522%253A%2522stdio%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522%2540democratize-quality%252Fmcp-server%2522%255D%252C%2522cwd%2522%253A%2522%2524%257BworkspaceFolder%257D%2522%252C%2522env%2522%253A%257B%2522NODE_ENV%2522%253A%2522production%2522%252C%2522OUTPUT_DIR%2522%253A%2522.%252Fapi-test-reports%2522%257D%257D)
+Created files:
+✅ With Books CRUD operations
+✅ Show on screen instructions for running the tests
 
-**For GitHub Copilot Agents:** [![Install Agents](https://img.shields.io/badge/Install_Agents-GitHub_Copilot-purple?style=flat-square&logo=github)](vscode:extension/GitHub.copilot-chat?command=workbench.action.quickOpen&text=%40terminal%20npx%20%40democratize-quality%2Fmcp-server%20--agents)
+Tests include:
+- ✅ GET /api/v1/Books - List all books
+- ✅ GET /api/v1/Books/{id} - Get book by ID
+- ✅ POST /api/v1/Books - Create new book
+- ✅ PUT /api/v1/Books/{id} - Update book
+- ✅ DELETE /api/v1/Books/{id} - Delete book
+- ✅ Error handling for invalid IDs
+- ✅ Validation for required fields
 
-### 🛠️ Manual Installation Options
+```
 
-**Option 1: Use with npx (Recommended)**
-```bash
-# Run directly without installation
-npx @democratize-quality/mcp-server --help
+**Example: Generate Postman Collection**
+```
+You: @🌐 api-generator create a Postman collection from the entire test plan
+
+Agent: Creating Postman collection for Fake REST API...
+
+Generated:
+✅ postman/FakeRestAPI.postman_collection.json
+✅ postman/environment.json (with base URL variables)
 
-# Use in Claude Desktop (see integration section below)
+Sample Collection includes:
+- 📁 Books (5 requests)
+- 📁 Users (4 requests)
+- 📁 Authors (4 requests)
+- 📁 Activities (3 requests)
+- 📁 CoverPhotos (4 requests)
+
+Import into Postman and start testing!
 ```
 
-**Option 2: Global Installation**
-```bash
-# Install globally 
-npm install -g @democratize-quality/mcp-server
+### 3. 🌐 @api-healer - The Fixer
 
-# Then run anywhere
-democratize-quality-mcp --help
-dq-mcp-server --help
+**What it does:** Automatically diagnoses and repairs failing tests
+
+**Best for:**
+- Fixing broken tests after API changes
+- Updating endpoint URLs
+- Resolving authentication issues
+- Schema mismatch corrections
+
+**Example: Fix Failing Tests**
 ```
+You: @🌐 api-healer the Books tests are failing with 404 errors. 
+Please analyze and fix them.
 
-**Option 3: Local Development**
-```bash
-# Clone and install dependencies
-git clone https://github.com/uppadhyayraj/democratize-quality-mcp-server.git
-cd mcp-server
-npm install
+Agent: Analyzing test failures in tests/books.spec.ts...
 
-# Test the server
-npm test
+Issues found:
+❌ Endpoint changed: /api/Books → /api/v1/Books
+❌ Response schema updated: added "pageCount" field
+❌ ID format changed: number → string
 
-# Start the server (API-only mode by default)
-npm start
+Applying fixes:
+✅ Updated all endpoint URLs to include /v1/ prefix
+✅ Updated response assertions to include pageCount
+✅ Fixed ID type in test data (42 → "42")
+✅ Backed up original file to tests/books.spec.ts.backup
+
+Re-running tests... ✅ All 15 tests now passing!
 ```
 
-## 🔌 Integration Methods
+**Example: Fix Schema Mismatches**
+```
+You: @🌐 api-healer fix assertion errors in tests/users.spec.ts
 
-### Claude Desktop Integration (Recommended)
+Agent: Analyzing assertion failures...
 
-Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+Found 3 schema mismatches:
+❌ Expected userName, API returns username (camelCase issue)
+❌ Password field removed from response (security update)
+❌ New field added: profileImageUrl
 
-```json
-{
-  "mcpServers": {
-    "democratize-quality": {
-      "command": "npx",
-      "args": ["@democratize-quality/mcp-server"],
-      "env": {
-        "NODE_ENV": "production"
-      }
-    }
-  }
-}
+Healing actions:
+✅ Updated assertions: userName → username
+✅ Removed password field validation
+✅ Added profileImageUrl to expected response
+✅ Updated TypeScript interfaces
+
+Tests healed successfully! ✅ 12/12 passing
 ```
 
-> **Note:** The server runs in `api-only` mode by default, providing secure and lightweight API testing capabilities.
+---
+
+## 💡 Usage Examples - E2E Testing Scenarios
 
-### Alternative Integration Methods
+### Scenario 1: Testing the Fake REST API (Complete Workflow)
 
-**Global Installation:**
-```bash
-npm install -g @democratize-quality/mcp-server
+**Real-world example using: https://fakerestapi.azurewebsites.net**
+
+**Step 1: Plan your tests**
+```
+@🌐 api-planner analyze the OpenAPI spec at 
+https://fakerestapi.azurewebsites.net/swagger/v1/swagger.json 
+and create a comprehensive test plan focusing on Books and Authors endpoints
 ```
 
-Then configure Claude Desktop:
-```json
-{
-  "mcpServers": {
-    "democratize-quality": {
-      "command": "democratize-quality-mcp"
-    }
+**What happens:**
+- ✅ Agent analyzes the Fake REST API schema
+- ✅ Identifies 5 resource types (Books, Authors, Users, Activities, CoverPhotos)
+- ✅ Creates 40+ test scenarios covering:
+  - Happy paths (GET all books, GET book by ID, CREATE book)
+  - Error cases (404 for invalid IDs, 400 for bad data)
+  - Edge cases (empty lists, ID boundaries)
+  - Data validation (response schema checks)
+- ✅ Generates realistic sample data:
+  ```json
+  {
+    "id": 1,
+    "title": "The Great Gatsby",
+    "description": "A classic American novel",
+    "pageCount": 180,
+    "excerpt": "In my younger and more vulnerable years...",
+    "publishDate": "1925-04-10T00:00:00Z"
   }
-}
-```
+  ```
 
-**MCP Inspector (Development/Testing):**
-```bash
-npx @modelcontextprotocol/inspector npx @democratize-quality/mcp-server
+**Step 2: Generate executable tests**
+```
+@🌐 api-generator create Playwright tests in TypeScript from the test plan, 
+focusing on the Books API section
 ```
 
-**Direct Usage:**
-```bash
-# Run the server directly
-npx @democratize-quality/mcp-server
+**What you get:**
+- `tests/books.spec.ts` - Complete Books CRUD test suite
+  ```typescript
+  import { test, expect } from '@playwright/test';
+  
+  test.describe('Books API', () => {
+    test('GET /api/v1/Books - should return all books', async ({ request }) => {
+      const response = await request.get('https://fakerestapi.azurewebsites.net/api/v1/Books');
+      expect(response.ok()).toBeTruthy();
+      expect(response.status()).toBe(200);
+      const books = await response.json();
+      expect(Array.isArray(books)).toBeTruthy();
+    });
+    
+    test('POST /api/v1/Books - should create a new book', async ({ request }) => {
+      const newBook = {
+        id: 201,
+        title: "Test Book",
+        pageCount: 350
+      };
+      const response = await request.post('https://fakerestapi.azurewebsites.net/api/v1/Books', {
+        data: newBook
+      });
+      expect(response.status()).toBe(200);
+    });
+  });
+  ```
+
+**Step 3: Run and heal tests**
+```
+# Run tests
+npx playwright test tests/books.spec.ts
 
-# Or if installed globally
-democratize-quality-mcp
+# If any tests fail due to API changes:
+@🌐 api-healer fix the failing tests in tests/books.spec.ts
 ```
 
-## 📚 Usage Examples
+**What healer fixes:**
+- ✅ Endpoint URL updates (if API version changes)
+- ✅ Response schema corrections (new/removed fields)
+- ✅ Data type adjustments (string vs number IDs)
+- ✅ Status code updates
 
-### 🤖 Agent-Powered API Testing Workflow
+### Scenario 2: Quick API Documentation with Postman
 
-**Complete end-to-end API testing with intelligent agents:**
+**What healer fixes:**
+- ✅ Endpoint URL updates (if API version changes)
+- ✅ Response schema corrections (new/removed fields)
+- ✅ Data type adjustments (string vs number IDs)
+- ✅ Status code updates
 
-```bash
-# 1. 🔍 Analyze API and create comprehensive test plan
-@🌐 api-planner analyze our user management API using the OpenAPI spec at https://api.example.com/swagger.json
+### Scenario 2: Quick API Documentation with Postman
 
-# 2. ⚡ Generate executable tests in multiple formats
-@🌐 api-generator create Jest and Playwright tests from the generated test plan
+**Goal:** Generate a ready-to-use Postman collection for the Fake REST API
 
-# 3. 🛠️ Automatically heal any failing tests
-@🌐 api-healer fix the failing authentication tests in ./tests/user-api.test.js
 ```
+Step 1:
+@🌐 api-planner create test plan from 
+https://fakerestapi.azurewebsites.net/swagger/v1/swagger.json
+with validation enabled to test actual endpoints
 
-**Individual agent usage:**
+Step 2:
+@🌐 api-generator create Postman collection from the test plan 
+with all endpoints and example requests
 
-```bash
-# API Planning Agent
-@🌐 api-planner create a test plan for our REST API with authentication, CRUD operations, and error handling scenarios
+Step 3: 
+Import the generated collection into Postman and start testing!
+```
 
-# Test Generation Agent  
-@🌐 api-generator generate Postman collection from ./docs/api-test-plan.md with authentication setup
+**What you get:**
+- 📦 `postman/FakeRestAPI.postman_collection.json` - Complete collection
+- 🌍 `postman/environment.json` - Environment variables
+- ✅ 20+ pre-configured requests across all resource types
+- 📝 Example request bodies with realistic data
+- ✔️ Response validation tests included
 
-# Test Healing Agent
-@🌐 api-healer analyze and fix all failing tests in ./tests/ directory with detailed healing report
-```
+**Result:** Professional Postman collection ready to share with your team
 
-### 🎯 Real-World Agent Scenarios
+---
 
-**Scenario 1: New API Testing**
-```bash
-# Start with schema analysis
-@🌐 api-planner analyze the GraphQL schema at /graphql/schema and create comprehensive test scenarios
+## 🔧 Calling Individual Tools
+
+### When to Use Individual Tools
+
+**Use agents (@api-planner, @api-generator, @api-healer) when:**
+- You want AI assistance and recommendations
+- You're working on complex, multi-step workflows
+- You need explanations and best practices
+
+**Use individual tools when:**
+- You need precise control over parameters
+- You're automating tests in CI/CD
+- You're integrating with other tools
+- You want to script repetitive tasks
 
-# Generate tests for multiple environments
-@🌐 api-generator create Jest tests with environment-specific configurations for dev, staging, and prod
+### Tool 1: `api_planner`
 
-# Heal tests after API changes
-@🌐 api-healer update tests to handle the new authentication flow and endpoint changes
+```
+@🌐 api-generator create Jest tests with environment-specific configurations
+for dev (api-dev.example.com), staging (api-staging.example.com), 
+and prod (api.example.com) environments
 ```
 
-**Scenario 2: Legacy API Modernization**
-```bash
-# Document existing API behavior
-@🌐 api-planner explore and document our legacy API endpoints by testing various HTTP methods
+**What you get:**
+```javascript
+// tests/config/environments.js
+module.exports = {
+  dev: { baseURL: 'https://api-dev.example.com', timeout: 5000 },
+  staging: { baseURL: 'https://api-staging.example.com', timeout: 3000 },
+  prod: { baseURL: 'https://api.example.com', timeout: 2000 }
+};
+
+// Run with: NODE_ENV=staging npm test
+```
+
+---
+
+## � Calling Individual Tools
+
+### When to Use Individual Tools
+
+**Use agents (@api-planner, @api-generator, @api-healer) when:**
+- You want AI assistance and recommendations
+- You're working on complex, multi-step workflows
+- You need explanations and best practices
+
+**Use individual tools when:**
+- You need precise control over parameters
+- You're automating tests in CI/CD
+- You're integrating with other tools
+- You want to script repetitive tasks
 
-# Create modern test suite
-@🌐 api-generator create comprehensive Playwright tests with modern async/await patterns
+### Tool 1: `api_planner`
 
-# Fix compatibility issues
-@🌐 api-healer resolve test failures caused by API versioning and deprecated endpoints
+**Purpose:** Analyze API schemas and generate comprehensive test plans with realistic sample data
+
+**Basic usage:**
+```javascript
+// In Claude Desktop or MCP client
+{
+  "tool": "api_planner",
+  "parameters": {
+    "schemaUrl": "https://api.example.com/swagger.json",
+    "schemaType": "openapi",
+    "outputPath": "./test-plan.md"
+  }
+}
 ```
 
-### 🔧 Manual API Testing (Core Tools)
+**With endpoint validation:**
+```javascript
+{
+  "tool": "api_planner",
+  "parameters": {
+    "schemaUrl": "https://petstore3.swagger.io/api/v3/openapi.json",
+    "schemaType": "openapi",
+    "outputPath": "./api-test-plan.md",
+    "includeAuth": true,
+    "includeSecurity": true,
+    "includeErrorHandling": true,
+    "testCategories": ["functional", "security", "edge-cases"],
+    "validateEndpoints": true,
+    "validationSampleSize": 3,
+    "validationTimeout": 5000
+  }
+}
+```
 
-**When you need direct control over API testing:**
+**Parameters explained:**
+- `schemaUrl` - URL to fetch API schema (OpenAPI/Swagger, GraphQL introspection endpoint)
+- `schemaContent` - Direct schema content as JSON/YAML string (alternative to schemaUrl)
+- `schemaType` - Type of schema: `openapi`, `swagger`, `graphql`, `auto` (default: auto)
+- `apiBaseUrl` - Base URL of the API (overrides schema baseUrl if provided)
+- `includeAuth` - Include authentication testing scenarios (default: true)
+- `includeSecurity` - Include security testing scenarios (default: true)
+- `includeErrorHandling` - Include error handling scenarios (default: true)
+- `outputPath` - File path to save test plan (default: ./api-test-plan.md)
+- `testCategories` - Types of tests: `functional`, `security`, `performance`, `integration`, `edge-cases`
+- `validateEndpoints` - Make actual API calls to validate endpoints (default: false)
+- `validationSampleSize` - Number of endpoints to validate, use -1 for all (default: 3)
+- `validationTimeout` - Timeout per validation request in ms (default: 5000)
+
+### Tool 2: `api_generator`
+
+**Purpose:** Generate executable tests (Playwright, Jest, Postman) from test plans using AI
+
+**Generate Playwright tests:**
+```javascript
+{
+  "tool": "api_generator",
+  "parameters": {
+    "testPlanPath": "./test-plan.md",
+    "outputFormat": "playwright",
+    "outputDir": "./tests",
+    "includeSetup": true,
+    "language": "typescript"
+  }
+}
+```
 
-### Basic API Testing
+**Generate Jest tests:**
+```javascript
+{
+  "tool": "api_generator",
+  "parameters": {
+    "testPlanPath": "./test-plan.md",
+    "outputFormat": "jest",
+    "outputDir": "./tests",
+    "testFramework": "jest",
+    "baseUrl": "https://api.example.com"
+  }
+}
+```
 
+**Generate Postman collection:**
 ```javascript
-// Single API request with validation
-await tools.api_request({
-  method: "GET", 
-  url: "https://jsonplaceholder.typicode.com/users/1",
-  expect: { 
-    status: 200,
-    contentType: "application/json"
+{
+  "tool": "api_generator",
+  "parameters": {
+    "testPlanPath": "./test-plan.md",
+    "outputFormat": "postman",
+    "outputDir": "./postman",
+    "includeAuth": true
+  }
+}
+```
+
+**Generate all formats:**
+```javascript
+{
+  "tool": "api_generator",
+  "parameters": {
+    "testPlanPath": "./test-plan.md",
+    "outputFormat": "all",
+    "outputDir": "./tests",
+    "language": "typescript"
   }
-})
+}
 ```
 
-### Advanced API Testing with Session Management
+**Parameters explained:**
+- `testPlanPath` - Path to test plan markdown file
+- `testPlanContent` - Direct test plan content as markdown (alternative to testPlanPath)
+- `outputFormat` - Format: `playwright`, `postman`, `jest`, `all` (default: all)
+- `outputDir` - Directory to save generated tests (default: ./tests)
+- `sessionId` - Session ID for tracking generated tests
+- `includeAuth` - Include authentication setup (default: true)
+- `includeSetup` - Include test setup/teardown code (default: true)
+- `testFramework` - Framework: `jest`, `mocha`, `playwright-test`
+- `baseUrl` - Base URL for API (optional)
+- `language` - Language: `javascript`, `typescript` (default: typescript)
+
+### Tool 3: `api_healer`
+
+**Purpose:** Debug and automatically fix failing API tests
 
+**Fix specific test file:**
 ```javascript
-// 1. Start a test session
-await tools.api_request({
-  sessionId: "user-workflow-test",
-  method: "POST", 
-  url: "https://jsonplaceholder.typicode.com/users",
-  data: {
-    name: "John Doe",
-    email: "john@example.com"
-  },
-  expect: { status: 201 }
-})
-
-// 2. Follow up request in same session
-await tools.api_request({
-  sessionId: "user-workflow-test",
-  method: "GET",
-  url: "https://jsonplaceholder.typicode.com/users/1",
-  expect: { 
-    status: 200,
-    body: { name: "John Doe" }
+{
+  "tool": "api_healer",
+  "parameters": {
+    "testPath": "./tests/auth.test.js",
+    "testType": "auto",
+    "autoFix": true,
+    "backupOriginal": true
+  }
+}
+```
+
+**Fix multiple test files:**
+```javascript
+{
+  "tool": "api_healer",
+  "parameters": {
+    "testFiles": ["./tests/auth.test.js", "./tests/users.test.js"],
+    "testType": "playwright",
+    "healingStrategies": ["schema-update", "endpoint-fix", "auth-repair"]
   }
-})
+}
+```
 
-// 3. Generate comprehensive HTML report
-await tools.api_session_report({
-  sessionId: "user-workflow-test",
-  outputPath: "user_workflow_test_report.html"
-})
+**Analysis only (no fixes):**
+```javascript
+{
+  "tool": "api_healer",
+  "parameters": {
+    "testPath": "./tests/api.test.js",
+    "analysisOnly": true
+  }
+}
 ```
 
-### Request Chaining Example
+**Parameters explained:**
+- `testPath` - Path to a specific test file to heal
+- `testFiles` - Array of test file paths (alternative to testPath)
+- `testType` - Type: `jest`, `playwright`, `postman`, `auto` (default: auto)
+- `sessionId` - Session ID for tracking healing process
+- `maxHealingAttempts` - Max attempts per test (default: 3)
+- `autoFix` - Automatically apply fixes (default: true)
+- `backupOriginal` - Create backup files (default: true)
+- `analysisOnly` - Only analyze without fixing (default: false)
+- `healingStrategies` - Specific strategies: `schema-update`, `endpoint-fix`, `auth-repair`, `data-correction`, `assertion-update`
+
+### Tool 4: `api_project_setup`
 
+**Purpose:** Detect project configuration for test generation
+
+**Detect project configuration:**
 ```javascript
-// Chain requests using response data
-await tools.api_request({
-  sessionId: "chained-test",
-  chain: [
+{
+  "tool": "api_project_setup",
+  "parameters": {
+    "outputDir": "./tests"
+  }
+}
+```
+
+**What it does:**
+- Scans for `playwright.config.ts/js`, `jest.config.ts/js`, `tsconfig.json`
+- Auto-detects framework (Playwright/Jest) and language (TypeScript/JavaScript)
+- Returns configuration or prompts user if ambiguous
+- **Must be called BEFORE `api_generator`** for optimal test generation
+
+**Response (when auto-detected):**
+```json
+{
+  "success": true,
+  "autoDetected": true,
+  "config": {
+    "framework": "playwright",
+    "language": "typescript",
+    "hasTypeScript": true,
+    "hasPlaywrightConfig": true,
+    "configFiles": ["playwright.config.ts", "tsconfig.json"]
+  },
+  "nextStep": "Call api_generator with outputFormat: 'playwright' and language: 'typescript'"
+}
+```
+
+**Response (when user input needed):**
+```json
+{
+  "success": true,
+  "needsUserInput": true,
+  "prompts": [
     {
-      name: "create_user",
-      method: "POST",
-      url: "https://jsonplaceholder.typicode.com/users",
-      data: { name: "Jane Doe", email: "jane@example.com" },
-      expect: { status: 201 },
-      extract: { userId: "id" }
+      "name": "framework",
+      "question": "Which test framework would you like to use?",
+      "choices": ["playwright", "jest", "postman", "all"]
     },
     {
-      name: "get_user",
-      method: "GET", 
-      url: "https://jsonplaceholder.typicode.com/users/{{ create_user.userId }}",
-      expect: { 
-        status: 200,
-        body: { name: "Jane Doe" }
-      }
+      "name": "language",
+      "question": "Which language would you like to use?",
+      "choices": ["typescript", "javascript"]
     }
   ]
-})
+}
 ```
 
-📖 **For comprehensive API testing examples and advanced usage patterns, see:** [API Tools Usage Guide](docs/api_tools_usage.md)
-
-## ⚙️ Configuration
+**Parameters:**
+- `outputDir` - Directory for tests (default: `./tests`). Used to locate project root
+- `promptUser` - Force user prompts even if config detected (default: false)
 
-### Environment Settings
+### Tool 5: `api_request`
 
-The server runs in **API-only mode** by default for secure, lightweight deployments focused on API testing.
+**Purpose:** Execute individual HTTP requests with validation
 
-```bash
-NODE_ENV=production                    # Default: API-only mode
-OUTPUT_DIR=./output                   # Output directory for reports
-MCP_FEATURES_ENABLEDEBUGMODE=true     # Enable debug logging
+**Simple GET request:**
+```javascript
+{
+  "tool": "api_request",
+  "parameters": {
+    "method": "GET",
+    "url": "https://api.example.com/users/1",
+    "expect": {
+      "status": 200,
+      "contentType": "application/json"
+    }
+  }
+}
 ```
 
-### Command Line Options
-```bash
-npx @democratize-quality/mcp-server [options]
-
-Options:
-  --help, -h                Show help
-  --version, -v             Show version
-  --agents                  Install GitHub Copilot Chat agents and VS Code MCP configuration
-  --agents --rollback       Rollback agents installation (future feature)
-  --debug                   Enable debug mode
-  --verbose                 Enable verbose output (useful with --agents)
-  --port <number>           Set server port
+**POST with authentication:**
+```javascript
+{
+  "tool": "api_request",
+  "parameters": {
+    "method": "POST",
+    "url": "https://api.example.com/users",
+    "headers": {
+      "Authorization": "Bearer your-token-here",
+      "Content-Type": "application/json"
+    },
+    "data": {
+      "name": "John Doe",
+      "email": "john@example.com"
+    },
+    "expect": {
+      "status": 201,
+      "body": {
+        "name": "John Doe",
+        "email": "john@example.com"
+      }
+    }
+  }
+}
 ```
 
-### Agent Installation Options
-```bash
-# Install agents with default settings
-npx @democratize-quality/mcp-server --agents
+**Request chaining (use response in next request):**
+```javascript
+{
+  "tool": "api_request",
+  "parameters": {
+    "sessionId": "user-workflow",
+    "chain": [
+      {
+        "name": "create_user",
+        "method": "POST",
+        "url": "https://api.example.com/users",
+        "data": { "name": "Jane Doe" },
+        "extract": { "userId": "id" }
+      },
+      {
+        "name": "get_user",
+        "method": "GET",
+        "url": "https://api.example.com/users/{{ create_user.userId }}",
+        "expect": { "status": 200 }
+      }
+    ]
+  }
+}
+```
 
-# Install with verbose output
-npx @democratize-quality/mcp-server --agents --verbose
+**Parameters explained:**
+- `method` - HTTP method (GET, POST, PUT, DELETE, PATCH, etc.)
+- `url` - Target endpoint
+- `headers` - Custom headers (authentication, content-type)
+- `data` - Request body for POST/PUT/PATCH
+- `expect` - Validation rules (status, headers, body)
+- `sessionId` - Group related requests
+- `chain` - Execute multiple requests in sequence
 
-# Future: Rollback installation
-npx @democratize-quality/mcp-server --agents --rollback
-```
+### Tool 6: `api_session_status`
 
-### Configuration Examples
+**Purpose:** Check status of API test sessions
 
-#### VS Code MCP Configuration (Auto-generated by --agents)
-When you run `npx @democratize-quality/mcp-server --agents`, this configuration is automatically created in `.vscode/mcp.json`:
+**Check session progress:**
+```javascript
+{
+  "tool": "api_session_status",
+  "parameters": {
+    "sessionId": "user-workflow"
+  }
+}
+```
 
+**Response example:**
 ```json
 {
-  "servers": {
-    "democratize-quality": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["@democratize-quality/mcp-server"],
-      "cwd": "${workspaceFolder}",
-      "env": {
-        "NODE_ENV": "production",
-        "OUTPUT_DIR": "./api-test-reports"
-      }
-    }
-  },
-  "inputs": []
+  "sessionId": "user-workflow",
+  "totalRequests": 5,
+  "successfulRequests": 4,
+  "failedRequests": 1,
+  "status": "completed",
+  "startTime": "2025-10-23T10:00:00Z",
+  "endTime": "2025-10-23T10:05:00Z",
+  "duration": "5 minutes"
 }
 ```
 
-> **Note:** If you already have an `mcp.json` file, the installation will safely merge the configuration and create a backup.
+### Tool 7: `api_session_report`
 
-#### Basic Claude Desktop Configuration
-```json
+**Purpose:** Generate comprehensive HTML test reports
+
+**Generate report:**
+```javascript
 {
-  "mcpServers": {
-    "democratize-quality": {
-      "command": "npx",
-      "args": ["@democratize-quality/mcp-server"],
-      "env": {
-        "OUTPUT_DIR": "~/api-test-reports"
-      }
-    }
+  "tool": "api_session_report",
+  "parameters": {
+    "sessionId": "user-workflow",
+    "outputPath": "./reports/user-workflow-report.html",
+    "includeCharts": true
   }
 }
 ```
 
-#### Debug Mode Configuration
+**What you get:**
+- 📊 Visual charts (success rate, response times)
+- 📋 Request/response details
+- ✅ Validation results (pass/fail with diffs)
+- 🕐 Timing information
+- 📸 Screenshots (if applicable)
+
+---
+---
+
+## ⚙️ Configuration
+
+### Environment Variables
+
+```bash
+NODE_ENV=production              # Run in production mode (default)
+OUTPUT_DIR=./api-test-reports    # Where to save reports (default)
+MCP_FEATURES_ENABLEDEBUGMODE=true # Enable detailed logging
+```
+
+### Command-Line Options
+
+```bash
+npx @democratize-quality/mcp-server [options]
+
+Options:
+  --help, -h        Show help information
+  --version, -v     Display version number
+  --agents          Install AI testing agents for GitHub Copilot
+  --debug           Enable debug mode with detailed logs
+  --verbose         Show detailed installation output
+  --port <number>   Specify server port (if needed)
+```
+
+### VS Code MCP Configuration
+
+After running `--agents`, this file is created at `.vscode/mcp.json`:
+
 ```json
 {
-  "mcpServers": {
+  "servers": {
     "democratize-quality": {
+      "type": "stdio",
       "command": "npx",
-      "args": ["@democratize-quality/mcp-server", "--debug"],
+      "args": ["@democratize-quality/mcp-server"],
+      "cwd": "${workspaceFolder}",
       "env": {
-        "MCP_FEATURES_ENABLEDEBUGMODE": "true"
+        "NODE_ENV": "production",
+        "OUTPUT_DIR": "./api-test-reports"
       }
     }
   }
 }
 ```
 
-### Output Directory Behavior
-- **VS Code/Local**: Uses `./output` in your project directory
-- **Claude Desktop**: Uses `~/.mcp-browser-control` (in your home directory)  
-- **Custom**: Set `OUTPUT_DIR` environment variable to specify location
+### Output Directory Locations
 
-> **Note:** API test reports and session data will be saved to the configured output directory.
+- **VS Code/Local Projects**: `./api-test-reports` in your project
+- **Claude Desktop**: `~/.mcp-browser-control` in your home directory
+- **Custom Location**: Set `OUTPUT_DIR` environment variable
 
-## 🔧 Troubleshooting
+---
+
+---
+
+## � Troubleshooting
 
 ### Agent Installation Issues
 
-**1. Agents not appearing in GitHub Copilot Chat**
-- Ensure you've restarted VS Code after running `--agents` installation
-- Check that `.vscode/mcp.json` was created in your project root
-- Verify GitHub Copilot extension is installed and enabled
-- Try refreshing the workspace: `Ctrl/Cmd + Shift + P` → "Developer: Reload Window"
+<details>
+<summary><strong>Agents not appearing in GitHub Copilot Chat</strong></summary>
+
+**Solution:**
+1. Restart VS Code completely
+2. Verify `.vscode/mcp.json` exists in your project root
+3. Check that GitHub Copilot extension is installed and active
+4. Reload the workspace: `Cmd/Ctrl + Shift + P` → "Developer: Reload Window"
+
+</details>
+
+<details>
+<summary><strong>"democratize-quality server not found" error</strong></summary>
+
+**Solution:**
+1. Test the server: `npx @democratize-quality/mcp-server --help`
+2. Check `.vscode/mcp.json` configuration
+3. Try manual installation of chatmode files
+4. Ensure Node.js 14+ is installed
 
-**2. "democratize-quality server not found" error**
-- Check the MCP configuration in `.vscode/mcp.json`
-- Ensure the server is running: Test with `npx @democratize-quality/mcp-server --help`
-- Try manual installation: Copy `.github/chatmodes/` files and recreate `.vscode/mcp.json`
+</details>
 
-**3. Agent installation overwrites existing MCP config**
-- The installer creates automatic backups with timestamps
-- Restore from backup: `.vscode/mcp.json.backup.{timestamp}`
-- The installer safely merges configurations, preserving existing servers
+<details>
+<summary><strong>Installation overwrites existing MCP config</strong></summary>
 
-**4. Permission errors during installation**
-- Run with elevated permissions if needed: `sudo npx @democratize-quality/mcp-server --agents`
-- Check directory permissions for `.github/` and `.vscode/` folders
-- Ensure you have write access to the project directory
+**Solution:**
+- Automatic backups are created: `.vscode/mcp.json.backup.{timestamp}`
+- The installer safely merges configurations
+- To restore: Copy backup file back to `mcp.json`
 
-### Common Issues
+</details>
 
-**1. "No such file or directory: mkdir /mcp-output"**
-- This happens when Claude Desktop runs the server with restricted permissions
-- The server automatically creates `~/.mcp-browser-control` in your home directory
-- API test reports will be saved there instead of your project folder
+<details>
+<summary><strong>Permission errors during installation</strong></summary>
 
-**2. Output files not appearing in expected location**
-- Check the actual output directory: `~/.mcp-browser-control/`
-- You can set a custom location with: `OUTPUT_DIR=/your/custom/path`
+**Solution:**
+1. Check directory permissions for `.github/` and `.vscode/`
+2. Run with elevated permissions if needed: `sudo npx @democratize-quality/mcp-server --agents`
+3. Ensure write access to project directory
 
-**3. Server not starting in Claude Desktop**
-- Verify the npx package is published: `npx @democratize-quality/mcp-server --help`
-- Check Claude Desktop logs for detailed error messages
-- Try running directly in terminal first to test functionality
+</details>
 
-**4. API validation failures not showing details**
-- The enhanced validation feature shows "expected vs actual" values
-- Check the generated HTML reports for detailed comparison views
-- Enable debug mode for more detailed logging
+### Common Runtime Issues
 
-### Debug Mode
+<details>
+<summary><strong>API test reports not appearing in expected location</strong></summary>
 
+**Solution:**
+- Check the configured `OUTPUT_DIR` environment variable
+- For Claude Desktop: Look in `~/.mcp-browser-control/`
+- For VS Code: Look in `./api-test-reports/` in your project
+- Set custom location: `OUTPUT_DIR=/your/custom/path`
+
+</details>
+
+<details>
+<summary><strong>Server not starting in Claude Desktop</strong></summary>
+
+**Solution:**
+1. Test package availability: `npx @democratize-quality/mcp-server --help`
+2. Check Claude Desktop logs for detailed errors
+3. Verify configuration in `claude_desktop_config.json`
+4. Try running in terminal first to isolate issues
+
+</details>
+
+<details>
+<summary><strong>API validation failures not showing details</strong></summary>
+
+**Solution:**
+- Enhanced validation automatically shows "expected vs actual"
+- Check generated HTML reports for detailed comparisons
+- Enable debug mode: `MCP_FEATURES_ENABLEDEBUGMODE=true`
+- Review session logs with `api_session_status` tool
+
+</details>
+
+### Getting Help
+
+**Enable debug mode for detailed logging:**
 ```bash
-# Enable debug output with CLI tool
+# CLI
 npx @democratize-quality/mcp-server --debug
 
-# Or via environment variable
+# Environment variable
 MCP_FEATURES_ENABLEDEBUGMODE=true node mcpServer.js
 ```
 
-**Logging Levels:**
-- **Production Mode**: Shows only essential startup messages and errors
-- **Debug Mode**: Shows detailed API request/response logs and validation details
-
-## 🔍 Advanced API Testing Features
+**Log levels:**
+- **Production**: Essential startup messages and errors only
+- **Debug**: Detailed request/response logs and validation details
 
-### 🤖 AI-Powered Testing Agents
-- **🧠 Intelligent Planning**: Automatically analyze API schemas and generate comprehensive test scenarios
-- **⚡ Multi-Format Generation**: Create Jest, Playwright, and Postman tests from the same test plan
-- **🛠️ Automatic Healing**: Detect and fix authentication issues, endpoint changes, and schema updates
-- **🔍 Schema Analysis**: Parse OpenAPI/Swagger specs and GraphQL schemas automatically
-- **🎯 End-to-End Workflow**: Complete testing pipeline from planning to generation to maintenance
+---
 
-### 🔧 Core Testing Capabilities
-- **📊 Session Management**: Track API test sequences across multiple requests
-- **🔗 Request Chaining**: Use response data from one request in subsequent requests  
-- **✅ Enhanced Validation**: Shows "expected vs actual" values when validation fails
-- **📈 Interactive Reports**: Beautiful HTML test reports with detailed validation results
-- **🎯 Comprehensive Testing**: Support for all HTTP methods (GET, POST, PUT, DELETE, PATCH, etc.)
-- **🔄 Response Extraction**: Extract and reuse data from API responses
-- **📝 Detailed Logging**: Complete request/response logging for debugging
+## � Additional Resources
 
-## 📄 License
+### Documentation
 
-ISC License
+- 📖 [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
+- �‍💻 [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
 
----
+### Quick Links
 
-**Ready to democratize quality through comprehensive API testing with MCP!** 🎯
+| Resource | Description |
+|----------|-------------|
+| [GitHub Repository](https://github.com/uppadhyayraj/democratize-quality-mcp-server) | Source code and issues |
+| [Discussions](https://github.com/uppadhyayraj/democratize-quality-mcp-server/discussions) | Community Q&A |
+| [Issue Tracker](https://github.com/uppadhyayraj/democratize-quality-mcp-server/issues) | Bug reports and feature requests |
+| [NPM Package](https://www.npmjs.com/package/@democratize-quality/mcp-server) | Package information |
 
-## 📚 Documentation
-
-- [📖 Getting Started](docs/getting-started.md) - Quick start guide
-- [🔧 Tool Reference](docs/api/tool-reference.md) - Complete tool documentation
-- [🎯 API Tools Usage Guide](docs/api_tools_usage.md) - Comprehensive API testing examples and patterns
-- [👨‍💻 Developer Guide](docs/development/adding-tools.md) - Extending the server
-- [⚙️ Configuration](docs/development/configuration.md) - Advanced configuration
-- [💡 Examples](docs/examples/) - Real-world usage examples
+---
 
 ## 🏗️ Architecture
 
+### Project Structure
+
 ```
-src/
-├── tools/api/      # API testing tools
-├── config/         # Configuration management
-└── utils/          # Utility functions
+democratize-quality-mcp-server/
+├── src/
+│   ├── tools/
+│   │   ├── api/              # API testing tools
+│   │   │   ├── api-planner.js
+│   │   │   ├── api-generator.js
+│   │   │   ├── api-healer.js
+│   │   │   ├── api-project-setup.js
+│   │   │   ├── api-request.js
+│   │   │   ├── api-session-status.js
+│   │   │   └── api-session-report.js
+│   │   └── base/             # Tool framework
+│   ├── chatmodes/            # AI agent definitions
+│   │   ├── 🌐 api-planner.chatmode.md
+│   │   ├── 🌐 api-generator.chatmode.md
+│   │   └── 🌐 api-healer.chatmode.md
+│   ├── config/               # Configuration management
+│   └── utils/                # Utility functions
+├── docs/                     # Documentation
+├── mcpServer.js             # Main MCP server
+└── cli.js                   # Command-line interface
 ```
 
 ### Key Features
-- **Automatic Tool Discovery**: API tools are automatically loaded and registered
-- **Configuration System**: Environment-based configuration with sensible defaults
-- **Error Handling**: Comprehensive error handling and validation with detailed reporting
-- **Session Management**: Track and manage API test sessions
 
-## 🔧 Development
+- **🔍 Automatic Tool Discovery**: Tools are automatically loaded and registered
+- **⚙️ Configuration System**: Environment-based config with sensible defaults
+- **🛡️ Error Handling**: Comprehensive validation and detailed error reporting
+- **📊 Session Management**: Track and manage multi-step API test workflows
+
+---
+
+## 🔒 Security Considerations
+
+### Security Posture
+
+- **✅ API-Only Mode**: Enabled by default for secure deployments
+- **✅ Standard HTTP Libraries**: All requests use trusted Node.js libraries
+- **✅ No File System Access**: API tools only write to configured output directory
+- **✅ No Browser Automation**: No browser processes in API-only mode
+
+### Production Deployment Best Practices
+
+```json
+{
+  "mcpServers": {
+    "democratize-quality": {
+      "command": "npx",
+      "args": ["@democratize-quality/mcp-server"],
+      "env": {
+        "NODE_ENV": "production",
+        "OUTPUT_DIR": "~/api-test-reports"
+      }
+    }
+  }
+}
+```
+
+### Security Recommendations
+
+1. **📁 Secure Output Directory**: Set appropriate permissions on report directories
+2. **🔄 Regular Updates**: Keep the package updated for security patches
+3. **🌍 Environment Separation**: Use different configs for dev vs production
+4. **📊 Monitoring**: Enable debug mode during initial deployment to monitor usage
+5. **� API Keys**: Never commit API keys or tokens to version control
+6. **🌐 Network Security**: Use HTTPS endpoints for production API testing
+
+---
+
+## 👨‍💻 Development & Contributing
+
+### Adding New Tools
 
-### Adding New API Tools
 1. Create tool file in `src/tools/api/`
 2. Extend `ToolBase` class
 3. Define tool schema and implementation
 4. Tools are automatically discovered!
 
-### Example API Tool
+**Example tool structure:**
 ```javascript
+const ToolBase = require('../base/ToolBase');
+
 class MyApiTool extends ToolBase {
   static definition = {
     name: "my_api_tool",
-    description: "Performs API testing operations",
-    input_schema: { /* JSON schema */ },
-    output_schema: { /* JSON schema */ }
+    description: "Performs custom API testing operations",
+    input_schema: {
+      type: "object",
+      properties: {
+        endpoint: { type: "string", description: "API endpoint URL" }
+      },
+      required: ["endpoint"]
+    }
   };
 
   async execute(parameters) {
-    // API tool implementation
-    return { success: true, data: responseData };
+    // Implementation
+    return {
+      success: true,
+      data: { /* results */ }
+    };
   }
 }
+
+module.exports = MyApiTool;
 ```
 
-## 🧪 Testing
+### Running Tests
 
 ```bash
-# Run tests
+# Run test suite
 npm test
 
-# Run with coverage
-npm run test:coverage
-```
+# Run MCP inspector for development
+npm run inspector
 
-## 🔒 Security Considerations
+# Start server in debug mode
+npm run dev
+```
 
-### Default Security Posture
-- **API-Only Mode**: Enabled by default for secure, lightweight deployments
-- **HTTP Requests**: All API requests are performed using standard HTTP libraries
-- **No File System Access**: API tools don't access local file system (except for report generation)
-- **No Browser Automation**: No browser processes are launched in API-only mode
+### Contributing Guidelines
 
-### Production Deployment Recommendations
-```json
-{
-  "mcpServers": {
-    "democratize-quality": {
-      "command": "npx",
-      "args": ["@democratize-quality/mcp-server"],
-      "env": {
-        "NODE_ENV": "production",
-        "OUTPUT_DIR": "~/api-test-reports"
-      }
-    }
-  }
-}
-```
+1. 🍴 Fork the repository
+2. 🌿 Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. ✅ Add tests for your changes
+4. 📝 Update documentation
+5. 🔍 Ensure tests pass (`npm test`)
+6. 📤 Submit a pull request
 
-### Security Levels
-- **🟢 Low Risk**: API Tools - HTTP requests with validation and reporting
+**What to include in PRs:**
+- Clear description of changes
+- Test coverage for new features
+- Updated documentation
+- Examples of usage (if applicable)
 
-### Best Practices
-1. **Secure Output Directory**: Ensure output directories have appropriate permissions
-2. **Regular Updates**: Keep the package updated for security patches
-3. **Environment Separation**: Use different configurations for development vs production
-4. **Monitoring**: Enable debug mode during initial deployment to monitor API usage
+---
 
 ## 📄 License
 
-[License Type] - see [LICENSE](LICENSE) file for details
+ISC License - See [LICENSE](LICENSE) file for details
 
-## 🤝 Contributing
+---
 
-1. Fork the repository
-2. Create a feature branch
-3. Add your changes with tests
-4. Update documentation
-5. Submit a pull request
+## 🙏 Acknowledgments
 
-## 📞 Support
+Built with the [Model Context Protocol](https://modelcontextprotocol.io/) framework.
 
-- [Issues](https://github.com/uppadhyayraj/democratize-quality-mcp-server/issues) - Bug reports and feature requests
-- [Discussions](https://github.com/uppadhyayraj/democratize-quality-mcp-server/discussions) - Questions and community support  
-- [Documentation](docs/) - Comprehensive guides and references
+Special thanks to the MCP community and all contributors!
 
 ---
 
-**Ready to democratize quality through intelligent API testing agents!** 🎯
+<div align="center">
+
+**Ready to democratize quality through intelligent API testing!** 🎯
+
+Made with ❤️ by [Raj Uppadhyay](https://github.com/uppadhyayraj)
+
+[⭐ Star on GitHub](https://github.com/uppadhyayraj/democratize-quality-mcp-server) • [📦 View on NPM](https://www.npmjs.com/package/@democratize-quality/mcp-server) • [🐛 Report Bug](https://github.com/uppadhyayraj/democratize-quality-mcp-server/issues) • [💡 Request Feature](https://github.com/uppadhyayraj/democratize-quality-mcp-server/issues)
 
-*Generated automatically from tool definitions and configuration*
+</div>