Human Loop

What Is This?

An MCP (Model Context Protocol) server that gives AI agents a way to ask the human operator questions through the browser.

1. A lightweight localhost HTTP server spins up
2. Your default browser opens a dialog page
3. You fill in the form (optionally attaching files) and submit
4. The response flows back to the agent through MCP

No Python, no Tkinter, no Electron — just a Node.js process, a browser tab, and clean HTML.

Why?

GUI-based human-in-the-loop tools often break on macOS (Accessibility permissions, focus stealing, Python framework builds). This project sidesteps all of that by using the browser as the UI layer — it works everywhere Node.js runs.

Features

Install

npm (recommended)

npm install -g human-loop-mcp

Or run directly without installing:

npx human-loop-mcp

From source

git clone https://github.com/dzulfiikar/human-loop-mcp.git
cd human-loop-mcp
npm install
npm run build

Quick Start

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

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

Cursor / Windsurf

Add to .cursor/mcp.json or equivalent:

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

GitHub Copilot CLI

[mcp_servers.human-loop]
command = "npx"
args = ["-y", "human-loop-mcp"]

From source (development)

[mcp_servers.human-loop-dev]
command = "npx"
args = ["tsx", "/path/to/human-loop-mcp/src/index.ts"]

Tools

Example: Text Input

{
  "title": "API Key",
  "prompt": "Enter your OpenAI API key:",
  "input_type": "password"
}

Example: Choice

{
  "title": "Database",
  "prompt": "Which database should I use?",
  "choices": ["PostgreSQL", "MySQL", "SQLite"],
  "allow_multiple": false
}

Example: Confirmation

{
  "title": "Deploy",
  "message": "Deploy v2.1.0 to production?",
  "confirm_label": "Deploy",
  "cancel_label": "Abort"
}

File Attachments

The get_multiline_input dialog supports file attachments through three methods:

Attachment behavior

• Any file type is accepted
• 5 MB per-file limit — oversized files are rejected with an inline error
• Files are base64-encoded and returned in the tool result alongside the text value
• Image previews are shown as thumbnails in the attachment chips
• Each chip shows the file name, size, and a remove button
• When no files are attached, the result is identical to the previous format (fully backward-compatible)

Result format

When attachments are present, the get_multiline_input tool returns:

{
  "action": "submit",
  "value": "Here is the screenshot",
  "attachments": [
    {
      "name": "screenshot.png",
      "type": "image/png",
      "size": 48210,
      "data": "iVBORw0KGgo..."
    }
  ]
}

When no attachments are provided, the attachments field is omitted entirely.

Configuration

Environment variables

Programmatic usage

import { BrowserDialogServer } from "human-loop-mcp/browser/browser-dialog-server";

const server = new BrowserDialogServer({
  port: 8080,
  launchUrl: async (url) => {
    console.log(`Open: ${url}`);
  },
});

Architecture

┌──────────────────────────────────────────┐
│           MCP Client (AI Agent)          │
│      Claude / Cursor / Copilot CLI       │
└──────────────┬───────────────────────────┘
               │ stdio (JSON-RPC)
┌──────────────▼───────────────────────────┐
│  index.ts        Tool registration       │
│  service.ts      Business logic          │
│  browser-dialog-server.ts   HTTP + APIs  │
│  dialog-session-manager.ts  Sessions     │
│  html.ts         HTML/CSS/JS renderer    │
└──────────────┬───────────────────────────┘
               │ HTTP (localhost)
┌──────────────▼───────────────────────────┐
│         Browser Dialog UI                │
│  Forms · Autocomplete · Attachments      │
│  Dark/light · Keyboard shortcuts         │
└──────────────────────────────────────────┘

Data flow

1. MCP client calls a tool (e.g. get_multiline_input) via stdio JSON-RPC
2. index.ts routes the call to HumanLoopService
3. service.ts transforms args and calls BrowserDialogServer.openDialog()
4. browser-dialog-server.ts creates a session, starts HTTP if needed, opens the browser
5. html.ts renders a self-contained HTML page with the dialog form
6. User submits (with optional file attachments) — the POST handler validates and resolves the session promise
7. Response flows back through MCP to the AI agent, including any base64-encoded attachments

Development

npm install          # Install dependencies
npm run dev          # Run from source (tsx, hot-reload)
npm run build        # Compile to dist/
npm test             # Run tests (Vitest)
npm run typecheck    # Type-check without emitting

Project structure

src/
├── index.ts                       MCP server entry point & tool registration
├── service.ts                     Tool handler business logic
└── browser/
    ├── browser-dialog-server.ts   HTTP server, browser launcher, API endpoints
    ├── dialog-session-manager.ts  Session lifecycle, validation & attachment types
    └── html.ts                    Dialog page renderer (forms, autocomplete, attachments)

tests/
├── service.test.ts
├── dialog-session-manager.test.ts
└── browser-dialog-server.test.ts

Contributing

See CONTRIBUTING.md for development setup, code style, and PR guidelines.

License

MIT