one-request-mcp

A web-based MCP (Model Context Protocol) server that creates an interactive loop between you and AI. Runs entirely in Node.js — no native executables required.

npx one-request-mcp@latest

English | 中文

Features

• Zero native dependencies — pure Node.js, works on Windows / macOS / Linux
• npx ready — npx one-request-mcp or node src/index.js locally
• Image support — paste images with Ctrl+V or drag & drop; images are sent as MCP image content that the AI can see and understand
• Persistent web UI — browser tab stays open across rounds; real-time updates via WebSocket
• Auto-reopen — if you close the browser window, it automatically reopens when a request is pending
• Dark theme UI — polished developer-friendly interface with keyboard shortcuts
• Tab notifications — title flash + browser notification when AI requests input

How It Works

┌─────────┐    stdio     ┌─────────────────┐   WebSocket   ┌─────────┐
│  Cursor  │◄───────────►│ one-request-mcp │◄─────────────►│ Browser │
│   (AI)   │  JSON-RPC   │    (Node.js)    │    + HTTP     │  (You)  │
└─────────┘              └─────────────────┘               └─────────┘

1. AI calls the onerequest tool with a summary of its work
2. The MCP server pushes the summary to your browser via WebSocket
3. You type a response (and optionally paste images) in the web UI
4. Your input is returned to the AI as the tool result
5. AI processes your input and calls the tool again → loop continues

All of this happens within a single Cursor request, so you get multi-turn interaction without extra billing.

Quick Start

1. Configure Cursor

Add to your Cursor MCP settings (.cursor/mcp.json or global settings):

{
  "mcpServers": {
    "onerequest": {
      "command": "npx",
      "args": ["-y", "one-request-mcp@latest"],
      "autoApprove": ["onerequest"]
    }
  }
}

Local development:

{
  "mcpServers": {
    "onerequest": {
      "command": "node",
      "args": ["C:/path/to/one-request-mcp/src/index.js"],
      "autoApprove": ["onerequest"]
    }
  }
}

2. Add Cursor Rules

Create or add to .cursor/rules/onerequest.mdc:

---
description: Interactive loop
globs:
alwaysApply: true
---

After completing your full response, you MUST call onerequest as your very last action. Do NOT call it in the middle of your answer.
After receiving the MCP result, if there is input, process it first. Then regardless of whether the input was empty, had content, or the call failed, you MUST call onerequest again. NEVER stop. Loop forever.
You are ABSOLUTELY FORBIDDEN from ending a request on your own. The user will manually stop you. Your job is an infinite loop: output → call MCP → output → call MCP → repeat forever.

3. Start chatting

Send any message to AI in Cursor. After the AI responds, it will automatically call onerequest. Your browser will open with the web UI where you can:

• Read the AI's work summary
• Type a text response
• Paste screenshots / images with Ctrl+V
• Drag & drop image files
• Press Ctrl+Enter or click the button to submit

CLI Options

| Option | Description | Default | |--------|-------------|---------| | --port <number> | Use a fixed port for the web UI | Random available port | | --no-browser | Don't open browser; use with the Cursor extension | Opens browser | | --help, -h | Show help message | | | --version, -v | Show version number | |

Examples:

# Browser mode (default) with fixed port
npx one-request-mcp --port 23198

# Extension-only mode (no browser window)
npx one-request-mcp --port 23198 --no-browser

MCP Tool

onerequest

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | summary | string | Yes | Summary of work done so far |

Returns: An array of content items:

• { type: "text", text: "..." } — user's text input
• { type: "image", data: "base64...", mimeType: "image/png" } — pasted/dropped images

Keyboard Shortcuts

| Shortcut | Action | |----------|--------| | Ctrl + Enter | Submit | | Ctrl + V | Paste image from clipboard |

Architecture

• MCP Server: Built with @modelcontextprotocol/sdk, communicates with Cursor via stdio JSON-RPC
• HTTP Server: Serves the web UI on 127.0.0.1 (localhost only)
• WebSocket: Real-time bidirectional communication between server and browser
• Image Processing: Client-side resizing (max 2048px) to keep payloads reasonable
• Auto-reopen: Detects when all WebSocket clients disconnect while a request is pending, and automatically reopens the browser

Requirements

• Node.js >= 18.0.0
• A modern browser (Chrome, Edge, Firefox, Safari)

License

MIT