@muggleai/works 2.0.0 → 2.0.2

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.
Files changed (2) hide show
  1. package/README.md +348 -210
  2. package/package.json +8 -3
package/README.md CHANGED
@@ -1,294 +1,357 @@
1
- # @muggleai/works
1
+ # muggle-ai-works
2
2
 
3
- Unified MCP server for Muggle AI - combines Cloud QA and Local Testing tools into a single package.
3
+ **Ship quality products, not just code.** AI-powered QA that validates your app's user experience — from Claude Code and Cursor to PR.
4
4
 
5
- ## Installation
5
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
6
+ [![npm](https://img.shields.io/npm/v/@muggleai/works)]()
7
+ [![MCP Tools](https://img.shields.io/badge/MCP_tools-70+-green)]()
8
+ [![Node](https://img.shields.io/badge/node-22+-orange)]()
6
9
 
7
- ```bash
8
- npm install -g @muggleai/works
9
- ```
10
-
11
- Or install directly from GitHub:
12
-
13
- ```bash
14
- npm install -g github:multiplex-ai/muggle-ai-works
15
- ```
16
-
17
- This is the canonical one-liner install path.
10
+ One install gives your AI coding assistant the ability to QA your app like a real user would — clicking through flows, catching broken experiences, and opening PRs with results.
18
11
 
19
- It automatically:
20
- 1. Installs the package
21
- 2. Downloads the Electron app binary (via postinstall)
22
- 3. Registers/updates `~/.cursor/mcp.json` with a `muggle` server entry
23
- 4. Sets up CLI commands
12
+ Part of the **Muggle AI** open-source ecosystem:
24
13
 
25
- ## Quick Start
14
+ | Package | Purpose | Install |
15
+ |---------|---------|---------|
16
+ | **muggle-ai-works** (this repo) | QA testing MCP server + autonomous dev pipeline | `npm install @muggleai/works` |
17
+ | **[muggle-ai-teams](https://github.com/multiplex-ai/muggle-ai-teams)** | Agent orchestration, workflow, skills, rules | `npm install @muggleai/teams` |
26
18
 
27
- ### 1. Validate your install
19
+ muggle-ai-works handles *QA verification* (test generation, browser replay, cloud results). muggle-ai-teams handles *how work gets done* (design → implement → review → deliver). Together, they form a complete AI-assisted development workflow with built-in quality assurance.
28
20
 
29
- ```bash
30
- muggle --version
31
- muggle doctor
32
- ```
21
+ ---
33
22
 
34
- ### 2. Add to your MCP client (if needed)
23
+ ## How Is This Different?
35
24
 
36
- **Cursor (`~/.cursor/mcp.json`):**
25
+ Most AI coding tools help you *write* code. muggle-ai-works helps you *test* it — automatically, using AI-driven browser automation.
37
26
 
38
- ```json
39
- {
40
- "mcpServers": {
41
- "muggle": {
42
- "command": "muggle",
43
- "args": ["serve"]
44
- }
45
- }
46
- }
47
- ```
27
+ | | **muggle-ai-works** | **Playwright MCP** | **Manual QA** |
28
+ |---|---|---|---|
29
+ | **Test creation** | Natural language → test cases | Write code manually | Write test plans manually |
30
+ | **Test execution** | AI-driven browser (Electron app) | Scripted browser automation | Human clicks through flows |
31
+ | **Localhost testing** | Built-in URL rewriting | Manual config | Manual |
32
+ | **Cloud sync** | Automatic (projects, cases, scripts, results) | None | Spreadsheets |
33
+ | **Integration** | MCP tools for any AI assistant | Playwright API | None |
34
+ | **Learning curve** | Describe what to test in English | Learn Playwright API | Train QA team |
48
35
 
49
- ### 2. Start using MCP tools
36
+ ---
50
37
 
51
- Ask your AI assistant to test your application! Authentication happens automatically when needed.
38
+ ## Quick Start
52
39
 
53
- ## CLI Commands
40
+ ### 1. Install
54
41
 
55
42
  ```bash
56
- # Server (main command - starts MCP server for AI clients)
57
- muggle serve # Start server with all tools (default)
58
- muggle serve --qa # Cloud QA tools only
59
- muggle serve --local # Local testing tools only
43
+ npm install @muggleai/works
44
+ ```
60
45
 
61
- # Setup & Diagnostics
62
- muggle setup # Download/update Electron app
63
- muggle setup --force # Force re-download
64
- muggle doctor # Diagnose installation issues
46
+ This automatically:
47
+ 1. Downloads the QA engine (Electron app) for browser automation
48
+ 2. Registers the MCP server in `~/.cursor/mcp.json`
49
+ 3. Installs skills (`/muggle-do`, `/test-feature-local`) to `~/.claude/`
65
50
 
66
- # Authentication (optional - auth happens automatically)
67
- muggle login # Manually trigger login
68
- muggle logout # Clear credentials
69
- muggle status # Show auth status
51
+ ### 2. Verify
70
52
 
71
- # Info
72
- muggle --version # Show version
73
- muggle --help # Show help
53
+ ```bash
54
+ muggle --version
55
+ muggle doctor
74
56
  ```
75
57
 
76
- ## Authentication
58
+ ### 3. Start testing
77
59
 
78
- Authentication happens automatically when you first use a tool that requires it:
60
+ In Claude Code or Cursor, just ask:
79
61
 
80
- 1. A browser window opens with a verification code
81
- 2. You log in with your Muggle AI account
82
- 3. The tool call continues with your credentials
62
+ > "Test my login flow on localhost:3000"
83
63
 
84
- Your credentials are stored in `~/.muggle-ai/credentials.json` and persist across sessions.
64
+ Your AI assistant will authenticate, find or create test cases, launch the browser, record/replay tests, and show you results with screenshots.
85
65
 
86
- ### Handling Expired Tokens
66
+ ---
87
67
 
88
- Tokens expire after a period of time. When this happens:
68
+ ## How It Works
89
69
 
90
- 1. **Check status**: Run `muggle status` or call `muggle-remote-auth-status` to see expiration
91
- 2. **Re-authenticate**: Run `muggle login` or call `muggle-remote-auth-login` to get fresh tokens
92
- 3. **If login fails with "unauthorized_client"**: Check your runtime target configuration (see Troubleshooting)
70
+ ### Design principle: "Create remotely, execute locally"
93
71
 
94
- The MCP server will attempt to auto-refresh tokens when possible, but manual re-authentication may be required if the refresh token has also expired.
72
+ All entity management (projects, use cases, test cases) lives in the **cloud** via `muggle-remote-*` tools. Local execution (`muggle-local-*`) is stateless — it receives everything it needs as input and just runs tests.
95
73
 
96
- ## Muggle Do (`/muggle-do`)
74
+ ### Entity model
97
75
 
98
- An autonomous development pipeline that takes your code changes through requirements analysis, testing, QA, and PR creation — all inside Claude Code.
76
+ ```
77
+ Project (e.g., "My App")
78
+ └── Use Case (e.g., "User Login Flow")
79
+ └── Test Case (e.g., "Login with valid credentials")
80
+ └── Test Script (recorded browser automation steps)
81
+ └── Run Result (pass/fail + screenshots)
82
+ ```
99
83
 
100
- ### How it works
84
+ ### Test execution flow
101
85
 
102
86
  ```
103
- You write code on a feature branch
104
- |
87
+ Your AI assistant describes what to test
88
+ │
89
+ v
90
+ muggle-remote-* tools create test cases in cloud
91
+ │
105
92
  v
106
- /muggle-do "what I built"
107
- |
108
- Stage 1: Requirements → extracts goal + acceptance criteria
109
- Stage 2: Impact Analysis → detects which repos have git changes
110
- Stage 3: Validate → checks feature branch, commits exist
111
- Stage 4: Unit Tests → runs test commands, fails fast
112
- Stage 5: QA → runs Muggle AI test cases
113
- Stage 6: Open PRs → pushes branch, creates PR with QA results
114
- |
93
+ muggle-local-execute-test-generation launches the QA engine
94
+ │
115
95
  v
116
- PR ready for review
96
+ AI agent drives the browser step-by-step (click, type, navigate, assert)
97
+ │
98
+ v
99
+ Screenshots captured per step → action-script.json recorded
100
+ │
101
+ v
102
+ Results: pass/fail with evidence at ~/.muggle-ai/sessions/{runId}/
103
+ │
104
+ v
105
+ muggle-local-publish-test-script uploads to cloud
117
106
  ```
118
107
 
119
- ### Step by step
108
+ ---
120
109
 
121
- **1. Make your changes on a feature branch:**
110
+ ## Three Ways to Use It
122
111
 
123
- ```bash
124
- cd /path/to/your/repo
125
- git checkout -b feat/add-login
126
- # ... write your code ...
127
- git add -A && git commit -m "feat: add login page"
128
- ```
112
+ ### 1. `/test-feature-local` — Test a feature on localhost
129
113
 
130
- **2. Configure your repos** — create `muggle-repos.json` in the muggle-ai-works root:
114
+ Interactive workflow: pick a project → pick a use case → pick a test case → run against localhost.
131
115
 
132
- ```json
133
- [
134
- { "name": "frontend", "path": "/absolute/path/to/frontend", "testCommand": "pnpm test" }
135
- ]
116
+ ```
117
+ > /test-feature-local
118
+
119
+ "Test my login changes on localhost:3999"
120
+
121
+ 1. Auth check ✓
122
+ 2. Found project: "My App"
123
+ 3. Found use case: "User Login"
124
+ 4. Found 2 test cases — recommend replay (minor changes detected)
125
+ 5. Launching QA engine... (approve? y)
126
+ 6. Results: 2/2 PASS
127
+ Screenshots: ~/.muggle-ai/sessions/abc123/screenshots/
128
+ 7. Publish to cloud? (y)
136
129
  ```
137
130
 
138
- **3. Open Claude Code and run the dev cycle:**
131
+ ### 2. `/muggle-do` — Autonomous dev pipeline
132
+
133
+ Full development cycle: requirements → code → unit tests → QA → PR creation.
139
134
 
140
135
  ```
141
- /muggle-do "Add a login page with email/password authentication"
136
+ > /muggle-do "Add a logout button to the header"
137
+
138
+ REQUIREMENTS → Goal: Add logout button. Criteria: visible, functional, redirects.
139
+ IMPACT → frontend repo, src/components/Header.tsx
140
+ VALIDATE → Branch: feat/add-logout, 1 commit
141
+ CODING → (writes/fixes code)
142
+ UNIT_TESTS → 12/12 pass
143
+ QA → 3/3 test cases pass
144
+ OPEN_PRS → PR #42 opened
145
+ DONE → 1 iteration, all green
142
146
  ```
143
147
 
144
- Claude will detect your changes, run tests, trigger QA, and open a PR.
145
-
146
- ### What if something fails?
148
+ Features:
149
+ - Session-based with crash recovery (`.muggle-do/sessions/`)
150
+ - Auto-triage: analyzes failures, jumps back to fix (max 3 iterations)
151
+ - Multi-repo support via `muggle-repos.json`
152
+ - Creates PRs with QA results in description
147
153
 
148
- | Failure | What happens |
149
- |---|---|
150
- | No changes detected | Stops — make changes first, re-run |
151
- | On main/master | Stops — create a feature branch first |
152
- | Unit tests fail | Shows output, stops — fix and re-run |
153
- | QA fails | Shows failing tests — fix and re-run |
154
+ ### 3. Direct MCP tool calls — Build your own workflow
154
155
 
155
- ### Repo config
156
+ Use any of the 70+ MCP tools directly from your AI assistant:
156
157
 
157
- | Field | Required | Default | Description |
158
- |---|---|---|---|
159
- | `name` | yes | — | Short identifier for the repo |
160
- | `path` | yes | — | Absolute path on your machine |
161
- | `testCommand` | no | `pnpm test` | Command to run unit tests |
158
+ ```
159
+ "Create a project called My App with URL https://myapp.com"
160
+ "Generate test cases for the checkout flow"
161
+ "Replay all test scripts against localhost:3000"
162
+ "Show me the latest QA results"
163
+ ```
162
164
 
163
165
  ---
164
166
 
165
- ## Available Tools
167
+ ## Integration with muggle-ai-teams
166
168
 
167
- ### Cloud QA Tools (muggle-remote-*)
169
+ When both packages are installed, muggle-ai-teams automatically integrates QA into its workflow:
168
170
 
169
- Tools that work with the Muggle AI cloud backend:
171
+ | Workflow Step | What Happens |
172
+ |--------------|-------------|
173
+ | **Step 1F** (Plan) | QA test instructions written per implementation slice |
174
+ | **Step 2** (Execute) | Per-slice QA via muggle-ai-works before each commit |
175
+ | **Step 3** (Verify) | Full regression sweep replaying all project scripts |
176
+ | **Step 5** (Push) | QA results published to cloud, linked in PR description |
170
177
 
171
- - `muggle-remote-project-create` - Create QA project
172
- - `muggle-remote-project-list` - List projects
173
- - `muggle-remote-use-case-create-from-prompts` - Create use cases
174
- - `muggle-remote-test-case-generate-from-prompt` - Generate test cases
175
- - `muggle-remote-workflow-start-*` - Start various workflows
176
- - And more...
178
+ Frontend slices get browser QA. Backend-only slices are verified by unit tests (browser QA skipped with documented reasoning).
177
179
 
178
- ### Local QA Tools (muggle-local-*)
180
+ Install both: `npm install @muggleai/works @muggleai/teams`
179
181
 
180
- Tools that work with local testing:
181
-
182
- - `muggle-local-check-status` - Check local status
183
- - `muggle-local-list-sessions` - List sessions
184
- - `muggle-local-execute-test-generation` - Generate test script
185
- - `muggle-local-execute-replay` - Replay test script
186
- - `muggle-local-run-result-list` - List run results
187
- - `muggle-local-publish-test-script` - Publish to cloud
188
- - And more...
189
-
190
- ## Data Directory
182
+ ---
191
183
 
192
- All Muggle AI data is stored in `~/.muggle-ai/`:
184
+ ## Available MCP Tools (70+)
185
+
186
+ ### Authentication (`muggle-remote-auth-*`)
187
+
188
+ | Tool | Purpose |
189
+ |------|---------|
190
+ | `muggle-remote-auth-status` | Check authentication status |
191
+ | `muggle-remote-auth-login` | Start device-code login flow |
192
+ | `muggle-remote-auth-poll` | Poll for login completion |
193
+ | `muggle-remote-auth-logout` | Clear credentials |
194
+
195
+ ### Project Management (`muggle-remote-project-*`)
196
+
197
+ | Tool | Purpose |
198
+ |------|---------|
199
+ | `muggle-remote-project-create` | Create QA project |
200
+ | `muggle-remote-project-list` | List all projects |
201
+ | `muggle-remote-project-get` | Get project details |
202
+ | `muggle-remote-project-update` | Update project |
203
+ | `muggle-remote-project-delete` | Delete project |
204
+
205
+ ### Use Cases (`muggle-remote-use-case-*`)
206
+
207
+ | Tool | Purpose |
208
+ |------|---------|
209
+ | `muggle-remote-use-case-list` | List use cases |
210
+ | `muggle-remote-use-case-create-from-prompts` | Create from natural language |
211
+ | `muggle-remote-use-case-prompt-preview` | Preview before creating |
212
+ | `muggle-remote-use-case-update-from-prompt` | Regenerate from new prompt |
213
+
214
+ ### Test Cases (`muggle-remote-test-case-*`)
215
+
216
+ | Tool | Purpose |
217
+ |------|---------|
218
+ | `muggle-remote-test-case-list` | List all test cases |
219
+ | `muggle-remote-test-case-list-by-use-case` | List by use case |
220
+ | `muggle-remote-test-case-get` | Get test case details |
221
+ | `muggle-remote-test-case-create` | Create test case |
222
+ | `muggle-remote-test-case-generate-from-prompt` | Generate from prompt |
223
+
224
+ ### Test Scripts & Workflows (`muggle-remote-workflow-*`)
225
+
226
+ | Tool | Purpose |
227
+ |------|---------|
228
+ | `muggle-remote-test-script-list` | List test scripts |
229
+ | `muggle-remote-test-script-get` | Get script details |
230
+ | `muggle-remote-workflow-start-website-scan` | Scan site for use cases |
231
+ | `muggle-remote-workflow-start-test-case-detection` | Generate test cases |
232
+ | `muggle-remote-workflow-start-test-script-generation` | Generate scripts |
233
+ | `muggle-remote-workflow-start-test-script-replay` | Replay single script |
234
+ | `muggle-remote-workflow-start-test-script-replay-bulk` | Batch replay |
235
+
236
+ ### Local Execution (`muggle-local-*`)
237
+
238
+ | Tool | Purpose |
239
+ |------|---------|
240
+ | `muggle-local-check-status` | Check local QA engine status |
241
+ | `muggle-local-execute-test-generation` | Generate test script locally |
242
+ | `muggle-local-execute-replay` | Replay existing script locally |
243
+ | `muggle-local-cancel-execution` | Cancel active execution |
244
+ | `muggle-local-run-result-list` | List run results |
245
+ | `muggle-local-run-result-get` | Get detailed results + screenshots |
246
+ | `muggle-local-publish-test-script` | Publish script to cloud |
247
+
248
+ ### Reports & Analytics (`muggle-remote-report-*`)
249
+
250
+ | Tool | Purpose |
251
+ |------|---------|
252
+ | `muggle-remote-report-stats-summary-get` | Report statistics |
253
+ | `muggle-remote-report-cost-query` | Query cost/usage |
254
+ | `muggle-remote-report-final-generate` | Generate final report (PDF/HTML/Markdown) |
255
+ | `muggle-remote-project-test-results-summary-get` | Test results summary |
256
+
257
+ Also available: PRD processing (`muggle-remote-prd-*`), secrets management (`muggle-remote-secret-*`), wallet/billing (`muggle-remote-wallet-*`), and scheduling recommendations (`muggle-remote-recommend-*`).
193
258
 
194
- ```
195
- ~/.muggle-ai/
196
- ├── credentials.json # Auth credentials (auto-generated)
197
- ├── projects/ # Local test projects
198
- ├── sessions/ # Test execution sessions
199
- └── electron-app/ # Downloaded Electron app
200
- └── 1.0.0/
201
- └── MuggleAI.exe
202
- ```
259
+ ---
203
260
 
204
- ## Requirements
261
+ ## CLI Commands
205
262
 
206
- - Node.js 22 or higher
207
- - For local testing: Electron app (downloaded automatically)
263
+ ```bash
264
+ # Server (main command — starts MCP server for AI clients)
265
+ muggle serve # Start with all tools (default)
266
+ muggle serve --qa # Cloud QA tools only
267
+ muggle serve --local # Local QA tools only
208
268
 
209
- ## Development
269
+ # Setup & Diagnostics
270
+ muggle setup # Download/update QA engine
271
+ muggle setup --force # Force re-download
272
+ muggle doctor # Diagnose installation issues
210
273
 
211
- ### Building
274
+ # Authentication
275
+ muggle login # Manually trigger login
276
+ muggle logout # Clear credentials
277
+ muggle status # Show auth status
212
278
 
213
- ```bash
214
- npm install
215
- npm run build
279
+ # Info
280
+ muggle --version # Show version
281
+ muggle --help # Show help
216
282
  ```
217
283
 
218
- ### Testing
284
+ ---
219
285
 
220
- ```bash
221
- npm test # Run tests once
222
- npm run test:watch # Watch mode
223
- ```
286
+ ## Authentication
224
287
 
225
- ### Linting
288
+ Authentication happens automatically when you first use a tool that requires it:
226
289
 
227
- ```bash
228
- npm run lint # Auto-fix issues
229
- npm run lint:check # Check only
230
- ```
290
+ 1. A browser window opens with a verification code
291
+ 2. You log in with your Muggle AI account
292
+ 3. The tool call continues with your credentials
231
293
 
232
- ## CI/CD Workflows
294
+ Credentials are stored in `~/.muggle-ai/` and persist across sessions.
233
295
 
234
- | Workflow | Trigger | Description |
235
- | :------- | :------ | :---------- |
236
- | `ci.yml` | Push/PR to `master` | Lint, test, build on multiple platforms/versions |
237
- | `publish-works.yml` | Tag `v*` or manual dispatch | Verify, package-audit, smoke-install, publish to npm |
296
+ ### Handling expired tokens
238
297
 
239
- ### Publishing a new version
298
+ 1. **Check status**: `muggle status` or `muggle-remote-auth-status`
299
+ 2. **Re-authenticate**: `muggle login` or `muggle-remote-auth-login`
300
+ 3. **If "unauthorized_client"**: Check `MUGGLE_MCP_PROMPT_SERVICE_TARGET` environment variable (see Troubleshooting)
240
301
 
241
- 1. Update version in `package.json`
242
- 2. Commit and push
243
- 3. Create a git tag: `git tag v1.0.1 && git push --tags`
244
- 4. The `publish-works.yml` workflow publishes to npm automatically
302
+ ---
245
303
 
246
- ## Troubleshooting
304
+ ## Data Directory
247
305
 
248
- ### Expired Token Errors
306
+ ```
307
+ ~/.muggle-ai/
308
+ ├── auth.json # OAuth tokens
309
+ ├── credentials.json # API key for service calls
310
+ ├── projects/ # Local project cache
311
+ ├── sessions/ # QA sessions
312
+ │ └── {runId}/
313
+ │ ├── action-script.json # Recorded browser steps
314
+ │ ├── results.md # Step-by-step report
315
+ │ └── screenshots/ # Per-step images
316
+ └── electron-app/ # Downloaded QA engine
317
+ └── {version}/
318
+ ```
249
319
 
250
- If you see authentication errors like "Not authenticated" or token expiration messages:
320
+ ---
251
321
 
252
- 1. **Check auth status**:
253
- ```bash
254
- muggle status
255
- ```
322
+ ## Platform Compatibility
256
323
 
257
- 2. **Re-authenticate**:
258
- ```bash
259
- muggle login
260
- ```
324
+ | Platform | MCP Tools | /muggle-do | /test-feature-local |
325
+ |----------|-----------|-----------|-------------------|
326
+ | **Claude Code** | Yes | Yes | Yes |
327
+ | **Cursor** | Yes (via MCP) | No (needs Agent tool) | No (needs Skill tool) |
328
+ | **Others** | Via MCP if supported | No | No |
261
329
 
262
- 3. **Clear and retry** (if login keeps failing):
263
- ```bash
264
- muggle logout
265
- muggle login
266
- ```
330
+ The MCP server (`muggle serve`) works with any MCP-compatible client. The distributed skills (`/muggle-do`, `/test-feature-local`) require Claude Code's Agent and Skill tools.
267
331
 
268
- ### "unauthorized_client" Error During Login
332
+ ---
269
333
 
270
- This error indicates a mismatch between your Auth0 client configuration and the target environment.
334
+ ## Configuration
271
335
 
272
- **Cause**: The MCP is configured for one environment (dev/production) but trying to authenticate against another.
336
+ ### MCP client config
273
337
 
274
- **Fix**: Ensure your MCP configuration matches your intended environment by setting the `MUGGLE_MCP_PROMPT_SERVICE_TARGET` environment variable in your MCP config:
338
+ **Cursor** (`~/.cursor/mcp.json`) — auto-configured on install:
275
339
 
276
- **For Production** (`~/.cursor/mcp.json`):
277
340
  ```json
278
341
  {
279
342
  "mcpServers": {
280
343
  "muggle": {
281
344
  "command": "muggle",
282
- "args": ["serve"],
283
- "env": {
284
- "MUGGLE_MCP_PROMPT_SERVICE_TARGET": "production"
285
- }
345
+ "args": ["serve"]
286
346
  }
287
347
  }
288
348
  }
289
349
  ```
290
350
 
291
- **For Development** (local services):
351
+ ### Environment targeting
352
+
353
+ Set `MUGGLE_MCP_PROMPT_SERVICE_TARGET` to switch between production and dev:
354
+
292
355
  ```json
293
356
  {
294
357
  "mcpServers": {
@@ -296,31 +359,106 @@ This error indicates a mismatch between your Auth0 client configuration and the
296
359
  "command": "muggle",
297
360
  "args": ["serve"],
298
361
  "env": {
299
- "MUGGLE_MCP_PROMPT_SERVICE_TARGET": "dev"
362
+ "MUGGLE_MCP_PROMPT_SERVICE_TARGET": "production"
300
363
  }
301
364
  }
302
365
  }
303
366
  }
304
367
  ```
305
368
 
306
- After changing the configuration, restart your MCP client (e.g., restart Cursor).
369
+ ### Multi-repo config for /muggle-do
307
370
 
308
- ### Credential Files
371
+ Create `muggle-repos.json` in your working directory:
309
372
 
310
- Credentials are stored in `~/.muggle-ai/`:
373
+ ```json
374
+ [
375
+ { "name": "frontend", "path": "/absolute/path/to/frontend", "testCommand": "pnpm test" },
376
+ { "name": "backend", "path": "/absolute/path/to/backend", "testCommand": "pnpm test" }
377
+ ]
378
+ ```
311
379
 
312
- | File | Purpose |
313
- | :--- | :------ |
314
- | `auth.json` | OAuth tokens (access token, refresh token, expiry) |
315
- | `credentials.json` | API key for service calls |
380
+ ---
381
+
382
+ ## Development
383
+
384
+ ```bash
385
+ # Install dependencies
386
+ pnpm install
387
+
388
+ # Build
389
+ pnpm run build
390
+
391
+ # Dev mode (watch)
392
+ pnpm run dev
393
+
394
+ # Test
395
+ pnpm test
396
+ pnpm run test:watch
397
+
398
+ # Lint
399
+ pnpm run lint # Auto-fix
400
+ pnpm run lint:check # Check only
401
+
402
+ # Typecheck
403
+ pnpm run typecheck
404
+ ```
405
+
406
+ ### CI/CD
407
+
408
+ | Workflow | Trigger | Description |
409
+ |----------|---------|-------------|
410
+ | `ci.yml` | Push/PR to `master` | Lint, test, build on multiple platforms |
411
+ | `publish-works.yml` | Tag `v*` or manual | Verify, audit, smoke-install, publish to npm |
412
+
413
+ ### Publishing
316
414
 
317
- If you need to reset authentication completely:
318
415
  ```bash
319
- rm ~/.muggle-ai/auth.json
320
- rm ~/.muggle-ai/credentials.json
321
- muggle login
416
+ # Update version in package.json
417
+ git tag v2.0.1 && git push --tags
418
+ # publish-works.yml handles the rest
322
419
  ```
323
420
 
421
+ ---
422
+
423
+ ## Troubleshooting
424
+
425
+ ### "unauthorized_client" during login
426
+
427
+ **Cause**: MCP configured for one environment but authenticating against another.
428
+
429
+ **Fix**: Set the correct `MUGGLE_MCP_PROMPT_SERVICE_TARGET` in your MCP config and restart your client.
430
+
431
+ ### QA engine not found
432
+
433
+ ```bash
434
+ muggle setup --force # Re-download
435
+ muggle doctor # Diagnose
436
+ ```
437
+
438
+ ### Authentication keeps expiring
439
+
440
+ ```bash
441
+ muggle logout # Clear all credentials
442
+ rm ~/.muggle-ai/auth.json ~/.muggle-ai/credentials.json
443
+ muggle login # Fresh login
444
+ ```
445
+
446
+ ---
447
+
448
+ ## About
449
+
450
+ Built by the team behind **[MuggleTest](https://www.muggletest.com)** — an AI-powered QA testing platform that makes software testing accessible to everyone, no coding required.
451
+
452
+ **Muggle AI open-source ecosystem:**
453
+ - **[muggle-ai-works](https://github.com/multiplex-ai/muggle-ai-works)** — QA testing MCP server + autonomous dev pipeline (this repo)
454
+ - **[muggle-ai-teams](https://github.com/multiplex-ai/muggle-ai-teams)** — Agent orchestration, workflow, skills, and rules
455
+
456
+ ---
457
+
324
458
  ## License
325
459
 
326
- MIT
460
+ [MIT](LICENSE) — Use it, fork it, make it yours.
461
+
462
+ ---
463
+
464
+ If this helps your development workflow, consider giving it a star. It helps others find it.
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@muggleai/works",
3
- "version": "2.0.0",
4
- "description": "Unified MCP server for Muggle AI - Cloud QA and Local Testing tools",
3
+ "version": "2.0.2",
4
+ "description": "Ship quality products, not just code. AI-powered QA that validates your app's user experience — from Claude Code and Cursor to PR.",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",
7
7
  "bin": {
@@ -81,7 +81,12 @@
81
81
  "qa",
82
82
  "testing",
83
83
  "automation",
84
- "localhost"
84
+ "localhost",
85
+ "ai-coding",
86
+ "user-experience",
87
+ "cursor",
88
+ "claude-code",
89
+ "vibe-coding"
85
90
  ],
86
91
  "author": "Muggle AI",
87
92
  "license": "MIT",