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

package/README.md

@@ -27,10 +27,13 @@ Or run it directly via MCP in your configuration:
 ```
 
 ## 🏁 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.
+1. **Initialize Project**: Run `init_project` to setup folders and templates.
+2. **Guided Design**: Tell the agent to "Create a new node". The agent will ask for the mandatory fields (Map, Node Name, Transitions) before executing.
+3. **Automatic Visualization**: Every map change regenerates a Mermaid diagram in `/maps`.
+4. **Execution**: Run `execute_suite` to launch the automated flow.
+
+## 🤖 AI Agent Interaction (Guided Design)
+This framework enforces a "Strict Contract" via MCP tools. Agents are instructed NOT to edit JSON files directly, but to use the management tools (`upsert_node`, `save_test_case`, `save_suite`) which provide validation and structure.
 
 ## 📚 Technical Documentation
 - [🧠 Technical Protocol & History](./SMS_Protocol.md)

package/index.js

@@ -326,16 +326,20 @@ 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 de Suite Completa", { name: z.string() }, async ({ name }) => {
+server.tool("execute_suite", "Ejecución de Suite Completa", { 
+    name: z.string().describe("Nombre de la suite a ejecutar (ej: 'Suite_Login'). Buscará el archivo en /suites.") 
+}, 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() 
+server.tool("upsert_node", "Añadir o actualizar un nodo en el mapa de estados.", { 
+    mapName: z.string().describe("Nombre del archivo del mapa (ej: 'home_map.json'). El servidor lo buscará en la carpeta /maps."), 
+    nodeName: z.string().describe("Identificador único del nodo (ej: 'LOGIN_PAGE', 'HOME')."), 
+    nodeData: z.object({
+        transiciones: z.any().optional().describe("Objeto que define las salidas del nodo. Ej: { 'IR_A_LOGIN': { 'destino': 'LOGIN_PAGE', 'accion': 'mcp:wdio-mcp/click_element ...' } }")
+    }).passthrough().describe("Datos completos del nodo, incluyendo transiciones y metadatos.") 
 }, async ({ mapName, nodeName, nodeData }) => {
     const mapPath = path.join(__dirname, 'maps', mapName);
     let map = { nodos: {} };
@@ -401,9 +405,12 @@ server.tool("inspect_framework", "Inspeccionar integridad y listar entidades del
     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()) 
+server.tool("save_test_case", "Crear o actualizar un caso de prueba.", { 
+    name: z.string().describe("Nombre identificador del test (ej: 'TC_Login_Exitoso')."), 
+    steps: z.array(z.object({
+        name: z.string().optional().describe("Descripción amigable del paso (ej: 'Ingresar Usuario')."),
+        action: z.string().optional().describe("Acción a realizar. Puede ser un nombre de transición del mapa o un comando mcp:wdio-mcp/...")
+    }).passthrough()).describe("Lista ordenada de pasos lógicos a ejecutar.") 
 }, async ({ name, steps }) => {
     const fileName = name.endsWith('.json') ? name : `${name}.json`;
     const filePath = path.join(__dirname, 'test_cases', fileName);
@@ -413,12 +420,12 @@ server.tool("save_test_case", "Crear o actualizar un caso de prueba", {
     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()))
+server.tool("save_suite", "Crear o actualizar una suite de pruebas.", { 
+    name: z.string().describe("Nombre de la suite (ej: 'Suite_E2E_Sanity')."), 
+    state_map: z.string().describe("Archivo del mapa de estados a usar (ej: 'mob_perfecto_map.json')."),
+    tests: z.array(z.string()).describe("Lista de nombres de casos de prueba a incluir en la suite."),
+    beforeSuite: z.array(z.string()).optional().default([]).describe("Acciones globales antes de la suite (ej: iniciar sesión)."),
+    afterSuite: z.array(z.string()).optional().default([]).describe("Acciones globales tras la suite (ej: cerrar sesión).")
 }, async ({ name, state_map, tests, beforeSuite, afterSuite }) => {
     const fileName = name.endsWith('.json') ? name : `${name}.json`;
     const filePath = path.join(__dirname, 'suites', fileName);
@@ -428,5 +435,76 @@ server.tool("save_suite", "Crear o actualizar una suite de pruebas", {
     return { content: [{ type: "text", text: `Suite '${name}' guardada correctamente.` }] };
 });
 
-async function main() { await maquina.cargar(); const transport = new StdioServerTransport(); await server.connect(transport); }
+server.tool("init_project", "Inicializa el proyecto con carpetas y archivos de plantilla", { 
+    force: z.optional(z.boolean()).default(false) 
+}, async ({ force }) => {
+    await ensureDirectories();
+    
+    const templates = {
+        'maps/template_map.json': {
+            nodos: {
+                HOME: {
+                    transiciones: {
+                        IR_A_LOGIN: { destino: "LOGIN", accion: "mcp:wdio-mcp/click_element { \"selector\": \"~Login\" }" }
+                    }
+                },
+                LOGIN: {
+                    transiciones: {
+                        VOLVER: { destino: "HOME", accion: "mcp:wdio-mcp/click_element { \"selector\": \"~Back\" }" }
+                    }
+                }
+            }
+        },
+        'test_cases/template_case.json': {
+            name: "Template Case",
+            steps: [
+                { name: "Ir a Login", action: "IR_A_LOGIN" },
+                { name: "Verificar Pantalla", action: "mcp:wdio-mcp/get_screenshot {}" }
+            ]
+        },
+        'suites/template_suite.json': {
+            name: "Template Suite",
+            state_map: "template_map.json",
+            tests: ["template_case"],
+            beforeSuite: ["mcp:wdio-mcp/start_session { \"platform\": \"android\", \"provider\": \"perfecto\" }"],
+            afterSuite: ["mcp:wdio-mcp/close_session {}"]
+        }
+    };
+
+    for (const [relPath, content] of Object.entries(templates)) {
+        const fullPath = path.join(__dirname, relPath);
+        try {
+            if (!force) {
+                try {
+                    await fs.access(fullPath);
+                    continue; // Skip if exists
+                } catch (e) {}
+            }
+            await fs.writeFile(fullPath, JSON.stringify(content, null, 2));
+        } catch (e) {
+            process.stderr.write(`[WARN] Error creando template ${relPath}: ${e.message}\n`);
+        }
+    }
+
+    return { content: [{ type: "text", text: "✅ Proyecto inicializado. Se han creado las carpetas y los archivos de plantilla (templates) para guiar al agente." }] };
+});
+
+async function ensureDirectories() {
+    const dirs = ['maps', 'suites', 'test_cases', 'reports', 'data'];
+    for (const dir of dirs) {
+        const dirPath = path.join(__dirname, dir);
+        try {
+            await fs.mkdir(dirPath, { recursive: true });
+        } catch (e) {
+            process.stderr.write(`[WARN] Error creando directorio ${dir}: ${e.message}\n`);
+        }
+    }
+}
+
+async function main() { 
+    await ensureDirectories();
+    await maquina.cargar(); 
+    const transport = new StdioServerTransport(); 
+    await server.connect(transport); 
+}
 main().catch(console.error);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-state-machine-test-framework",
-  "version": "1.0.5",
+  "version": "1.0.8",
   "description": "High-fidelity State Machine MCP Server for autonomous E2E testing orchestration.",
   "main": "index.js",
   "type": "module",