Metadata-Version: 2.4
Name: humanbridge-mcp
Version: 1.0.1
Summary: HumanBridge MCP Server by Jatin Iyer — AI-to-human GUI dialogs with dynamic sizing and scrollable content
Project-URL: Homepage, https://github.com/jatiniyer/humanbridge-mcp
Project-URL: Repository, https://github.com/jatiniyer/humanbridge-mcp
Project-URL: Issues, https://github.com/jatiniyer/humanbridge-mcp/issues
Author: Jatin Iyer
License: MIT
Keywords: ai-assistant,cross-platform,dialog,fastmcp,gui,human-in-the-loop,mcp,model-context-protocol,tkinter,user-interaction
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: OS Independent
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: User Interfaces
Requires-Python: >=3.12
Requires-Dist: fastmcp>=2.8.1
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: build>=0.10.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.20.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: twine>=4.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# HumanBridge MCP Server

**by Jatin Iyer**

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![PyPI version](https://img.shields.io/pypi/v/humanbridge-mcp.svg)](https://pypi.org/project/humanbridge-mcp/)

A **Model Context Protocol (MCP) Server** that enables AI assistants to interact with
humans through polished, modern GUI dialogs. HumanBridge bridges the gap between automated
AI processes and human decision-making — providing text input, multiple choice, confirmations,
and info notifications, all in dynamically-sized, scrollable windows that never overflow your screen.

---

## Features

- **Text Input** — get text, numbers, or other data with validation
- **Multiple Choice** — single or multi-select option lists
- **Multi-line Input** — collect code, descriptions, or long-form content
- **Confirmation Dialogs** — yes/no decisions before proceeding
- **Information Messages** — display notifications and status updates
- **Health Check** — monitor server and GUI availability
- **Dynamic sizing** — windows grow to fit content, cap at 80% screen height, then scroll
- **Scrollable content** — title/prompt area scrolls automatically when text is long
- **Cross-platform** — Windows 11-style, macOS native, Linux compatible

---

## Installation

### Quick Install with uvx (Recommended)

```bash
uvx humanbridge-mcp
```

### pip

```bash
pip install humanbridge-mcp
humanbridge-mcp
```

---

## Configuration

### VS Code GitHub Copilot

Add to your VS Code `settings.json` or `.vscode/mcp.json`:

```json
{
  "mcp": {
    "servers": {
      "humanbridge": {
        "command": "uvx",
        "args": ["humanbridge-mcp"]
      }
    }
  }
}
```

### Claude Desktop

**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`  
**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`  
**Linux:** `~/.config/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "humanbridge": {
      "command": "uvx",
      "args": ["humanbridge-mcp"]
    }
  }
}
```

Restart after updating the config.

---

## Available Tools

### `get_user_input`
Single-line text, integer, or float input.

| Parameter | Type | Description |
|-----------|------|-------------|
| `title` | str | Dialog window title |
| `prompt` | str | Question shown to user |
| `default_value` | str | Pre-filled value (optional) |
| `input_type` | str | `"text"`, `"integer"`, or `"float"` |

### `get_user_choice`
Pick one or many options from a list.

| Parameter | Type | Description |
|-----------|------|-------------|
| `title` | str | Dialog window title |
| `prompt` | str | Question shown to user |
| `choices` | list[str] | Options to present |
| `allow_multiple` | bool | Allow multi-select (default: false) |

### `get_multiline_input`
Large text area for code, descriptions, or long content.

| Parameter | Type | Description |
|-----------|------|-------------|
| `title` | str | Dialog window title |
| `prompt` | str | Question shown to user |
| `default_value` | str | Pre-filled text (optional) |

### `show_confirmation_dialog`
Yes/No decision dialog.

| Parameter | Type | Description |
|-----------|------|-------------|
| `title` | str | Dialog window title |
| `message` | str | Confirmation message |

### `show_info_message`
Informational notification — user clicks OK to dismiss.

| Parameter | Type | Description |
|-----------|------|-------------|
| `title` | str | Dialog window title |
| `message` | str | Information message |

### `health_check`
Returns server status, platform details, and GUI availability.

---

## Response Format

All tools return structured JSON:

```json
{
  "success": true,
  "user_input": "User's response",
  "cancelled": false,
  "platform": "windows"
}
```

**Common fields:** `success`, `cancelled`, `platform`, `error`  
**Tool-specific:** `user_input`, `input_type`, `selected_choice`, `selected_choices`, `confirmed`, `response`, `acknowledged`, `character_count`, `line_count`

---

## Dialog Behaviour

- **Short content**: window sizes exactly to content — compact and clean
- **Long content**: window grows up to 80% of screen height, then the title/prompt area becomes scrollable (mousewheel supported)
- **Input widgets** (entry field, text area, choice list) are always fully visible — they never scroll away
- All dialogs are resizable by the user

---

## Troubleshooting

**Dialogs not appearing**
- Verify you're in a desktop environment (not headless)
- Check tkinter: `python -c "import tkinter"`
- Run `health_check` tool to diagnose

**macOS permission error**
- Grant Accessibility permissions: System Preferences → Security & Privacy → Accessibility

**Dialog timeout**
- Default timeout is 5 minutes. Dialogs return `cancelled: true` after timeout.

---

## Platform Support

| Platform | Status | Notes |
|----------|--------|-------|
| Windows 10/11 | ✅ Full | Modern Windows 11-style UI, Segoe UI font |
| macOS | ✅ Full | SF Pro Display font, Accessibility permission needed |
| Linux | ✅ Full | Ubuntu/Debian compatible, system fonts |

---

## License

MIT License — see [LICENSE](LICENSE)

---

*HumanBridge MCP Server by Jatin Iyer*
