wopee-mcp 1.0.1

package/INTEGRATION.md

@@ -0,0 +1,441 @@
+# VS Code & Cursor Integration Guide
+
+This guide provides detailed instructions for integrating the Wopee.io MCP server with VS Code and Cursor editors.
+
+## Quick Start
+
+### One-Click Installation
+
+**For both VS Code and Cursor:**
+
+1. Open your editor
+2. Press `Ctrl+Shift+P` (Windows/Linux) or `Cmd+Shift+P` (Mac)
+3. Type "MCP: Install Server" and select it
+4. Enter: `wopee-mcp`
+5. Configure your API key when prompted
+
+That's it! The Wopee MCP server is now ready to use.
+
+## 🔐 Environment Configuration
+
+**Recommended Approach: Use .env files**
+
+The Wopee.io MCP server automatically loads configuration from `.env` files, making it more secure than hardcoding API keys in configuration files.
+
+### Setting up .env file
+
+1. **Create a .env file in your project root:**
+   ```bash
+   # Copy the example file
+   cp .env.example .env
+   
+   # Edit with your actual API key
+   nano .env
+   ```
+
+2. **Add your configuration:**
+   ```bash
+   # Wopee API Configuration
+   WOPEE_API_KEY=your_actual_api_key_here
+   WOPEE_PROJECT_UUID=your_project_uuid_here
+   ```
+
+The server will automatically load your `.env` file from the project root directory (where `package.json` is located).
+
+## Prerequisites
+
+Before starting, ensure you have:
+
+- **VS Code** with MCP extension or **Cursor** (built-in MCP support)
+- **Node.js 18+** installed
+- **Wopee API key** from [wopee.io](https://wopee.io)
+
+## VS Code Integration
+
+### Installing the MCP Extension
+
+If you don't have the MCP extension:
+
+1. Open VS Code
+2. Go to Extensions (`Ctrl+Shift+X` or `Cmd+Shift+X`)
+3. Search for "MCP" or "Model Context Protocol"
+4. Install the official MCP extension
+
+### Method 1: One-Click Installation (Recommended)
+
+1. **Open Command Palette**: `Ctrl+Shift+P` (Windows/Linux) or `Cmd+Shift+P` (Mac)
+2. **Type**: `MCP: Install Server`
+3. **Enter package name**: `wopee-mcp`
+4. **Configure API key** when prompted
+5. **Restart VS Code** if required
+
+### Method 2: Manual Configuration
+
+1. **Install globally**:
+   ```bash
+   npm install -g wopee-mcp
+   ```
+
+2. **Open VS Code settings** (`Ctrl+,` or `Cmd+,`)
+
+3. **Search for "MCP"** in settings
+
+4. **Add server configuration**:
+   ```json
+   {
+     "mcp.servers": {
+       "wopee": {
+         "command": "wopee-mcp",
+         "args": [],
+         "env": {}
+       }
+     }
+   }
+   ```
+
+5. **Restart VS Code**
+
+### Method 3: Workspace Configuration
+
+For project-specific configuration, create `.vscode/settings.json`:
+
+```json
+{
+  "mcp.servers": {
+    "wopee": {
+      "command": "wopee-mcp",
+      "args": [],
+      "env": {}
+    }
+  }
+}
+```
+
+## Cursor Integration
+
+### Method 1: One-Click Installation (Recommended)
+
+1. **Open Command Palette**: `Ctrl+Shift+P` (Windows/Linux) or `Cmd+Shift+P` (Mac)
+2. **Type**: `MCP: Install Server`
+3. **Enter package name**: `wopee-mcp`
+4. **Configure API key** when prompted
+5. **Restart Cursor** if required
+
+### Method 2: Manual Configuration
+
+1. **Install globally**:
+   ```bash
+   npm install -g wopee-mcp
+   ```
+
+2. **Open Cursor settings** (`Ctrl+,` or `Cmd+,`)
+
+3. **Navigate to MCP settings** in the sidebar
+
+4. **Add server configuration**:
+   ```json
+   {
+     "mcp.servers": {
+       "wopee": {
+         "command": "wopee-mcp",
+         "args": [],
+         "env": {
+           "WOPEE_API_KEY": "your_api_key_here",
+           "WOPEE_PROJECT_UUID": "your_project_uuid_here",
+           "WOPEE_API_URL": "https://api.wopee.io/"
+         }
+       }
+     }
+   }
+   ```
+
+5. **Restart Cursor**
+
+## Using the Tools
+
+Once configured, you can use Wopee tools in your chat interface:
+
+### Available Tools
+
+#### 1. Dispatch Analysis
+```
+@wopee wopee_dispatch_analysis
+Suite Analysis Config:
+  - Username: testuser
+  - Password: testpass
+  - Cookies Preference: ACCEPT_ALL
+```
+
+#### 2. Dispatch Agent
+```
+@wopee wopee_dispatch_agent
+Analysis Identifier: analysis-123
+Test Cases: [{"testCaseId": "test-1", "userStoryId": "story-1"}]
+```
+
+#### 3. Generate App Context
+```
+@wopee wopee_generate_app_context
+Suite UUID: suite-123
+Extra Prompt: Focus on user authentication flows
+```
+
+#### 4. Generate General User Stories
+```
+@wopee wopee_generate_general_user_stories
+Suite UUID: suite-123
+Extra Prompt: Include high-level business requirements
+```
+
+#### 5. Generate User Stories
+```
+@wopee wopee_generate_user_stories
+Suite UUID: suite-123
+Extra Prompt: Include edge cases and error scenarios
+```
+
+#### 6. Generate Test Cases
+```
+@wopee wopee_generate_test_cases
+Suite UUID: suite-123
+Extra Prompt: Generate comprehensive test coverage
+Selected User Stories: ["story-1", "story-2"]
+```
+
+#### 7. Get App Context
+```
+@wopee wopee_get_app_context
+Suite UUID: suite-123
+```
+
+#### 8. Get User Stories
+```
+@wopee wopee_get_user_stories
+Suite UUID: suite-123
+```
+
+#### 9. Get Test Cases
+```
+@wopee wopee_get_test_cases
+Suite UUID: suite-123
+```
+
+#### 10. Fetch Analysis Suites
+```
+@wopee wopee_fetch_analysis_suites
+Project UUID: project-123
+```
+
+### Example Workflow
+
+1. **Start with analysis**:
+   ```
+   @wopee wopee_dispatch_analysis
+   Suite Analysis Config:
+     - Username: testuser
+     - Password: testpass
+   ```
+
+2. **Generate app context**:
+   ```
+   @wopee wopee_generate_app_context
+   Suite UUID: [from previous step]
+   Extra Prompt: Focus on user registration and login flows
+   ```
+
+3. **Generate general user stories**:
+   ```
+   @wopee wopee_generate_general_user_stories
+   Suite UUID: [from step 1]
+   Extra Prompt: Include high-level business requirements
+   ```
+
+4. **Create detailed user stories**:
+   ```
+   @wopee wopee_generate_user_stories
+   Suite UUID: [from step 1]
+   Extra Prompt: Include error handling and edge cases
+   ```
+
+5. **Generate test cases**:
+   ```
+   @wopee wopee_generate_test_cases
+   Suite UUID: [from step 1]
+   Extra Prompt: Generate comprehensive test coverage
+   ```
+
+6. **Execute tests**:
+   ```
+   @wopee wopee_dispatch_agent
+   Suite UUID: [from step 1]
+   Analysis Identifier: [from step 1]
+   ```
+
+## Troubleshooting
+
+### Common Issues
+
+#### 1. "Command not found" Error
+
+**Problem**: The `wopee-mcp` command is not found.
+
+**Solutions**:
+- Install globally: `npm install -g wopee-mcp`
+- Check Node.js is in PATH: `node --version`
+- Restart your terminal/editor
+
+#### 2. "API key not configured" Error
+
+**Problem**: API key is missing or invalid.
+
+**Solutions**:
+- Verify API key set in .env file
+- Check environment variables are set correctly
+- Ensure API key is valid at [wopee.io](https://wopee.io)
+
+#### 3. "Connection failed" Error
+
+**Problem**: Cannot connect to Wopee API.
+
+**Solutions**:
+- Check internet connection
+- Verify API URL is correct: `https://api.wopee.io/`
+- Test API key validity
+- Check firewall/proxy settings
+
+#### 4. Tools Not Appearing
+
+**Problem**: Wopee tools don't show up in chat interface.
+
+**Solutions**:
+- Restart your editor (VS Code/Cursor)
+- Check MCP server logs in output panel
+- Verify server configuration
+- Run `wopee-mcp --version` to test installation
+
+#### 5. Permission Errors
+
+**Problem**: Permission denied when installing or running.
+
+**Solutions**:
+- Use `sudo` for global installation (Linux/Mac)
+- Check file permissions
+- Run as administrator (Windows)
+
+### Debugging Steps
+
+1. **Check installation**:
+   ```bash
+   wopee-mcp --version
+   wopee-mcp --help
+   ```
+
+2. **Test API connection**:
+   ```bash
+   curl -H "api_key: YOUR_API_KEY" https://api.wopee.io/
+   ```
+
+3. **Check MCP server logs**:
+   - Open Output panel in VS Code/Cursor
+   - Select "MCP" from dropdown
+   - Look for error messages
+
+4. **Verify configuration**:
+   - Check MCP server settings
+   - Ensure environment variables are set
+   - Validate JSON configuration syntax
+
+### Getting Help
+
+- **Check logs**: Look in the MCP server output panel
+- **Verify installation**: Run `wopee-mcp --help` in terminal
+- **Test connection**: Use a simple tool like `wopee_dispatch_analysis`
+- **Community support**: Check the repository issues
+- **Documentation**: Refer to the main README.md
+
+## Advanced Configuration
+
+### Custom Environment Variables
+
+You can set additional environment variables:
+
+```json
+{
+  "mcp.servers": {
+    "wopee": {
+      "command": "wopee-mcp",
+      "args": [],
+      "env": {
+        "WOPEE_API_KEY": "your_api_key_here",
+        "WOPEE_PROJECT_UUID": "your_project_uuid_here",
+        "WOPEE_API_URL": "https://api.wopee.io/",
+        "NODE_ENV": "production",
+        "DEBUG": "wopee:*"
+      }
+    }
+  }
+}
+```
+
+### Multiple Server Instances
+
+You can run multiple instances with different configurations:
+
+```json
+{
+  "mcp.servers": {
+    "wopee-prod": {
+      "command": "wopee-mcp",
+      "args": [],
+      "env": {
+        "WOPEE_API_KEY": "prod_api_key",
+        "WOPEE_API_URL": "https://api.wopee.io/"
+      }
+    },
+    "wopee-dev": {
+      "command": "wopee-mcp",
+      "args": [],
+      "env": {
+        "WOPEE_API_KEY": "dev_api_key",
+        "WOPEE_API_URL": "https://api.dev.wopee.io/"
+      }
+    }
+  }
+}
+```
+
+### Custom Arguments
+
+You can pass custom arguments to the server:
+
+```json
+{
+  "mcp.servers": {
+    "wopee": {
+      "command": "wopee-mcp",
+      "args": ["--verbose", "--debug"],
+      "env": {
+        "WOPEE_API_KEY": "your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+## Best Practices
+
+1. **Use environment variables** for sensitive data like API keys
+2. **Test with dry-run** before using in production
+3. **Keep API keys secure** and don't commit them to version control
+4. **Use workspace-specific** configurations for different projects
+5. **Monitor logs** for debugging and performance insights
+6. **Update regularly** to get the latest features and fixes
+
+## Support
+
+For additional help:
+
+- **Documentation**: Check the main README.md
+- **Issues**: Create an issue in the repository
+- **Community**: Join the Wopee community discussions
+- **Email**: Contact support at [help@wopee.io](mailto:help@wopee.io)

package/LICENSE

@@ -0,0 +1,200 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (which shall not include communications that are clearly marked or
+      otherwise designated in writing by the copyright owner as "Not a Work").
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based upon (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and derivative works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control
+      systems, and issue tracking systems that are managed by, or on behalf
+      of, the Licensor for the purpose of discussing and improving the Work,
+      but excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Work".
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to use, reproduce, modify, merge, publish,
+      distribute, sublicense, and/or sell copies of the Work, and to
+      permit persons to whom the Work is furnished to do so, subject to
+      the following conditions:
+
+      The above copyright notice and this permission notice shall be
+      included in all copies or substantial portions of the Work.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright notice to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Support. You may choose to offer, and to
+      charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or support.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2024 Wopee Labs
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/QUICK_START.md

@@ -0,0 +1,50 @@
+# Quick Start Guide
+
+## 🚀 One-Click Installation
+
+### VS Code / Cursor
+1. `Ctrl+Shift+P` → "MCP: Install Server"
+2. Enter: `wopee-mcp`
+3. Add your API key into .env file
+
+## 🛠 Available Tools
+
+| Tool | Purpose | Example |
+|------|---------|---------|
+| `wopee_dispatch_analysis` | Start app analysis | `@wopee wopee_dispatch_analysis Project UUID: project-123` |
+| `wopee_dispatch_agent` | Execute tests | `@wopee wopee_dispatch_agent Project UUID: project-123 Suite UUID: suite-123` |
+| `wopee_generate_app_context` | Generate app context | `@wopee wopee_generate_app_context Project UUID: project-123 Suite UUID: suite-123` |
+| `wopee_generate_general_user_stories` | Generate general user stories | `@wopee wopee_generate_general_user_stories Project UUID: project-123 Suite UUID: suite-123` |
+| `wopee_generate_user_stories` | Generate detailed user stories | `@wopee wopee_generate_user_stories Project UUID: project-123 Suite UUID: suite-123` |
+| `wopee_generate_test_cases` | Generate test cases | `@wopee wopee_generate_test_cases Project UUID: project-123 Suite UUID: suite-123` |
+| `wopee_get_app_context` | Get existing app context | `@wopee wopee_get_app_context Project UUID: project-123 Suite UUID: suite-123` |
+| `wopee_get_user_stories` | Get existing user stories | `@wopee wopee_get_user_stories Project UUID: project-123 Suite UUID: suite-123` |
+| `wopee_get_test_cases` | Get existing test cases | `@wopee wopee_get_test_cases Project UUID: project-123 Suite UUID: suite-123` |
+| `wopee_fetch_analysis_suites` | Fetch all analysis suites | `@wopee wopee_fetch_analysis_suites Project UUID: project-123` |
+
+## 🔧 Manual Installation
+
+```bash
+npm install -g wopee-mcp
+```
+
+## ⚙️ Configuration
+
+Set environment variables:
+```bash
+export WOPEE_API_KEY=your_api_key_here
+export WOPEE_PROJECT_UUID=your_project_uuid_here
+```
+
+## 🆘 Troubleshooting
+
+- **Command not found**: `npm install -g wopee-mcp`
+- **API key error**: Check environment variables
+- **Connection failed**: Verify internet and API key
+- **Tools not showing**: Restart editor
+
+## 📚 More Info
+
+- [Full Integration Guide](INTEGRATION.md)
+- [Main Documentation](README.md)
+- [Publishing Guide](PUBLISHING.md)