Add MCP test-code-review & reporting handlers and docs

kavitaj11 · kavitaj11 · commit 4c194782827b · 2025-12-25T23:06:47.000-06:00
diff --git a/docs/MCP_SERVER_ARCHITECTURE.md b/docs/MCP_SERVER_ARCHITECTURE.md
@@ -0,0 +1,73 @@
+**MCP Server Architecture**
+
+**Overview**
+
+This document describes the architecture of the Model Control Plane (MCP) server implemented in this repository. The MCP provides a lightweight HTTP front-end that accepts prompts and workflow requests, orchestrates AI clients and local tools (Playwright bridge), and stores short-term context.
+
+**Components**
+
+- **MCP server (Java):** The entry point that binds HTTP endpoints and dispatches requests to handlers. See [src/main/java/org/k11techlab/framework/ai/mcp/MCPServer.java](src/main/java/org/k11techlab/framework/ai/mcp/MCPServer.java#L1).
+- **Handlers:** Small HttpHandler classes for each endpoint (health, completion, context, generate-page-object, generate-and-run-playwright-test, generate-and-run-selenium-test, correct-code, workflow). See [src/main/java/org/k11techlab/framework/ai/mcp/handlers](src/main/java/org/k11techlab/framework/ai/mcp/handlers/).
+- **AI Clients:** Pluggable clients used by handlers to call LLMs or RAG services (RAGEnhancedAIClient, OpenAIClient). These encapsulate prompt formatting, API calls and retry/timeout logic.
+- **Playwright bridge (PlaywrightMCPClient):** A process-based JSON-RPC client wrapper that runs `npx @playwright/mcp` and communicates over stdio to control Playwright for browser-driven test execution. See [src/main/java/org/k11techlab/framework/ai/mcp/util/PlaywrightMCPClient.java](src/main/java/org/k11techlab/framework/ai/mcp/util/PlaywrightMCPClient.java#L1).
+- **Workflows:** Higher-level orchestration (e.g., PlaywrightWorkflow) that generates a test, runs it, and archives logs/reports. See [src/main/java/org/k11techlab/framework/ai/mcp/workflow/playwright/PlaywrightWorkflow.java](src/main/java/org/k11techlab/framework/ai/mcp/workflow/playwright/PlaywrightWorkflow.java#L1).
+- **Context store (MongoContextStore):** Optional persistence for conversation/context objects using MongoDB. Configured via `config/mcp-config.properties`. See [src/main/java/org/k11techlab/framework/ai/mcp/store/MongoContextStore.java](src/main/java/org/k11techlab/framework/ai/mcp/store/MongoContextStore.java#L1).
+- **Prompts folder:** `mcp_prompts/` holds prompt files referenced by requests (e.g. `mcp_prompts/k11softwaresolutions/pages/pageobject_creation_prompt_multi.txt`). The server can accept a `promptFile` reference to load prompts server-side.
+
+**Endpoints (summary)**
+
+- `GET /mcp/health` — simple liveness check handled by HealthHandler.
+- `POST /mcp/completion` — textual prompt completion using AI client.
+- `POST /mcp/generate-page-object` — accept `{ "promptFile":"<relpath>" }` or text and run the page-object generator.
+- `POST /mcp/generate-and-run-playwright-test` — generate Playwright code and run it via the Playwright bridge; archives logs to `mcp_testlog/` and `mcp_testreport/`.
+- `POST /mcp/generate-and-run-selenium-test` — generate Selenium (Java/TestNG) test and run via Maven/Surefire.
+- `POST /mcp/correct-code` — fix or transform submitted code.
+
+See handlers directory for implementation details: [src/main/java/org/k11techlab/framework/ai/mcp/handlers](src/main/java/org/k11techlab/framework/ai/mcp/handlers/).
+
+**Data & control flow (high-level)**
+
+1. Client sends HTTP request to MCP server endpoint (e.g., generate-page-object).
+2. Handler validates input, loads prompt text (inline or from `mcp_prompts/`), and prepares LLM input.
+3. Handler invokes an AI client (RAG or direct LLM) to generate code (page object or test).
+4. For run requests, the handler either:
+   - writes generated artifacts to disk and calls the Playwright bridge (PlaywrightMCPClient) which runs Playwright and streams test results; or
+   - generates Java test code and invokes Maven to run the test (Selenium path).
+5. Workflow copies outputs to `mcp_testlog/` and `mcp_testreport/` and returns a response with run metadata.
+
+**Configuration**
+
+- `config/mcp-config.properties` controls port, prompt mappings, classNameBase, log.dir and Mongo connection settings. See [config/mcp-config.properties](config/mcp-config.properties#L1).
+- Default port observed in the repo is `8090` (property `mcp.port`).
+
+**Runtime requirements**
+
+- Java 17+ / JDK 21 recommended for running the server (project was prepared for Java 21 migration).
+- Node.js + Playwright CLI (`npx @playwright/mcp`) for Playwright runs.
+- MongoDB if you want persistent context storage (optional; in-memory alternatives may exist).
+
+**Artifacts & logs**
+
+- Generated tests and page objects: `src/test/java/org/k11techlab/framework_unittests/ai_generated/...` (example generated test: [GeneratedPlaywrightLoginTest.java](src/test/java/org/k11techlab/framework_unittests/ai_generated/k11softwaresolutions/GeneratedPlaywrightLoginTest.java#L1)).
+- Test run logs: `mcp_testlog/`.
+- HTML reports: `mcp_testreport/` and `target/surefire-reports/` for Maven-run tests.
+
+**Troubleshooting notes**
+
+- If endpoints return connection errors, ensure the MCP server process is running and listening on the configured port (look for startup message: "MCP Server started on port <port>").
+- Playwright runs require `npx` available in PATH and appropriate browser binaries; run `npx playwright install` if required.
+- Check `mcp_testlog/` for Playwright bridge logs and `mcp_testreport/` for HTML test reports after a run.
+
+**Where to look in the code**
+
+- Server bootstrap: [src/main/java/org/k11techlab/framework/ai/mcp/MCPServer.java](src/main/java/org/k11techlab/framework/ai/mcp/MCPServer.java#L1)
+- Handlers: [src/main/java/org/k11techlab/framework/ai/mcp/handlers](src/main/java/org/k11techlab/framework/ai/mcp/handlers/)
+- Playwright bridge: [src/main/java/org/k11techlab/framework/ai/mcp/util/PlaywrightMCPClient.java](src/main/java/org/k11techlab/framework/ai/mcp/util/PlaywrightMCPClient.java#L1)
+- Playwright orchestration: [src/main/java/org/k11techlab/framework/ai/mcp/workflow/playwright/PlaywrightWorkflow.java](src/main/java/org/k11techlab/framework/ai/mcp/workflow/playwright/PlaywrightWorkflow.java#L1)
+- Prompts: `mcp_prompts/` folder (example: [mcp_prompts/k11softwaresolutions/pages/pageobject_creation_prompt_multi.txt](mcp_prompts/k11softwaresolutions/pages/pageobject_creation_prompt_multi.txt#L1)).
+
+**Next steps / improvements (suggested)**
+
+- Harden generated interactions with robust waits / fallback actions in generators (addresses flaky selectors like the "login menu not visible" case).
+- Add a small systemd/Windows service script or a Dockerfile to run MCP persistently for CI/demo scenarios.
+- Add a health-check and readiness probe endpoint that also verifies Playwright and Mongo availability.
diff --git a/mcp_prompts/k11softwaresolutions/pages/pageobject_creation_prompt_multi.txt b/mcp_prompts/k11softwaresolutions/pages/pageobject_creation_prompt_multi.txt
@@ -1,25 +1,123 @@
-# Page Object Creation Prompt for HomePage and LoginPage
+# Page Object Creation Prompt — site pages and element id mappings
 
 {
-  "pageObjects": [
-    {
-      "className": "HomePage",
-      "fields": {
-        "isDashboardVisible": {"id": "Dashboard", "method": "isVisible"},
-        "clickServiceLink": {"id": "service", "text": "Service", "method": "click"},
-        "clickLoginMenu": {"id": "loginMenu", "text": "Login", "method": "click"},
-        "clickRegisterMenu": {"id": "registerMenu", "text": "Register", "method": "click"}
-      }
-    },
-    {
-      "className": "LoginPage",
-      "fields": {
-        "enterUsername": {"id": "username", "name": "username", "text": "Username", "method": "fill"},
-        "enterPassword": {"id": "password", "name": "password", "text": "Password", "method": "fill"},
-        "clickLogin": {"id": "login", "name": "login", "text": "Login", "method": "click"}
-      }
+  "pages": {
+    "frontend/app/home/page.js": {
+      "container": { "id": "home-hero-section", "type": "section" },
+      "hero_bg": { "id": "home-hero-bg", "type": "background" },
+      "hero_content": { "id": "home-hero-content", "type": "container" },
+      "hero_grid": { "id": "home-hero-grid", "type": "layout" },
+      "hero_left": { "id": "home-hero-left", "type": "container" },
+      "hero_announcement": { "id": "home-hero-announcement", "type": "text" },
+      "hero_title": { "id": "home-hero-title", "type": "heading" },
+      "hero_description": { "id": "home-hero-description", "type": "text" },
+      "hero_actions": { "id": "home-hero-actions", "type": "container" },
+      "explore_services_btn": { "id": "home-explore-services-btn", "type": "link" },
+      "contact_btn": { "id": "home-contact-btn", "type": "link" },
+      "hero_benefits": { "id": "home-hero-benefits", "type": "list" },
+      "benefit_fast": { "id": "home-benefit-fast", "type": "badge" },
+      "benefit_scalable": { "id": "home-benefit-scalable", "type": "badge" },
+      "benefit_ai": { "id": "home-benefit-ai", "type": "badge" },
+      "hero_image_container": { "id": "home-hero-image-container", "type": "container" },
+      "hero_image": { "id": "home-hero-image", "type": "image" },
+      "quick_actions_section": { "id": "home-quick-actions-section", "type": "section" },
+      "quick_actions_container": { "id": "home-quick-actions-container", "type": "container" },
+      "quick_actions_header": { "id": "home-quick-actions-header", "type": "container" },
+      "quick_actions_header_content": { "id": "home-quick-actions-header-content", "type": "container" },
+      "quick_actions_title": { "id": "home-quick-actions-title", "type": "heading" },
+      "quick_actions_desc": { "id": "home-quick-actions-desc", "type": "text" },
+      "quick_actions_grid": { "id": "home-quick-actions-grid", "type": "grid" },
+      "dashboard_link": { "id": "home-dashboard-link", "type": "link" },
+      "dashboard_card": { "id": "home-dashboard-card", "type": "card" },
+      "dashboard_card_body": { "id": "home-dashboard-card-body", "type": "container" },
+      "dashboard_icon": { "id": "home-dashboard-icon", "type": "icon" },
+      "dashboard_content": { "id": "home-dashboard-content", "type": "container" },
+      "dashboard_title_row": { "id": "home-dashboard-title-row", "type": "container" },
+      "dashboard_title": { "id": "home-dashboard-title", "type": "heading" },
+      "dashboard_arrow": { "id": "home-dashboard-arrow", "type": "icon" },
+      "dashboard_desc": { "id": "home-dashboard-desc", "type": "text" },
+      "services_link": { "id": "home-services-link", "type": "link" },
+      "services_card": { "id": "home-services-card", "type": "card" },
+      "services_card_body": { "id": "home-services-card-body", "type": "container" },
+      "services_icon": { "id": "home-services-icon", "type": "icon" },
+      "services_content": { "id": "home-services-content", "type": "container" },
+      "services_title_row": { "id": "home-services-title-row", "type": "container" },
+      "services_title": { "id": "home-services-title", "type": "heading" },
+      "services_arrow": { "id": "home-services-arrow", "type": "icon" },
+      "services_desc": { "id": "home-services-desc", "type": "text" }
+    },
+    "frontend/app/login/page.js": {
+      "container": { "id": "login-container", "type": "form-container" },
+      "title": { "id": "login-title", "type": "heading" },
+      "error": { "id": "login-error", "type": "text" },
+      "form": { "id": "login-form", "type": "form" },
+      "username": { "id": "login-username", "type": "input" },
+      "password": { "id": "login-password", "type": "input" },
+      "forgot_password_link": { "id": "login-forgot-password-link", "type": "container" },
+      "forgot_link": { "id": "login-forgot-link", "type": "link" },
+      "submit": { "id": "login-submit", "type": "button" },
+      "register_link": { "id": "login-register-link", "type": "text" },
+      "register_here": { "id": "login-register-here", "type": "link" }
+    },
+    "frontend/app/forgot-password/page.js": {
+      "container": { "id": "forgot-password-container", "type": "form-container" },
+      "form": { "id": "forgot-password-form", "type": "form" },
+      "email": { "id": "forgot-password-email", "type": "input" },
+      "submit": { "id": "forgot-password-submit", "type": "button" },
+      "message": { "id": "forgot-password-message", "type": "text" },
+      "error": { "id": "forgot-password-error", "type": "text" }
+    },
+    "frontend/app/reset-password/page.js": {
+      "container": { "id": "reset-password-container", "type": "form-container" },
+      "title": { "id": "reset-password-title", "type": "heading" },
+      "message": { "id": "reset-password-message", "type": "text" },
+      "error": { "id": "reset-password-error", "type": "text" },
+      "form": { "id": "reset-password-form", "type": "form" },
+      "password": { "id": "reset-password-password", "type": "input" },
+      "confirm": { "id": "reset-password-confirm", "type": "input" },
+      "submit": { "id": "reset-password-submit", "type": "button" }
+    },
+    "frontend/app/register/page.js": {
+      "container": { "id": "register-container", "type": "form-container" },
+      "title": { "id": "register-title", "type": "heading" },
+      "error": { "id": "register-error", "type": "text" },
+      "success": { "id": "register-success", "type": "text" },
+      "form": { "id": "register-form", "type": "form" },
+      "username": { "id": "register-username", "type": "input" },
+      "email": { "id": "register-email", "type": "input" },
+      "password": { "id": "register-password", "type": "input" },
+      "subscription": { "id": "register-subscription", "type": "select" },
+      "submit": { "id": "register-submit", "type": "button" }
+    },
+    "frontend/app/contact/page.js": {
+      "container": { "id": "contact-container", "type": "form-container" },
+      "title": { "id": "contact-title", "type": "heading" },
+      "form": { "id": "contact-form", "type": "form" },
+      "name": { "id": "contact-name", "type": "input" },
+      "email": { "id": "contact-email", "type": "input" },
+      "message": { "id": "contact-message", "type": "textarea" },
+      "submit": { "id": "contact-submit", "type": "button" },
+      "sent": { "id": "contact-sent", "type": "text" }
+    },
+    "frontend/app/services/page.js": {
+      "container": { "id": "services-container", "type": "container" },
+      "title": { "id": "services-title", "type": "heading" }
+    },
+    "frontend/app/about/page.js": {
+      "container": { "id": "about-container", "type": "container" },
+      "title": { "id": "about-title", "type": "heading" }
+    },
+    "frontend/app/insights/page.js": {
+      "container": { "id": "insights-container", "type": "container" }
+    },
+    "frontend/app/dashboard/page.js": {
+      "container": { "id": "dashboard-container", "type": "container" },
+      "title": { "id": "dashboard-title", "type": "heading" },
+      "welcome": { "id": "dashboard-welcome", "type": "text" },
+      "email": { "id": "dashboard-email", "type": "text" },
+      "logout": { "id": "dashboard-logout", "type": "button" }
     }
-  ]
+  }
 }
 
 - Use id as the first preference, then name, then text for selectors.
diff --git a/scripts/test_mcp.sh b/scripts/test_mcp.sh
@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Test MCP endpoints script
+# Usage: MCP_PORT=8090 MCP_HOST=http://localhost ./scripts/test_mcp.sh
+
+HOST=${MCP_HOST:-http://localhost}
+PORT=${MCP_PORT:-8090}
+BASE="$HOST:$PORT/mcp"
+
+echo "Using MCP at $BASE"
+
+echo "\n=== /mcp/health ==="
+curl -sS "$BASE/health" || true
+
+echo "\n=== /mcp/workflow ==="
+curl -sS -X POST "$BASE/workflow" -H "Content-Type: text/plain" -d "Run login workflow for test user" || true
+
+# Sample broken Java for /mcp/correct-code
+BROKEN_JAVA='public class X { public static void main(String[] args) { System.out.println("hi") } }'
+
+echo "\n=== /mcp/correct-code ==="
+curl -sS -X POST "$BASE/correct-code" -H "Content-Type: text/plain" -d "$BROKEN_JAVA" || true
+
+# Read page object prompt file from repository and post it to MCP
+PROMPT_REL="k11softwaresolutions/pages/pageobject_creation_prompt_multi.txt"
+PROMPT_FILE="mcp_prompts/$PROMPT_REL"
+
+if [ -f "$PROMPT_FILE" ]; then
+  echo "\n=== /mcp/generate-page-object (using promptFile reference) ==="
+  # Instruct server to load the prompt file from its mcp-prompts folder
+  curl -sS -X POST "$BASE/generate-page-object" -H "Content-Type: application/json" -d "{\"promptFile\":\"$PROMPT_REL\"}" || true
+
+  # Extract human-readable instruction lines (bulleted lines starting with '-') and send to completion endpoint
+  INSTRUCTIONS=$(awk '/^- /{flag=1} flag{print}' "$PROMPT_FILE" | sed 's/^- //') || true
+  if [ -n "$INSTRUCTIONS" ]; then
+    echo "\n=== /mcp/completion (text prompt from file instructions) ==="
+    curl -sS -X POST "$BASE/completion" -H "Content-Type: text/plain" -d "$INSTRUCTIONS" || true
+  fi
+else
+  echo "\nPrompt file not found: $PROMPT_FILE — skipping generate-page-object requests"
+fi
+
+# Generate and run tests (playwright + selenium)
+echo "\n=== /mcp/generate-and-run-playwright-test ==="
+curl -sS -X POST "$BASE/generate-and-run-playwright-test?engine=playwright&packageName=org.k11techlab.framework_unittests.ai_generated.k11softwaresolutions" -H "Content-Type: text/plain" -d "Open login page and sign in" || true
+
+echo "\n=== /mcp/generate-and-run-selenium-test ==="
+curl -sS -X POST "$BASE/generate-and-run-selenium-test?engine=selenium&packageName=org.k11techlab.framework_unittests.ai_generated.k11softwaresolutions" -H "Content-Type: text/plain" -d "Open login page and sign in" || true
+
+# Done
+
+echo "\nAll MCP endpoint checks completed."
diff --git a/src/main/java/org/k11techlab/framework/ai/mcp/MCPServer.java b/src/main/java/org/k11techlab/framework/ai/mcp/MCPServer.java
@@ -30,6 +30,8 @@ public void start(int port) throws IOException {
         server.createContext("/mcp/generate-and-run-selenium-test", new GenerateAndRunTestHandler());
         server.createContext("/mcp/generate-and-run-playwright-test", new GenerateAndRunTestHandler());
         server.createContext("/mcp/generate-page-object", new GeneratePageObjectHandler());
+        server.createContext("/mcp/test-code-review", new TestCodeReviewHandler(aiClient));
+        server.createContext("/mcp/report", new ReportingHandler());
 
         server.setExecutor(null);
         server.start();
diff --git a/src/main/java/org/k11techlab/framework/ai/mcp/handlers/ReportingHandler.java b/src/main/java/org/k11techlab/framework/ai/mcp/handlers/ReportingHandler.java
diff --git a/src/main/java/org/k11techlab/framework/ai/mcp/handlers/TestCodeReviewHandler.java b/src/main/java/org/k11techlab/framework/ai/mcp/handlers/TestCodeReviewHandler.java
