mcp-vibepowerpack 1.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jens Duttke
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,406 @@
+<h1 align="center">🎨 Vibe Powerpack MCP 🎨</h1>
+<h3 align="center">Stop typing choices into chat. Start clicking them in a real UI.</h3>
+
+<p align="center">
+  <strong>
+    <em>Beautiful browser-based popup forms for your AI coding assistant. When your LLM needs user input, it opens a real UI — radio buttons, checkboxes, comments — instead of dumping numbered lists into the chat.</em>
+  </strong>
+</p>
+
+<p align="center">
+  <!-- Package Info -->
+  <a href="https://www.npmjs.com/package/mcp-vibepowerpack"><img alt="npm" src="https://img.shields.io/npm/v/mcp-vibepowerpack.svg?style=flat-square&color=4D87E6"></a>
+  <a href="#"><img alt="node" src="https://img.shields.io/badge/node-18+-4D87E6.svg?style=flat-square"></a>
+  &nbsp;&nbsp;•&nbsp;&nbsp;
+  <!-- Features -->
+  <a href="https://opensource.org/licenses/MIT"><img alt="license" src="https://img.shields.io/badge/License-MIT-F9A825.svg?style=flat-square"></a>
+  <a href="#"><img alt="platform" src="https://img.shields.io/badge/platform-macOS_|_Linux_|_Windows-2ED573.svg?style=flat-square"></a>
+  <a href="#-tool-reference"><img alt="tools" src="https://img.shields.io/badge/tools-2-2ED573.svg?style=flat-square"></a>
+</p>
+
+<p align="center">
+  <img alt="zero config" src="https://img.shields.io/badge/🔧_zero_config-no_API_keys_needed-2ED573.svg?style=for-the-badge">
+  <img alt="ephemeral" src="https://img.shields.io/badge/🔒_ephemeral-popup_closes_after_use-2ED573.svg?style=for-the-badge">
+</p>
+
+<div align="center">
+
+### 🧭 Quick Navigation
+
+[**⚡ Get Started**](#-get-started-in-60-seconds) •
+[**🎯 Why Vibe Powerpack**](#-why-vibe-powerpack) •
+[**🎮 Tools**](#-tool-reference) •
+[**⚙️ Configuration**](#%EF%B8%8F-environment-variables) •
+[**📚 Workflows**](#-recommended-workflows) •
+[**🛠️ Development**](#%EF%B8%8F-development)
+
+</div>
+
+---
+
+**`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."
+
+<div align="center">
+<table>
+<tr>
+<td align="center">
+<h3>🔘</h3>
+<b>Single-Select</b><br/>
+<sub>Radio buttons with descriptions</sub>
+</td>
+<td align="center">
+<h3>☑️</h3>
+<b>Multi-Select</b><br/>
+<sub>Checkboxes for multiple picks</sub>
+</td>
+<td align="center">
+<h3>💬</h3>
+<b>Comments</b><br/>
+<sub>Add context to your choices</sub>
+</td>
+<td align="center">
+<h3>❓</h3>
+<b>Explain First</b><br/>
+<sub>Ask for details before deciding</sub>
+</td>
+</tr>
+</table>
+</div>
+
+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](https://github.com/nicobailon/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.
+
+<table align="center">
+<tr>
+<td align="center"><b>❌ Old Way (Text Chat)</b></td>
+<td align="center"><b>✅ New Way (Vibe Powerpack)</b></td>
+</tr>
+<tr>
+<td>
+<ol>
+  <li>AI dumps a numbered list into chat.</li>
+  <li>You squint at 8 options with no descriptions.</li>
+  <li>You type "3" — wait, was PostgreSQL 3 or 4?</li>
+  <li>AI misparses your response half the time.</li>
+  <li>Repeat until frustrated.</li>
+</ol>
+</td>
+<td>
+<ol>
+  <li>AI calls <code>ask_user</code> with labeled options.</li>
+  <li>A popup opens with clear descriptions.</li>
+  <li>You click the one you want.</li>
+  <li>AI gets structured data — zero ambiguity.</li>
+  <li>Move on with your life. ☕</li>
+</ol>
+</td>
+</tr>
+</table>
+
+**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
+
+<div align="center">
+
+| Client | One-Line Install | Manual Config |
+|:------:|:----------------:|:-------------:|
+| 🖥️ **Claude Desktop** | `npx install-mcp mcp-vibepowerpack --client claude-desktop` | [Config](#claude-desktop) |
+| ⌨️ **Claude Code** | `npx install-mcp mcp-vibepowerpack --client claude-code` | [Config](#claude-code-cli) |
+| 🎯 **Cursor / 🏄 Windsurf** | `npx install-mcp mcp-vibepowerpack --client cursor` | [Config](#cursorwindsurf) |
+
+</div>
+
+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`:
+
+```json
+{
+  "mcpServers": {
+    "vibepowerpack": {
+      "command": "npx",
+      "args": ["-y", "mcp-vibepowerpack"]
+    }
+  }
+}
+```
+
+#### Claude Code (CLI)
+
+```bash
+claude mcp add vibepowerpack npx --scope user -- -y mcp-vibepowerpack
+```
+
+Or manually add to `~/.claude.json`:
+
+```json
+{
+  "mcpServers": {
+    "vibepowerpack": {
+      "command": "npx",
+      "args": ["-y", "mcp-vibepowerpack"]
+    }
+  }
+}
+```
+
+#### Cursor/Windsurf
+
+Add to `.cursor/mcp.json` or equivalent:
+
+```json
+{
+  "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.
+
+---
+
+## 🎮 Tool Reference
+
+<div align="center">
+<table>
+<tr>
+<td align="center">
+<h3>🔘</h3>
+<b><code>ask_user</code></b><br/>
+<sub>Single-select (radio buttons)</sub>
+</td>
+<td align="center">
+<h3>☑️</h3>
+<b><code>ask_user_multiple</code></b><br/>
+<sub>Multi-select (checkboxes)</sub>
+</td>
+</tr>
+</table>
+</div>
+
+### `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:**
+
+```json
+{
+  "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:**
+
+```json
+{
+  "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:**
+
+```json
+{
+  "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:**
+
+```json
+{
+  "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
+
+```bash
+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
+
+<details>
+<summary><b>Expand for troubleshooting tips</b></summary>
+
+| 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. |
+
+</details>
+
+---
+
+<div align="center">
+
+MIT © [Yiğit Konur](https://github.com/yigitkonur)
+
+Based on [mcp-popup-ui](https://github.com/nicobailon/mcp-popup-ui) by [Jens Duttke](https://github.com/nicobailon) — original MIT license preserved.
+
+</div>