@muuktest/maintenance-mcp 0.1.4 → 0.1.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,926 +1,88 @@
1
- # MuukTest Maintenance MCP# MuukTest Maintenance MCP# MuukTest Maintenance MCP
2
-
3
-
4
-
5
- MCP server for analyzing and repairing E2E test failures (Playwright, Cypress, Selenium, etc.) with AI-powered suggestions.
6
-
7
-
8
-
9
- ```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.
10
-
11
- User → AI Agent → MCP Server → MuukTest API → AI Analysis
12
-
13
-
14
-
15
- Reads local files
16
-
17
- (test files, screenshots, JSON)``````
18
-
19
- ```
20
-
21
- User → AI Agent → MCP Server → MuukTest API → AI AnalysisUser → AI Agent → MCP Server → MuukTest API → AI Analysis
22
-
23
- ---
24
-
25
- ↑ ↑
1
+ # MuukTest Maintenance MCP
2
+ MCP server for analyzing and repairing E2E test failures (Playwright) with AI-powered suggestions.
26
3
 
27
4
  ## Requirements
28
5
 
29
- Reads local files Reads local files
30
6
 
31
7
  Before you begin, make sure you have:
32
8
 
33
- (test files, screenshots, JSON) (test files, screenshots, JSON)
34
-
35
9
  - **Node.js 24+** — Check with `node --version`
36
10
 
37
- - **npm** — Comes with Node.js, check with `npm --version```````
38
-
39
- - **MuukTest Key** — Available in MuukTest Portal. If you don't have one yet, request access at [MuukTest](https://muuktest.com).
40
-
41
-
42
-
43
- ---
44
-
45
- ------
46
-
47
- ## Step 1: Install the MCP Server
48
-
49
-
50
-
51
- You have two options for installation:
52
-
53
- ## Requirements## Requirements
54
-
55
- ### Option A: Install from npm (when published)
56
-
57
-
58
-
59
- ```bash
60
-
61
- npm install -g muuk-maintenanceBefore you begin, make sure you have:Before you begin, make sure you have:
62
-
63
- ```
64
-
65
-
66
-
67
- Or use directly with npx (no installation needed):
68
-
69
- - **Node.js 24+** — Check with `node --version`- **Python 3.10+** — Check with `python --version` or `python3 --version`
70
-
71
- ```bash
72
-
73
- 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).
74
-
75
- ```
11
+ - **npm** — Comes with Node.js, check with `npm --version`
76
12
 
77
13
  - **MuukTest Key** — Available in MuukTest Portal. If you don't have one yet, request access at [MuukTest](https://muuktest.com).
78
14
 
79
- ### Option B: Install from source (current setup)
80
-
81
15
  ---
82
16
 
83
- ```bash
84
-
85
- # Clone the repository---
86
-
87
- git clone <repository-url>
88
-
89
- cd muukAgents-mcp## Step 1: Install uv
17
+ ## Setup
90
18
 
91
19
 
92
-
93
- # Install dependencies and build## Step 1: Install the MCP Server
94
-
95
- npm install
96
-
97
- First, check if you already have `uvx` installed:
98
-
99
- # Link globally for local development
100
-
101
- npm linkYou have two options for installation:
102
-
20
+ **Open:** Command Palette → "MCP: Open User Configuration"
21
+ ### VSCode:
103
22
  ```
104
-
105
- ```bash
106
-
107
- Verify the installation:
108
-
109
- ### Option A: Install from npm (when published)uvx --version
110
-
111
- ```bash
112
-
113
- npx muuk-maintenance```
114
-
115
- # Should start and wait for stdio input (press Ctrl+C to exit)
116
-
117
- ``````bash
118
-
119
-
120
-
121
- ---npm install -g muuk-maintenanceIf you see a version number, skip to **Step 2**. Otherwise, install `uv` for your operating system:
122
-
123
-
124
-
125
- ## Step 2: Configure Your AI Client```
126
-
127
-
128
-
129
- Choose your AI client below:**macOS / Linux:**
130
-
131
-
132
-
133
- - [VS Code / GitHub Copilot](#vs-code--github-copilot)### Option B: Install from source (current setup)```bash
134
-
135
- - [Claude Desktop](#claude-desktop)
136
-
137
- - [Claude Code (CLI)](#claude-code-cli)curl -LsSf https://astral.sh/uv/install.sh | sh
138
-
139
- - [Cursor](#cursor)
140
-
141
- ```bash```
142
-
143
- ---
144
-
145
- # Clone the repository
146
-
147
- ### VS Code / GitHub Copilot
148
-
149
- git clone <repository-url>**Windows (PowerShell):**
150
-
151
- 1. Open Command Palette: `Cmd+Shift+P` (Mac) or `Ctrl+Shift+P` (Windows/Linux)
152
-
153
- 2. Search for **"MCP: Open User Configuration"**cd muukAgents-mcp```powershell
154
-
155
- 3. Add this configuration:
156
-
157
- powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
158
-
159
- ```json
160
-
161
- {# Install dependencies and build```
162
-
23
+ {
163
24
  "inputs": [
164
-
165
- {npm install
166
-
25
+ {
167
26
  "id": "muuk_key",
168
-
169
- "type": "promptString",**Homebrew (macOS/Linux):**
170
-
171
- "description": "MuukTest Key (available in your MuukTest account)",
172
-
173
- "password": true# Link globally for local development (optional)```bash
174
-
27
+ "type": "promptString",
28
+ "description": "MuukTest Key (from your MuukTest Portal)",
29
+ "password": true
175
30
  }
176
-
177
- ],npm linkbrew install uv
178
-
31
+ ],
179
32
  "servers": {
180
-
181
- "muuk-maintenance": {``````
182
-
33
+ "muuk-maintenance": {
183
34
  "command": "npx",
184
-
185
- "args": ["-y", "muuk-maintenance"],
186
-
35
+ "args": ["-y", "@muuktest/maintenance-mcp"],
187
36
  "env": {
188
-
189
- "MUUK_KEY": "${input:muuk_key}"Verify the build:After installation, restart your terminal and verify:
190
-
37
+ "MUUK_KEY": "${input:muuk_key}"
191
38
  }
192
-
193
39
  }
194
-
195
40
  }
196
-
197
- }```bash```bash
198
-
199
- ```
200
-
201
- node build/index.jsuvx --version
202
-
203
- 4. Restart VS Code
204
-
205
- 5. When prompted, enter your MuukTest Key# Should start and wait for stdio input (press Ctrl+C to exit)```
206
-
207
-
208
-
209
- **Note**: The `-y` flag automatically accepts the npx prompt. If using local development, use:```
210
-
211
- ```json
212
-
213
- {---
214
-
215
- "command": "node",
216
-
217
- "args": ["/absolute/path/to/muukAgents-mcp/build/index.js"]---
218
-
219
41
  }
42
+ ```
220
43
 
221
- ```## Step 2: Configure Your AI Client
222
-
223
-
224
-
225
- ---## Step 2: Configure Your AI Client
226
-
227
-
228
-
229
- ### Claude DesktopChoose your AI client below:
230
-
231
-
232
-
233
- 1. Open the configuration file:Choose your AI client below:
234
-
235
- - **macOS**: `~/.config/claude/claude_desktop_config.json`
236
-
237
- - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`- [VS Code / GitHub Copilot](#vs-code--github-copilot)
238
-
239
-
240
-
241
- 2. Add this configuration:- [VS Code / GitHub Copilot](#vs-code--github-copilot)- [Claude Desktop](#claude-desktop)
242
-
243
-
244
-
245
- ```json- [Claude Desktop](#claude-desktop)- [Claude Code (CLI)](#claude-code-cli)
246
-
44
+ ### Claude Desktop
45
+ **File**: `~/.config/claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows)
46
+ ```
247
47
  {
248
-
249
- "mcpServers": {- [Claude Code (CLI)](#claude-code-cli)- [Cursor](#cursor)
250
-
48
+ "mcpServers": {
251
49
  "muuk-maintenance": {
252
-
253
- "command": "npx",- [Cursor](#cursor)
254
-
255
- "args": ["-y", "muuk-maintenance"],
256
-
257
- "env": {---
258
-
259
- "MUUK_KEY": "your-api-key-here"
260
-
261
- }---
262
-
50
+ "command": "npx",
51
+ "args": ["-y", "@muuktest/maintenance-mcp"],
52
+ "env": {
53
+ "MUUK_KEY": "their-muuktest-key-here"
54
+ }
263
55
  }
264
-
265
- }### VS Code / GitHub Copilot
266
-
56
+ }
267
57
  }
268
-
269
- ```### VS Code / GitHub Copilot
270
-
271
-
272
-
273
- 3. Replace `your-api-key-here` with your actual MuukTest Key1. Open Command Palette: `Cmd+Shift+P` (Mac) or `Ctrl+Shift+P` (Windows/Linux)
274
-
275
- 4. Restart Claude Desktop
276
-
277
- 1. Open Command Palette: `Cmd+Shift+P` (Mac) or `Ctrl+Shift+P` (Windows/Linux)2. Search for **"MCP: Open User Configuration"**
278
-
279
- **Note**: For local development, use:
280
-
281
- ```json2. Search for **"MCP: Open User Configuration"**3. Add this configuration:
282
-
283
- {
284
-
285
- "command": "node",3. Add this configuration:
286
-
287
- "args": ["/absolute/path/to/muukAgents-mcp/build/index.js"]
288
-
289
- }```json
290
-
291
- ```
292
-
293
- ```json{
294
-
295
- ---
296
-
297
- { "inputs": [
298
-
299
- ### Claude Code (CLI)
300
-
301
- "inputs": [ {
302
-
303
- Run this command in your terminal (replace YOUR_KEY with your actual key):
304
-
305
- { "id": "muuk_key",
306
-
307
- ```bash
308
-
309
- claude mcp add muuk-maintenance --transport stdio -e MUUK_KEY=YOUR_KEY -- npx -y muuk-maintenance "id": "muuk_key", "type": "promptString",
310
-
311
- ```
312
-
313
- "type": "promptString", "description": "MuukTest Key (available in your MuukTest account)",
314
-
315
- Verify the setup:
316
-
317
- "description": "MuukTest Key (available in your MuukTest account)", "password": true
318
-
319
- ```bash
320
-
321
- claude /mcp "password": true }
322
-
323
58
  ```
324
59
 
325
- } ],
326
-
327
- ---
328
-
329
- ], "servers": {
330
60
 
331
61
  ### Cursor
332
-
333
- "servers": { "muuk-maintenance": {
334
-
335
- 1. Open Cursor Settings (`Cmd+,` or `Ctrl+,`)
336
-
337
- 2. Search for **"MCP"** in settings "muuk-maintenance": { "command": "node",
338
-
339
- 3. Add this server configuration:
340
-
341
- "command": "node", "args": ["/path/to/muukAgents-mcp/build/index.js"],
342
-
62
+ **Settings** → Search "MCP"
343
63
  ```json
344
-
345
- { "args": ["/absolute/path/to/muukAgents-mcp/build/index.js"], "env": {
346
-
64
+ {
347
65
  "muuk-maintenance": {
348
-
349
- "command": "npx", "env": { "MUUK_KEY": "${input:muuk_key}"
350
-
351
- "args": ["-y", "muuk-maintenance"],
352
-
353
- "env": { "MUUK_KEY": "${input:muuk_key}" }
354
-
355
- "MUUK_KEY": "your-api-key-here"
356
-
357
- } } }
358
-
66
+ "command": "npx",
67
+ "args": ["-y", "@muuktest/maintenance-mcp"],
68
+ "env": {
69
+ "MUUK_KEY": "their-key-here"
70
+ }
359
71
  }
360
-
361
- } } }
362
-
363
- ```
364
-
365
- }}
366
-
367
- 4. Replace `your-api-key-here` with your actual MuukTest Key
368
-
369
- 5. Restart Cursor}```
370
-
371
-
372
-
373
- ---```
374
-
375
-
376
-
377
- ## Step 3: Start Using It4. Replace `/path/to/muukAgents-mcp/build/index.js` with the actual path to your installation
378
-
379
-
380
-
381
- 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
382
-
383
-
384
-
385
- **Basic usage:**5. Restart VS Code6. When prompted, enter your MuukTest Key
386
-
387
- ```
388
-
389
- Analyze the test failure with test files in ./tests/ and failure data in ./failure-artifacts/6. When prompted, enter your MuukTest Key
390
-
72
+ }
391
73
  ```
392
74
 
393
75
  ---
76
+ ## Supported Tools
394
77
 
395
- **Natural language:**
396
-
397
- ```---
398
-
399
- I have a failing E2E test. The test files are in ./e2e/booking-flow/
400
-
401
- and the failure screenshots and logs are in ./test-results/. ### Claude Desktop
402
-
403
- Please analyze and suggest a fix.
404
-
405
- ```### Claude Desktop
406
-
407
-
408
-
409
- ---1. Open the configuration file:
78
+ - `fix_selectors`: Fixes selector issues in E2E tests. Returns suggested fixes by generating an updated selector.
410
79
 
80
+ - `fix_ui_flow`: Fixes UI/flow issues in E2E tests. Returns suggested fixes by removing unnecessary steps or adding missing ones. (NOT YET IMPLEMENTED)
411
81
 
82
+ - `fix_data_dependance`: Fixes data dependence issues in E2E tests. Returns suggested fixes by updating test data used in a step. (NOT YET IMPLEMENTED)
412
83
 
413
- ## Reference1. Open the configuration file: - **macOS**: `~/.config/claude/claude_desktop_config.json`
414
-
415
-
416
-
417
- ### Available Tools - **macOS**: `~/.config/claude/claude_desktop_config.json` - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
418
-
419
-
420
-
421
- The MCP server provides three tools: - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
422
-
423
-
424
-
425
- - **fix_selectors** - Fixing selector issues in E2E tests2. Add this configuration:
426
-
427
- - **fix_ui_flow** - Fixing UI/flow issues in E2E tests
428
-
429
- - **fix_data_dependence** - Fixing data dependence issues in E2E tests2. Add this configuration:
430
-
431
-
432
-
433
- ### Environment Variables```json
434
-
435
-
436
-
437
- | Variable | Description | Default |```json{
438
-
439
- |----------|-------------|---------|
440
-
441
- | `MUUK_KEY` | Your MuukTest API key (required) | - |{ "mcpServers": {
442
-
443
- | `MUUK_API_URL` | MuukTest API endpoint | `https://oztodz5qove7dnpts5yln3ccl40bitlo.lambda-url.us-east-2.on.aws/` |
444
-
445
- | `MUUK_SIGNED_URL_ENDPOINT` | S3 signed URL endpoint | `https://bm5s428g6e.execute-api.us-east-2.amazonaws.com/v1/mcp/getSignedUrl` | "mcpServers": { "muuk-maintenance": {
446
-
447
- | `MUUK_TIMEOUT_SECS` | Request timeout in seconds | `300` |
448
-
449
- "muuk-maintenance": { "command": "node",
450
-
451
- ---
452
-
453
- "command": "node", "args": ["/path/to/muukAgents-mcp/build/index.js"],
454
-
455
- ## Development
456
-
457
- "args": ["/absolute/path/to/muukAgents-mcp/build/index.js"], "env": {
458
-
459
- ### Building
460
-
461
- "env": { "MUUK_KEY": "your-api-key-here"
462
-
463
- ```bash
464
-
465
- npm run build "MUUK_KEY": "your-api-key-here" }
466
-
467
- ```
468
-
469
- } }
470
-
471
- ### Watch mode
472
-
473
- } }
474
-
475
- ```bash
476
-
477
- npm run watch }}
478
-
479
- ```
480
-
481
- }```
482
-
483
- ### Project Structure
484
-
485
- ```
486
-
487
- ```
488
-
489
- ├── src/3. Replace `/path/to/muukAgents-mcp/build/index.js` with the actual path
490
-
491
- │ ├── index.ts # Main entry point and MCP server setup
492
-
493
- │ ├── 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
494
-
495
- │ └── utils.ts # Utility functions (zip, S3 upload, etc.)
496
-
497
- ├── build/ # Compiled JavaScript (generated)4. Replace `your-api-key-here` with your actual MuukTest Key5. Restart Claude Desktop
498
-
499
- ├── package.json
500
-
501
- ├── tsconfig.json5. Restart Claude Desktop
502
-
503
- └── .nvmrc # Node version specification
504
-
505
- ```---
506
-
507
-
508
-
509
- ------
510
-
511
-
512
-
513
- ## Troubleshooting### Claude Code (CLI)
514
-
515
-
516
-
517
- ### "Cannot find module" or "Command not found"### Claude Code (CLI)
518
-
519
-
520
-
521
- If using `npx`:Run this command in your terminal (replace paths and key accordingly):
522
-
523
- - Make sure npm is in your PATH: `which npm`
524
-
525
- - Try with full path: `npx muuk-maintenance`Run this command in your terminal (replace paths and key accordingly):
526
-
527
- - Clear npx cache: `npx clear-npx-cache`
528
-
529
- ```bash
530
-
531
- If using local development:
532
-
533
- - 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
534
-
535
- - Verify the path to `build/index.js` is correct
536
-
537
- - 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```
538
-
539
-
540
-
541
- ### "Invalid or missing MUUK_KEY"```
542
-
543
-
544
-
545
- - Verify your key is correct in your MuukTest accountVerify the setup:
546
-
547
- - Check that the environment variable is properly set in your configuration
548
-
549
- - For VS Code: make sure you're entering the key when promptedVerify the setup:
550
-
551
-
552
-
553
- ### MCP server not appearing in your AI client```bash
554
-
555
-
556
-
557
- - Restart your AI client completely```bashclaude /mcp
558
-
559
- - Verify the JSON configuration syntax is valid (use a JSON validator)
560
-
561
- - Test that the server starts manually:claude /mcp```
562
-
563
- ```bash
564
-
565
- npx muuk-maintenance```
566
-
567
- # Or: node /path/to/build/index.js
568
-
569
- ```---
570
-
571
- It should start and wait for stdio input. Press Ctrl+C to exit.
572
-
573
- ---
574
-
575
- ### Node version issues
576
-
577
- ### Cursor
578
-
579
- If you're using nvm, make sure you're on Node 24:
580
-
581
- ### Cursor
582
-
583
- ```bash
584
-
585
- nvm use 241. Open Cursor Settings (`Cmd+,` or `Ctrl+,`)
586
-
587
- # Or if not installed
588
-
589
- nvm install 241. Open Cursor Settings (`Cmd+,` or `Ctrl+,`)2. Search for **"MCP"** in settings
590
-
591
- nvm use 24
592
-
593
- ```2. Search for **"MCP"** in settings3. Add this server configuration:
594
-
595
-
596
-
597
- The repository includes an `.nvmrc` file, so you can also just run:3. Add this server configuration:
598
-
599
- ```bash
600
-
601
- nvm use```json
602
-
603
- ```
604
-
605
- ```json{
606
-
607
- ### TypeScript compilation errors
608
-
609
- { "muuk-maintenance": {
610
-
611
- Make sure you have the correct dependencies installed:
612
-
613
- "muuk-maintenance": { "command": "node",
614
-
615
- ```bash
616
-
617
- npm install "command": "node", "args": ["/path/to/muukAgents-mcp/build/index.js"],
618
-
619
- ```
620
-
621
- "args": ["/absolute/path/to/muukAgents-mcp/build/index.js"], "env": {
622
-
623
- If you see type errors, try cleaning and rebuilding:
624
-
625
- "env": { "MUUK_KEY": "your-api-key-here"
626
-
627
- ```bash
628
-
629
- rm -rf build node_modules "MUUK_KEY": "your-api-key-here" }
630
-
631
- npm install
632
-
633
- npm run build } }
634
-
635
- ```
636
-
637
- }}
638
-
639
- ### npx prompts or hangs
640
-
641
- }```
642
-
643
- If npx asks for confirmation, use the `-y` flag:
644
-
645
- ```bash```
646
-
647
- npx -y muuk-maintenance
648
-
649
- ```4. Replace `/path/to/muukAgents-mcp/build/index.js` with the actual path
650
-
651
-
652
-
653
- 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
654
-
655
-
656
-
657
- ---5. Replace `your-api-key-here` with your actual MuukTest Key6. Restart Cursor
658
-
659
-
660
-
661
- ## Publishing to npm6. Restart Cursor
662
-
663
-
664
-
665
- To publish this package to npm (for maintainers):---
666
-
667
-
668
-
669
- ```bash---
670
-
671
- # 1. Login to npm
672
-
673
- npm login## Step 3: Start Using It
674
-
675
-
676
-
677
- # 2. Update version in package.json## Step 3: Start Using It
678
-
679
- npm version patch # or minor, or major
680
-
681
- Once configured, ask your AI agent to analyze test failures:
682
-
683
- # 3. Publish
684
-
685
- npm publish --access publicOnce configured, ask your AI agent to analyze test failures:
686
-
687
- ```
688
-
689
- **Basic usage:**
690
-
691
- After publishing, users can install with:
692
-
693
- ```bash**Basic usage:**```
694
-
695
- npm install -g muuk-maintenance
696
-
697
- ``````Analyze the test failure with test files in ./tests/ and failure data in ./failure-artifacts/
698
-
699
-
700
-
701
- Or use directly:Analyze the test failure with test files in ./tests/ and failure data in ./failure-artifacts/```
702
-
703
- ```bash
704
-
705
- npx muuk-maintenance```
706
-
707
- ```
708
-
709
- **Natural language:**
710
-
711
- ---
712
-
713
- **Natural language:**```
84
+ ---
714
85
 
715
86
  ## Support
716
87
 
717
- ```I have a failing E2E test. The test files are in ./e2e/booking-flow/
718
-
719
- For issues and questions:
720
-
721
- - 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/.
722
-
723
- - Check the [GitHub Issues](https://github.com/muuklabs/muukAgents-mcp/issues)
724
-
725
- and the failure screenshots and logs are in ./test-results/. Please analyze and suggest a fix.
726
-
727
- ---
728
-
729
- Please analyze and suggest a fix.```
730
-
731
- ## License
732
-
733
- ```
734
-
735
- MIT
736
-
737
- ---
738
-
739
- ---
740
-
741
- ## Reference
742
-
743
- ## Reference
744
-
745
- ### Environment Variables
746
-
747
- ### Available Tools
748
-
749
- | Variable | Description |
750
-
751
- The MCP server provides three tools:|----------|-------------|
752
-
753
- | `MUUK_KEY` | Your MuukTest API key |
754
-
755
- - **fix_selectors** - Fixing selector issues in E2E tests
756
-
757
- - **fix_ui_flow** - Fixing UI/flow issues in E2E tests ---
758
-
759
- - **fix_data_dependence** - Fixing data dependence issues in E2E tests
760
-
761
- ## Troubleshooting
762
-
763
- ### Environment Variables
764
-
765
- ### "Cannot find module" or "Command not found"
766
-
767
- | Variable | Description | Default |
768
-
769
- |----------|-------------|---------|Your AI client can't find the Node.js executable or the built files.
770
-
771
- | `MUUK_KEY` | Your MuukTest API key (required) | - |
772
-
773
- | `MUUK_API_URL` | MuukTest API endpoint | `https://oztodz5qove7dnpts5yln3ccl40bitlo.lambda-url.us-east-2.on.aws/` |1. Make sure you've built the project:
774
-
775
- | `MUUK_SIGNED_URL_ENDPOINT` | S3 signed URL endpoint | `https://bm5s428g6e.execute-api.us-east-2.amazonaws.com/v1/mcp/getSignedUrl` | ```bash
776
-
777
- | `MUUK_TIMEOUT_SECS` | Request timeout in seconds | `300` | npm run build
778
-
779
- ```
780
-
781
- ---
782
-
783
- 2. Verify the path to `build/index.js` is correct in your configuration
784
-
785
- ## Development
786
-
787
- 3. Use absolute paths in your MCP configuration
788
-
789
- ### Building
790
-
791
- ### "Invalid or missing MUUK_KEY"
792
-
793
- ```bash
794
-
795
- npm run build- Verify your key is correct in your MuukTest account
796
-
797
- ```- Check that the environment variable is properly set in your configuration
798
-
799
- - For VS Code: make sure you're entering the key when prompted
800
-
801
- ### Watch mode
802
-
803
- ### MCP server not appearing in your AI client
804
-
805
- ```bash
806
-
807
- npm run watch- Restart your AI client completely
808
-
809
- ```- Verify the JSON configuration syntax is valid
810
-
811
- - Check that `node build/index.js` runs successfully in your terminal (it should wait for stdio input)
812
-
813
- ### Project Structure- Make sure Node.js 24+ is installed and in your PATH
814
-
815
-
816
-
817
- ```### Node version issues
818
-
819
- ├── src/
820
-
821
- │ ├── index.ts # Main entry point and MCP server setupIf you're using nvm, make sure you're on Node 24:
822
-
823
- │ ├── server.ts # Core analysis logic
824
-
825
- │ └── utils.ts # Utility functions (zip, S3 upload, etc.)```bash
826
-
827
- ├── build/ # Compiled JavaScript (generated)nvm use 24
828
-
829
- ├── package.json# Or if not installed
830
-
831
- ├── tsconfig.jsonnvm install 24
832
-
833
- └── .nvmrc # Node version specificationnvm use 24
834
-
835
- ``````
836
-
837
-
838
-
839
- ------
840
-
841
-
842
-
843
- ## Troubleshooting## Support
844
-
845
-
846
-
847
- ### "Cannot find module" or "Command not found"TBD
848
-
849
- Your AI client can't find the Node.js executable or the built files.
850
-
851
- 1. Make sure you've built the project:
852
- ```bash
853
- npm run build
854
- ```
855
-
856
- 2. Verify the path to `build/index.js` is correct in your configuration
857
-
858
- 3. Use **absolute paths** in your MCP configuration (not relative paths like `~/` or `./`)
859
-
860
- 4. Check Node.js is in your PATH:
861
- ```bash
862
- which node # macOS/Linux
863
- where node # Windows
864
- ```
865
-
866
- ### "Invalid or missing MUUK_KEY"
867
-
868
- - Verify your key is correct in your MuukTest account
869
- - Check that the environment variable is properly set in your configuration
870
- - For VS Code: make sure you're entering the key when prompted
871
-
872
- ### MCP server not appearing in your AI client
873
-
874
- - Restart your AI client completely
875
- - Verify the JSON configuration syntax is valid (use a JSON validator)
876
- - Test that the server starts manually:
877
- ```bash
878
- node /path/to/build/index.js
879
- ```
880
- It should start and wait for stdio input. Press Ctrl+C to exit.
881
-
882
- ### Node version issues
883
-
884
- If you're using nvm, make sure you're on Node 24:
885
-
886
- ```bash
887
- nvm use 24
888
- # Or if not installed
889
- nvm install 24
890
- nvm use 24
891
- ```
892
-
893
- The repository includes an `.nvmrc` file, so you can also just run:
894
- ```bash
895
- nvm use
896
- ```
897
-
898
- ### TypeScript compilation errors
899
-
900
- Make sure you have the correct dependencies installed:
901
-
902
- ```bash
903
- npm install
904
- ```
905
-
906
- If you see type errors, try cleaning and rebuilding:
907
-
908
- ```bash
909
- rm -rf build node_modules
910
- npm install
911
- npm run build
912
- ```
913
-
914
- ---
915
-
916
- ## Support
917
-
918
- For issues and questions:
919
- - Visit [MuukTest](https://muuktest.com)
920
- - Check the [GitHub Issues](https://github.com/muuklabs/muukAgents-mcp/issues)
921
-
922
- ---
923
-
924
- ## License
925
-
926
- MIT
88
+ - Contact [MuukTest](https://muuktest.com)
package/build/index.js CHANGED
@@ -16,7 +16,7 @@ const SIGNED_URL_ENDPOINT = process.env.MUUK_SIGNED_URL_ENDPOINT ||
16
16
  // Create server instance
17
17
  const server = new Server({
18
18
  name: "muuk-maintenance",
19
- version: "0.1.4",
19
+ version: "0.1.6",
20
20
  }, {
21
21
  capabilities: {
22
22
  tools: {},
@@ -48,26 +48,16 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
48
48
  tools: [
49
49
  {
50
50
  name: "fix_selectors",
51
- description: "Fixing selector issues in E2E tests. Returns suggested fixes by generating an updated selector.",
51
+ description: "Fixes selector issues in E2E tests. Returns suggested fixes by generating an updated selector.",
52
52
  inputSchema: INPUT_SCHEMA,
53
- },
54
- {
55
- name: "fix_ui_flow",
56
- description: "Fixing UI/flow issues in E2E tests. Returns suggested fixes by removing unnecessary steps or adding missing ones.",
57
- inputSchema: INPUT_SCHEMA,
58
- },
59
- {
60
- name: "fix_data_dependence",
61
- description: "Fixing data dependence issues in E2E tests. Returns suggested fixes by updating test data used in a step.",
62
- inputSchema: INPUT_SCHEMA,
63
- },
53
+ }
64
54
  ],
65
55
  };
66
56
  });
67
57
  // Handle tool calls
68
58
  server.setRequestHandler(CallToolRequestSchema, async (request) => {
69
59
  const { name, arguments: args } = request.params;
70
- if (!["fix_selectors", "fix_ui_flow", "fix_data_dependence"].includes(name)) {
60
+ if (!["fix_selectors"].includes(name)) {
71
61
  return {
72
62
  content: [
73
63
  {
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
package/package.json CHANGED
@@ -1,9 +1,11 @@
1
1
  {
2
2
  "name": "@muuktest/maintenance-mcp",
3
- "version": "0.1.4",
3
+ "version": "0.1.6",
4
4
  "description": "MCP server for analyzing and repairing E2E test failures",
5
5
  "type": "module",
6
- "bin": "./build/index.js",
6
+ "bin": {
7
+ "maintenance-mcp": "build/index.js"
8
+ },
7
9
  "files": [
8
10
  "build/**/*",
9
11
  "README.md",