portal

# Portal  **[English](README.md)** · **[简体中文](README.zh-CN.md)** Portal turns a local folder into a **public MCP (Model Context Protocol) endpoint** — deliberately minimal: **shell commands and file transfer only**. Connect any MCP client (Claude, ChatGPT, Cursor, a custom agent, or plain `curl`) to your machine over a tunnel, run commands, and move files. The same idea ships in two forms in this repository: | App | Folder | What it is | | --- | --- | --- | | **Portal Client** | [`client/`](client/README.md) | Standalone **Windows** desktop app (Electron + Fluent UI). No VS Code required. Adds native **browser-window docking**. | | **Portal (VS Code extension)** | [`vscode-extension/`](vscode-extension/README.md) | The original VS Code extension. Full manual: [User Guide](vscode-extension/USAGE.md). | > 📖 Start with the README of the app you actually want to run: > - **Client →** [`client/README.md`](client/README.md) · [简体中文](client/README.md) > - **Extension →** [`vscode-extension/README.md`](vscode-extension/README.md) · [简体中文](vscode-extension/README.zh-CN.md) > - 📘 **Extension User Guide** (install, tunnels, client setup, tool & file-API reference, troubleshooting) → [`vscode-extension/USAGE.md`](vscode-extension/USAGE.md) · [简体中文](vscode-extension/USAGE.zh-CN.md) ## What you get (both forms) | Surface | Role | | --- | --- | | MCP Streamable HTTP | `https://<tunnel>/mcp/<token>` | | File HTTP API | `https://<tunnel>/files/<token>/…` (same token) | | Exactly five tools | `run_command` · `start_command` · `read_command` · `stop_command` · `file_transfer_info` | | Tunnels | ngrok reserved domain · Cloudflare Quick / Named · custom command | | Localized UI | English / 简体中文 | > ⚠️ **Testing status** — Only the **ngrok** tunnel option has been tested. Cloudflare Quick / Named tunnels and custom tunnel commands are implemented but **untested**; treat them as experimental and please report anything broken. ## Which one should I use? - **No VS Code, want a dedicated app, or want to dock your real browser inside it?** → [`client/`](client/README.md) - **Already live inside VS Code?** → [`vscode-extension/`](vscode-extension/README.md) — then read the [User Guide](vscode-extension/USAGE.md) Both expose the **same MCP contract** — they are drop-in replacements for each other (and for a single folder, run one of them at a time). ## Repository layout ``` portal/ client/ Portal Client — Electron desktop app (Windows) vscode-extension/ Portal — VS Code extension (USAGE.md = user guide) resources/ logos LICENSE GNU General Public License v3 ``` ## License [GNU General Public License v3](LICENSE) — GPL-3.0-or-later. ## VS Code extension file tools The extension now provides bounded native text I/O, exact patches, directory pagination and retry-safe chunk uploads. HTTP and MCP share path checks, write locks and publication primitives. See [File tools](vscode-extension/FILE-TOOLS.md). The duplicated standalone desktop client is not migrated in this change; its file-tool capabilities differ from the extension.