# OpenPost

<p align="center">
  <strong>The Clean-Room, Local-First Postman Scratch Pad Replacement.</strong><br>
  <em>Purely offline. Zero accounts. Zero telemetry. 100% Agent-Operable via Model Context Protocol (MCP).</em>
</p>

<p align="center">
  <img src="https://img.shields.io/badge/Python-3.10%2B-blue?logo=python" alt="Python Version" />
  <img src="https://img.shields.io/badge/FastAPI-0.115%2B-009688?logo=fastapi" alt="FastAPI" />
  <img src="https://img.shields.io/badge/MCP-23%20Tools-6366f1" alt="MCP 23 Tools" />
  <img src="https://img.shields.io/badge/Desktop-Tauri%20v2-orange?logo=tauri" alt="Tauri v2" />
  <img src="https://img.shields.io/badge/Offline%20First-100%25-success" alt="Offline First" />
  <img src="https://img.shields.io/badge/License-MIT-green" alt="MIT License" />
</p>

---

## 🚀 Why OpenPost?

In late 2023, Postman deprecated and removed the beloved **offline Scratch Pad**, mandating cloud-synced accounts and forcing all API test traffic, collections, and sensitive credentials through external cloud servers.

**OpenPost** is a clean-room, open-source replacement designed from the ground up to restore the speed, privacy, and simplicity of local API testing:

* **Zero Cloud Mandate:** Stored 100% locally on your machine in human-readable flat JSON files and SQLite.
* **100% Postman Collection v2.1.0 Interoperability:** Flawless import and round-trip export compatible with Postman schemas.
* **Agent-Operable via MCP:** Exposes **23 structured Model Context Protocol (MCP) tools** so AI agents (Antigravity, Claude, Cursor, Codex) can browse, author, execute, and verify APIs autonomously.
* **JavaScript Script Engine (`pm.*`):** Full pre-request and test script execution sandbox with Chai-compatible `pm.test()` and `pm.expect()` assertions.
* **Dual Desktop Options:** Ships with both a zero-wait native browser-app desktop launcher and a compiled **Tauri v2** standalone application with Windows MSI and NSIS installers.

---

## 🔬 Clean-Room Reverse-Engineering (REA Package)

OpenPost was built through clean-room schema mapping and protocol analysis of Postman's legacy and modern formats using our built-in `rea` (**Reverse Engineer Anything**) package:

```
┌────────────────────────────────────────────────────────────────────────┐
│                      REA REVERSE-ENGINEERING PHASES                    │
├────────────────────────────────────────────────────────────────────────┤
│ Phase 1: Legacy "Scratch Pad" Autopsy (Postman v9.x / v10.14)          │
│ • Extracted app.asar (313MB) to map offline architecture without root.  │
│ • Discovered the 10 core IndexedDB stores (collections, requests,      │
│   environments, globals, history, scratchpad, workspaces, etc.).       │
│ • Decoded Electron IPC event bus (PM_EB_INT_BROADCAST_MAIN / REND).    │
│ • Implemented the 7 legacy schema migration rules (dataMode: "raw",   │
│   rawModeData, headerData, compound UID decomposition, etc.).          │
├────────────────────────────────────────────────────────────────────────┤
│ Phase 2: Cloud Sync & Export Mechanics                                 │
│ • Analyzed HAR network waterfall captures for Ctrl+S save requests.    │
│ • Deconstructed runtime variable interpolation & URL path variables.  │
│ • Built bidirectional adapter: UI/IPC state <-> Collection v2.1.0.     │
└────────────────────────────────────────────────────────────────────────┘
```

---

## 🏛 Architecture

```mermaid
flowchart TB
    subgraph Clients["Clients and Autonomous Agents"]
        Agent["AI Agents<br/>(Antigravity / Claude / Cursor)"]
        UI["Dark-Mode WebUI<br/>(Linear / Postman Style)"]
        Desktop["Desktop Application<br/>(Tauri v2 / WebView2)"]
    end

    subgraph OpenPost["OpenPost Core Engine"]
        MCP["Model Context Protocol Server<br/>(backend/mcp_server.py - 23 Tools)"]
        API["FastAPI REST Server<br/>(backend/main.py)"]
        
        Parser["Postman v2.1.0 Parser and Exporter<br/>(backend/collection_parser.py)"]
        Engine["HTTP Dispatcher and Var Engine<br/>(backend/request_engine.py)"]
        Sandbox["Node.js pm.* Script Sandbox<br/>(backend/script_sandbox.js)"]
        Store["Local Persistence Layer<br/>(backend/local_db.py)"]
    end

    subgraph Storage["Zero-Cloud Local Storage"]
        JSONFiles["Flat JSON Collections<br/>(data/collections/*.json)"]
        SQLiteDB["SQLite Database<br/>(data/openpost.db)"]
    end

    Agent <-->|"MCP Protocol (stdio/HTTP)"| MCP
    UI <-->|"REST API"| API
    Desktop <-->|"Localhost / IPC"| API

    MCP --> Parser
    MCP --> Engine
    MCP --> Store
    MCP --> Sandbox

    API --> Parser
    API --> Engine
    API --> Store
    API --> Sandbox

    Parser <--> JSONFiles
    Store <--> SQLiteDB
    Engine --> Sandbox
```

---

## 🤖 Model Context Protocol (MCP) Integration

OpenPost transforms API testing into an entirely agent-operable workflow. Every UI capability is accessible as a structured tool:

### Complete MCP Tool Matrix (23 Tools)
| Domain | Available MCP Tools |
| :--- | :--- |
| **Collections** | `import_postman_collection`, `export_postman_collection`, `list_collections`, `get_collection`, `create_collection`, `delete_collection` |
| **Request Authoring** | `create_folder`, `save_request`, `delete_request` |
| **Execution & Runner** | `interpolate_preview`, `send_request`, `run_collection_request`, `run_collection` |
| **Scripting & Sandbox** | `execute_postman_script` (executes sandboxed JS with `pm.test` assertions) |
| **Environments** | `list_environments`, `get_environment`, `save_environment`, `set_environment_variable`, `delete_environment` |
| **History & Audit** | `list_request_history`, `get_history_entry`, `clear_request_history` |
| **REA Autopsy & Sandbox**| `rea_inspect_legacy_postman`, `rea_diff_collection_payload`, `sandbox_hosts_control` |

### Connecting to Your AI Client

Add OpenPost to your `mcp_config.json` (Antigravity, Claude Desktop, Cursor, or Cline):

```json
{
  "mcpServers": {
    "openpost": {
      "command": "python",
      "args": ["-m", "backend.mcp_server"],
      "cwd": "/path/to/openpost",
      "env": {
        "PYTHONPATH": "/path/to/openpost;/path/to/openpost/rea_pkg"
      }
    }
  }
}
```

---

## 🧪 Pre-Request & Test Scripts (`pm.*` Sandbox)

OpenPost includes a Node.js-powered execution sandbox supporting authentic Postman scripts:

```javascript
// Pre-request Script:
pm.environment.set("request_id", "req_" + Date.now());

// Test Script (Chai-Compatible Assertions):
pm.test("Status code is 200", function () {
    pm.response.to.have.status(200);
});

pm.test("Response body matches schema", function () {
    var json = pm.response.json();
    pm.expect(json.status).to.equal("success");
    pm.expect(json.data.user.email).to.include("@example.com");
});

// Chaining Tokens into Environment for Downstream Requests:
pm.environment.set("auth_token", pm.response.json().token);
```

When running a collection, environment variables updated by `pm.environment.set()` automatically persist and chain into all subsequent requests in the run.

---

## 📦 Getting Started

### 1. Installation
Clone the repository and set up the Python environment:
```bash
git clone https://github.com/zshortbusz/openpost.git
cd openpost

python -m venv .venv
.\.venv\Scripts\activate

pip install -r requirements.txt
```

### 2. Launch Options

#### Option A: WebUI (Browser Mode)
```bash
uvicorn backend.main:app --port 8000 --reload
```
Open `http://127.0.0.1:8000` to access the dark-mode Scratch Pad interface.

#### Option B: Instant Desktop Launcher
```bash
python desktop/run_desktop.py
# Or: npm run desktop:launch
```
Spawns the backend and opens a clean, standalone desktop window in native app mode.

#### Option C: Tauri Standalone Desktop Build
```bash
# Development:
npm run desktop:dev

# Build Windows MSI and EXE Installers:
npm run desktop:build
```
Compiled installers are output to `src-tauri/target/release/bundle/msi/` and `nsis/`.

---

## 🛡 Windows Hosts Sandbox Blocker

To run legacy Postman v9.x or v10.14 without risk of forced auto-updating or cloud sync mandates, use our reversible sandbox blocker:

```powershell
# In an Administrator PowerShell terminal:
python scripts/block_postman_hosts.py --enable

# Undo / restore hosts file at any time:
python scripts/block_postman_hosts.py --restore

# Check current block status:
python scripts/block_postman_hosts.py --status
```

---

## 🧪 Running Automated Tests

OpenPost maintains a strict 100% test-passing invariant across schema ingest, interpolation, MCP tools, and desktop integration:

```bash
pytest -v
```

---

## 📄 License

OpenPost is released under the [MIT License](LICENSE).
Postman is a registered trademark of Postman, Inc. OpenPost is an independent clean-room open-source project and is not affiliated with, endorsed by, or associated with Postman, Inc.