npm package: @muggleai/mcp
Description: Unified MCP server for Muggle AI - Cloud QA and Local Testing tools
Author: Muggle AI
Latest version: 1.0.26

# @muggleai/mcp

Unified MCP server for Muggle AI - combines Cloud QA and Local Testing tools into a single package.

## Installation

```bash
npm install -g @muggleai/mcp
```

This automatically:
1. Installs the package
2. Downloads the Electron app binary (via postinstall)
3. Sets up CLI commands

## Quick Start

### 1. Add to your MCP client

**Cursor (`~/.cursor/mcp.json`):**

```json
{
  "mcpServers": {
    "muggle": {
      "command": "muggle-mcp",
      "args": ["serve"]
    }
  }
}
```

### 2. Start using MCP tools

Ask your AI assistant to test your application! Authentication happens automatically when needed.

## CLI Commands

```bash
# Server (main command - starts MCP server for AI clients)
muggle-mcp serve              # Start server with all tools (default)
muggle-mcp serve --qa         # Cloud QA tools only
muggle-mcp serve --local      # Local testing tools only

# Setup & Diagnostics
muggle-mcp setup              # Download/update Electron app
muggle-mcp setup --force      # Force re-download
muggle-mcp doctor             # Diagnose installation issues

# Authentication (optional - auth happens automatically)
muggle-mcp login              # Manually trigger login
muggle-mcp logout             # Clear credentials
muggle-mcp status             # Show auth status

# Info
muggle-mcp --version          # Show version
muggle-mcp --help             # Show help
```

## Authentication

Authentication happens automatically when you first use a tool that requires it:

1. A browser window opens with a verification code
2. You log in with your Muggle AI account
3. The tool call continues with your credentials

Your credentials are stored in `~/.muggle-ai/credentials.json` and persist across sessions.

### Handling Expired Tokens

Tokens expire after a period of time. When this happens:

1. **Check status**: Run `muggle-mcp status` or call `muggle-remote-auth-status` to see expiration
2. **Re-authenticate**: Run `muggle-mcp login` or call `muggle-remote-auth-login` to get fresh tokens
3. **If login fails with "unauthorized_client"**: Check your runtime target configuration (see Troubleshooting)

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.

## Available Tools

### Cloud QA Tools (muggle-remote-*)

Tools that work with the Muggle AI cloud backend:

- `muggle-remote-project-create` - Create QA project
- `muggle-remote-project-list` - List projects
- `muggle-remote-use-case-create-from-prompts` - Create use cases
- `muggle-remote-test-case-generate-from-prompt` - Generate test cases
- `muggle-remote-workflow-start-*` - Start various workflows
- And more...

### Local QA Tools (muggle-local-*)

Tools that work with local testing:

- `muggle-local-check-status` - Check local status
- `muggle-local-list-sessions` - List sessions
- `muggle-local-execute-test-generation` - Generate test script
- `muggle-local-execute-replay` - Replay test script
- `muggle-local-run-result-list` - List run results
- `muggle-local-publish-test-script` - Publish to cloud
- And more...

## Data Directory

All Muggle AI data is stored in `~/.muggle-ai/`:

```
~/.muggle-ai/
├── credentials.json      # Auth credentials (auto-generated)
├── projects/             # Local test projects
├── sessions/             # Test execution sessions
└── electron-app/         # Downloaded Electron app
    └── 1.0.0/
        └── MuggleAI.exe
```

## Requirements

- Node.js 22 or higher
- For local testing: Electron app (downloaded automatically)

## Development

### Building

```bash
npm install
npm run build
```

### Testing

```bash
npm test              # Run tests once
npm run test:watch    # Watch mode
```

### Linting

```bash
npm run lint          # Auto-fix issues
npm run lint:check    # Check only
```

## CI/CD Workflows

| Workflow | Trigger | Description |
| :------- | :------ | :---------- |
| `ci.yml` | Push/PR to main | Lint, test, build on multiple platforms/versions |
| `publish-mcp.yml` | Tag `v*` | Publish package to npm |
| `release-electron-app.yml` | Tag `electron-app@*` | Build and release Electron binaries |

### Publishing a new version

1. Update version in `package.json`
2. Commit and push
3. Create a git tag: `git tag v1.0.1 && git push --tags`
4. The `publish-mcp.yml` workflow publishes to npm automatically

### Releasing Electron app

1. Update `muggleConfig.electronAppVersion` in `package.json`
2. Run the `release-electron-app.yml` workflow manually
3. Or create a tag: `git tag electron-app@1.0.1 && git push --tags`

## Troubleshooting

### Expired Token Errors

If you see authentication errors like "Not authenticated" or token expiration messages:

1. **Check auth status**:
   ```bash
   muggle-mcp status
   ```

2. **Re-authenticate**:
   ```bash
   muggle-mcp login
   ```

3. **Clear and retry** (if login keeps failing):
   ```bash
   muggle-mcp logout
   muggle-mcp login
   ```

### "unauthorized_client" Error During Login

This error indicates a mismatch between your Auth0 client configuration and the target environment.

**Cause**: The MCP is configured for one environment (dev/production) but trying to authenticate against another.

**Fix**: Ensure your MCP configuration matches your intended environment by setting the `MUGGLE_MCP_PROMPT_SERVICE_TARGET` environment variable in your MCP config:

**For Production** (`~/.cursor/mcp.json`):
```json
{
  "mcpServers": {
    "muggle": {
      "command": "muggle-mcp",
      "args": ["serve"],
      "env": {
        "MUGGLE_MCP_PROMPT_SERVICE_TARGET": "production"
      }
    }
  }
}
```

**For Development** (local services):
```json
{
  "mcpServers": {
    "muggle": {
      "command": "muggle-mcp",
      "args": ["serve"],
      "env": {
        "MUGGLE_MCP_PROMPT_SERVICE_TARGET": "dev"
      }
    }
  }
}
```

After changing the configuration, restart your MCP client (e.g., restart Cursor).

### Credential Files

Credentials are stored in `~/.muggle-ai/`:

| File | Purpose |
| :--- | :------ |
| `auth.json` | OAuth tokens (access token, refresh token, expiry) |
| `credentials.json` | API key for service calls |

If you need to reset authentication completely:
```bash
rm ~/.muggle-ai/auth.json
rm ~/.muggle-ai/credentials.json
muggle-mcp login
```

## License

MIT