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.

Installation

Run without installing

npx pipestage

Install globally

npm install -g @thedecipherist/pipestage
pipestage

From source

git clone https://github.com/TheDecipherist/pipestage.git
cd pipestage
pnpm install
pnpm build
node bin/pipestage.js

Prerequisites: Node.js >= 20.0.0

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

1. The user writes a MongoDB query in the CodeMirror editor (find, aggregate, countDocuments, etc.)
2. The client sends POST /api/q with the connection ID, database, collection, filter/pipeline, and pagination options
3. The server compiles find queries to aggregation pipelines internally and strips write stages ($out, $merge) to prevent accidental writes during preview
4. Results are returned with document count estimation and execution stats
5. 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

1. Select a MongoDB query in your JavaScript or TypeScript file — a find(), aggregate(), countDocuments(), etc.
2. 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)
3. The extension extracts the query using Claude/Copilot and opens it in PipeStage
4. Edit the query visually — adjust filters, add pipeline stages, test against real data
5. Confirm your edits in PipeStage
6. 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