# mcp-pop-up

An [MCP](https://modelcontextprotocol.io) server that lets a local LLM **ask you
for guidance through a native desktop pop-up** — just like the question prompts
Claude shows in the app.

The model calls a single tool, `ask_user`, with a question and up to **6**
suggested answers. An **"Other"** free-text choice is always added automatically,
and the model decides whether you may pick **one** answer (radio buttons) or
**several** (checkboxes). Your choice is returned to the model so it knows how to
proceed.

Built for **LM Studio**, but it works with any MCP client that speaks stdio.

---

## How it works

```
LM Studio ─stdio─► mcp_pop_up.server ─subprocess─► mcp_pop_up.dialog (tkinter)
   ▲                                                          │
   └──────────────  "The user selected: …"  ◄─────────────────┘
```

The server exposes the `ask_user` tool. When called, it launches the dialog in a
short-lived subprocess to render the Tk window. Running the GUI in its own
process keeps the blocking Tk event loop from colliding with the server's async
loop, and works reliably across Windows, macOS, and Linux.

The code is split so each module has one job:

| Module                       | Responsibility |
|------------------------------|----------------|
| `mcp_pop_up/protocol.py`     | Request/result data model — validation, JSON (de)serialization, and result formatting. The single source of truth for the contract; depends on neither `mcp` nor tkinter. |
| `mcp_pop_up/server.py`       | The FastMCP server and the `ask_user` tool. |
| `mcp_pop_up/runner.py`       | Launches the dialog subprocess and parses its result. |
| `mcp_pop_up/dialog/view.py`  | The `PopupDialog` tkinter window. |
| `mcp_pop_up/dialog/__main__.py` | Subprocess entry point: stdin → dialog → stdout. |
| `server.py` (root)           | Thin launcher so clients can point at a file path without installing. |

---

## The `ask_user` tool

| Argument         | Type        | Default | Description |
|------------------|-------------|---------|-------------|
| `question`       | string      | —       | The question shown to the user (required). |
| `options`        | string[]    | `[]`    | Up to 6 suggested answers. May be empty for an open-ended question. |
| `allow_multiple` | boolean     | `false` | `true` → checkboxes (pick several). `false` → radio buttons (pick one). |

An **"Other (type your own answer)"** choice with a text box is always appended,
so the user is never limited to the options you provide.

**Returns** a short human-readable summary, e.g.:

- `The user selected: Wait for review`
- `The user selected 2 options:\n- Lint\n- Build`
- `The user selected: Refactor the parser first` *(typed into "Other")*
- `The user cancelled the pop-up without choosing an answer.`

---

## Requirements

- **Python 3.10+**
- **tkinter** — bundled with the standard Python installers on **Windows** and
  **macOS**. On **Linux** install it separately:
  ```bash
  sudo apt install python3-tk      # Debian/Ubuntu
  sudo dnf install python3-tkinter # Fedora
  ```
- The [`mcp`](https://pypi.org/project/mcp/) Python SDK (installed below).

## Install

```bash
git clone https://github.com/GiantBeaver9/mcp-pop-up.git
cd mcp-pop-up
pip install -r requirements.txt        # just the runtime dep, or:
pip install -e .                        # installs the `mcp-pop-up` command too
```

Verify it starts (Ctrl-C to stop — it waits silently for a client on stdio):

```bash
python server.py          # via the file-path launcher, or:
python -m mcp_pop_up       # via the package, or:
mcp-pop-up                 # via the console script (after `pip install -e .`)
```

---

## Configure LM Studio

LM Studio manages MCP servers through its `mcp.json` file
(**Program → Edit `mcp.json`**, or the "Integrations" / MCP settings panel).
Add this entry, using an **absolute path** to the launcher:

```json
{
  "mcpServers": {
    "pop-up": {
      "command": "python",
      "args": ["/absolute/path/to/mcp-pop-up/server.py"]
    }
  }
}
```

On Windows, use `python` (or the full path to `python.exe`) and a full path such
as `C:\\Users\\you\\mcp-pop-up\\server.py`.

The root `server.py` launcher works without installing the package. If you ran
`pip install -e .`, you can instead use `"command": "mcp-pop-up", "args": []`, or
`"args": ["-m", "mcp_pop_up"]`.

Reload the MCP servers in LM Studio. The `ask_user` tool should now appear and
be available to the model. Ask your model something like *"Ask me whether to
deploy now or wait, then act on my answer"* to see the pop-up.

> **Tip:** Make sure LM Studio runs the same Python interpreter that has both
> `mcp` and `tkinter` installed — the server launches the dialog with that same
> interpreter.

### Use with other MCP clients

Any stdio MCP client works. Point it at `python /absolute/path/to/server.py`.

---

## Project layout

```
mcp-pop-up/
├── server.py                 # thin launcher (point MCP clients here)
├── pyproject.toml            # packaging + `mcp-pop-up` console script
├── requirements.txt          # runtime dependency (mcp)
└── mcp_pop_up/
    ├── __main__.py           # `python -m mcp_pop_up` → server
    ├── protocol.py           # request/result model: validation + JSON + formatting
    ├── server.py             # FastMCP server + the `ask_user` tool
    ├── runner.py             # launches the dialog subprocess, parses its result
    └── dialog/
        ├── __main__.py       # subprocess entry: stdin → dialog → stdout
        └── view.py           # PopupDialog tkinter window
```

## Troubleshooting

- **`GUI is unavailable: No module named 'tkinter'`** — install tkinter for the
  interpreter LM Studio uses (see *Requirements*).
- **No window appears** — the pop-up shows on the machine running the server. It
  needs a desktop session; it won't display over a headless SSH connection.
- **Tool doesn't show up in LM Studio** — double-check the absolute path in
  `mcp.json` and reload the MCP servers.