PipeStage

May 5, 2026 · View on GitHub

PipeStage

A fast, web-native MongoDB GUI that launches with a single command and runs in any browser — no installation, no Electron, no paid seats.

npx pipestage

Why PipeStage?

Tool	Problem
MongoDB Compass	Slow/unresponsive on large datasets (>30 MB collections, >5 MB documents). Desktop-only.
Studio 3T / NoSQLBooster	Paid seats. Heavy UI. Can't run in remote or virtual environments.
mongo-express / mongo-gui	Missing aggregation builder, explain plans, profiler, and multi-connection support.

PipeStage is lightweight, web-native, and deployable anywhere. It has no external dependencies beyond the MongoDB native driver.

Features

Multi-connection — manage multiple MongoDB connections simultaneously, including SSH tunnel and TLS support
Query editor — CodeMirror 6-based editor with MongoDB syntax highlighting and variable placeholder support
Pipeline builder — visual stage-by-stage aggregation builder with form and code modes
Results viewer — virtual scrolling for large result sets, expandable JSON tree, inline document editing
Explain plans — visual execution plan with stage breakdown, keysExamined, and docsExamined
Profiler — MongoDB slow-query profiler integration with ESR index recommendations and COLLSCAN warnings
Backup & restore — full database backup via mongodump/mongorestore with real-time WebSocket progress streaming
Workspace layouts — saveable pane layouts (split horizontal/vertical), multi-tab per pane, persistent state
VS Code extension — select a MongoDB query in your editor, open it in PipeStage for visual editing, write it back automatically
MCP server — local HTTP relay bridging VS Code's AI assistant (Claude, Copilot) to PipeStage for query extraction and reconstruction
Zero install — runs as a single npx binary, no Electron, no native modules required

Quick Start

# Run directly (no global install needed)
npx pipestage

# Run on a custom port
npx pipestage --port 3000

# Listen on all interfaces (e.g. for Docker or remote access)
npx pipestage --host 0.0.0.0

# Don't auto-open the browser
npx pipestage --no-open

PipeStage opens at http://localhost:27018 by default.

CLI Options

Flag	Default	Description
`--port <num>`	`27018`	HTTP server port
`--host <addr>`	`127.0.0.1`	Listen address
`--config-dir <path>`	OS default¹	Directory for connections and workspace state
`--basic-auth <user:pass>`	—	Enable HTTP basic authentication
`--allow-plaintext-passwords`	—	Store passwords unencrypted (dev only)
`--read-only`	—	Disable all write operations
`--no-open`	—	Don't auto-open the browser on start
`--daemon`	—	Run in the background
`--benchmark`	—	Print cold-start time and exit

¹ Default config directory: ~/.config/pipestage on Linux/macOS, %APPDATA%\pipestage on Windows.

Environment variables

Variable	Description
`PIPESTAGE_CONFIG_DIR`	Override the default config directory
`PIPESTAGE_PORT`	Main server port (used by MCP to locate PipeStage)
`PIPESTAGE_MCP_PORT`	MCP relay server port (default `27019`)
`PIPESTAGE_MCP_SECRET`	Shared secret enabling the Code Query feature

How It Works

Architecture

Browser (React + CodeMirror)
        │  REST API + WebSocket
        ▼
Node.js HTTP Server
        │  MongoDB native driver
        ▼
MongoDB instance(s)

The server is a plain Node.js HTTP server — no Express, no framework. The client is a React 19 app bundled by Vite. State is managed with Zustand; API data is cached with React Query. WebSockets handle real-time events (backup progress, live query results, multi-tab sync).

Query execution

The user writes a MongoDB query in the CodeMirror editor (find, aggregate, countDocuments, etc.)
The client sends POST /api/q with the connection ID, database, collection, filter/pipeline, and pagination options
The server compiles find queries to aggregation pipelines internally and strips write stages ($out, $merge) to prevent accidental writes during preview
Results are returned with document count estimation and execution stats
The results pane renders documents with virtual scrolling — large collections don't block the UI

Storage

PipeStage stores all state locally in the config directory:

Path	Contents
`<config-dir>/<id>.json`	One JSON file per saved connection
`<config-dir>/workspaces/`	Pane layouts and workspace state
`<config-dir>/backup-history.json`	Backup job history

Passwords are stored encrypted via the system keyring by default. Use --allow-plaintext-passwords only for development.

Security

Each server instance generates a 32-byte random authentication token at startup, embedded in the served HTML as window.__PIPESTAGE_TOKEN__. Every API request must include this token in the X-PipeStage-Token header. Requests without a valid token are rejected.

MCP Server

The MCP server is a local HTTP relay that enables the VS Code extension to open MongoDB queries from your source code directly in PipeStage for visual editing.

How it works

VS Code Extension
      │  1. Extract query from selection (via Claude/Copilot)
      ▼
MCP Server (port 27019)
      │  2. Forward to PipeStage with session ID
      ▼
PipeStage UI
      │  3. User edits query visually
      ▼
MCP Server
      │  4. Receive edited query via callback
      ▼
VS Code Extension
      5. Reconstruct original code with updated query
      6. Write back to editor

Enabling the MCP server

Set PIPESTAGE_MCP_SECRET to any shared secret before starting PipeStage. The same secret must be set in the VS Code extension settings.

PIPESTAGE_MCP_SECRET=my-secret npx pipestage

API reference

`POST /extract`

Receives a MongoDB query extracted from VS Code. Creates a session and forwards the query to PipeStage for editing.

Request body:

{
  "sessionId": "string",
  "query": "string",
  "language": "javascript | typescript",
  "connectionHint": "optional connection ID or URI"
}

Response: 200 OK with { "sessionId": "string" }

`GET /result/:sessionId`

Polls for the edited query. The VS Code extension calls this with exponential backoff.

Responses:

Status	Meaning
`200 OK`	Edit complete — body contains `{ "query": "string" }`
`204 No Content`	Not ready yet — keep polling
`404 Not Found`	Session expired (35-minute TTL) or never existed

`POST /callback/:sessionId`

Called by PipeStage when the user confirms their edits. Not called by the extension directly.

`GET /health`

Returns 200 OK if the MCP server is running.

Configuration

Variable	Default	Description
`PIPESTAGE_MCP_PORT`	`27019`	Port the MCP relay listens on
`PIPESTAGE_PORT`	`27018`	Port used to locate the main PipeStage server
`PIPESTAGE_MCP_SECRET`	—	Required to enable the MCP server

Sessions expire automatically after 35 minutes and are cleaned up periodically.

VS Code Extension

The PipeStage VS Code extension lets you select any MongoDB query in your code and open it in PipeStage for visual editing. When you're done, it writes the updated query back into your source file, preserving your code structure, variable references, and comments.

Requirements

VS Code 1.85+
PipeStage running locally (npx pipestage)
The Claude VS Code extension or GitHub Copilot (used for query extraction/reconstruction)
PIPESTAGE_MCP_SECRET set in both PipeStage and the extension settings

Installation

Install the .vsix package from the releases page:

code --install-extension pipestage-vscode-<version>.vsix

Or search for PipeStage in the VS Code Extensions marketplace.

Configuration

Open VS Code settings and search for pipestage:

Setting	Description
`pipestage.mcpSecret`	Must match `PIPESTAGE_MCP_SECRET` set on the server
`pipestage.mcpPort`	MCP server port (default `27019`)
`pipestage.pipestagePort`	Main PipeStage port (default `27018`)

You can also set PIPESTAGE_DEFAULT_CONNECTION in a .env file at your project root to hint which connection PipeStage should open the query against.

Usage

Select a MongoDB query in your JavaScript or TypeScript file — a find(), aggregate(), countDocuments(), etc.
Open the command palette (Ctrl+Shift+P / Cmd+Shift+P) and run Open in PipeStage Editor — or use the keyboard shortcut: Ctrl+Alt+P (Windows/Linux) / Cmd+Alt+P (macOS)
The extension extracts the query using Claude/Copilot and opens it in PipeStage
Edit the query visually — adjust filters, add pipeline stages, test against real data
Confirm your edits in PipeStage
The extension reconstructs your original code with the updated query and writes it back to the file

What gets preserved

Variable references (the extension does not hardcode values from your runtime environment)
Code structure and surrounding context
Comments
Code style (Mongoose queries are detected and rejected — only the native MongoDB driver is supported)

Development

# Install dependencies
pnpm install

# Build server and client
pnpm build

# Run unit tests
pnpm test:unit

# Run E2E tests (against in-memory MongoDB)
pnpm test:e2e

# Run E2E tests against a real MongoDB instance
PIPESTAGE_E2E_MONGO_URI=mongodb://localhost:27017 pnpm test:e2e

# Lint
pnpm lint

# Analyse bundle size
pnpm bench:bundle

# Measure cold-start time
pnpm bench:cold-start

Project structure

pipestage/
├── bin/
│   └── pipestage.js              # CLI entry point
├── src/
│   ├── client/                   # React frontend (Vite)
│   │   ├── components/           # UI components
│   │   ├── stores/               # Zustand state stores
│   │   ├── menu-items/           # Context menu actions
│   │   └── main.tsx              # App entry point
│   └── server/                   # Node.js HTTP server
│       ├── handlers/             # API route handlers
│       ├── query-engine/         # Query compilation and execution
│       └── mcp/                  # MCP relay server
├── packages/
│   └── pipestage-vscode/         # VS Code extension
│       └── src/
│           ├── extension.ts      # Command registration
│           ├── claude-extractor.ts
│           ├── claude-reconstructor.ts
│           └── mcp-client.ts
├── tests/                        # Playwright E2E tests
├── vite.config.ts
├── tsconfig.server.json
└── tsconfig.client.json

License

MIT

PipeStage

Why PipeStage?

Features

Quick Start

Installation

Run without installing

Install globally

From source

CLI Options

Environment variables

How It Works

Architecture

Query execution

Storage

Security

MCP Server

How it works

Enabling the MCP server

API reference

`POST /extract`

`GET /result/:sessionId`

`POST /callback/:sessionId`

`GET /health`

Configuration

VS Code Extension

Requirements

Installation

Configuration

Usage

What gets preserved

Development

Project structure

License