🧭 Quick Navigation

⚡ Get Started • 🎯 Why Vibe Powerpack • 🎮 Tools • ⚙️ Configuration • 📚 Workflows • 🛠️ Development

mcp-vibepowerpack replaces the clunky "type a number" workflow with a polished browser popup. When your AI needs a decision, it opens a real form — radio buttons for single-select, checkboxes for multi-select — and waits for your click. No more miscounted options. No more "I said option 3, not 4."

Here's how it works:

• AI: "Which database should I use?" → Opens a popup with your options
• You: Click your choice, optionally add a comment, hit Submit
• AI: Gets structured JSON back — no parsing, no ambiguity
• Result: Faster decisions, zero miscommunication. ☕

Fork note: This is a fork of mcp-popup-ui by Jens Duttke, enhanced with additional features like "Other" input, explanation requests, and Markdown descriptions.

🎯 Why Vibe Powerpack

Text-based option selection is error-prone and slow. mcp-vibepowerpack replaces it with a real UI.

Key advantages:

• Markdown descriptions — options can include code snippets, pros/cons, links
• Recommended highlights — flag the best option so users see it immediately
• Skip button — user can opt out without breaking the flow
• Explanation requests — ask the AI to elaborate before committing
• "Other" input — let users type a custom answer if nothing fits
• Ephemeral server — popup opens on 127.0.0.1, auto-closes after submit, zero cleanup

🚀 Get Started in 60 Seconds

1. Install

| Client | One-Line Install | Manual Config | |:------:|:----------------:|:-------------:| | 🖥️ Claude Desktop | npx install-mcp mcp-vibepowerpack --client claude-desktop | Config | | ⌨️ Claude Code | npx install-mcp mcp-vibepowerpack --client claude-code | Config | | 🎯 Cursor / 🏄 Windsurf | npx install-mcp mcp-vibepowerpack --client cursor | Config |

That's it. No API keys. No environment variables. Just install and go.

2. Manual Configuration

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "vibepowerpack": {
      "command": "npx",
      "args": ["-y", "mcp-vibepowerpack"]
    }
  }
}

Claude Code (CLI)

claude mcp add vibepowerpack npx --scope user -- -y mcp-vibepowerpack

Or manually add to ~/.claude.json:

{
  "mcpServers": {
    "vibepowerpack": {
      "command": "npx",
      "args": ["-y", "mcp-vibepowerpack"]
    }
  }
}

Cursor/Windsurf

Add to .cursor/mcp.json or equivalent:

{
  "mcpServers": {
    "vibepowerpack": {
      "command": "npx",
      "args": ["-y", "mcp-vibepowerpack"]
    }
  }
}

Backward compatibility: The old binary name vibe-powerpack still works if you have existing configs using it.

🌐 Transport Modes

Vibe Powerpack supports two transport modes:

| Mode | Use Case | How to Start | |------|----------|-------------| | STDIO (default) | Claude Desktop, Cursor, Windsurf | npx mcp-vibepowerpack | | HTTP Streamable | Self-hosted, Docker, LAN sharing | MCP_TRANSPORT=http npx mcp-vibepowerpack |

Self-Hosted HTTP Streamable

# Start on default port 3001
MCP_TRANSPORT=http npx mcp-vibepowerpack

# Custom port
MCP_TRANSPORT=http MCP_PORT=8080 npx mcp-vibepowerpack

{
  "mcpServers": {
    "vibepowerpack-http": {
      "type": "streamable-http",
      "url": "http://localhost:3001/mcp"
    }
  }
}

🎮 Tool Reference

ask_user

Single-select popup — presents radio buttons and returns exactly one selection.

Use this whenever your AI is about to list numbered options and ask "which do you prefer?"

| Parameter | Type | Required | Default | Description | |-----------|------|:--------:|:-------:|-------------| | options | object[] | ✅ | — | Options to display (min 2). Each: { label, description?, recommended? } | | title | string | — | — | Heading displayed above the options | | description | string | — | — | Subheading below the title | | allow_other | boolean | — | false | Show an "Other" free-text input | | other_label | string | — | "Other" | Custom label for the Other option |

Example call:

{
  "options": [
    { "label": "PostgreSQL", "description": "Battle-tested RDBMS with JSON support", "recommended": true },
    { "label": "SQLite", "description": "Zero-config, embedded, perfect for prototyping" },
    { "label": "MongoDB", "description": "Document store, flexible schema" }
  ],
  "title": "Which database?",
  "description": "Choose the database for your new project.",
  "allow_other": true
}

Response format:

{
  "action": "submit",
  "selection": "PostgreSQL",
  "comments": "Let's use the latest v17"
}

Possible action values: "submit" | "skip" | "request_explanation"

ask_user_multiple

Multi-select popup — presents checkboxes and returns one or more selections.

Use this when the user can pick multiple non-exclusive options (e.g., "Which features to include?").

| Parameter | Type | Required | Default | Description | |-----------|------|:--------:|:-------:|-------------| | options | object[] | ✅ | — | Options to display (min 2). Each: { label, description?, recommended? } | | title | string | — | — | Heading displayed above the options | | description | string | — | — | Subheading below the title | | allow_other | boolean | — | false | Show an "Other" free-text input | | other_label | string | — | "Other" | Custom label for the Other option |

Example call:

{
  "options": [
    { "label": "Authentication", "description": "JWT + OAuth2 login flow", "recommended": true },
    { "label": "Rate Limiting", "description": "Token bucket per API key" },
    { "label": "Caching", "description": "Redis-backed response cache" },
    { "label": "Logging", "description": "Structured JSON logs with correlation IDs" }
  ],
  "title": "Select features to scaffold",
  "description": "Pick all that apply. You can add more later."
}

Response format:

{
  "action": "submit",
  "selections": ["Authentication", "Rate Limiting", "Logging"],
  "comments": "Skip caching for now, we'll add it in v2"
}

⚙️ Environment Variables

None required. Vibe Powerpack works out of the box with zero configuration.

The server spins up an ephemeral HTTP server on 127.0.0.1 (random port), opens the user's browser, and tears everything down after the response. No API keys, no tokens, no secrets.

📚 Recommended Workflows

Architecture Decisions

AI: "I can implement this three ways..."
→ Calls ask_user with pros/cons in descriptions
→ User clicks their choice in the popup
→ AI proceeds with the selected approach

Feature Selection

AI: "Here are the available modules for your project..."
→ Calls ask_user_multiple with feature list
→ User checks the ones they want
→ AI scaffolds only the selected features

Clarification Before Proceeding

AI: "Which testing framework?"
→ Calls ask_user with allow_other: true
→ User picks "Other" and types "Bun test"
→ AI uses the custom answer

Explain-Then-Decide

AI: "Which caching strategy?"
→ Calls ask_user with options
→ User clicks "Explain" on an unfamiliar option
→ AI gets request_explanation action, explains that option
→ AI re-opens the popup for the final decision

🛠️ Development

git clone https://github.com/yigitkonur/mcp-vibepowerpack.git
cd mcp-vibepowerpack
npm install
npm run dev       # Start Vite dev server with hot reload
npm run build     # Build for production
npm run lint      # Run linters

How It Works Under the Hood

1. MCP client calls ask_user or ask_user_multiple
2. Server creates an ephemeral HTTP server on 127.0.0.1 (random available port)
3. Server opens the user's browser in app mode (no address bar) — prefers Edge/Chrome, falls back to system default
4. The React frontend loads the form config from /api/config
5. An SSE connection at /api/connection detects if the browser closes (auto-skips)
6. User submits → frontend POSTs to /api/submit → server returns structured JSON to the MCP client
7. Ephemeral server shuts down — nothing left running

Project Structure

mcp-vibepowerpack/
├── mcp/                 # MCP server (TypeScript)
│   ├── server/          # Server setup & tool routing
│   ├── tools/           # Tool definitions & handlers
│   ├── http/            # Ephemeral HTTP server & static serving
│   └── types/           # Shared TypeScript types
├── frontend/            # React popup UI (Vite + React 19)
├── dist/                # Built output (published to npm)
└── assets/              # Screenshots

🔧 Troubleshooting

| Problem | Solution | | :--- | :--- | | Popup doesn't open | Make sure you have Chrome or Edge installed. The server tries to open a chromium-based browser in app mode first. If none is found, it falls back to your system default browser. | | Popup opens but shows blank page | The built frontend assets may be missing. Run npm run build if running from source, or reinstall the package with npx -y mcp-vibepowerpack. | | Tool not appearing in Claude | Restart Claude Desktop / Claude Code after adding the MCP config. Check that the config JSON is valid (no trailing commas). | | "Unknown tool" error | Make sure you're using ask_user or ask_user_multiple (exact names). Tool names are case-sensitive. | | Browser closes = response lost? | No — if the browser closes before submission, the server detects it via SSE and returns a "skip" action automatically. | | Port conflicts | The server uses a random available port each time. If you're seeing port issues, another instance may still be running. Check for stale node processes. | | Windows: popup blocked by firewall | The server only binds to 127.0.0.1 (localhost). No firewall rule should be needed. If prompted, allow the connection — it never leaves your machine. |

MIT © Yiğit Konur

Based on mcp-popup-ui by Jens Duttke — original MIT license preserved.