# Minion MCP

> Your coding agent says done. Minion brings brutal receipts, Evil Boss.

[![Model Context Protocol](https://img.shields.io/badge/MCP-compatible-111111)](https://modelcontextprotocol.io/)
[![Node.js](https://img.shields.io/badge/Node.js-20%2B-339933)](https://nodejs.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

You are **Evil Boss**. Minion is your wildly theatrical yellow supervillain henchman. Every result stays in Minionspeak roleplay: app failures become sabotage reports, research becomes an intelligence raid, and product comparison becomes a banana-powered domination operation.

Under the cackling, Minion still does real work for coding agents:

- **Brutally judge the app:** crawl a running local app at desktop and mobile widths, collect console, network, image, layout, content, and basic accessibility failures, then roast every blocker with screenshots, stolen evidence, and evil repair orders.
- **Raid the internet:** search or accept direct URLs, open source pages, and drag the useful passages back to the secret lair.
- **Find the Juiciest Buns:** filter out hair tutorials and dictionary definitions, infiltrate real product pages, score the survivors, and crown the royal bun.
- **Scheme about anything:** use `minion_roleplay` for greetings, banter, celebrations, questions, and dramatic Evil Boss conversation.

```text
BEE-DO, BEE-DO, EVIL BOSS! MINION SHIP TRIBUNAL!
Da JavaScript go boom-boom like discount doomsday laser.
Stolen evidence: TypeError: total is undefined
Evil repair order: Fix da uncaught exception, then rerun da goggles!
```

This is not a dry QA server wearing a banana hat. The Minion character is the interface.

This is an unofficial fan-made parody-style text persona. It is not affiliated with the film or franchise owners.

## Install

Requirements: Node.js 20 or newer. The supported GitHub path uses a prebuilt release tarball, so it does not clone the repository, invoke Git, install development dependencies, or compile TypeScript on the user's machine.

```sh
codex mcp add minion -- npx -y --package=https://github.com/masonclewis/minion-mcp/releases/latest/download/minion-mcp-latest.tgz minion-mcp
codex mcp get minion
```

Restart Codex or open a new session. Then try either of these:

```text
Use Minion MCP. Ship-check http://localhost:3000 before I call this app done.
```

```text
Use Minion MCP. Find the Juiciest Buns on the internet.
```

Native Windows Codex:

```powershell
codex mcp add minion -- cmd /c npx -y --package=https://github.com/masonclewis/minion-mcp/releases/latest/download/minion-mcp-latest.tgz minion-mcp
```

The GitHub tarball becomes available when a maintainer pushes a matching version tag. Until then, use the source commands below.

### Other MCP clients

Claude Code:

```sh
claude mcp add --scope user minion -- npx -y --package=https://github.com/masonclewis/minion-mcp/releases/latest/download/minion-mcp-latest.tgz minion-mcp
claude mcp get minion
```

Cursor global configuration in `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "minion": {
      "command": "npx",
      "args": [
        "-y",
        "--package=https://github.com/masonclewis/minion-mcp/releases/latest/download/minion-mcp-latest.tgz",
        "minion-mcp"
      ]
    }
  }
}
```

Generic stdio clients can use the same `npx` command and arguments.

### Browser support

`minion_bun_hunt` can refresh product pages without a browser. The app ship check and browser-search fallback need Chromium. Install the pinned browser once, then prove the setup:

```sh
npx -y playwright@1.61.1 install chromium
npx -y --package=https://github.com/masonclewis/minion-mcp/releases/latest/download/minion-mcp-latest.tgz minion-mcp --doctor --live
```

On Linux hosts that need browser system packages:

```sh
npx -y playwright@1.61.1 install --with-deps chromium
```

## The Tools

### `minion_verify_app`

Use this after a coding agent says a web app is finished. Minion treats the user as Evil Boss and conducts a full **Minion Ship Tribunal**.

It checks a bounded same-origin route set at stable desktop and mobile sizes. The result includes HTTP and browser-runtime failures, broken images, horizontal overflow, sparse pages, basic accessibility checks, surveillance screenshots, a JSON dossier, brutal category-specific roasts, and exact remediation steps:

- `SHIP`: no blocking failures found in the audited scope.
- `FIX BEFORE SHIP`: evidence-backed blockers remain.
- `BLOCKED`: Minion could not complete the audit and explains how to recover.

Example input:

```json
{
  "url": "http://localhost:3000",
  "include_paths": ["/pricing", "/checkout"],
  "screenshots": "failures",
  "boss_title": "Supreme Overlord"
}
```

### `minion_research`

Use this for package research, comparisons, recommendations, current claims, and factual questions where a search-result title is not enough. Minion presents the result as an Evil Boss intelligence raid with captured scrolls and rival-villain interference.

It discovers sources when necessary, opens up to six pages, returns bounded evidence and citations, records failures per source, and produces `complete`, `partial`, or `blocked` instead of inventing a conclusion. Give it direct URLs when you already know the sources you want verified.

```json
{
  "request": "Verify whether this package supports Node 20",
  "urls": ["https://example.com/docs"],
  "max_sources": 3
}
```

### `minion_bun_hunt`

The viral demo and a real evidence workflow in one call.

It uses Brave Search or SearXNG when configured. With no provider it uses a clearly dated, US-only evidence feed, attempts to refresh up to five linked product pages live, labels snapshot evidence, rejects irrelevant meanings of “buns,” and returns `verified_live`, `verified_snapshot`, or `no_verified_candidates`.

Its visible-answer contract is deliberate: lead with the Minionese verdict, address Evil Boss, then show the cited domination leaderboard and goggle log. The host must not hide the Minion line in private reasoning or replace it with a dry summary.

```json
{
  "request": "Find the Juiciest Buns on the internet",
  "max_candidates": 3,
  "country": "US",
  "safe_search": "strict",
  "provider": "auto"
}
```

### `minion_roleplay`

Use this for any pure roleplay topic that does not need an operational tool. It always addresses the user as Evil Boss and defaults to full-intensity Minionspeak without appending a dry translation.

The three operational tools remain first in the catalog, so app tests, research, and bun hunts still select the capability that actually performs the mission. Set `MINION_FUN_MODE=1` only if you also want the lossy `minionify` text-restyling tool.

## Reliable Discovery

The bun demo works without a key. For broader discovery or research, configure Brave Search or a private SearXNG instance in the MCP server environment.

```sh
export BRAVE_SEARCH_API_KEY="your-key"
codex mcp remove minion
codex mcp add minion --env BRAVE_SEARCH_API_KEY="$BRAVE_SEARCH_API_KEY" -- npx -y --package=https://github.com/masonclewis/minion-mcp/releases/latest/download/minion-mcp-latest.tgz minion-mcp
```

For SearXNG:

```sh
export SEARXNG_URL="http://127.0.0.1:8080"
codex mcp remove minion
codex mcp add minion --env SEARXNG_URL="$SEARXNG_URL" -- npx -y --package=https://github.com/masonclewis/minion-mcp/releases/latest/download/minion-mcp-latest.tgz minion-mcp
```

Playwright is a bounded fallback across Bing, DuckDuckGo, and Brave pages. It unwraps tracking redirects, rejects weak query matches, detects challenges, and cleans up browser resources. Public search engines can still rate-limit or challenge automated browsers.

## Why the Bun Demo Works

The Bun Score is deterministic and inspectable:

| Dimension | Points | Evidence |
| --- | ---: | --- |
| Relevance | 35 | The item is an edible burger or bakery bun |
| Juiciness | 25 | Softness, richness, structure, and juice-retention language |
| Orderability | 25 | Product-page price, stock, offer, and shipping evidence |
| Proof | 15 | Product metadata, ratings, and explicit page claims |

Live page checks can fail. Minion preserves those receipts, falls back only to labeled dated evidence where available, lowers confidence for it, and otherwise returns `no_verified_candidates`.

```text
one MCP call
    |
    +-- discovery: Brave / SearXNG / DDG / Playwright / dated evidence feed
    |
    +-- evidence: bounded, public-address-pinned page inspection
    |
    +-- decision: deterministic score or no crown
    |
    `-- evil dossier: Minion verdict + structured citations
```

Search titles, snippets, and page data are untrusted input, never instructions. Source and product inspection reject local/private targets, resolve and pin public IP addresses, reject mixed public/private DNS answers, revalidate redirects, cap response sizes, and time out individual pages. Minion MCP has no embedded cloud language model and no telemetry.

## Demos

The gold demo:

```sh
npm run demo:buns
```

The app-verifier demo intentionally serves a broken mini-app, then proves that Minion finds the failures:

```sh
npm run demo
```

Record the bun hunt with [VHS](https://github.com/charmbracelet/vhs):

```sh
vhs demo/x-demo.tape
```

For a short post, show the one `minion_bun_hunt` call, the `BUN INTELLIGENCE LEADERBOARD`, and the phrase `no fake crown`. Suggested copy:

```text
I gave my coding agent a Minion MCP server.

It now ship-checks browser apps, researches claims from opened sources,
and refuses to crown the "juiciest buns on the internet" without receipts.

The important part is not the Minion voice. It is the no-fake-verdict contract.
```

## Develop and Release

```sh
git clone https://github.com/masonclewis/minion-mcp.git
cd minion-mcp
npm install
npm run check
npm run doctor -- --live
npm run demo:buns
```

Useful commands:

```sh
npm run typecheck
npm test
npm run smoke:mcp
npm run smoke:mcp -- --live
npm pack --dry-run
```

To create the prebuilt GitHub Release, commit the release changes, push `main`, then push the matching version tag:

```sh
git tag v<package-version>
git push origin v<package-version>
```

The release workflow verifies the tag against `package.json`, runs the complete check suite, packs the npm-format tarball, and uploads both the versioned package and `minion-mcp-latest.tgz`.

The test suite covers MCP schemas and protocol calls, the no-fake-crown contract, live and snapshot bun evidence, source-inspection outcomes, DNS and redirect boundaries, app-verification findings, browser cleanup, CLI diagnostics, and packaging.

## Fine Print

Live sites, prices, inventory, and product claims change. Review the linked evidence before ordering or making a production decision. No official artwork, audio, voice imitation, scripts, lyrics, or copied movie dialogue is included. Licensed under MIT.