wopee-mcp 1.26.2 → 1.28.0

package/README.md

@@ -290,7 +290,7 @@ Update app context file for the most recent suite with this content: <YourMarkdo
 
 #### `wopee_dispatch_agent`
 
-Dispatches an autonomous testing agent to execute test cases for a selected suite.
+Dispatches an autonomous testing agent to execute test cases for a selected suite. Tests run **asynchronously** (typically 1-3 minutes). This tool confirms dispatch and returns tracking info — not final results.
 
 - **Parameters:**
   - `suiteUuid` - The UUID of the suite containing the test cases
@@ -298,7 +298,7 @@ Dispatches an autonomous testing agent to execute test cases for a selected suit
   - `testCases` - Array of test case objects to execute, each containing:
     - `testCaseId` - The ID of the test case
     - `userStoryId` - The ID of the associated user story
-- **Returns:** Array of executed test case objects with their initial execution state (uuid, executionStatus, agentReportStatus, codeReportStatus, etc.)
+- **Returns:** Dispatch confirmation with tracking info (suite UUID, analysis identifier, per-test-case execution status). Does NOT return pass/fail results — use `wopee_fetch_recent_executions` or `wopee_fetch_executed_test_cases` to check results later.
 
 **Example Usage:**
 
@@ -308,6 +308,23 @@ Dispatch agent for my latest suite's user story US001 and test case TC003
 
 ### Test Results
 
+#### `wopee_fetch_recent_executions`
+
+Fetches the most recent test case executions for the current project (up to 20, newest first). Use this to quickly check the status of recently dispatched tests without needing to remember specific suite UUIDs.
+
+- **Parameters:** None (uses `WOPEE_PROJECT_UUID` from environment)
+- **Returns:** List of recent executions with execution status (IN_PROGRESS, IN_QUEUE, FINISHED, FAILED), agent reports, and pass/fail results
+
+**Example Usage:**
+
+```
+What's the status of my recent test runs?
+```
+
+```
+How did my tests go?
+```
+
 #### `wopee_fetch_executed_test_cases`
 
 Fetches executed test cases and their results for a given analysis suite. Use this to check the status and reports of dispatched agent runs.
@@ -348,7 +365,8 @@ Show me the executed test cases for my latest analysis suite
    - Use `wopee_dispatch_agent` to execute test cases with the autonomous testing agent
 
 5. **Check results:**
-   - Use `wopee_fetch_executed_test_cases` to check the status and reports of dispatched agent runs
+   - Use `wopee_fetch_recent_executions` to quickly check status of recent test runs
+   - Use `wopee_fetch_executed_test_cases` to check detailed status and reports for a specific suite
    - Or use the `fetch-test-results` prompt for a formatted summary of all test results
 
 ## Available Prompts

package/build/tools/index.js

@@ -6,13 +6,19 @@ import { wopeeDispatchAnalysis } from "./wopee_dispatch_analysis/index.js";
 import { wopeeCreateBlankSuite } from "./wopee_create_blank_suite/index.js";
 import { wopeeFetchAnalysisSuites } from "./wopee_fetch_analysis_suites/index.js";
 import { wopeeFetchExecutedTestCases } from "./wopee_fetch_executed_test_cases/index.js";
+import { wopeeFetchRecentExecutions } from "./wopee_fetch_recent_executions/index.js";
 import { wopeeSendChatMessage } from "./wopee_send_chat_message/index.js";
 import { wopeeReadChatHistory } from "./wopee_read_chat_history/index.js";
 import { wopeeCreateGithubIssue } from "./wopee_create_github_issue/index.js";
+import { wopeeFetchVariables } from "./wopee_fetch_variables/index.js";
+import { wopeeUpdateVariables } from "./wopee_update_variables/index.js";
 export const TOOLS = [
     wopeeCreateBlankSuite,
     wopeeFetchAnalysisSuites,
     wopeeFetchExecutedTestCases,
+    wopeeFetchRecentExecutions,
+    wopeeFetchVariables,
+    wopeeUpdateVariables,
     wopeeDispatchAnalysis,
     wopeeDispatchAgent,
     wopeeFetchArtifact,

package/build/tools/shared/gql-queries.js

@@ -13,6 +13,26 @@ export const UpdateArtifact = `
     updateArtifact(input: $input)
   }
 `;
+export const FetchProjectVariables = `
+  query FetchProjectVariables($projectUuid: ID!) {
+    fetchProjectVariables(projectUuid: $projectUuid)
+  }
+`;
+export const FetchSuiteVariables = `
+  query FetchSuiteVariables($suiteUuid: ID!) {
+    fetchSuiteVariables(suiteUuid: $suiteUuid)
+  }
+`;
+export const UpdateProjectVariables = `
+  mutation UpdateProjectVariables($input: UpdateProjectVariablesInput!) {
+    updateProjectVariables(input: $input)
+  }
+`;
+export const UpdateSuiteVariables = `
+  mutation UpdateSuiteVariables($suiteUuid: ID!, $additionalVariables: String!) {
+    updateSuiteVariables(suiteUuid: $suiteUuid, additionalVariables: $additionalVariables)
+  }
+`;
 export const DispatchAgent = `
   mutation DispatchAgent(
     $input: TestCasesInput!
@@ -249,6 +269,25 @@ export const FetchChatRoom = `
     }
   }
 `;
+export const FetchRecentExecutedTestCases = `
+  query FetchRecentExecutedTestCases($projectUuid: ID!) {
+    fetchRecentExecutedTestCases(projectUuid: $projectUuid) {
+      uuid
+      suiteUuid
+      analysisSuiteUuid
+      analysisIdentifier
+      userStoryId
+      testCaseId
+      executionStatus
+      agentReport
+      agentReportStatus
+      codeReport
+      codeReportStatus
+      createdAt
+      updatedAt
+    }
+  }
+`;
 export const CreateGitHubIssue = `
   mutation CreateGitHubIssue($projectUuid: ID!, $title: String!, $body: String!, $labels: [String!]) {
     createGitHubIssue(projectUuid: $projectUuid, title: $title, body: $body, labels: $labels) {

package/build/tools/shared/schemas.js

@@ -14,6 +14,18 @@ export const SuiteAnalysisConfigSchema = z.object({
     additionalInstructions: z.string().nullable().default(null),
     additionalVariables: z.string().nullable().default(null),
 });
+// Shared by wopee_dispatch_analysis and wopee_update_variables. Keys must be
+// uppercase (server enforces the same EnvVarKeyRegex on write).
+export const AdditionalVariableSchema = z.object({
+    key: z
+        .string({
+        description: "Variable name. Must be uppercase with underscores only (e.g. MY_VAR, BASE_URL).",
+    })
+        .regex(/^[A-Z_][A-Z0-9_]*$/, "Key must be uppercase alphanumeric with underscores, starting with a letter or underscore"),
+    value: z
+        .string({ description: "Variable value. Must be a non-empty string." })
+        .min(1, "Value must be a non-empty string"),
+});
 export const GenerateAIDataHandlerInputSchema = z.object({
     type: z.nativeEnum(GenerateArtifactType, {
         description: "Type of test artifact to generate. One of: APP_CONTEXT, GENERAL_USER_STORIES, USER_STORIES_WITH_TEST_CASES, TEST_CASES, TEST_CASE_STEPS, REUSABLE_TEST_CASES, REUSABLE_TEST_CASE_STEPS. Start with APP_CONTEXT, then generate stories and test cases from it.",

package/build/tools/shared/types.js

@@ -3,6 +3,7 @@ export var ToolName;
     ToolName["WOPEE_CREATE_BLANK_SUITE"] = "wopee_create_blank_suite";
     ToolName["WOPEE_FETCH_ANALYSIS_SUITES"] = "wopee_fetch_analysis_suites";
     ToolName["WOPEE_FETCH_EXECUTED_TEST_CASES"] = "wopee_fetch_executed_test_cases";
+    ToolName["WOPEE_FETCH_RECENT_EXECUTIONS"] = "wopee_fetch_recent_executions";
     ToolName["WOPEE_DISPATCH_ANALYSIS"] = "wopee_dispatch_analysis";
     ToolName["WOPEE_DISPATCH_AGENT"] = "wopee_dispatch_agent";
     ToolName["WOPEE_FETCH_ARTIFACT"] = "wopee_fetch_artifact";
@@ -11,7 +12,14 @@ export var ToolName;
     ToolName["WOPEE_SEND_CHAT_MESSAGE"] = "wopee_send_chat_message";
     ToolName["WOPEE_READ_CHAT_HISTORY"] = "wopee_read_chat_history";
     ToolName["WOPEE_CREATE_GITHUB_ISSUE"] = "wopee_create_github_issue";
+    ToolName["WOPEE_FETCH_VARIABLES"] = "wopee_fetch_variables";
+    ToolName["WOPEE_UPDATE_VARIABLES"] = "wopee_update_variables";
 })(ToolName || (ToolName = {}));
+export var VariableLevel;
+(function (VariableLevel) {
+    VariableLevel["PROJECT"] = "PROJECT";
+    VariableLevel["ANALYSIS"] = "ANALYSIS";
+})(VariableLevel || (VariableLevel = {}));
 export var GenerateArtifactType;
 (function (GenerateArtifactType) {
     GenerateArtifactType["APP_CONTEXT"] = "APP_CONTEXT";

package/build/tools/wopee_dispatch_agent/index.js

@@ -5,11 +5,28 @@ import { createDispatchAgentInput } from "./factory.js";
 import { DispatchAgent } from "../shared/gql-queries.js";
 import { requestClient } from "../../utils/requestClient.js";
 import { withRetry } from "../../utils/withRetry.js";
+function formatDispatchSuccess(testCases, input) {
+    const lines = [
+        "DISPATCH SUCCESSFUL — tests are now RUNNING (not yet completed).",
+        "",
+        "Tracking:",
+        `- Suite UUID: ${testCases[0]?.suiteUuid ?? input.suiteUuid}`,
+        `- Analysis Suite UUID: ${testCases[0]?.analysisSuiteUuid ?? "N/A"}`,
+        `- Analysis Identifier: ${testCases[0]?.analysisIdentifier ?? input.analysisIdentifier}`,
+        "",
+        "Test cases dispatched:",
+    ];
+    for (const tc of testCases) {
+        lines.push(`- ${tc.userStoryId}:${tc.testCaseId} → executionStatus: ${tc.executionStatus}`);
+    }
+    lines.push("", "IMPORTANT: These tests are RUNNING asynchronously. Do NOT report them as passed or failed.", "Tell the user their tests are running and results will be available shortly (typically 1-3 minutes).", "You will receive a follow-up notification in chat when tests complete with full results.");
+    return lines.join("\n");
+}
 export const wopeeDispatchAgent = {
     name: ToolName.WOPEE_DISPATCH_AGENT,
     config: {
         title: "Dispatch autonomous testing agent",
-        description: "Execute a specific test case by dispatching an autonomous AI agent. The agent opens a real browser, navigates the web app, follows the test case steps, captures screenshots at each step, and reports pass/fail with detailed findings. Prerequisite: test cases must exist in the suite — generate them first with wopee_generate_artifact (type USER_STORIES_WITH_TEST_CASES). Do NOT use this to analyze or crawl an app — use wopee_dispatch_analysis for that. Side effects: creates execution records and screenshots on the Wopee.io platform. Rate limit: 10 seconds between dispatches per project; concurrent calls auto-retry with exponential backoff. On success, returns executed test case results. On failure (invalid suite/test case ID), returns an error message. Use wopee_fetch_executed_test_cases afterward to get full results.",
+        description: "Dispatch an autonomous AI agent to execute specific test cases. The agent opens a real browser, navigates the app, follows test steps, and reports results. Tests run ASYNCHRONOUSLY (1-3 minutes). This tool returns tracking info confirming dispatch — NOT final results. Do NOT interpret the response as pass/fail. Results arrive later via chat notifications. Prerequisite: test cases must exist in the suite (generate with wopee_generate_artifact type USER_STORIES_WITH_TEST_CASES). Use wopee_fetch_recent_executions or wopee_fetch_executed_test_cases to check status later.",
         inputSchema: WopeeDispatchAgentInputSchema.shape,
     },
     handler: async (input) => {
@@ -24,7 +41,7 @@ export const wopeeDispatchAgent = {
                     content: [
                         {
                             type: "text",
-                            text: "Failed to dispatch agent: no dispatch result returned",
+                            text: "DISPATCH FAILED — tests were NOT started.\nReason: No dispatch result returned from the API.\nSuggest the user try again or check that the suite and test cases exist.",
                         },
                     ],
                 };
@@ -32,12 +49,22 @@ export const wopeeDispatchAgent = {
                 content: [
                     {
                         type: "text",
-                        text: JSON.stringify(result.dispatchAgent, null, 2),
+                        text: formatDispatchSuccess(result.dispatchAgent, input),
                     },
                 ],
             };
         }
         catch (error) {
+            if (error instanceof Error) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `DISPATCH FAILED — tests were NOT started.\nReason: ${error.message}\nThis is a dispatch/infrastructure error, not a test failure. Suggest the user try again.`,
+                        },
+                    ],
+                };
+            }
             return _parseError(error);
         }
     },

package/build/tools/wopee_dispatch_analysis/schema.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { SuiteAnalysisConfigSchema } from "../shared/schemas.js";
+import { SuiteAnalysisConfigSchema, AdditionalVariableSchema, } from "../shared/schemas.js";
 var RerunMode;
 (function (RerunMode) {
     RerunMode["FULL"] = "FULL";
@@ -15,16 +15,6 @@ export const DispatchAnalysisInputSchema = z.object({
     suiteAnalysisConfig: SuiteAnalysisConfigSchema,
     rerun: RerunOptionsSchema.nullable().default(null),
 });
-const AdditionalVariableSchema = z.object({
-    key: z
-        .string({
-        description: "Variable name. Must be uppercase with underscores only (e.g. MY_VAR, BASE_URL).",
-    })
-        .regex(/^[A-Z_][A-Z0-9_]*$/, "Key must be uppercase alphanumeric with underscores, starting with a letter or underscore"),
-    value: z
-        .string({ description: "Variable value. Must be a non-empty string." })
-        .min(1, "Value must be a non-empty string"),
-});
 const WopeeRerunOptionsSchema = z.object({
     suiteUuid: z
         .string({

package/build/tools/wopee_fetch_recent_executions/index.js

@@ -0,0 +1,78 @@
+import { getConfig } from "../../utils/getConfig.js";
+import { requestClient } from "../../utils/requestClient.js";
+import { _parseError } from "../shared/helpers.js";
+import { ToolName } from "../shared/types.js";
+import { FetchRecentExecutedTestCases } from "../shared/gql-queries.js";
+export const wopeeFetchRecentExecutions = {
+    name: ToolName.WOPEE_FETCH_RECENT_EXECUTIONS,
+    config: {
+        title: "Fetch recent test executions",
+        description: "Fetch the most recent test case executions for the current project (up to 20, newest first). Use this to check the status of recently dispatched tests without needing to remember specific suite UUIDs. Returns execution status (IN_PROGRESS, IN_QUEUE, FINISHED, FAILED), agent reports, and pass/fail results. Takes no input; uses WOPEE_PROJECT_UUID from environment. Prefer this tool when the user asks 'what's the status?' or 'how did the tests go?' and you don't have the specific suite UUID handy.",
+    },
+    handler: async () => {
+        try {
+            const { WOPEE_PROJECT_UUID } = getConfig();
+            if (!WOPEE_PROJECT_UUID)
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: "WOPEE_PROJECT_UUID is not set",
+                        },
+                    ],
+                };
+            const result = await requestClient(FetchRecentExecutedTestCases, {
+                projectUuid: WOPEE_PROJECT_UUID,
+            });
+            if (!result?.fetchRecentExecutedTestCases)
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: "No recent test executions found for this project.",
+                        },
+                    ],
+                };
+            const executions = result.fetchRecentExecutedTestCases;
+            if (executions.length === 0)
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: "No recent test executions found for this project.",
+                        },
+                    ],
+                };
+            const lines = [
+                `Recent test executions (${executions.length} most recent):`,
+                "",
+            ];
+            for (const tc of executions) {
+                let status;
+                if (tc.executionStatus === "FINISHED") {
+                    status = tc.agentReportStatus ?? "FINISHED";
+                }
+                else {
+                    status = tc.executionStatus;
+                }
+                lines.push(`- ${tc.userStoryId}:${tc.testCaseId} [${tc.analysisIdentifier}] → ${status} (${tc.updatedAt})`);
+                if (tc.executionStatus === "FINISHED" && tc.agentReport) {
+                    const shortReport = tc.agentReport.slice(0, 200);
+                    lines.push(`  Report: ${shortReport}${tc.agentReport.length > 200 ? "..." : ""}`);
+                }
+            }
+            lines.push("", `Suite UUID of most recent: ${executions[0].suiteUuid}`, `Analysis Identifier of most recent: ${executions[0].analysisIdentifier}`);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: lines.join("\n"),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return _parseError(error);
+        }
+    },
+};

package/build/tools/wopee_fetch_variables/index.js

@@ -0,0 +1,36 @@
+import { getConfig } from "../../utils/getConfig.js";
+import { requestClient } from "../../utils/requestClient.js";
+import { _parseError } from "../shared/helpers.js";
+import { ToolName, VariableLevel } from "../shared/types.js";
+import { FetchProjectVariables, FetchSuiteVariables, } from "../shared/gql-queries.js";
+import { WopeeFetchVariablesInputSchema, } from "./schema.js";
+const textResult = (text) => ({
+    content: [{ type: "text", text }],
+});
+export const wopeeFetchVariables = {
+    name: ToolName.WOPEE_FETCH_VARIABLES,
+    config: {
+        title: "Fetch run-time variables",
+        description: "Read the run-time variables (additionalVariables) that drive analysis/agent runs, at either level. level: PROJECT returns the project-level variables (uses WOPEE_PROJECT_UUID from the environment); level: ANALYSIS returns a specific analysis suite's variables and requires suiteUuid. Read-only. Returns a JSON string array of { key, value, sourceType } entries, or [] when none are set. Use wopee_fetch_analysis_suites to discover suite UUIDs.",
+        inputSchema: WopeeFetchVariablesInputSchema.shape,
+    },
+    handler: async (input) => {
+        try {
+            const { level, suiteUuid } = input;
+            if (level === VariableLevel.ANALYSIS) {
+                if (!suiteUuid)
+                    return textResult("suiteUuid is required when level is ANALYSIS");
+                const result = await requestClient(FetchSuiteVariables, { suiteUuid });
+                return textResult(result?.fetchSuiteVariables ?? "[]");
+            }
+            const { WOPEE_PROJECT_UUID } = getConfig();
+            if (!WOPEE_PROJECT_UUID)
+                return textResult("WOPEE_PROJECT_UUID is not set");
+            const result = await requestClient(FetchProjectVariables, { projectUuid: WOPEE_PROJECT_UUID });
+            return textResult(result?.fetchProjectVariables ?? "[]");
+        }
+        catch (error) {
+            return _parseError(error);
+        }
+    },
+};

package/build/tools/wopee_fetch_variables/schema.js

@@ -0,0 +1,12 @@
+import { z } from "zod";
+import { VariableLevel } from "../shared/types.js";
+export const WopeeFetchVariablesInputSchema = z.object({
+    level: z.nativeEnum(VariableLevel, {
+        description: "Which variable set to read. PROJECT reads the project-level variables (uses WOPEE_PROJECT_UUID from the environment). ANALYSIS reads a specific analysis suite's variables and requires suiteUuid.",
+    }),
+    suiteUuid: z
+        .string({
+        description: "UUID of the analysis suite to read variables from. Required when level is ANALYSIS; ignored when level is PROJECT.",
+    })
+        .nullish(),
+});

package/build/tools/wopee_update_variables/factory.js

@@ -0,0 +1,24 @@
+import { getConfig } from "../../utils/getConfig.js";
+/**
+ * Wire payload for the updateSuiteVariables mutation. The handler guarantees
+ * suiteUuid is present before calling this (ANALYSIS level).
+ */
+export const createUpdateSuiteVariablesInput = (input) => ({
+    suiteUuid: input.suiteUuid,
+    additionalVariables: JSON.stringify(input.variables),
+});
+/**
+ * Wire payload for the updateProjectVariables mutation, injecting
+ * WOPEE_PROJECT_UUID from the environment (PROJECT level).
+ */
+export const createUpdateProjectVariablesInput = (input) => {
+    const { WOPEE_PROJECT_UUID } = getConfig();
+    if (!WOPEE_PROJECT_UUID)
+        throw new Error("WOPEE_PROJECT_UUID is not set");
+    return {
+        input: {
+            projectUuid: WOPEE_PROJECT_UUID,
+            additionalVariables: JSON.stringify(input.variables),
+        },
+    };
+};

package/build/tools/wopee_update_variables/index.js

@@ -0,0 +1,38 @@
+import { requestClient } from "../../utils/requestClient.js";
+import { withRetry } from "../../utils/withRetry.js";
+import { _parseError } from "../shared/helpers.js";
+import { ToolName, VariableLevel } from "../shared/types.js";
+import { UpdateProjectVariables, UpdateSuiteVariables, } from "../shared/gql-queries.js";
+import { createUpdateProjectVariablesInput, createUpdateSuiteVariablesInput, } from "./factory.js";
+import { WopeeUpdateVariablesInputSchema, } from "./schema.js";
+const textResult = (text) => ({
+    content: [{ type: "text", text }],
+});
+export const wopeeUpdateVariables = {
+    name: ToolName.WOPEE_UPDATE_VARIABLES,
+    config: {
+        title: "Update run-time variables",
+        description: "Upsert the run-time variables (additionalVariables) that drive analysis/agent runs, at either level. level: PROJECT writes the project-level variables (uses WOPEE_PROJECT_UUID from the environment); level: ANALYSIS writes a specific analysis suite's variables and requires suiteUuid. Merge semantics: keys in variables[] are added or overwritten, existing keys not listed are preserved. Keys must be uppercase (e.g. BASE_URL); the server re-sanitizes and drops invalid keys. Returns a confirmation on success.",
+        inputSchema: WopeeUpdateVariablesInputSchema.shape,
+    },
+    handler: async (input) => {
+        try {
+            const { level, suiteUuid } = input;
+            if (level === VariableLevel.ANALYSIS) {
+                if (!suiteUuid)
+                    return textResult("suiteUuid is required when level is ANALYSIS");
+                const result = await withRetry(() => requestClient(UpdateSuiteVariables, createUpdateSuiteVariablesInput(input)));
+                if (!result?.updateSuiteVariables)
+                    return textResult("Failed to update suite variables");
+                return textResult("Suite variables updated successfully");
+            }
+            const result = await withRetry(() => requestClient(UpdateProjectVariables, createUpdateProjectVariablesInput(input)));
+            if (!result?.updateProjectVariables)
+                return textResult("Failed to update project variables");
+            return textResult("Project variables updated successfully");
+        }
+        catch (error) {
+            return _parseError(error);
+        }
+    },
+};

package/build/tools/wopee_update_variables/schema.js

@@ -0,0 +1,16 @@
+import { z } from "zod";
+import { VariableLevel } from "../shared/types.js";
+import { AdditionalVariableSchema } from "../shared/schemas.js";
+export const WopeeUpdateVariablesInputSchema = z.object({
+    level: z.nativeEnum(VariableLevel, {
+        description: "Which variable set to write. PROJECT writes the project-level variables (uses WOPEE_PROJECT_UUID from the environment). ANALYSIS writes a specific analysis suite's variables and requires suiteUuid.",
+    }),
+    suiteUuid: z
+        .string({
+        description: "UUID of the analysis suite to write variables to. Required when level is ANALYSIS; ignored when level is PROJECT.",
+    })
+        .nullish(),
+    variables: z.array(AdditionalVariableSchema, {
+        description: "Variables to upsert. Each needs an uppercase key (e.g. BASE_URL) and a non-empty value. Merge semantics: keys listed here are added or overwritten; existing keys not listed here are preserved.",
+    }),
+});

package/package.json

@@ -4,7 +4,7 @@
   "bin": {
     "wopee-mcp": "./build/index.js"
   },
-  "version": "1.26.2",
+  "version": "1.28.0",
   "mcpName": "io.github.Wopee-io/wopee-mcp",
   "description": "Wopee.io MCP server for autonomous testing platform",
   "main": "./build/index.js",