@muuktest/maintenance-mcp 0.1.3

package/README.md

@@ -0,0 +1,926 @@
+# MuukTest Maintenance MCP# MuukTest Maintenance MCP# MuukTest Maintenance MCP
+
+
+
+MCP server for analyzing and repairing E2E test failures (Playwright, Cypress, Selenium, etc.) with AI-powered suggestions.
+
+
+
+```MCP server for analyzing and repairing E2E test failures (Playwright, Cypress, Selenium, etc.) with AI-powered suggestions.MCP server for analyzing and repairing E2E test failures (Playwright, Cypress, Selenium, etc.) with AI-powered suggestions.
+
+User → AI Agent → MCP Server → MuukTest API → AI Analysis
+
+                     ↑
+
+              Reads local files
+
+              (test files, screenshots, JSON)``````
+
+```
+
+User → AI Agent → MCP Server → MuukTest API → AI AnalysisUser → AI Agent → MCP Server → MuukTest API → AI Analysis
+
+---
+
+                     ↑                     ↑
+
+## Requirements
+
+              Reads local files              Reads local files
+
+Before you begin, make sure you have:
+
+              (test files, screenshots, JSON)              (test files, screenshots, JSON)
+
+- **Node.js 24+** — Check with `node --version`
+
+- **npm** — Comes with Node.js, check with `npm --version```````
+
+- **MuukTest Key** — Available in MuukTest Portal. If you don't have one yet, request access at [MuukTest](https://muuktest.com).
+
+
+
+---
+
+------
+
+## Step 1: Install the MCP Server
+
+
+
+You have two options for installation:
+
+## Requirements## Requirements
+
+### Option A: Install from npm (when published)
+
+
+
+```bash
+
+npm install -g muuk-maintenanceBefore you begin, make sure you have:Before you begin, make sure you have:
+
+```
+
+
+
+Or use directly with npx (no installation needed):
+
+- **Node.js 24+** — Check with `node --version`- **Python 3.10+** — Check with `python --version` or `python3 --version`
+
+```bash
+
+npx muuk-maintenance- **npm** — Comes with Node.js, check with `npm --version`- **MuukTest Key** — Available in MuukTest Portal. If you don’t have one yet, request access at [MuukTest](https://muuktest.com).
+
+```
+
+- **MuukTest Key** — Available in MuukTest Portal. If you don't have one yet, request access at [MuukTest](https://muuktest.com).
+
+### Option B: Install from source (current setup)
+
+---
+
+```bash
+
+# Clone the repository---
+
+git clone <repository-url>
+
+cd muukAgents-mcp## Step 1: Install uv
+
+
+
+# Install dependencies and build## Step 1: Install the MCP Server
+
+npm install
+
+First, check if you already have `uvx` installed:
+
+# Link globally for local development
+
+npm linkYou have two options for installation:
+
+```
+
+```bash
+
+Verify the installation:
+
+### Option A: Install from npm (when published)uvx --version
+
+```bash
+
+npx muuk-maintenance```
+
+# Should start and wait for stdio input (press Ctrl+C to exit)
+
+``````bash
+
+
+
+---npm install -g muuk-maintenanceIf you see a version number, skip to **Step 2**. Otherwise, install `uv` for your operating system:
+
+
+
+## Step 2: Configure Your AI Client```
+
+
+
+Choose your AI client below:**macOS / Linux:**
+
+
+
+- [VS Code / GitHub Copilot](#vs-code--github-copilot)### Option B: Install from source (current setup)```bash
+
+- [Claude Desktop](#claude-desktop)
+
+- [Claude Code (CLI)](#claude-code-cli)curl -LsSf https://astral.sh/uv/install.sh | sh
+
+- [Cursor](#cursor)
+
+```bash```
+
+---
+
+# Clone the repository
+
+### VS Code / GitHub Copilot
+
+git clone <repository-url>**Windows (PowerShell):**
+
+1. Open Command Palette: `Cmd+Shift+P` (Mac) or `Ctrl+Shift+P` (Windows/Linux)
+
+2. Search for **"MCP: Open User Configuration"**cd muukAgents-mcp```powershell
+
+3. Add this configuration:
+
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+
+```json
+
+{# Install dependencies and build```
+
+  "inputs": [
+
+    {npm install
+
+      "id": "muuk_key",
+
+      "type": "promptString",**Homebrew (macOS/Linux):**
+
+      "description": "MuukTest Key (available in your MuukTest account)",
+
+      "password": true# Link globally for local development (optional)```bash
+
+    }
+
+  ],npm linkbrew install uv
+
+  "servers": {
+
+    "muuk-maintenance": {``````
+
+      "command": "npx",
+
+      "args": ["-y", "muuk-maintenance"],
+
+      "env": {
+
+        "MUUK_KEY": "${input:muuk_key}"Verify the build:After installation, restart your terminal and verify:
+
+      }
+
+    }
+
+  }
+
+}```bash```bash
+
+```
+
+node build/index.jsuvx --version
+
+4. Restart VS Code
+
+5. When prompted, enter your MuukTest Key# Should start and wait for stdio input (press Ctrl+C to exit)```
+
+
+
+**Note**: The `-y` flag automatically accepts the npx prompt. If using local development, use:```
+
+```json
+
+{---
+
+  "command": "node",
+
+  "args": ["/absolute/path/to/muukAgents-mcp/build/index.js"]---
+
+}
+
+```## Step 2: Configure Your AI Client
+
+
+
+---## Step 2: Configure Your AI Client
+
+
+
+### Claude DesktopChoose your AI client below:
+
+
+
+1. Open the configuration file:Choose your AI client below:
+
+   - **macOS**: `~/.config/claude/claude_desktop_config.json`
+
+   - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`- [VS Code / GitHub Copilot](#vs-code--github-copilot)
+
+
+
+2. Add this configuration:- [VS Code / GitHub Copilot](#vs-code--github-copilot)- [Claude Desktop](#claude-desktop)
+
+
+
+```json- [Claude Desktop](#claude-desktop)- [Claude Code (CLI)](#claude-code-cli)
+
+{
+
+  "mcpServers": {- [Claude Code (CLI)](#claude-code-cli)- [Cursor](#cursor)
+
+    "muuk-maintenance": {
+
+      "command": "npx",- [Cursor](#cursor)
+
+      "args": ["-y", "muuk-maintenance"],
+
+      "env": {---
+
+        "MUUK_KEY": "your-api-key-here"
+
+      }---
+
+    }
+
+  }### VS Code / GitHub Copilot
+
+}
+
+```### VS Code / GitHub Copilot
+
+
+
+3. Replace `your-api-key-here` with your actual MuukTest Key1. Open Command Palette: `Cmd+Shift+P` (Mac) or `Ctrl+Shift+P` (Windows/Linux)
+
+4. Restart Claude Desktop
+
+1. Open Command Palette: `Cmd+Shift+P` (Mac) or `Ctrl+Shift+P` (Windows/Linux)2. Search for **"MCP: Open User Configuration"**
+
+**Note**: For local development, use:
+
+```json2. Search for **"MCP: Open User Configuration"**3. Add this configuration:
+
+{
+
+  "command": "node",3. Add this configuration:
+
+  "args": ["/absolute/path/to/muukAgents-mcp/build/index.js"]
+
+}```json
+
+```
+
+```json{
+
+---
+
+{  "inputs": [
+
+### Claude Code (CLI)
+
+  "inputs": [    {
+
+Run this command in your terminal (replace YOUR_KEY with your actual key):
+
+    {      "id": "muuk_key",
+
+```bash
+
+claude mcp add muuk-maintenance --transport stdio -e MUUK_KEY=YOUR_KEY -- npx -y muuk-maintenance      "id": "muuk_key",      "type": "promptString",
+
+```
+
+      "type": "promptString",      "description": "MuukTest Key (available in your MuukTest account)",
+
+Verify the setup:
+
+      "description": "MuukTest Key (available in your MuukTest account)",      "password": true
+
+```bash
+
+claude /mcp      "password": true    }
+
+```
+
+    }  ],
+
+---
+
+  ],  "servers": {
+
+### Cursor
+
+  "servers": {    "muuk-maintenance": {
+
+1. Open Cursor Settings (`Cmd+,` or `Ctrl+,`)
+
+2. Search for **"MCP"** in settings    "muuk-maintenance": {      "command": "node",
+
+3. Add this server configuration:
+
+      "command": "node",      "args": ["/path/to/muukAgents-mcp/build/index.js"],
+
+```json
+
+{      "args": ["/absolute/path/to/muukAgents-mcp/build/index.js"],      "env": {
+
+  "muuk-maintenance": {
+
+    "command": "npx",      "env": {        "MUUK_KEY": "${input:muuk_key}"
+
+    "args": ["-y", "muuk-maintenance"],
+
+    "env": {        "MUUK_KEY": "${input:muuk_key}"      }
+
+      "MUUK_KEY": "your-api-key-here"
+
+    }      }    }
+
+  }
+
+}    }  }
+
+```
+
+  }}
+
+4. Replace `your-api-key-here` with your actual MuukTest Key
+
+5. Restart Cursor}```
+
+
+
+---```
+
+
+
+## Step 3: Start Using It4. Replace `/path/to/muukAgents-mcp/build/index.js` with the actual path to your installation
+
+
+
+Once configured, ask your AI agent to analyze test failures:4. Replace `/absolute/path/to/muukAgents-mcp/build/index.js` with the actual absolute path to your installation5. Restart VS Code
+
+
+
+**Basic usage:**5. Restart VS Code6. When prompted, enter your MuukTest Key
+
+```
+
+Analyze the test failure with test files in ./tests/ and failure data in ./failure-artifacts/6. When prompted, enter your MuukTest Key
+
+```
+
+---
+
+**Natural language:**
+
+```---
+
+I have a failing E2E test. The test files are in ./e2e/booking-flow/ 
+
+and the failure screenshots and logs are in ./test-results/. ### Claude Desktop
+
+Please analyze and suggest a fix.
+
+```### Claude Desktop
+
+
+
+---1. Open the configuration file:
+
+
+
+## Reference1. Open the configuration file:   - **macOS**: `~/.config/claude/claude_desktop_config.json`
+
+
+
+### Available Tools   - **macOS**: `~/.config/claude/claude_desktop_config.json`   - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+
+
+The MCP server provides three tools:   - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+
+
+- **fix_selectors** - Fixing selector issues in E2E tests2. Add this configuration:
+
+- **fix_ui_flow** - Fixing UI/flow issues in E2E tests  
+
+- **fix_data_dependence** - Fixing data dependence issues in E2E tests2. Add this configuration:
+
+
+
+### Environment Variables```json
+
+
+
+| Variable | Description | Default |```json{
+
+|----------|-------------|---------|
+
+| `MUUK_KEY` | Your MuukTest API key (required) | - |{  "mcpServers": {
+
+| `MUUK_API_URL` | MuukTest API endpoint | `https://oztodz5qove7dnpts5yln3ccl40bitlo.lambda-url.us-east-2.on.aws/` |
+
+| `MUUK_SIGNED_URL_ENDPOINT` | S3 signed URL endpoint | `https://bm5s428g6e.execute-api.us-east-2.amazonaws.com/v1/mcp/getSignedUrl` |  "mcpServers": {    "muuk-maintenance": {
+
+| `MUUK_TIMEOUT_SECS` | Request timeout in seconds | `300` |
+
+    "muuk-maintenance": {      "command": "node",
+
+---
+
+      "command": "node",      "args": ["/path/to/muukAgents-mcp/build/index.js"],
+
+## Development
+
+      "args": ["/absolute/path/to/muukAgents-mcp/build/index.js"],      "env": {
+
+### Building
+
+      "env": {        "MUUK_KEY": "your-api-key-here"
+
+```bash
+
+npm run build        "MUUK_KEY": "your-api-key-here"      }
+
+```
+
+      }    }
+
+### Watch mode
+
+    }  }
+
+```bash
+
+npm run watch  }}
+
+```
+
+}```
+
+### Project Structure
+
+```
+
+```
+
+├── src/3. Replace `/path/to/muukAgents-mcp/build/index.js` with the actual path
+
+│   ├── index.ts      # Main entry point and MCP server setup
+
+│   ├── server.ts     # Core analysis logic3. Replace `/absolute/path/to/muukAgents-mcp/build/index.js` with the actual absolute path4. Replace `your-api-key-here` with your actual MuukTest Key
+
+│   └── utils.ts      # Utility functions (zip, S3 upload, etc.)
+
+├── build/            # Compiled JavaScript (generated)4. Replace `your-api-key-here` with your actual MuukTest Key5. Restart Claude Desktop
+
+├── package.json
+
+├── tsconfig.json5. Restart Claude Desktop
+
+└── .nvmrc           # Node version specification
+
+```---
+
+
+
+------
+
+
+
+## Troubleshooting### Claude Code (CLI)
+
+
+
+### "Cannot find module" or "Command not found"### Claude Code (CLI)
+
+
+
+If using `npx`:Run this command in your terminal (replace paths and key accordingly):
+
+- Make sure npm is in your PATH: `which npm`
+
+- Try with full path: `npx muuk-maintenance`Run this command in your terminal (replace paths and key accordingly):
+
+- Clear npx cache: `npx clear-npx-cache`
+
+```bash
+
+If using local development:
+
+- Make sure you've built the project: `npm run build````bashclaude mcp add muuk-maintenance --transport stdio -e MUUK_KEY=YOUR_KEY -- node /path/to/muukAgents-mcp/build/index.js
+
+- Verify the path to `build/index.js` is correct
+
+- Use **absolute paths** in your MCP configurationclaude mcp add muuk-maintenance --transport stdio -e MUUK_KEY=YOUR_KEY -- node /absolute/path/to/muukAgents-mcp/build/index.js```
+
+
+
+### "Invalid or missing MUUK_KEY"```
+
+
+
+- Verify your key is correct in your MuukTest accountVerify the setup:
+
+- Check that the environment variable is properly set in your configuration
+
+- For VS Code: make sure you're entering the key when promptedVerify the setup:
+
+
+
+### MCP server not appearing in your AI client```bash
+
+
+
+- Restart your AI client completely```bashclaude /mcp
+
+- Verify the JSON configuration syntax is valid (use a JSON validator)
+
+- Test that the server starts manually:claude /mcp```
+
+  ```bash
+
+  npx muuk-maintenance```
+
+  # Or: node /path/to/build/index.js
+
+  ```---
+
+  It should start and wait for stdio input. Press Ctrl+C to exit.
+
+---
+
+### Node version issues
+
+### Cursor
+
+If you're using nvm, make sure you're on Node 24:
+
+### Cursor
+
+```bash
+
+nvm use 241. Open Cursor Settings (`Cmd+,` or `Ctrl+,`)
+
+# Or if not installed
+
+nvm install 241. Open Cursor Settings (`Cmd+,` or `Ctrl+,`)2. Search for **"MCP"** in settings
+
+nvm use 24
+
+```2. Search for **"MCP"** in settings3. Add this server configuration:
+
+
+
+The repository includes an `.nvmrc` file, so you can also just run:3. Add this server configuration:
+
+```bash
+
+nvm use```json
+
+```
+
+```json{
+
+### TypeScript compilation errors
+
+{  "muuk-maintenance": {
+
+Make sure you have the correct dependencies installed:
+
+  "muuk-maintenance": {    "command": "node",
+
+```bash
+
+npm install    "command": "node",    "args": ["/path/to/muukAgents-mcp/build/index.js"],
+
+```
+
+    "args": ["/absolute/path/to/muukAgents-mcp/build/index.js"],    "env": {
+
+If you see type errors, try cleaning and rebuilding:
+
+    "env": {      "MUUK_KEY": "your-api-key-here"
+
+```bash
+
+rm -rf build node_modules      "MUUK_KEY": "your-api-key-here"    }
+
+npm install
+
+npm run build    }  }
+
+```
+
+  }}
+
+### npx prompts or hangs
+
+}```
+
+If npx asks for confirmation, use the `-y` flag:
+
+```bash```
+
+npx -y muuk-maintenance
+
+```4. Replace `/path/to/muukAgents-mcp/build/index.js` with the actual path
+
+
+
+This is already included in the configuration examples above.4. Replace `/absolute/path/to/muukAgents-mcp/build/index.js` with the actual absolute path5. Replace `your-api-key-here` with your actual MuukTest Key
+
+
+
+---5. Replace `your-api-key-here` with your actual MuukTest Key6. Restart Cursor
+
+
+
+## Publishing to npm6. Restart Cursor
+
+
+
+To publish this package to npm (for maintainers):---
+
+
+
+```bash---
+
+# 1. Login to npm
+
+npm login## Step 3: Start Using It
+
+
+
+# 2. Update version in package.json## Step 3: Start Using It
+
+npm version patch  # or minor, or major
+
+Once configured, ask your AI agent to analyze test failures:
+
+# 3. Publish
+
+npm publish --access publicOnce configured, ask your AI agent to analyze test failures:
+
+```
+
+**Basic usage:**
+
+After publishing, users can install with:
+
+```bash**Basic usage:**```
+
+npm install -g muuk-maintenance
+
+``````Analyze the test failure with test files in ./tests/ and failure data in ./failure-artifacts/
+
+
+
+Or use directly:Analyze the test failure with test files in ./tests/ and failure data in ./failure-artifacts/```
+
+```bash
+
+npx muuk-maintenance```
+
+```
+
+**Natural language:**
+
+---
+
+**Natural language:**```
+
+## Support
+
+```I have a failing E2E test. The test files are in ./e2e/booking-flow/ 
+
+For issues and questions:
+
+- Visit [MuukTest](https://muuktest.com)I have a failing E2E test. The test files are in ./e2e/booking-flow/ and the failure screenshots and logs are in ./test-results/. 
+
+- Check the [GitHub Issues](https://github.com/muuklabs/muukAgents-mcp/issues)
+
+and the failure screenshots and logs are in ./test-results/. Please analyze and suggest a fix.
+
+---
+
+Please analyze and suggest a fix.```
+
+## License
+
+```
+
+MIT
+
+---
+
+---
+
+## Reference
+
+## Reference
+
+### Environment Variables
+
+### Available Tools
+
+| Variable | Description |
+
+The MCP server provides three tools:|----------|-------------|
+
+| `MUUK_KEY` | Your MuukTest API key |
+
+- **fix_selectors** - Fixing selector issues in E2E tests
+
+- **fix_ui_flow** - Fixing UI/flow issues in E2E tests  ---
+
+- **fix_data_dependence** - Fixing data dependence issues in E2E tests
+
+## Troubleshooting
+
+### Environment Variables
+
+### "Cannot find module" or "Command not found"
+
+| Variable | Description | Default |
+
+|----------|-------------|---------|Your AI client can't find the Node.js executable or the built files.
+
+| `MUUK_KEY` | Your MuukTest API key (required) | - |
+
+| `MUUK_API_URL` | MuukTest API endpoint | `https://oztodz5qove7dnpts5yln3ccl40bitlo.lambda-url.us-east-2.on.aws/` |1. Make sure you've built the project:
+
+| `MUUK_SIGNED_URL_ENDPOINT` | S3 signed URL endpoint | `https://bm5s428g6e.execute-api.us-east-2.amazonaws.com/v1/mcp/getSignedUrl` |   ```bash
+
+| `MUUK_TIMEOUT_SECS` | Request timeout in seconds | `300` |   npm run build
+
+   ```
+
+---
+
+2. Verify the path to `build/index.js` is correct in your configuration
+
+## Development
+
+3. Use absolute paths in your MCP configuration
+
+### Building
+
+### "Invalid or missing MUUK_KEY"
+
+```bash
+
+npm run build- Verify your key is correct in your MuukTest account
+
+```- Check that the environment variable is properly set in your configuration
+
+- For VS Code: make sure you're entering the key when prompted
+
+### Watch mode
+
+### MCP server not appearing in your AI client
+
+```bash
+
+npm run watch- Restart your AI client completely
+
+```- Verify the JSON configuration syntax is valid
+
+- Check that `node build/index.js` runs successfully in your terminal (it should wait for stdio input)
+
+### Project Structure- Make sure Node.js 24+ is installed and in your PATH
+
+
+
+```### Node version issues
+
+├── src/
+
+│   ├── index.ts      # Main entry point and MCP server setupIf you're using nvm, make sure you're on Node 24:
+
+│   ├── server.ts     # Core analysis logic
+
+│   └── utils.ts      # Utility functions (zip, S3 upload, etc.)```bash
+
+├── build/            # Compiled JavaScript (generated)nvm use 24
+
+├── package.json# Or if not installed
+
+├── tsconfig.jsonnvm install 24
+
+└── .nvmrc           # Node version specificationnvm use 24
+
+``````
+
+
+
+------
+
+
+
+## Troubleshooting## Support
+
+
+
+### "Cannot find module" or "Command not found"TBD
+
+Your AI client can't find the Node.js executable or the built files.
+
+1. Make sure you've built the project:
+   ```bash
+   npm run build
+   ```
+
+2. Verify the path to `build/index.js` is correct in your configuration
+
+3. Use **absolute paths** in your MCP configuration (not relative paths like `~/` or `./`)
+
+4. Check Node.js is in your PATH:
+   ```bash
+   which node  # macOS/Linux
+   where node  # Windows
+   ```
+
+### "Invalid or missing MUUK_KEY"
+
+- Verify your key is correct in your MuukTest account
+- Check that the environment variable is properly set in your configuration
+- For VS Code: make sure you're entering the key when prompted
+
+### MCP server not appearing in your AI client
+
+- Restart your AI client completely
+- Verify the JSON configuration syntax is valid (use a JSON validator)
+- Test that the server starts manually:
+  ```bash
+  node /path/to/build/index.js
+  ```
+  It should start and wait for stdio input. Press Ctrl+C to exit.
+
+### Node version issues
+
+If you're using nvm, make sure you're on Node 24:
+
+```bash
+nvm use 24
+# Or if not installed
+nvm install 24
+nvm use 24
+```
+
+The repository includes an `.nvmrc` file, so you can also just run:
+```bash
+nvm use
+```
+
+### TypeScript compilation errors
+
+Make sure you have the correct dependencies installed:
+
+```bash
+npm install
+```
+
+If you see type errors, try cleaning and rebuilding:
+
+```bash
+rm -rf build node_modules
+npm install
+npm run build
+```
+
+---
+
+## Support
+
+For issues and questions:
+- Visit [MuukTest](https://muuktest.com)
+- Check the [GitHub Issues](https://github.com/muuklabs/muukAgents-mcp/issues)
+
+---
+
+## License
+
+MIT