mcp-state-machine-test-framework 1.0.0

package/DOCUMENTATION/API.md

@@ -0,0 +1,49 @@
+# 🌐 API Testing (REST / Services)
+
+SMS allows for native integration and sanity testing of APIs.
+
+## 🚀 Strategy 1: System Commands (`sh:curl`)
+For quick and direct tests, you can use `curl`.
+
+```json
+{
+  "name": "TC_API_Status_Check",
+  "steps": [
+    {
+      "name": "Validate Endpoint",
+      "actions": [
+        "sh:curl -X GET https://api.example.com/status -I"
+      ]
+    }
+  ]
+}
+```
+
+## 🧠 Strategy 2: Data-Driven API Testing
+You can use a CSV to send multiple payloads to an API.
+
+### CSV (`payloads.csv`):
+```csv
+id,name,status
+1,"Test 1",201
+2,"Test 2",400
+```
+
+### Test Case:
+```json
+"actions": [
+  "sh:curl -X POST https://api.com/users -d '{\"id\": {{id}}, \"name\": \"{{name}}\"}'"
+]
+```
+
+## 🛠️ Strategy 3: MCP API Servers
+For more complex validation (JSON Schema, dynamic Headers), it is recommended to connect a specialized HTTP MCP server.
+
+- **Advantage**: The report will show the response JSON formatted and elegant.
+- **Conceptual Example**: `mcp:http-client/request { \"method\": \"GET\", \"url\": \"...\" }`
+
+## 🔗 Hybrid Testing (Real E2E)
+The greatest power of SMS is mixing layers:
+1. **Step 1 (API)**: Create a user via `sh:curl`.
+2. **Step 2 (Web)**: Log in with that user in the browser via `mcp:wdio-mcp/navigate`.
+3. **Step 3 (DB)**: Validate the record in the database.

package/DOCUMENTATION/Architecture.md

@@ -0,0 +1,39 @@
+# 🏛️ SMS Universal Architecture V12.3 (Multi-Map & Integrity)
+
+The **State Machine Simulator (SMS)** framework has evolved into a **Multi-Project Orchestration** model, introducing isolated data universes and automated integrity checks.
+
+## 📡 The "Multi-Map" Concept (V12.3)
+To support parallel execution and multiple applications, SMS now uses isolated state map files:
+- **Isolation**: Each project (Web, Mobile, API) has its own file in the `maps/` directory.
+- **Pre-flight Integrity Check**: Before execution, the engine validates that the Suite and the Map are compatible, preventing cross-environment errors.
+Unlike traditional frameworks that import libraries (like Selenium or WDIO) directly into the code, SMS acts as a **Message Bus**.
+- **Transport**: Communicates with external servers (MCP Servers) via `stdio`.
+- **Agnosticism**: The engine doesn't know what a "browser" or a "selector" is; it only knows how to send `JSON-RPC` commands and receive responses.
+- **Session Persistence**: Unlike standard MCP clients, the engine keeps connections open throughout the entire Suite execution, allowing multiple Test Cases to share the same browser/app state.
+
+## 🛠️ Core Components
+
+### 1. The Orchestrator (`index.js`)
+The brain of the system. Its functions are:
+- **Client Management**: Starts and maintains persistent MCP server processes defined in `mcp_config.json`.
+- **Iteration Engine (Data-Driven)**: Processes data arrays or external CSV/JSON files, injecting variables in real-time.
+- **Interpolator**: Replaces `{{variable}}` syntax before sending commands to the server.
+- **Evidence Generator**: Performs a deep scan of responses to extract Base64 images and inject them into the report.
+
+### 2. Data Layer (Universal Data Bridge)
+The engine supports three levels of data:
+- **Hardcoded**: Literal actions.
+- **Internal Data**: Arrays defined within the Test Case.
+- **External Data**: Paths to external `.csv` or `.json` files.
+
+### 3. Hook System (Lifecycle)
+The framework manages the lifecycle at hierarchical levels:
+1. **Suite Level**: `beforeSuite` (Global Setup) and `afterSuite` (Global Teardown).
+2. **Case Level**: `beforeCase` and `afterCase`.
+3. **Step Level**: `afterStep` (Ideal for automatic screenshots).
+
+## 📊 Reporting Dashboard (Glassmorphism)
+The generated report is a **self-contained** HTML file:
+- **Portable**: No external files needed (images are Base64).
+- **Encapsulated**: Technical JSON logs are hidden under collapsible menus to prioritize action readability and visual evidence.
+- **Premium Design**: Modern aesthetics with 'Outfit' fonts and a neon/dark color palette.

package/DOCUMENTATION/DataDriven.md

@@ -0,0 +1,47 @@
+# 📊 Data-Driven Master Guide
+
+The SMS V11.2 engine allows for massive test execution by decoupling data from logic.
+
+## 1. Internal Data (JSON)
+Ideal for quick tests. Define the `data` array within the Test Case `.json` file.
+
+```json
+"data": [
+  { "user": "admin", "pass": "123" },
+  { "user": "guest", "pass": "abc" }
+]
+```
+
+## 2. External Data (CSV)
+The professional and scalable approach. Create a `.csv` file and link to it from the Test Case.
+
+### The CSV File (`users.csv`):
+The first row **MUST** be the header.
+```csv
+user,pass,comment
+admin,secret,"Admin test"
+tester,test,"Base user test"
+```
+
+### The Test Case:
+```json
+{
+  "name": "TC_Massive_Login",
+  "data": "users.csv",
+  "steps": [
+    {
+      "name": "Login",
+      "actions": [
+        "mcp:wdio-mcp/set_value { \"selector\": \"#u\", \"value\": \"{{user}}\" }",
+        "mcp:wdio-mcp/set_value { \"selector\": \"#p\", \"value\": \"{{pass}}\" }"
+      ]
+    }
+  ]
+}
+```
+
+## 🧠 Golden Rules for Data-Driven
+1. **Interpolation**: Always use `{{column}}` to reference data.
+2. **Iteration**: The engine will execute **ALL** test case steps once for each row in the CSV.
+3. **Persistence**: If you start the session in `beforeSuite`, all iterations will occur in the same browser window (much faster).
+4. **Cleanup**: The engine automatically strips extra quotes from CSVs to prevent errors in command JSON strings.

package/DOCUMENTATION/Master_Test_Plan_V12.md

@@ -0,0 +1,36 @@
+# 🔬 Master Test Plan - SMS Universal V12.3
+
+This plan verifies the full spectrum of the MCP framework's capabilities, ensuring that all V12.3 architectural changes are stable and production-ready.
+
+## 🏁 Test Matrix
+
+| Feature | Platform | Test Strategy | Goal |
+| :--- | :--- | :--- | :--- |
+| **Pure MCP Orchestration** | Universal | Persistent Session Test | Verify that MCP connections stay open across multiple Test Cases. |
+| **Multi-Platform (Web)** | Web (Chrome) | Navigation & Interactivity | Validate standard web automation via `wdio-mcp`. |
+| **Multi-Platform (Mobile)** | Android (Perfecto) | Cloud Session & Cloud APK | Validate cloud device allocation and mobile interactions. |
+| **Hybrid Orchestration** | Web + System | `sh:` and `mcp:` mix | Verify that system commands (API/Files) can coexist with UI actions. |
+| **Data-Driven (CSV)** | Universal | Variable Interpolation | Ensure `{{variable}}` mapping works from external files. |
+| **Multi-Map Support** | Universal | Isolated map switching | Verify that different suites use different files in `/maps`. |
+| **Pre-flight Integrity** | Universal | Negative & Positive Validation | Ensure the engine blocks execution if the map is missing or invalid. |
+| **Symmetrical Hooks** | Universal | Step-level lifecycle | Validate that `beforeStep` and `afterStep` execute correctly. |
+
+---
+
+## 🧪 Master Smoke Suite (Hybrid Scenario)
+
+To validate everything in a single "Stress Run", we will execute a hybrid suite:
+1. **Pre-condition**: Integrity check validates `maps/web_map.json`.
+2. **Step 1 (API)**: Use `sh:curl` to verify an endpoint.
+3. **Step 2 (Web)**: Open a browser and use a CSV to perform a search.
+4. **Step 3 (Evidence)**: Capture screenshots after every step via `afterStep`.
+5. **Post-condition**: Close session.
+
+## 📊 Acceptance Criteria
+- 100% of the integrity checks must pass for valid maps.
+- Visual evidence (Base64) must be present for all UI steps in the final report.
+- The report must show the correct "Iteration X" label for Data-Driven tests.
+- System logs must show the "V12.3 Integrity Check" header.
+
+---
+*Verified by SMS Orchestrator V12.3*

package/DOCUMENTATION/Mobile.md

@@ -0,0 +1,34 @@
+# 📱 Mobile Automation (Appium)
+
+The SMS engine supports testing on real devices and emulators using the `wdio-mcp` server configured for Appium.
+
+## 🛠️ Mobile Session Setup
+Unlike Web, Mobile requires a robust set of **Capabilities**. These are defined in the `beforeSuite` hook.
+
+### Example: Android Emulator
+```json
+"beforeSuite": [
+  "mcp:wdio-mcp/start_session { 
+      \"platform\": \"android\", 
+      \"deviceName\": \"emulator-5554\", 
+      \"automationName\": \"UiAutomator2\",
+      \"app\": \"C:/path/my_app.apk\",
+      \"capabilities\": {
+          \"noReset\": true,
+          \"autoGrantPermissions\": true
+      }
+  }"
+]
+```
+
+## 🖐️ Mobile-Specific Actions
+When the session platform is `android` or `ios`, you can use exclusive tools:
+
+- **Tap**: `mcp:wdio-mcp/tap_element { \"selector\": \"~login_button\" }`
+- **Swipe**: `mcp:wdio-mcp/swipe { \"direction\": \"up\", \"percent\": 0.8 }`
+- **Hide Keyboard**: `mcp:wdio-mcp/hide_keyboard {}`
+
+## 🧪 Mobile Testing Strategy
+1. **Accessibility IDs**: Always use `~ID` in your selectors for maximum stability.
+2. **Context Switching**: If your app is hybrid (Webview), use `mcp:wdio-mcp/switch_context { \"context\": \"WEBVIEW_...\" }`.
+3. **Evidence Capture**: The `mcp:wdio-mcp/get_screenshot {}` command works the same as in Web and is vital for the report.

package/DOCUMENTATION/Perfecto_Setup.md

@@ -0,0 +1,45 @@
+# 📱 Perfecto Mobile Cloud Setup
+
+This guide details how to connect the SMS Framework to the **Perfecto Mobile** cloud using the modular `wdio-mcp` provider.
+
+## 🔗 Connection Configuration
+The framework is optimized to use the `perfecto` provider directly, which simplifies the configuration.
+
+### Recommended Suite Configuration
+
+```json
+{
+  "name": "Suite_Mobile_Perfecto",
+  "state_map": "your_map.json",
+  "beforeSuite": [
+    "mcp:wdio-mcp/start_session { 
+      \"platform\": \"android\", 
+      \"provider\": \"perfecto\", 
+      \"app\": \"PRIVATE:Advantage+demo+3.3.apk\",
+      \"automationName\": \"UiAutomator2\",
+      \"capabilities\": {
+        \"appium:useVirtualDevice\": true,
+        \"appium:waitForAvailableLicense\": true,
+        \"perfecto:options\": {
+          \"securityToken\": \"YOUR_TOKEN_HERE\"
+        }
+      }
+    }"
+  ],
+  "afterSuite": [
+    "mcp:wdio-mcp/close_session {}"
+  ]
+}
+```
+
+## 🛡️ Security & Privacy
+- **Automatic Masking**: The SMS server automatically detects the `securityToken` in your suite files and masks it in the HTML/JSON reports as `********`.
+- **Environment Variables**: For production environments, it is highly recommended to set the `PERFECTO_TOKEN` as an environment variable instead of hardcoding it in the JSON file.
+
+## 🧠 Best Practices
+1. **Selector Stability**: Use **Accessibility IDs** (`~User Name`) whenever possible. They are the most stable across cloud latency.
+2. **Pre-flight Checks**: The server performs an integrity check on your state map before execution to catch path errors early.
+3. **Session Management**: Always include `close_session` in your `afterSuite` to free up cloud licenses immediately.
+
+---
+*V1.1 - Updated for Pure-MCP Standard*

package/DOCUMENTATION/Reference.md

@@ -0,0 +1,78 @@
+# 📖 Configuration and Command Reference
+
+This guide details how to write Test Cases, Suites, and Commands for the SMS engine.
+
+## 📋 Test Case Structure (`/test_cases`)
+
+A test case is a JSON file with the following structure:
+
+```json
+{
+  "name": "TC_Unique_Name",
+  "data": "path/to/file.csv", // Optional: For Data-Driven
+  "steps": [
+    {
+      "name": "Step Name",
+      "actions": [
+        "sh:echo 'System Command'",
+        "mcp:server/tool { \"arg\": \"value\" }"
+      ]
+    }
+  ]
+}
+```
+
+## 📋 Suite Structure (`/suites`)
+
+The suite groups cases and defines the global lifecycle:
+
+```json
+{
+  "name": "Suite_Name",
+  "state_map": "project_map.json", // Optional: Separate state machine file
+  "tests": ["TC_1", "TC_2"],
+  "beforeSuite": ["mcp:wdio-mcp/start_session {...}"],
+  "afterSuite": ["mcp:wdio-mcp/close_session {}"],
+  "beforeCase": [],
+  "afterCase": [],
+  "beforeStep": [],
+  "afterStep": ["mcp:wdio-mcp/get_screenshot {}"]
+}
+```
+
+## ⚡ Action Syntax
+
+### 1. System Commands (`sh:`)
+Executes commands directly on the host's terminal.
+- Example: `sh:npm run build`
+- Example: `sh:echo 'Hello {{user}}'`
+
+### 2. MCP Commands (`mcp:`)
+Calls a tool from a configured MCP server.
+- Syntax: `mcp:server-name/tool-name { "json": "args" }`
+- Example: `mcp:wdio-mcp/navigate { "url": "https://google.com" }`
+
+## 📂 Project Structure Standard
+- `/test_cases`: Test logic (Steps).
+- `/suites`: Execution flow and lifecycle hooks.
+- `/maps`: **[NEW]** Isolated state machine database files (.json).
+- `/reports`: Self-contained visual execution results.
+
+## 🔗 MCP Servers (`mcp_config.json`)
+
+Configure your persistent servers here:
+
+```json
+{
+  "mcpServers": {
+    "wdio-mcp": {
+      "command": "node",
+      "args": ["C:/path/to/server/index.js"]
+    }
+  }
+}
+```
+
+## 🔄 Variables and Placeholders
+The engine automatically replaces any string enclosed in `{{ }}` using the column names from your CSV or keys from your data JSON.
+- Example: `{{search_query}}`, `{{password}}`.

package/DOCUMENTATION/Setup_AI_Environments.md

@@ -0,0 +1,73 @@
+# 🤖 AI Environment Configuration Guide
+
+The SMS engine uses the MCP (Model Context Protocol) standard. Here we explain how to connect your servers (`index.js` and `wdio-mcp`) to different AI tools.
+
+## 📦 Required Dependencies
+To ensure the engine and servers run smoothly, make sure you have installed:
+- **Node.js**: v18 or higher.
+- **MCP SDK**: `@modelcontextprotocol/sdk`.
+- **Zod**: For schema validation.
+
+Quick installation:
+```bash
+npm install @modelcontextprotocol/sdk zod
+```
+
+---
+
+## 🌩️ 1. Antigravity (Google Gemini) - *Current Environment*
+In this environment, the agent (me) interacts directly with the SMS orchestrator.
+- **Connection**: Performed via terminal commands (`node index.js`).
+- **Advantage**: Allows for dynamic orchestration and real-time report visualization within the workspace.
+
+---
+
+## 🎭 2. Claude Desktop
+Claude can "see" your automation tools if you edit its configuration file.
+
+### Configuration (`claude_desktop_config.json`):
+Locate the file at `%APPDATA%\Claude\claude_desktop_config.json` and add:
+
+```json
+{
+  "mcpServers": {
+    "sms-orchestrator": {
+      "command": "node",
+      "args": ["C:/path/to/your/project/index.js"]
+    },
+    "wdio-automation": {
+      "command": "node",
+      "args": ["C:/path/to/wdio-mcp/index.js"]
+    }
+  }
+}
+```
+
+---
+
+## 💻 3. VS Code (Copilot / Cline / Roo Code)
+VS Code does not yet support MCP natively in Copilot, but powerful extensions do.
+
+### For Cline (Claude Dev) or Roo Code:
+1. Open the extension settings.
+2. Look for the **"MCP Servers"** section.
+3. Add a configuration similar to Claude Desktop.
+4. The AI can now create and run your test suites directly from the VS Code chat!
+
+---
+
+## 🚀 4. Cursor IDE
+Cursor is one of the most advanced IDEs with MCP support.
+
+1. Go to **Settings > Features > MCP**.
+2. Click **"+ Add Server"**.
+3. **Name**: `SMS-Engine`.
+4. **Type**: `command`.
+5. **Command**: `node C:/path/to/index.js`.
+6. This will enable `execute_suite` and other tools within the Cursor "Composer".
+
+---
+
+## 🧠 Security Notes
+- Always use **absolute paths** in IDE configurations.
+- Ensure the server has no interactive prompts (keyboard inputs), as the AI won't be able to respond to them via MCP (always use `--yes` or similar flags).

package/README.md

@@ -0,0 +1,41 @@
+# 🚀 MCP State Machine Test Framework (SMS)
+
+The high-fidelity, autonomous orchestration engine for Next-Generation E2E Testing.
+
+## 🌟 Key Features
+- **Pure-MCP Architecture**: 100% compliant with the Model Context Protocol for seamless AI agent integration.
+- **Universal**: Supports Web, Mobile, and API testing through modular MCP tool aggregation.
+- **Secure by Design**: Automatic masking of sensitive data (tokens, JWTs) in reports and logs.
+- **Premium Reporting**: Generates high-fidelity HTML/JSON dashboards with glassmorphism aesthetics.
+- **Data-Driven Core**: Native support for complex testing scenarios via CSV and JSON data injection.
+
+## 🛠️ Quick Installation
+
+You can install it as a dependency in your project:
+
+```bash
+npm install mcp-state-machine-test-framework
+```
+
+Or run it directly via MCP in your configuration:
+
+```json
+"mcp-sms": {
+  "command": "npx",
+  "args": ["mcp-state-machine-test-framework"]
+}
+```
+
+## 🏁 Basic Workflow
+1. **Initialize Maps**: Create a state map in `/maps`.
+2. **Define Test Cases**: Create modular steps in `/test_cases`.
+3. **Assemble Suite**: Group cases in `/suites`.
+4. **Execute**: Call the `execute_suite` tool from your AI agent or orchestrator.
+
+## 📚 Technical Documentation
+- [🧠 Technical Protocol & History](./SMS_Protocol.md)
+- [📱 Perfecto Mobile Cloud Setup](./DOCUMENTATION/Perfecto_Setup.md)
+- [🤖 Agent Guidelines](./agent_protocol.md)
+
+---
+*Developed with ❤️ for maximum automation efficiency.*

package/SMS_Protocol.md

@@ -0,0 +1,41 @@
+# 🧠 Historial Técnico y Protocolo: SMS MCP Server
+
+Este documento registra el aprendizaje evolutivo sobre el uso del **State Machine Server (SMS)** y su integración con otros servidores MCP (ej. `wdio-mcp`). **No contiene lógica de negocio**, sino maestría técnica.
+
+## 🛠️ Integración con WDIO-MCP (Aprendizajes Clave)
+
+### 1. Gestión de Capacidades (Mobile Cloud)
+- **Timeouts**: En entornos cloud (Perfecto), las sesiones tardan en inicializarse. Es vital usar `timeout: 30000` en acciones críticas de navegación.
+- **Capabilities Estables**: Para Android en Perfecto, el set mínimo estable es:
+    - `automationName: "UiAutomator2"`
+    - `useVirtualDevice: true`
+    - `app: "PRIVATE:NombreDeLaApp.apk"`
+- **Ciclo de Sesión**: Es preferible cerrar y abrir sesiones entre suites independientes para evitar colisiones de estado en el driver.
+
+### 2. Estrategias de Selectores en MCP
+- **Prioridad de Accesibilidad**: Siempre intentar primero `~ID_Accesibilidad`. Es el método más rápido y compatible con MCP.
+- **XPaths Robustos**: Cuando no hay IDs, usar `//*[@resource-id='com.id.app:id/elemento']//android.widget.EditText`. La doble barra `//` ayuda a mitigar cambios menores en la jerarquía.
+- **Scroll Automático**: Para elementos fuera de vista, usar el selector nativo de Android: `android=new UiScrollable(new UiSelector().scrollable(true)).scrollIntoView(new UiSelector().resourceId("..."))`.
+
+### 3. Autenticación y Credenciales
+- **Estrategia de Descubrimiento**: Si las variables de entorno están vacías, rastrear archivos de "scratch" o scripts de verificación (`verify_*.js`) donde el usuario suele dejar tokens hardcodeados para pruebas rápidas.
+- **Formato Perfecto**: El token debe inyectarse en `perfecto:options` -> `securityToken`.
+
+## ⚙️ Arquitectura del Servidor SMS
+
+### 1. Protocolo de Comunicación "Pure MCP"
+- **STDOUT Protegido**: Nunca usar `console.log` para depuración. Cualquier salida no-JSON rompe la conexión. Usar `process.stderr.write` o volcar a un archivo de log externo.
+- **Resolución de Rutas**: Los servidores MCP se lanzan desde contextos variables. Siempre usar `path.join(__dirname, ...)` para localizar mapas, casos y suites.
+
+### 2. Motor de Reportes y Evidencia
+- **Agregación de Resultados**: El servidor SMS itera sobre el array `content` de las respuestas MCP. Captura automáticamente:
+    - `type: "image"` -> Se convierte en miniatura visual.
+    - `type: "text"` -> Se guarda como log técnico expandible.
+- **Interpolación Dinámica**: Soporte para `{{variable}}` en las acciones, permitiendo inyectar datos de archivos CSV/JSON en tiempo de ejecución.
+
+## 🔄 Formatos de Ejecución
+- **Tool Principal**: `execute_suite({ "name": "Nombre_Suite" })`.
+- **Estructura Modular**: Suite -> Test Cases -> Steps -> Actions. Esta jerarquía garantiza que los reportes sean legibles y la evidencia se asocie correctamente a cada paso lógico.
+
+---
+*Documento en evolución constante. Agregue nuevos aprendizajes técnicos aquí.*

package/agent_protocol.md

@@ -0,0 +1,24 @@
+# 🤖 SMS Agent Protocol V12.3 (Multi-Project Edition)
+
+This document defines the rules for AI Agents. The framework now supports multiple isolated state maps.
+
+## 🎯 Your Mission
+Act as a Senior Automation Architect. You are responsible for maintaining the integrity of multiple test environments (Web, Mobile, API).
+
+## 🏗️ Multi-Project Laws
+
+### 1. Map Isolation
+- **Context Awareness**: Before modeling or creating nodes, you MUST identify which map you are working on (e.g., `maps/web_map.json` or `maps/mobile_map.json`).
+- **Prefixing**: Although maps are separate files, continue using prefixes (`web_`, `mob_`) for absolute clarity in logs and reports.
+- **Project Switching**: If you change from a Web task to a Mobile task, explicitly state: *"Switching context to [Map Name]"*.
+
+### 2. Pre-flight Integrity
+- **Validation First**: Before suggesting a suite execution, verify that the `state_map` property is defined in the Suite JSON and that the file exists in the `maps/` directory.
+- **Mismatch Prevention**: Never mix nodes from different maps in the same Suite unless it is a documented Hybrid flow.
+
+## 📡 Technical Governance
+- **Orchestrator Integrity**: `index.js` V12.3 includes a validation layer. If an "Integrity Check Failed" error occurs, analyze the mismatch between the Suite and the Map file.
+- **Path Standard**: All state maps MUST reside in the `maps/` directory.
+
+---
+*The SMS framework is now a multi-tenant orchestration engine. Handle each project with its own context.*

package/config.json

@@ -0,0 +1,14 @@
+{
+  "activeEnv": "QA",
+  "environments": {
+    "QA": {
+      "baseUrl": "https://www.advantageonlineshopping.com",
+      "apiUrl": "https://www.advantageonlineshopping.com/catalog/api/v1"
+    },
+    "PROD": {
+      "baseUrl": "https://www.advantageonlineshopping.com",
+      "apiUrl": "https://www.advantageonlineshopping.com/catalog/api/v1"
+    }
+  },
+  "globalRetries": 1
+}

package/data/mob_users.csv

@@ -0,0 +1,2 @@
+user,pass
+admin,Password123

package/index.js

@@ -0,0 +1,335 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { z } from "zod";
+import fs from "fs/promises";
+import fsSync from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import { exec } from "child_process";
+import { promisify } from "util";
+
+const execAsync = promisify(exec);
+
+async function log(msg) {
+    const time = new Date().toISOString();
+    const line = `[${time}] ${msg}\n`;
+    await fs.appendFile("sms_server.log", line);
+}
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const DB_FILE = path.join(__dirname, "maquina_db.json");
+const SUITES_DIR = path.join(__dirname, "suites");
+const CASOS_DIR = path.join(__dirname, "test_cases");
+const REPORTS_ROOT = path.join(__dirname, "reports");
+const CONFIG_FILE = path.join(__dirname, "mcp_config.json");
+
+export class MaquinaDeEstados {
+    constructor() {
+        this.nodos = new Map();
+        this.casosPrueba = new Map();
+        this.suites = new Map();
+        this.mcpClients = new Map();
+    }
+
+    async cargar() {
+        for (const dir of [CASOS_DIR, SUITES_DIR]) {
+            if (!fsSync.existsSync(dir)) await fs.mkdir(dir, { recursive: true });
+            const files = await fs.readdir(dir);
+            for (const f of files) {
+                if (f.endsWith(".json")) {
+                    const content = JSON.parse(await fs.readFile(path.join(dir, f), "utf-8"));
+                    if (dir === CASOS_DIR) this.casosPrueba.set(content.name, content);
+                    else this.suites.set(content.name, content);
+                }
+            }
+        }
+    }
+
+    async getMcpClient(serverName) {
+        if (this.mcpClients.has(serverName)) return this.mcpClients.get(serverName);
+        const configRaw = await fs.readFile(CONFIG_FILE, "utf-8");
+        const config = JSON.parse(configRaw).mcpServers[serverName];
+        if (!config) throw new Error(`Configuración no encontrada para ${serverName}`);
+        const transport = new StdioClientTransport({
+            command: config.command,
+            args: config.args || [],
+            env: { ...process.env, ...config.env }
+        });
+        const client = new Client({ name: "SMS-Client", version: "11.1.0" }, { capabilities: {} });
+        await client.connect(transport);
+        const data = { client, transport };
+        this.mcpClients.set(serverName, data);
+        return data;
+    }
+
+    interpolate(text, data) {
+        if (!data) return text;
+        let result = text;
+        for (const key in data) {
+            result = result.replace(new RegExp(`{{${key}}}`, 'g'), data[key]);
+        }
+        return result;
+    }
+
+    async loadExternalData(dataPath) {
+        const fullPath = path.isAbsolute(dataPath) ? dataPath : path.join(__dirname, dataPath);
+        if (!fsSync.existsSync(fullPath)) return null;
+        
+        const content = await fs.readFile(fullPath, "utf-8");
+        if (fullPath.endsWith(".json")) return JSON.parse(content);
+        
+        if (fullPath.endsWith(".csv")) {
+            const lines = content.split("\n").map(l => l.trim()).filter(l => l.length > 0);
+            if (lines.length < 2) return [];
+            const headers = lines[0].split(",").map(h => h.trim().replace(/^["']|["']$/g, ""));
+            return lines.slice(1).map(line => {
+                const values = line.split(",");
+                const obj = {};
+                headers.forEach((h, i) => {
+                    let val = values[i] ? values[i].trim() : "";
+                    // Quitar comillas si existen
+                    val = val.replace(/^["']|["']$/g, "");
+                    obj[h] = val;
+                });
+                return obj;
+            });
+        }
+        return null;
+    }
+
+    async ejecutarSuite(suiteName) {
+        const suite = this.suites.get(suiteName);
+        if (!suite) throw new Error(`Suite '${suiteName}' no encontrada.`);
+        
+        if (suite.state_map) {
+            process.stderr.write(`\n📍 [V12.3] Pre-flight Integrity Check for: ${suite.state_map}\n`);
+            // Simplified validation: Ensure the file exists and has the required structure
+            const mapPath = path.join(__dirname, 'maps', suite.state_map);
+            try {
+                await fs.access(mapPath);
+                const mapData = JSON.parse(await fs.readFile(mapPath, 'utf8'));
+                const nodes = mapData.nodos || mapData;
+                process.stderr.write(`✅ Map validated (${Object.keys(nodes).length} nodes found).\n`);
+            } catch (e) {
+                process.stderr.write(`❌ CRITICAL: State Map '${suite.state_map}' not found or invalid!\n`);
+                throw new Error(`Integrity Check Failed: ${e.message}`);
+            }
+        }
+
+        const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+        const reportDir = path.join(REPORTS_ROOT, `exec_${suiteName}_${timestamp}`);
+        await fs.mkdir(reportDir, { recursive: true });
+        const results = { suiteName, timestamp, cases: [], hooks: { beforeSuite: [], afterSuite: [] } };
+
+        const maskSecrets = (text) => {
+            if (typeof text !== "string") return text;
+            // Enmascarar tokens de seguridad y JWTs
+            return text.replace(/("securityToken"\s*:\s*")[^"]+(")/g, '$1********$2')
+                       .replace(/("token"\s*:\s*")[^"]+(")/g, '$1********$2')
+                       .replace(/eyJhbGciOi[A-Za-z0-9-_=]+\.[A-Za-z0-9-_=]+\.?[A-Za-z0-9-_.+/=]*/g, '********[JWT_MASKED]********');
+        };
+
+        const runActions = async (actions, targetRes, data) => {
+            if (!actions) return;
+            for (const action of actions) {
+                const maskedAction = maskSecrets(action);
+                process.stderr.write(`[EXEC] Running action: ${maskedAction}\n`);
+                const actionRes = { action: maskedAction, status: "passed" };
+                targetRes.push(actionRes);
+                try {
+                    let lastResult = null;
+                    const executeAction = async (act) => {
+                        const subRes = (act === action) ? actionRes : { action: act, status: "passed" };
+                        if (act !== action) targetRes.push(subRes);
+                        
+                        let finalAction = act;
+                        try {
+                            if (act.startsWith("transicion:")) {
+                                const transName = act.replace("transicion:", "").trim();
+                                const mapPath = path.join(__dirname, 'maps', suite.state_map);
+                                const mapData = JSON.parse(await fs.readFile(mapPath, 'utf8'));
+                                const nodes = mapData.nodos || mapData;
+                                
+                                let foundAction = null;
+                                for (const node of Object.values(nodes)) {
+                                    if (node.transiciones && node.transiciones[transName]) {
+                                        foundAction = node.transiciones[transName].accion;
+                                        break;
+                                    }
+                                }
+                                if (!foundAction) throw new Error(`Transición '${transName}' no encontrada en el mapa '${suite.state_map}'`);
+                                finalAction = foundAction;
+                            }
+
+                            if (Array.isArray(finalAction)) {
+                                for (const subAct of finalAction) {
+                                    await executeAction(subAct);
+                                }
+                                return;
+                            }
+
+                            const interpolatedAction = this.interpolate(finalAction, data);
+
+                            if (interpolatedAction.startsWith("sh:")) {
+                                subRes.output = (await execAsync(interpolatedAction.replace("sh:", ""))).stdout;
+                            } else if (interpolatedAction.startsWith("mcp:")) {
+                                const raw = interpolatedAction.replace("mcp:", "").trim();
+                                const slashIndex = raw.indexOf("/");
+                                const serverName = raw.substring(0, slashIndex);
+                                const rest = raw.substring(slashIndex + 1);
+                                const spaceIndex = rest.indexOf(" ");
+                                const toolName = spaceIndex === -1 ? rest : rest.substring(0, spaceIndex);
+                                const toolArgs = JSON.parse(spaceIndex === -1 ? "{}" : rest.substring(spaceIndex + 1));
+
+                                const { client } = await this.getMcpClient(serverName);
+                                lastResult = await client.callTool({ name: toolName, arguments: toolArgs }, undefined, { timeout: 600000 });
+                                
+                                if (lastResult.isError && toolName !== "close_session") {
+                                    throw new Error(lastResult.content?.[0]?.text || "Error desconocido en herramienta MCP");
+                                }
+                                
+                                if (lastResult.content) {
+                                     for (const item of lastResult.content) {
+                                         if (item.text) {
+                                             subRes.output = (subRes.output || "") + "\n" + maskSecrets(item.text);
+                                         }
+                                     }
+                                 }
+
+                                if (lastResult.content) {
+                                    let base64 = "";
+                                    for (const item of lastResult.content) {
+                                        if (item.type === "image") base64 = item.data;
+                                        else if (item.text && (item.text.startsWith("iVBOR") || item.text.length > 5000)) base64 = item.text;
+                                    }
+                                    if (base64) {
+                                        subRes.image = base64.startsWith("data:") ? base64 : `data:image/png;base64,${base64}`;
+                                        subRes.output = (subRes.output || "") + "\nEvidencia visual capturada.";
+                                    }
+                                }
+                            }
+                        } catch (e) {
+                            subRes.status = "failed";
+                            subRes.error = e.message;
+                            throw e;
+                        }
+                    };
+
+                    await executeAction(action);
+                } catch (e) {
+                    actionRes.status = "failed";
+                    actionRes.error = e.message;
+                    throw e;
+                }
+            }
+        };
+
+        try {
+            await runActions(suite.beforeSuite, results.hooks.beforeSuite);
+            for (const caseName of suite.tests) {
+                const testCase = this.casosPrueba.get(caseName);
+                if (!testCase) continue;
+                
+                let dataRows = [null];
+                if (testCase.data) {
+                    if (Array.isArray(testCase.data)) dataRows = testCase.data;
+                    else if (typeof testCase.data === "string") dataRows = await this.loadExternalData(testCase.data) || [null];
+                }
+                
+                for (let i = 0; i < dataRows.length; i++) {
+                    const row = dataRows[i];
+                    const suffix = row ? ` [Iteration ${i+1}]` : "";
+                    const caseRes = { name: testCase.name + suffix, steps: [], status: "passed", hooks: { beforeCase: [], afterCase: [] } };
+                    results.cases.push(caseRes);
+                    
+                    try {
+                        await runActions(suite.beforeCase, caseRes.hooks.beforeCase, row);
+                        for (const step of testCase.steps) {
+                            const stepRes = { name: step.name, actions: [], status: "passed" };
+                            caseRes.steps.push(stepRes);
+                            try {
+                                await runActions(suite.beforeStep, stepRes.actions, row);
+                                await runActions(step.actions, stepRes.actions, row);
+                            } catch (e) {
+                                stepRes.status = "failed";
+                                stepRes.error = e.message;
+                                throw e;
+                            } finally {
+                                await runActions(suite.afterStep, stepRes.actions, row);
+                            }
+                        }
+                        await runActions(suite.afterCase, caseRes.hooks.afterCase, row);
+                    } catch (e) { caseRes.status = "failed"; caseRes.error = e.message; }
+                }
+            }
+            await runActions(suite.afterSuite, results.hooks.afterSuite);
+        } finally {
+            for (const { transport } of this.mcpClients.values()) await transport.close();
+            this.mcpClients.clear();
+            await this.finalizarReporte(reportDir, results);
+        }
+        return reportDir;
+    }
+
+    async finalizarReporte(dir, data) {
+        const renderActions = (actions) => actions.map(a => `
+            <div style="margin-top:15px; border-bottom: 1px solid #1e293b; padding-bottom: 15px;">
+                <div style="display:flex; justify-content:space-between; align-items:center;">
+                    <code style="color: #60a5fa; font-weight:bold;">${a.action}</code>
+                    <span style="font-size:0.7em; padding:2px 8px; border-radius:10px; background:${a.status === 'passed' ? '#065f46' : '#991b1b'}; color:white;">${a.status}</span>
+                </div>
+                ${a.image ? `<div style="margin-top:15px; text-align:center;"><img src="${a.image}" style="max-width:100%; border-radius:12px; box-shadow: 0 10px 30px rgba(0,0,0,0.5); border: 1px solid #334155;"></div>` : ""}
+                ${a.output ? `
+                    <details style="margin-top:10px;">
+                        <summary style="cursor:pointer; color:#64748b; font-size:0.8em; outline:none;">View technical logs</summary>
+                        <pre style="background:#020617; padding:15px; border-radius:8px; font-size:0.85em; color:#10b981; margin-top:10px; border:1px solid #1e293b; overflow-x:auto;">${a.output}</pre>
+                    </details>` : ""}
+                ${a.error ? `<pre style="background:#450a0a; padding:15px; border-radius:8px; font-size:0.85em; color:#fca5a5; margin-top:10px;">${a.error}</pre>` : ""}
+            </div>
+        `).join("");
+
+        const html = `<!DOCTYPE html><html lang="es"><head><meta charset="UTF-8"><title>SMS Dashboard V11.1 CSV-Ready</title>
+            <style>
+                @import url('https://fonts.googleapis.com/css2?family=Outfit:wght@300;400;600;800&display=swap');
+                body { font-family: 'Outfit', sans-serif; background: #020617; color: #f8fafc; padding: 60px; line-height: 1.6; }
+                .container { max-width: 1000px; margin: 0 auto; }
+                .card { background: #0f172a; border: 1px solid #1e293b; border-radius: 20px; padding: 40px; margin-bottom: 30px; box-shadow: 0 20px 50px rgba(0,0,0,0.3); }
+                .hook-label { background: #3b82f6; color: white; font-size: 0.7em; font-weight: 800; padding: 5px 12px; border-radius: 50px; text-transform: uppercase; margin-bottom: 15px; display: inline-block; letter-spacing: 1px; }
+                h1 { font-size: 3.5em; font-weight: 800; background: linear-gradient(to right, #60a5fa, #a855f7); -webkit-background-clip: text; -webkit-text-fill-color: transparent; margin-bottom: 0.2em; }
+                .step { border-left: 3px solid #3b82f6; padding-left: 30px; margin: 40px 0; }
+                h2 { font-size: 2em; margin-bottom: 1em; color: #f1f5f9; }
+                h3 { color: #94a3b8; font-weight: 400; text-transform: uppercase; font-size: 0.9em; letter-spacing: 2px; }
+            </style></head>
+        <body><div class="container">
+            <h1>SMS Dashboard</h1>
+            <p style="color: #64748b; font-size: 1.1em; margin-bottom: 40px;">Universal Data-Driven Framework • V11.2</p>
+            ${data.hooks.beforeSuite.length ? `<div class="card"><span class="hook-label">Global Setup</span>${renderActions(data.hooks.beforeSuite)}</div>` : ""}
+            ${data.cases.map(c => `
+                <div class="card">
+                    <h3 style="color:#60a5fa; margin-bottom:10px;">TEST CASE EXECUTION</h3>
+                    <h2>${c.name}</h2>
+                    ${c.hooks.beforeCase.length ? `<div><span class="hook-label">Pre-Condition</span>${renderActions(c.hooks.beforeCase)}</div>` : ""}
+                    ${c.steps.map(s => `<div class="step"><h3>STEP: ${s.name}</h3>${renderActions(s.actions)}</div>`).join("")}
+                    ${c.hooks.afterCase.length ? `<div><span class="hook-label">Post-Condition</span>${renderActions(c.hooks.afterCase)}</div>` : ""}
+                </div>
+            `).join("")}
+            ${data.hooks.afterSuite.length ? `<div class="card"><span class="hook-label">Global Teardown</span>${renderActions(data.hooks.afterSuite)}</div>` : ""}
+        </div></body></html>`;
+        await fs.writeFile(path.join(dir, "index.html"), html);
+        await fs.writeFile(path.join(dir, "results.json"), JSON.stringify(data, null, 2));
+    }
+}
+
+const maquina = new MaquinaDeEstados();
+const server = new McpServer({ name: "demo-state-machine", version: "11.1.0" });
+server.tool("execute_suite", "Ejecución External Data", { name: z.string() }, async ({ name }) => {
+    await maquina.cargar();
+    const dir = await maquina.ejecutarSuite(name);
+    return { content: [{ type: "text", text: `Reporte: ${dir}` }] };
+});
+async function main() { await maquina.cargar(); const transport = new StdioServerTransport(); await server.connect(transport); }
+main().catch(console.error);

package/maquina_db.json

@@ -0,0 +1 @@
+{"nodoActual": "home_page", "nodos": {}}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "mcp-state-machine-test-framework",
+  "version": "1.0.0",
+  "description": "High-fidelity State Machine MCP Server for autonomous E2E testing orchestration.",
+  "main": "index.js",
+  "type": "module",
+  "bin": {
+    "mcp-sms": "index.js"
+  },
+  "scripts": {
+    "start": "node index.js"
+  },
+  "keywords": [
+    "mcp",
+    "state-machine",
+    "testing",
+    "automation",
+    "webdriverio",
+    "agentic-ai"
+  ],
+  "author": "SDET Cloud Team",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^3.22.4",
+    "webdriverio": "^8.32.0"
+  }
+}

package/status_check.json

@@ -0,0 +1 @@
+'{"status": "online"}'