wopee-mcp 1.2.2 → 1.4.0

package/README.md

@@ -0,0 +1,277 @@
+# Wopee MCP Server
+
+A Model Context Protocol (MCP) server for interacting with Wopee.io's autonomous testing platform. This server provides tools for managing analysis suites, generating test cases, user stories, and dispatching autonomous testing agents.
+
+## Setup
+
+### Prerequisites
+
+- Node.js (v18 or higher recommended)
+- An IDE that supports MCP (Model Context Protocol), such as Cursor or VSCode
+
+### MCP Server Configuration
+
+Add this server to your MCP configuration.
+
+### Configuration Example
+
+```json
+{
+  "mcpServers": {
+    "wopee": {
+      "command": "npx wopee-mcp",
+      "env": {
+        "WOPEE_PROJECT_UUID": "your-project-uuid-here",
+        "WOPEE_API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+#### Required Environment Variables
+
+- **`WOPEE_PROJECT_UUID`** - Your Wopee project UUID. This identifies which project you're working with.
+- **`WOPEE_API_KEY`** - Your Wopee API key. You can create one at [cmd.wopee.io](https://cmd.wopee.io), in your project's settings.
+
+#### Optional Environment Variables
+
+- **`WOPEE_API_URL`** - The Wopee API endpoint URL. Should be specified only for testing/development purposes.
+
+## Getting Started
+
+Most tools in this MCP server require a `suiteUuid` to operate. You have two options to get started:
+
+### Option 1: Use Existing Suites
+
+Start by fetching your existing analysis suites:
+
+```
+Use the wopee_fetch_analysis_suites tool to retrieve all available suites for your project.
+```
+
+This will return a list of all analysis suites with their UUIDs, which you can then use with other tools.
+
+### Option 2: Create a New Suite
+
+If you don't have any suites yet, create a fresh analysis suite:
+
+```
+Use the wopee_dispatch_analysis tool to create and dispatch a new analysis/crawling suite.
+```
+
+This will create a new suite and return its UUID, which you can use for subsequent operations.
+
+## Available Tools
+
+### Suite Management
+
+#### `wopee_fetch_analysis_suites`
+
+Fetches all analysis suites for your project. This is a good starting point to see what suites are available.
+
+- **Returns:** Array of analysis suites with their UUIDs, names, statuses, and metadata
+
+**Example Usage:**
+
+```
+Fetch all existing analysis suites for my project
+```
+
+#### `wopee_dispatch_analysis`
+
+Creates and dispatches a new analysis/crawling suite for your project. Use this to start a fresh analysis session.
+
+- **Returns:** Success message with the created suite information
+
+**Example Usage:**
+
+```
+Dispatch a new analysis suite
+```
+
+### Generation Tools
+
+These tools generate various artifacts for a specific suite. All require a `suiteUuid`.
+
+#### `wopee_generate_app_context`
+
+Generates an application context markdown file for the selected suite. This provides a comprehensive overview of the application being analyzed.
+
+- **Parameters:**
+  - `suiteUuid` - The UUID of the suite to generate context for
+- **Returns:** Generated output in case of successful generation
+
+**Example Usage:**
+
+```
+Generate app context for suite abc-123-def-456
+```
+
+#### `wopee_generate_general_user_stories`
+
+Generates general user stories markdown file for the selected suite.
+
+- **Parameters:**
+  - `suiteUuid` - The UUID of the suite
+- **Returns:** Generated output in case of successful generation
+
+**Example Usage:**
+
+```
+Generate general user stories for my latest suite
+```
+
+#### `wopee_generate_user_stories`
+
+Generates detailed user stories JSON file for the selected suite.
+
+- **Parameters:**
+  - `suiteUuid` - The UUID of the suite
+- **Returns:** Generated output in case of successful generation
+
+**Example Usage:**
+
+```
+Generate user stories for suite abc-123-def-456
+```
+
+#### `wopee_generate_test_cases`
+
+Generates test cases for the selected suite based on the analysis and user stories.
+
+- **Parameters:**
+  - `suiteUuid` - The UUID of the suite
+- **Returns:** Generated output in case of successful generation
+
+**Example Usage:**
+
+```
+Generate test cases for suite abc-123-def-456
+```
+
+### Fetch Tools
+
+These tools retrieve generated artifacts for a specific suite. All require a `suiteUuid`.
+
+#### `wopee_fetch_app_context`
+
+Fetches the application context markdown file for a suite.
+
+- **Parameters:**
+  - `suiteUuid` - The UUID of the suite
+- **Returns:** The application context markdown content
+
+**Example Usage:**
+
+```
+Fetch app context for my latest suite
+```
+
+#### `wopee_fetch_general_user_stories`
+
+Fetches the general user stories markdown file for a suite.
+
+- **Parameters:**
+  - `suiteUuid` - The UUID of the suite
+- **Returns:** The general user stories markdown content
+
+**Example Usage:**
+
+```
+Fetch general user stories for suite abc-123-def-456
+```
+
+#### `wopee_fetch_user_stories`
+
+Fetches the user stories JSON file for a suite.
+
+- **Parameters:**
+  - `suiteUuid` - The UUID of the suite
+- **Returns:** The user stories JSON content
+
+**Example Usage:**
+
+```
+Fetch user stories for suite abc-123-def-456
+```
+
+#### `wopee_fetch_test_cases`
+
+Fetches the test cases JSON file for a suite.
+
+- **Parameters:**
+  - `suiteUuid` - The UUID of the suite
+- **Returns:** The test cases JSON content
+
+**Example Usage:**
+
+```
+Fetch test cases for suite abc-123-def-456
+```
+
+### Update Tools
+
+These tools are used to update or set certain files(artifacts) for a specific suite. `suiteUuid`, `fileType` and `fileContent` is required.
+
+#### `wopee_update_file`
+
+Updates/replaces existing file(artifact) for a specific suite
+
+- **Parameters:**
+  - `suiteUuid` - The UUID of the suite
+  - `fileType` - `"APP_CONTEXT" | "GENERAL_USER_STORIES" | "USER_STORIES" | "TEST_CASES"`
+  - `fileContent` - Markdown content for `app context` and `general user stories`, structured JSON for `user stories` and `test cases`
+- **Returns:** Boolean based of success status of the tool call
+
+**Example Usage:**
+
+```
+Update app context file for the most recent suite with this content: <YourMarkdown>
+```
+
+### Agent Testing
+
+#### `wopee_dispatch_agent`
+
+Dispatches an autonomous testing agent to execute test cases for a selected suite.
+
+- **Parameters:**
+  - `suiteUuid` - The UUID of the suite containing the test cases
+  - `analysisIdentifier` - The analysis identifier for the suite
+  - `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:** Success message indicating the agent has been dispatched
+
+**Example Usage:**
+
+```
+Dispatch agent for my latest suite's user story US001 and test case TC003
+```
+
+## Typical Workflow
+
+1. **Start with a suite:**
+
+   - Use `wopee_fetch_analysis_suites` to see existing suites, OR
+   - Use `wopee_dispatch_analysis` to create a new suite
+
+2. **Generate artifacts:**
+
+   - Generate app context: `wopee_generate_app_context`
+   - Generate user stories: `wopee_generate_user_stories` or `wopee_generate_general_user_stories`
+   - Generate test cases: `wopee_generate_test_cases`
+
+3. **Fetch generated content:**
+
+   - Use the fetch tools to retrieve generated markdown/JSON files
+
+4. **Run tests:**
+   - Use `wopee_dispatch_agent` to execute test cases with the autonomous testing agent
+
+## Notes
+
+- Most tools require a `suiteUuid`. Always start by fetching or creating a suite.
+- `wopee_dispatch_analysis` tool will go through whole cycle of processing - crawling the application and generating all of the artifacts one by one.
+- It is advisable to use [cmd.wopee.io](https://cmd.wopee.io) for a convenient visual representation of the generated data and results of the agent runs.

package/build/tools/index.js

@@ -1,3 +1,4 @@
+import { wopeeUpdateFile } from "./wopee_update_file/index.js";
 import { wopeeDispatchAgent } from "./wopee_dispatch_agent/index.js";
 import { wopeeFetchTestCases } from "./wopee_fetch_test_cases/index.js";
 import { wopeeFetchAppContext } from "./wopee_fetch_app_context/index.js";
@@ -21,4 +22,5 @@ export const TOOLS = [
     wopeeFetchGeneralUserStories,
     wopeeFetchUserStories,
     wopeeFetchTestCases,
+    wopeeUpdateFile,
 ];

package/build/tools/shared/factories.js

@@ -30,3 +30,14 @@ export const createGenerateAIDataInput = (input) => {
         sourceSuiteUuid: null,
     };
 };
+export const createUpdateFileInput = (input) => {
+    const { WOPEE_PROJECT_UUID } = getConfig();
+    if (!WOPEE_PROJECT_UUID)
+        throw new Error("WOPEE_PROJECT_UUID is not set");
+    return {
+        bucket: input.bucket,
+        projectUuid: WOPEE_PROJECT_UUID,
+        suiteUuid: input.suiteUuid,
+        [input.type === "markdown" ? "code" : "json"]: input.fileContent,
+    };
+};

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

@@ -104,3 +104,8 @@ export const GenerateUserStories = `
     generateUserStories(input: $input)
   }
 `;
+export const UpdateFile = `
+  mutation UpdateFile($input: UpdateFileInput!) {
+    updateFile(input: $input)
+  }
+`;

package/build/tools/shared/handlers.js

@@ -1,8 +1,8 @@
 import { z } from "zod";
-import { FetchFileInputSchema, GenerateAIDataInputSchema, } from "./schemas.js";
-import { FetchFile, GenerateTestCases, GenerateAppContext, GenerateUserStories, GenerateGeneralUserStories, } from "./gql-queries.js";
-import { createFetchFileInput, createGenerateAIDataInput, } from "./factories.js";
-import { Bucket, GenerationType } from "./types.js";
+import { FetchFileInputSchema, UpdateFileInputSchema, GenerateAIDataInputSchema, } from "./schemas.js";
+import { FetchFile, UpdateFile, GenerateTestCases, GenerateAppContext, GenerateUserStories, GenerateGeneralUserStories, } from "./gql-queries.js";
+import { createFetchFileInput, createUpdateFileInput, createGenerateAIDataInput, } from "./factories.js";
+import { Bucket, FileType } from "./types.js";
 import { requestClient } from "../../utils/requestClient.js";
 export function parseError(error) {
     console.error(error instanceof z.ZodError ? error.issues : error);
@@ -21,40 +21,46 @@ export function parseError(error) {
         ],
     };
 }
-function parseGenerationType(type) {
+function parseFileType(type) {
     switch (type) {
-        case GenerationType.APP_CONTEXT:
+        case FileType.APP_CONTEXT:
             return {
                 query: GenerateAppContext,
                 dataKey: "generateAppContext",
                 bucket: Bucket.APP_CONTEXT,
+                type: "markdown",
                 description: "application's context markdown file for selected suite",
             };
-        case GenerationType.GENERAL_USER_STORIES:
+        case FileType.GENERAL_USER_STORIES:
             return {
                 query: GenerateGeneralUserStories,
                 dataKey: "generateGeneralUserStories",
                 bucket: Bucket.GENERAL_USER_STORIES,
+                type: "markdown",
                 description: "general user stories markdown file for selected suite",
             };
-        case GenerationType.USER_STORIES:
+        case FileType.USER_STORIES:
             return {
                 query: GenerateUserStories,
                 dataKey: "generateUserStories",
                 bucket: Bucket.USER_STORIES,
+                type: "json",
                 description: "user stories JSON file for selected suite",
             };
-        case GenerationType.TEST_CASES:
+        case FileType.TEST_CASES:
             return {
                 query: GenerateTestCases,
                 dataKey: "generateTestCases",
                 bucket: Bucket.USER_STORIES,
+                type: "json",
                 description: "test cases for selected suite",
             };
         default:
             return {
                 query: null,
                 dataKey: null,
+                bucket: null,
+                type: null,
                 description: null,
             };
     }
@@ -87,7 +93,7 @@ export async function fetchFile(input) {
     }
 }
 export async function generateAIDataFile(type, input) {
-    const { query, dataKey, bucket, description } = parseGenerationType(type);
+    const { query, dataKey, bucket, description } = parseFileType(type);
     if (!query || !dataKey || !description || !bucket)
         return {
             content: [
@@ -121,3 +127,47 @@ export async function generateAIDataFile(type, input) {
         return parseError(error);
     }
 }
+export async function updateFile(input) {
+    try {
+        const { bucket, type } = parseFileType(input.fileType);
+        if (!bucket || !type)
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "Failed to parse file type",
+                    },
+                ],
+            };
+        const updateFileInput = createUpdateFileInput({
+            type,
+            bucket,
+            suiteUuid: input.suiteUuid,
+            fileContent: input.fileContent,
+        });
+        const parsedInput = UpdateFileInputSchema.parse(updateFileInput);
+        const updateFileResult = await requestClient(UpdateFile, {
+            input: parsedInput,
+        });
+        if (!updateFileResult || !updateFileResult.updateFile)
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "Failed to update file",
+                    },
+                ],
+            };
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "File updated successfully",
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return parseError(error);
+    }
+}

package/build/tools/shared/schemas.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { Bucket } from "./types.js";
+import { Bucket, FileType } from "./types.js";
 var CookiesPreference;
 (function (CookiesPreference) {
     CookiesPreference["ACCEPT_ALL"] = "ACCEPT_ALL";
@@ -15,7 +15,9 @@ export const SuiteAnalysisConfigSchema = z.object({
     additionalVariables: z.string().nullable().default(null),
 });
 export const GenerateAIDataHandlerInputSchema = z.object({
-    suiteUuid: z.string().min(1, "Suite UUID is required"),
+    suiteUuid: z
+        .string({ description: "UUID of the suite to generate AI data for" })
+        .min(1, "Suite UUID is required"),
 });
 export const GenerateAIDataInputSchema = z.object({
     projectUuid: z.string().min(1, "Project UUID is required"),
@@ -27,7 +29,9 @@ export const GenerateAIDataInputSchema = z.object({
     continueGeneration: z.boolean().nullish().default(false),
 });
 export const FetchFileHandlerInputSchema = z.object({
-    suiteUuid: z.string().min(1, "Suite UUID is required"),
+    suiteUuid: z
+        .string({ description: "UUID of the suite to fetch the file from" })
+        .min(1, "Suite UUID is required"),
 });
 export const FetchFileFactoryInputSchema = z.object({
     suiteUuid: z.string().min(1, "Suite UUID is required"),
@@ -38,3 +42,27 @@ export const FetchFileInputSchema = z.object({
     suiteUuid: z.string().min(1, "Suite UUID is required"),
     bucket: z.nativeEnum(Bucket),
 });
+export const UpdateFileHandlerInputSchema = z.object({
+    fileType: z.nativeEnum(FileType, {
+        description: "Chosen file/artifact to update",
+    }),
+    fileContent: z.string({
+        description: "Content of the file/artifact to update",
+    }),
+    suiteUuid: z
+        .string({ description: "UUID of the suite to update the file for" })
+        .min(1, "Suite UUID is required"),
+});
+export const UpdateFileFactoryInputSchema = z.object({
+    bucket: z.nativeEnum(Bucket),
+    suiteUuid: z.string().min(1, "Suite UUID is required"),
+    fileContent: z.string(),
+    type: z.enum(["markdown", "json"]),
+});
+export const UpdateFileInputSchema = z.object({
+    projectUuid: z.string().min(1, "Project UUID is required"),
+    suiteUuid: z.string().min(1, "Suite UUID is required"),
+    bucket: z.nativeEnum(Bucket),
+    json: z.string().nullish(),
+    code: z.string().nullish(),
+});

package/build/tools/shared/types.js

@@ -11,6 +11,7 @@ export var ToolName;
     ToolName["WOPEE_GENERATE_GENERAL_USER_STORIES"] = "wopee_generate_general_user_stories";
     ToolName["WOPEE_GENERATE_USER_STORIES"] = "wopee_generate_user_stories";
     ToolName["WOPEE_GENERATE_TEST_CASES"] = "wopee_generate_test_cases";
+    ToolName["WOPEE_UPDATE_FILE"] = "wopee_update_file";
 })(ToolName || (ToolName = {}));
 export const Bucket = {
     APP_CONTEXT: "project-suite-app-context",
@@ -21,13 +22,13 @@ export const Bucket = {
     PLAYWRIGHT_CODE: "project-suite-playwright-code",
     UPLOADED_PAGE_DATA: "project-uploaded-page-data",
 };
-export var GenerationType;
-(function (GenerationType) {
-    GenerationType["APP_CONTEXT"] = "APP_CONTEXT";
-    GenerationType["GENERAL_USER_STORIES"] = "GENERAL_USER_STORIES";
-    GenerationType["USER_STORIES"] = "USER_STORIES";
-    GenerationType["TEST_CASES"] = "TEST_CASES";
-})(GenerationType || (GenerationType = {}));
+export var FileType;
+(function (FileType) {
+    FileType["APP_CONTEXT"] = "APP_CONTEXT";
+    FileType["GENERAL_USER_STORIES"] = "GENERAL_USER_STORIES";
+    FileType["USER_STORIES"] = "USER_STORIES";
+    FileType["TEST_CASES"] = "TEST_CASES";
+})(FileType || (FileType = {}));
 export var SuiteType;
 (function (SuiteType) {
     SuiteType["BOT"] = "BOT";

package/build/tools/wopee_dispatch_agent/schema.js

@@ -1,12 +1,28 @@
 import { z } from "zod";
 const SelectedTestCasesSchema = z.object({
-    testCaseId: z.string().min(1, "Test case ID is required"),
-    userStoryId: z.string().min(1, "User story ID is required"),
+    testCaseId: z
+        .string({
+        description: "ID of the test case belonging to the user story to dispatch the agent for (ex. TC001)",
+    })
+        .min(1, "Test case ID is required"),
+    userStoryId: z
+        .string({
+        description: "ID of the user story that the test case belongs to (ex. US001)",
+    })
+        .min(1, "User story ID is required"),
 });
 export const WopeeDispatchAgentInputSchema = z.object({
-    suiteUuid: z.string().min(1, "Suite UUID is required"),
-    analysisIdentifier: z.string().min(1, "Analysis identifier is required"),
-    testCases: z.array(SelectedTestCasesSchema),
+    suiteUuid: z
+        .string({ description: "UUID of the suite to dispatch the agent for" })
+        .min(1, "Suite UUID is required"),
+    analysisIdentifier: z
+        .string({
+        description: "Analysis identifier of the suite to dispatch the agent for",
+    })
+        .min(1, "Analysis identifier is required"),
+    testCases: z.array(SelectedTestCasesSchema, {
+        description: "Chosen test cases to dispatch the agent for",
+    }),
 });
 export const DispatchAgentInputSchema = z.object({
     projectUuid: z.string().min(1, "Project UUID is required"),

package/build/tools/wopee_fetch_analysis_suites/index.js

@@ -1,7 +1,7 @@
+import { getConfig } from "../../utils/getConfig.js";
 import { requestClient } from "../../utils/requestClient.js";
 import { ToolName } from "../shared/types.js";
 import { FetchAnalysisSuites } from "../shared/gql-queries.js";
-import { getConfig } from "../../utils/getConfig.js";
 export const wopeeFetchAnalysisSuites = {
     name: ToolName.WOPEE_FETCH_ANALYSIS_SUITES,
     config: {

package/build/tools/wopee_fetch_app_context/index.js

@@ -1,6 +1,6 @@
+import { FetchFileHandlerInputSchema, } from "../shared/schemas.js";
 import { fetchFile } from "../shared/handlers.js";
 import { Bucket, ToolName } from "../shared/types.js";
-import { FetchFileHandlerInputSchema, } from "../shared/schemas.js";
 export const wopeeFetchAppContext = {
     name: ToolName.WOPEE_FETCH_APP_CONTEXT,
     config: {

package/build/tools/wopee_generate_app_context/index.js

@@ -1,6 +1,6 @@
 import { GenerateAIDataHandlerInputSchema, } from "../shared/schemas.js";
+import { FileType, ToolName } from "../shared/types.js";
 import { generateAIDataFile } from "../shared/handlers.js";
-import { GenerationType, ToolName } from "../shared/types.js";
 export const wopeeGenerateAppContext = {
     name: ToolName.WOPEE_GENERATE_APP_CONTEXT,
     config: {
@@ -8,5 +8,5 @@ export const wopeeGenerateAppContext = {
         description: "Generate application's context markdown file for selected suite",
         inputSchema: GenerateAIDataHandlerInputSchema.shape,
     },
-    handler: async (input) => await generateAIDataFile(GenerationType.APP_CONTEXT, input),
+    handler: async (input) => await generateAIDataFile(FileType.APP_CONTEXT, input),
 };

package/build/tools/wopee_generate_general_user_stories/index.js

@@ -1,6 +1,6 @@
 import { GenerateAIDataHandlerInputSchema, } from "../shared/schemas.js";
+import { FileType, ToolName } from "../shared/types.js";
 import { generateAIDataFile } from "../shared/handlers.js";
-import { GenerationType, ToolName } from "../shared/types.js";
 export const wopeeGenerateGeneralUserStories = {
     name: ToolName.WOPEE_GENERATE_GENERAL_USER_STORIES,
     config: {
@@ -8,5 +8,5 @@ export const wopeeGenerateGeneralUserStories = {
         description: "Generate general user stories markdown file for selected suite",
         inputSchema: GenerateAIDataHandlerInputSchema.shape,
     },
-    handler: async (input) => await generateAIDataFile(GenerationType.GENERAL_USER_STORIES, input),
+    handler: async (input) => await generateAIDataFile(FileType.GENERAL_USER_STORIES, input),
 };

package/build/tools/wopee_generate_test_cases/index.js

@@ -1,6 +1,6 @@
 import { GenerateAIDataHandlerInputSchema, } from "../shared/schemas.js";
+import { FileType, ToolName } from "../shared/types.js";
 import { generateAIDataFile } from "../shared/handlers.js";
-import { GenerationType, ToolName } from "../shared/types.js";
 export const wopeeGenerateTestCases = {
     name: ToolName.WOPEE_GENERATE_TEST_CASES,
     config: {
@@ -8,5 +8,5 @@ export const wopeeGenerateTestCases = {
         description: "Generate test cases for selected suite",
         inputSchema: GenerateAIDataHandlerInputSchema.shape,
     },
-    handler: async (input) => await generateAIDataFile(GenerationType.TEST_CASES, input),
+    handler: async (input) => await generateAIDataFile(FileType.TEST_CASES, input),
 };

package/build/tools/wopee_generate_user_stories/index.js

@@ -1,6 +1,6 @@
 import { GenerateAIDataHandlerInputSchema, } from "../shared/schemas.js";
+import { FileType, ToolName } from "../shared/types.js";
 import { generateAIDataFile } from "../shared/handlers.js";
-import { GenerationType, ToolName } from "../shared/types.js";
 export const wopeeGenerateUserStories = {
     name: ToolName.WOPEE_GENERATE_USER_STORIES,
     config: {
@@ -8,5 +8,5 @@ export const wopeeGenerateUserStories = {
         description: "Generate user stories JSON file for selected suite",
         inputSchema: GenerateAIDataHandlerInputSchema.shape,
     },
-    handler: async (input) => await generateAIDataFile(GenerationType.USER_STORIES, input),
+    handler: async (input) => await generateAIDataFile(FileType.USER_STORIES, input),
 };

package/build/tools/wopee_update_file/index.js

@@ -0,0 +1,12 @@
+import { UpdateFileHandlerInputSchema, } from "../shared/schemas.js";
+import { ToolName } from "../shared/types.js";
+import { updateFile } from "../shared/handlers.js";
+export const wopeeUpdateFile = {
+    name: ToolName.WOPEE_UPDATE_FILE,
+    config: {
+        title: "Update file",
+        description: "Update file(artifact) in the project",
+        inputSchema: UpdateFileHandlerInputSchema.shape,
+    },
+    handler: async (input) => await updateFile(input),
+};

package/package.json

@@ -4,7 +4,7 @@
   "bin": {
     "wopee-mcp": "./build/index.js"
   },
-  "version": "1.2.2",
+  "version": "1.4.0",
   "description": "Wopee.io MCP server",
   "main": "./build/index.js",
   "scripts": {