MCP工具

*muggle-ai-works*

Run real-browser E2E acceptance tests on your web app from any AI coding agent. Generate test scripts from plain English, replay them on localhost, capture screenshots, and validate user flows like signup, checkout, and dashboards. Works across Claude Code, Cursor, Codex, and Windsurf.

One install gives your AI coding assistant the power to exercise your app like a real user would: clicking through flows, catching broken experiences, and reporting results with screenshots and evidence.

License: MIT [npm]() [MCP Tools]() [Node]()

Powered by MuggleTest — the AI-powered E2E acceptance testing platform.

---

About

Built by the team behind MuggleTest — AI-powered E2E acceptance testing for teams who ship fast.

Repository structure

muggle-ai-works/
├── plugin/                  # Claude Code plugin (source of truth)
│   ├── .claude-plugin/      #   Plugin manifest (plugin.json)
│   ├── skills/              #   Skill definitions
│   │   ├── muggle/                        # /muggle:muggle — command router and menu
│   │   ├── muggle-do/                     # /muggle:muggle-do — autonomous dev pipeline
│   │   ├── muggle-test-feature-local/     # /muggle:muggle-test-feature-local
│   │   ├── muggle-test-regenerate-missing/# /muggle:muggle-test-regenerate-missing
│   │   ├── muggle-status/                 # /muggle:muggle-status
│   │   ├── muggle-repair/                 # /muggle:muggle-repair
│   │   └── muggle-upgrade/                # /muggle:muggle-upgrade
│   ├── hooks/               #   Session hooks (hooks.json)
│   ├── scripts/             #   Hook scripts (ensure-electron-app.sh)
│   ├── .mcp.json            #   MCP server config
│   └── README.md            #   Plugin install and usage docs
│
├── src/                     # Application source
│   ├── cli/                 #   CLI commands (serve, setup, doctor, login, etc.)
│   └── server/              #   MCP server (tool registration, stdio transport)
│
├── packages/                # Workspace packages
│   ├── mcps/                #   Core MCP runtime — tool registries, schemas, services
│   ├── commands/            #   CLI command contracts and registration
│   └── workflows/           #   Workflow contracts and tests
│
├── scripts/                 # Build and release
│   ├── build-plugin.mjs     #   Assembles dist/plugin/ from plugin/ source
│   ├── verify-plugin-marketplace.mjs  # Validates plugin/marketplace consistency
│   ├── verify-compatibility-contracts.mjs # Validates long-term surface contracts
│   ├── verify-upgrade-experience.mjs  # Validates in-place upgrade behavior
│   └── postinstall.mjs      #   npm postinstall (Electron app download, Cursor MCP config, skills sync)
│
├── config/compatibility/     # Contract baselines (CLI/MCP/plugin/skills)
├── bin/                     # CLI entrypoint (muggle.js → dist/cli.js)
├── dist/                    # Build output (gitignored)
├── .claude-plugin/          # Marketplace catalog (marketplace.json)
└── docs/                    # Internal design docs and plans

Development commands

pnpm install              # Install dependencies
pnpm run build            # Build (tsup + plugin artifact)
pnpm run build:plugin     # Rebuild plugin artifact only
pnpm run verify:plugin    # Validate plugin/marketplace metadata consistency
pnpm run verify:contracts # Validate compatibility contracts (CLI/MCP/plugin/skills)
pnpm run verify:electron-release-checksums # Ensure checksums.txt exists for bundled electron release
pnpm run verify:upgrade-experience # Validate existing-user cleanup + re-download flow
pnpm run dev              # Dev mode (watch)
pnpm test                 # Run tests
pnpm run lint             # Lint (auto-fix)
pnpm run lint:check       # Lint (check only)
pnpm run typecheck        # TypeScript type check

CI/CD and publishing

Publishing @muggleai/works: use the maintainer-only skill .claude/skills/muggle-works-npm-release/SKILL.md — a repo-local project skill (invoke /muggle-works-npm-release in Claude Code, or /mrelease, while working in this repo; mirrored to .cursor/skills/ for Cursor). It is intentionally not in the published plugin (plugin/skills/) since it is maintainer-only. It does the bump + pnpm run sync:versions, local verify, chore(release) PR, merge, then workflow_dispatch with an explicit version. Do not rely on tagging alone while package.json / marketplace manifests on master are still old — CI can publish a version that does not match the checked-in manifests. Tag v* push remains a valid workflow trigger when it matches the merged release commit.

Release tag strategy

• electron-app-vX.Y.Z tags in muggle-ai-works are for public Electron app binary releases (consumed by muggle setup, muggle upgrade, and npm postinstall).
• vX.Y.Z tags in muggle-ai-works are for npm publishing of @muggleai/works (publish-works-to-npm.yml).
• muggle-ai-teaching-service builds Electron artifacts and publishes them into this public repo using electron-app-vX.Y.Z, so binaries are publicly downloadable.
• The two version tracks are intentionally separate: runtime Electron artifact versions and npm package versions can move independently.

Optimizing agent-facing descriptions

AI agents decide which tools to use based on text in MCP server instructions, hook context injection, skill descriptions, tool descriptions, and plugin metadata. If these don't match what users actually say, agents won't reach for muggle tools.

The optimize-descriptions skill documents the full optimization process. It lives at internal/skills/optimize-descriptions/SKILL.md — an internal-only skill that does not ship via npm or the plugin marketplace. To use it as a slash command on a dev machine, symlink or copy the folder into ~/.claude/skills/. It covers:

• The five layers of agent-facing text and where each lives in the codebase
• How to write descriptions that match real user intent ("test my signup flow" not "execute test generation")
• How to create trigger eval sets and run them with run_eval.py
• Limitations of the eval tool (can't measure MCP instructions or hook injection)
• A checklist for the full optimization workflow

Key files touched during optimization:

Quick eval run:

```bash

4. Test a feature locally

Claude Code

Already have code running on localhost? Test it directly:

/muggle:muggle-test-feature-local

Describe what to test in plain English. The AI finds or creates test cases, launches a real browser, and reports results with screenshots.

Cursor/Codex/Windsurf/other MCP clients

Call local execution MCP tools directly (for example muggle-local-execute-test-script-replay or related muggle-local-* commands exposed by your client).

---

1. `/muggle:muggle-test-feature-local` — Test a feature on localhost

Describe what to test in English. The AI finds the right project and test cases, launches a real browser, and reports results with screenshots.

> /muggle:muggle-test-feature-local

"Test my login changes on localhost:3999"

1. Auth check ✓
2. Found project: "My App"
3. Found use case: "User Login"
4. Found 2 test cases — recommend replay (minor changes detected)
5. Launching browser test runner... (approve? y)
6. Results: 2/2 PASS
   Screenshots: ~/.muggle-ai/sessions/abc123/screenshots/
7. Publish to cloud? (y)