@muggleai/mcp

@muggleai/mcp

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

Installation

npm install -g @muggleai/mcp

This automatically:

• Installs the package
• Downloads the Electron app binary (via postinstall)
• Sets up CLI commands

Quick Start

1. Add to your MCP client

Cursor (~/.cursor/mcp.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

# 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:

• A browser window opens with a verification code
• You log in with your Muggle AI account
• 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:

• Check status: Run muggle-mcp status or call muggle-remote-auth-status to see expiration
• Re-authenticate: Run muggle-mcp login or call muggle-remote-auth-login to get fresh tokens
• 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

npm install
npm run build

Testing

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

Linting

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

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

Releasing Electron app

• Update muggleConfig.electronAppVersion in package.json
• Run the release-electron-app.yml workflow manually
• 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:

• Check auth status:

  muggle-mcp status
  

• Re-authenticate:

  muggle-mcp login
  

• Clear and retry (if login keeps failing):

  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):

{
  "mcpServers": {
    "muggle": {
      "command": "muggle-mcp",
      "args": ["serve"],
      "env": {
        "MUGGLE_MCP_PROMPT_SERVICE_TARGET": "production"
      }
    }
  }
}

For Development (local services):

{
  "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:

rm ~/.muggle-ai/auth.json
rm ~/.muggle-ai/credentials.json
muggle-mcp login

License

MIT