mcp-state-machine-test-framework 1.0.0 → 1.0.5

package/SMS_Protocol.md

@@ -37,5 +37,13 @@ Este documento registra el aprendizaje evolutivo sobre el uso del **State Machin
 - **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.
 
+## 🛠️ Herramientas de Gestión (Management Tools)
+
+A partir de la versión 1.0.1, el servidor incluye herramientas para la construcción estructurada del framework:
+
+- **`upsert_node`**: Garantiza la integridad del mapa de estados. Valida que cada nodo tenga sus transiciones correctamente definidas.
+- **`save_test_case`**: Normaliza la creación de pasos de prueba, asegurando que la jerarquía Suite -> Case -> Step se mantenga para el generador de reportes.
+- **`save_suite`**: Orquesta el ensamblaje final, permitiendo la inyección de hooks (`before/afterSuite`) que son críticos para la gestión de sesiones en la nube.
+
 ---
 *Documento en evolución constante. Agregue nuevos aprendizajes técnicos aquí.*

package/agent_protocol.md

@@ -1,24 +1,24 @@
-# 🤖 SMS Agent Protocol V12.3 (Multi-Project Edition)
+# 🤖 Protocolo de Operación del Agente: SMS Framework
 
-This document defines the rules for AI Agents. The framework now supports multiple isolated state maps.
+Este protocolo es de **obligado cumplimiento** para cualquier agente que opere el MCP State Machine Test Framework.
 
-## 🎯 Your Mission
-Act as a Senior Automation Architect. You are responsible for maintaining the integrity of multiple test environments (Web, Mobile, API).
+## ⚖️ Reglas de Construcción de Pruebas
 
-## 🏗️ Multi-Project Laws
+### 1. Gestión de Mapas y Estados
+- **PROHIBIDO**: Crear o editar archivos en `/maps` usando herramientas genéricas de escritura de archivos.
+- **MANDATORIO**: Usar la herramienta `upsert_node` para añadir o modificar nodos. Esto asegura que la estructura de transiciones y acciones sea válida para el motor de ejecución.
 
-### 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. Definición de Casos de Prueba
+- **MANDATORIO**: Usar `save_test_case`. El agente debe definir los `steps` como un array de objetos, asegurando que cada paso tenga un nombre descriptivo para el reporte final.
 
-### 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.
+### 3. Ensamblaje de Suites
+- **MANDATORIO**: Usar `save_suite`. El agente debe verificar que el `state_map` referenciado exista antes de guardar la suite.
 
-## 📡 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.
+## 🔄 Flujo de Trabajo Autónomo (Discovery-to-Code)
+1. **Explorar**: Usar `wdio-mcp/get_elements` para identificar selectores.
+2. **Registrar**: Inmediatamente usar `upsert_node` para añadir el hallazgo al mapa de estados.
+3. **Validar**: Ejecutar un `save_test_case` rápido para confirmar que la nueva transición funciona.
+4. **Reportar**: Usar `execute_suite` para generar la evidencia visual del nuevo flujo descubierto.
 
 ---
-*The SMS framework is now a multi-tenant orchestration engine. Handle each project with its own context.*
+*V1.1 - Protocolo de Integridad Estructural*

package/index.js

@@ -326,10 +326,107 @@ export class MaquinaDeEstados {
 
 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 }) => {
+server.tool("execute_suite", "Ejecución de Suite Completa", { name: z.string() }, async ({ name }) => {
     await maquina.cargar();
     const dir = await maquina.ejecutarSuite(name);
     return { content: [{ type: "text", text: `Reporte: ${dir}` }] };
 });
+
+server.tool("upsert_node", "Añadir o actualizar un nodo en el mapa de estados", { 
+    mapName: z.string(), 
+    nodeName: z.string(), 
+    nodeData: z.any() 
+}, async ({ mapName, nodeName, nodeData }) => {
+    const mapPath = path.join(__dirname, 'maps', mapName);
+    let map = { nodos: {} };
+    try {
+        const content = await fs.readFile(mapPath, 'utf8');
+        map = JSON.parse(content);
+        if (!map.nodos) map = { nodos: map };
+    } catch (e) {}
+    
+    map.nodos[nodeName] = nodeData;
+    await fs.mkdir(path.dirname(mapPath), { recursive: true });
+    await fs.writeFile(mapPath, JSON.stringify(map, null, 2));
+
+    // Generar/Actualizar Diagrama Mermaid
+    try {
+        let mermaid = "graph TD\n";
+        for (const [name, node] of Object.entries(map.nodos)) {
+            if (node.transiciones) {
+                for (const [transName, trans] of Object.entries(node.transiciones)) {
+                    mermaid += `  ${name} -- "${transName}" --> ${trans.destino}\n`;
+                }
+            }
+        }
+        const mermaidPath = mapPath.replace('.json', '.md');
+        await fs.writeFile(mermaidPath, `# 🗺️ Diagrama de Estados: ${mapName}\n\n\`\`\`mermaid\n${mermaid}\`\`\``);
+    } catch (me) {
+        process.stderr.write(`[WARN] Error generando Mermaid: ${me.message}\n`);
+    }
+
+    return { content: [{ type: "text", text: `Nodo '${nodeName}' actualizado. Diagrama visual regenerado en maps/${mapName.replace('.json', '.md')}` }] };
+});
+
+server.tool("inspect_framework", "Inspeccionar integridad y listar entidades del framework", { 
+    filter: z.optional(z.string()) 
+}, async () => {
+    const entities = { maps: [], test_cases: [], suites: [], health: [] };
+    const getFiles = async (dir) => {
+        try { return (await fs.readdir(path.join(__dirname, dir))).filter(f => f.endsWith('.json')); }
+        catch (e) { return []; }
+    };
+
+    entities.maps = await getFiles('maps');
+    entities.test_cases = await getFiles('test_cases');
+    entities.suites = await getFiles('suites');
+
+    // Validación de integridad simple
+    for (const suiteFile of entities.suites) {
+        try {
+            const suite = JSON.parse(await fs.readFile(path.join(__dirname, 'suites', suiteFile), 'utf8'));
+            if (!entities.maps.includes(suite.state_map)) {
+                entities.health.push(`❌ Suite '${suiteFile}' referencia a mapa inexistente: ${suite.state_map}`);
+            }
+            for (const tc of suite.tests) {
+                if (!entities.test_cases.includes(`${tc}.json`) && !entities.test_cases.includes(tc)) {
+                    entities.health.push(`❌ Suite '${suiteFile}' referencia a test case inexistente: ${tc}`);
+                }
+            }
+        } catch (e) { entities.health.push(`❌ Error leyendo suite '${suiteFile}': ${e.message}`); }
+    }
+
+    if (entities.health.length === 0) entities.health.push("✅ Estructura íntegra. Todos los vínculos son correctos.");
+
+    return { content: [{ type: "text", text: JSON.stringify(entities, null, 2) }] };
+});
+
+server.tool("save_test_case", "Crear o actualizar un caso de prueba", { 
+    name: z.string(), 
+    steps: z.array(z.any()) 
+}, async ({ name, steps }) => {
+    const fileName = name.endsWith('.json') ? name : `${name}.json`;
+    const filePath = path.join(__dirname, 'test_cases', fileName);
+    const testCase = { name: name.replace('.json', ''), steps };
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    await fs.writeFile(filePath, JSON.stringify(testCase, null, 2));
+    return { content: [{ type: "text", text: `Caso de prueba '${name}' guardado correctamente.` }] };
+});
+
+server.tool("save_suite", "Crear o actualizar una suite de pruebas", { 
+    name: z.string(), 
+    state_map: z.string(),
+    tests: z.array(z.string()),
+    beforeSuite: z.optional(z.array(z.string())),
+    afterSuite: z.optional(z.array(z.string()))
+}, async ({ name, state_map, tests, beforeSuite, afterSuite }) => {
+    const fileName = name.endsWith('.json') ? name : `${name}.json`;
+    const filePath = path.join(__dirname, 'suites', fileName);
+    const suite = { name: name.replace('.json', ''), state_map, tests, beforeSuite, afterSuite };
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    await fs.writeFile(filePath, JSON.stringify(suite, null, 2));
+    return { content: [{ type: "text", text: `Suite '${name}' guardada correctamente.` }] };
+});
+
 async function main() { await maquina.cargar(); const transport = new StdioServerTransport(); await server.connect(transport); }
 main().catch(console.error);

package/mcp_cli.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import fs from "fs/promises";
+import path from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+async function run() {
+    const args = process.argv.slice(2);
+    if (args.length < 2) {
+        console.error("Uso: mcp-cli <server-name> <tool-name> [json-args]");
+        process.exit(1);
+    }
+
+    const [serverName, toolName, toolArgsRaw] = args;
+    const toolArgs = toolArgsRaw ? JSON.parse(toolArgsRaw) : {};
+
+    // Cargar config
+    let config;
+    try {
+        const configPath = path.join(process.cwd(), "mcp_config.json");
+        const content = await fs.readFile(configPath, "utf8");
+        config = JSON.parse(content).mcpServers[serverName];
+    } catch (e) {
+        console.error(`❌ No se encontró la configuración para el servidor '${serverName}' en mcp_config.json`);
+        process.exit(1);
+    }
+
+    console.error(`🔌 Conectando a ${serverName}...`);
+    const transport = new StdioClientTransport({
+        command: config.command,
+        args: config.args || [],
+        env: { ...process.env, ...config.env }
+    });
+
+    const client = new Client({ name: "mcp-cli-client", version: "1.0.0" }, { capabilities: {} });
+    await client.connect(transport);
+
+    console.error(`🚀 Ejecutando herramienta: ${toolName}`);
+    try {
+        const result = await client.callTool({ name: toolName, arguments: toolArgs });
+        console.log(JSON.stringify(result, null, 2));
+    } catch (error) {
+        console.error(`❌ Error ejecutando herramienta: ${error.message}`);
+    } finally {
+        process.exit(0);
+    }
+}
+
+run().catch(console.error);

package/new_project_demo/maps/default_map.json

@@ -0,0 +1,20 @@
+{
+  "nodos": {
+    "HOME": {
+      "transiciones": {
+        "IR_A_LOGIN": {
+          "destino": "LOGIN_PAGE",
+          "accion": "mcp:wdio-mcp/click_element { \"selector\": \"~Main Menu\" }"
+        }
+      }
+    },
+    "LOGIN_PAGE": {
+      "transiciones": {
+        "VOLVER": {
+          "destino": "HOME",
+          "accion": "mcp:wdio-mcp/click_element { \"selector\": \"~Back\" }"
+        }
+      }
+    }
+  }
+}