Skip to content
Back to search

local-workspace-mcp

Local code workspace: web editor + MCP server so any AI can read and write files on your machine. Public access via localhost.run, no account needed.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/rinaldisign--local-workspace-mcp/badge.svg)](/listings/rinaldisign--local-workspace-mcp)

HTML

<a href="/listings/rinaldisign--local-workspace-mcp"><img src="/api/listings/rinaldisign--local-workspace-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 581 lines
  1. # Local Workspace MCP
  2. <p align="center">
  3. <img src="docs/hero.png" alt="Local Workspace MCP: one local workspace connected over MCP to any MCP-capable AI agent" width="100%">
  4. </p>
  5. <p align="center">
  6. <strong>Satu folder di PC kamu, bisa dibaca dan ditulis oleh AI mana pun.</strong><br>
  7. <strong>One folder on your machine that any AI can read and write.</strong>
  8. </p>
  9. <p align="center">
  10. <a href="#bahasa-indonesia">Bahasa Indonesia</a> &nbsp;·&nbsp; <a href="#english">English</a>
  11. </p>
  12. ---
  13. ## Bahasa Indonesia
  14. ### Apa ini?
  15. Local Workspace MCP berjalan sepenuhnya di komputermu. Ada dua bagian:
  16. 1. **Editor web** di `http://127.0.0.1:43787` — file tree, edit, autosave, buat/rename/hapus file.
  17. 2. **Server MCP** — protokol yang dipakai agent AI apa pun yang mendukung MCP (aplikasi desktop, CLI, ekstensi IDE, atau agent web) untuk memanggil *tools*. Lewat MCP, AI bisa membaca file, menulis kode, mengedit sebagian, menyusun struktur folder, mencari teks, dan menghapus file — langsung di disk kamu.
  18. Tidak ada cloud, tidak ada akun, tidak ada database, tidak ada telemetri. Hanya Node.js dan dua dependency.
  19. Supaya bisa dipakai dari client di perangkat lain, pilih salah satu jalur akses publik di bawah — mulai dari tunnel gratis dengan `cloudflared` (tanpa akun, tanpa domain, tanpa membuka port router).
  20. ### Kelebihan
  21. | Kelebihan | Penjelasan |
  22. |---|---|
  23. | **Satu workspace, banyak AI** | Semua client MCP memakai folder yang sama. Ganti AI tanpa memindahkan file. |
  24. | **Langsung ke disk** | AI menulis file asli, bukan potongan kode di chat. Penulisan atomik, folder induk dibuat otomatis. |
  25. | **11 tool siap pakai** | Baca, tulis, edit sebagian, scaffold struktur, cari, pindah, hapus. |
  26. | **Dua mode koneksi** | `stdio` (paling aman, tanpa jaringan) dan HTTP `/mcp` untuk remote. |
  27. | **Publik tanpa akun** | Cloudflare quick tunnel: tanpa domain, tanpa akun, tanpa build step. |
  28. | **Editor yang tidak mengganggu** | Autosave 700 ms, Ctrl+S, Tab = 2 spasi, indikator Ln/Col. |
  29. | **Sandbox** | Semua operasi dikunci ke satu folder; path traversal dan symlink keluar ditolak. |
  30. | **Bisa diaudit** | Setiap tulis, edit, pindah, dan hapus dicatat di `.logs/activity.jsonl`. |
  31. | **Ringan** | Tanpa framework, tanpa DB, tanpa bundler. `npm install` lalu `npm start`. |
  32. | **Lintas OS** | Windows, macOS, Linux. |
  33. ### Cara menjalankan (langkah pemula)
  34. **Yang perlu disiapkan:** komputer Windows/macOS/Linux, koneksi internet, dan **Node.js 18.17 atau lebih baru**. Unduh versi **LTS** di https://nodejs.org, klik Next sampai selesai. Cek dengan membuka terminal dan mengetik `node -v`.
  35. **1. Ambil kodenya**
  36. Paling mudah: buka halaman repo di GitHub → tombol **Code** → **Download ZIP** → ekstrak ke folder biasa (misalnya `Dokumen\local-workspace-mcp`). Jangan taruh di `C:\Windows` atau `C:\Program Files`.
  37. Kalau sudah punya git:
  38. ```bash
  39. git clone https://github.com/rinaldisign/local-workspace-mcp.git
  40. ```
  41. **2. Pasang dependency (sekali saja)**
  42. Buka terminal di folder tadi, lalu:
  43. ```bash
  44. npm install
  45. ```
  46. Windows: kalau muncul pesan `npm.ps1 cannot be loaded`, jalankan `npm.cmd install`.
  47. **3. Jalankan aplikasi**
  48. - Windows: klik dua kali **`start.bat`**, lalu biarkan jendelanya terbuka.
  49. - macOS/Linux: `chmod +x start.sh` lalu `./start.sh`.
  50. - Atau dari terminal mana pun: `npm start`.
  51. Di jendela itu akan muncul:
  52. ```
  53. Editor UI : http://127.0.0.1:43787
  54. MCP (local) : http://127.0.0.1:43787/mcp
  55. Workspace : ...
  56. TOKEN : 3f9c...
  57. ```
  58. **4. Buka editor di browser**
  59. Buka `http://127.0.0.1:43787`. Saat diminta token, salin baris `TOKEN` dari jendela tadi (atau isi file `.token`). Token disimpan di browser, jadi cukup sekali.
  60. **5. Pilih folder kerja**
  61. Isi path absolut folder yang mau dipakai AI di kolom `folder` pada header, lalu klik **use**. Kalau foldernya belum ada, kamu akan ditanya apakah mau dibuat. Pilihan disimpan di `config.json` dan dipakai lagi saat start berikutnya.
  62. Urutan prioritas: `config.json` → `WORKSPACE_DIR` di `.env` → `./workspace`. Root drive (`C:\`) dan folder sistem ditolak.
  63. **6. Hubungkan AI** — lihat bagian *Hubungkan AI* di bawah. Untuk client di perangkat lain (misalnya agent web hosted), pilih dan nyalakan jalur akses publik dulu.
  64. ### Akses publik: untuk agent AI berbasis web
  65. Bagian ini khusus untuk **agent AI berbasis web** yang berjalan di internet:
  66. server hanya mendengarkan di `127.0.0.1`, jadi butuh URL HTTPS publik. Syarat,
  67. perintah, dan verifikasi tiap jalur ada di
  68. **[docs/public-access.md](docs/public-access.md)**.
  69. | Situasi | Jalur | Syarat | URL stabil |
  70. |---|---|---|---|
  71. | Punya domain di Cloudflare | Cloudflare Named Tunnel | akun Cloudflare + domain | ya |
  72. | Tanpa domain | Cloudflare Quick Tunnel | `cloudflared` saja | tidak (acak) |
  73. | Tanpa domain, ingin stabil | Tailscale Funnel | akun Tailscale gratis | ya |
  74. | Alternatif | ngrok | akun ngrok | hanya versi bayar |
  75. | Kontrol penuh | VPS + Caddy | VPS + domain | ya |
  76. Contoh tercepat tanpa akun dan tanpa domain (**Cloudflare Quick Tunnel**):
  77. **1. Pasang `cloudflared` (sekali saja)**
  78. - Windows: `winget install --id Cloudflare.cloudflared`
  79. - macOS: `brew install cloudflared`
  80. - Linux: unduh paket `.deb`/`.rpm` dari https://github.com/cloudflare/cloudflared/releases
  81. Cek dengan `cloudflared --version`.
  82. **2. Nyalakan tunnel (jendela baru, biarkan terbuka)**
  83. - Windows: klik dua kali **`tunnel-cf.bat`**
  84. - macOS/Linux: `./tunnel-cf.sh`
  85. - Atau dari terminal mana pun: `npm run tunnel`
  86. Tunggu beberapa detik sampai muncul baris seperti ini:
  87. ```
  88. Your quick Tunnel has been created! Visit it at:
  89. https://kata-kata-acak.trycloudflare.com
  90. ```
  91. **3. Susun URL MCP**
  92. ```
  93. https://kata-kata-acak.trycloudflare.com/mcp?token=<TOKEN>
  94. ```
  95. `<TOKEN>` sama dengan isi file `.token`.
  96. **4. Tes cepat (opsional)**
  97. ```bash
  98. curl "https://kata-kata-acak.trycloudflare.com/health"
  99. ```
  100. Balasan yang benar: `{"ok":true,...}`. Kalau `502` atau `no tunnel`, tunggu beberapa detik lalu coba lagi.
  101. **Catatan penting**
  102. - URL quick tunnel **berganti** setiap `cloudflared` dijalankan ulang. Kalau berganti, perbarui URL di connector AI.
  103. - Tunnel mati kalau jendelanya ditutup, PC sleep, atau internet putus.
  104. - Mau URL yang tidak berubah? Buat **named tunnel** di Cloudflare (perlu akun + domain) atau pakai Tailscale Funnel.
  105. - Alternatif tanpa Cloudflare: Tailscale Funnel (akun gratis, URL stabil) atau ngrok.
  106. ### Hubungkan AI
  107. Semua client MCP bisa dipakai. Ada dua bentuk konfigurasi yang umum; sesuaikan
  108. dengan bentuk yang dipakai client-mu.
  109. **Bentuk `mcpServers` — stdio (paling aman, tanpa jaringan, tanpa token):**
  110. ```json
  111. {
  112. "mcpServers": {
  113. "local-workspace": {
  114. "command": "node",
  115. "args": ["/path/ke/local-workspace-mcp/mcp-stdio.js"]
  116. }
  117. }
  118. }
  119. ```
  120. **Bentuk `mcp` + `type: local` — stdio:**
  121. ```json
  122. {
  123. "mcp": {
  124. "local-workspace": {
  125. "type": "local",
  126. "command": ["node", "/path/ke/local-workspace-mcp/mcp-stdio.js"],
  127. "enabled": true
  128. }
  129. }
  130. }
  131. ```
  132. **Bentuk `mcp` + `type: remote` — lewat tunnel:**
  133. ```json
  134. {
  135. "mcp": {
  136. "local-workspace-http": {
  137. "type": "remote",
  138. "url": "https://kata-kata-acak.trycloudflare.com/mcp",
  139. "headers": { "Authorization": "Bearer <TOKEN>" },
  140. "enabled": true
  141. }
  142. }
  143. }
  144. ```
  145. **Hosted connector:** buka menu connector di UI client, pilih *Add custom
  146. connector*, isi `https://<host>/mcp?token=<TOKEN>`, authentication **None**
  147. (token sudah ikut di URL). Kalau UI punya kolom header, `Authorization: Bearer
  148. <TOKEN>` juga bisa dipakai.
  149. Hosted connector biasanya tidak menyediakan kolom header, jadi token harus lewat
  150. `?token=`. Karena itu token ikut tercatat di log tunnel — wajar untuk pemakaian
  151. pribadi, bukan untuk produksi.
  152. **Client lain:** sama. Pakai URL `.../mcp` dan kirim token sebagai header
  153. `Authorization: Bearer <TOKEN>` atau query `?token=<TOKEN>`, sesuai yang
  154. didukung client.
  155. > **Penting:** kolom *workspace* adalah folder lokal di komputermu (mis.
  156. > `/Users/kamu/dev/project-alpha` atau `D:\project\alpha`). URL GitHub hanya
  157. > dipakai sekali untuk mengambil kode (`git clone`), bukan untuk diisi sebagai
  158. > workspace.
  159. Setelah tersambung, cukup minta: *"buat landing page di workspace saya"* — AI
  160. memanggil `create_tree` / `save_code` dan file benar-benar muncul di disk.
  161. ### Keamanan
  162. - Default-nya **token aktif** (`OPEN_MODE=false`). Pertahankan begitu.
  163. - `OPEN_MODE=true` mematikan auth sepenuhnya: siapa pun yang bisa mencapai URL itu bisa membaca, menulis, dan menghapus file. Hanya untuk uji lokal — **jangan** dipakai bersamaan dengan tunnel publik.
  164. - URL tunnel itu publik, bukan rahasia. Hanya token yang membatasi akses.
  165. - Token di query (`?token=`) ikut tercatat di log tunnel. Untuk pemakaian pribadi itu wajar; ganti token dengan menghapus `.token` lalu restart.
  166. - Server hanya bind ke `127.0.0.1`, jadi tidak terbuka ke LAN.
  167. - Jangan menaruh kredensial di folder workspace selama tunnel hidup; trafik melewati server pihak ketiga.
  168. - Persempit permukaan dengan `ALLOWED_EXTENSIONS` dan `MAX_FILE_BYTES`. Semua perubahan tercatat di `.logs/activity.jsonl`.
  169. Detail lengkap: [SECURITY.md](SECURITY.md).
  170. ---
  171. ## English
  172. ### What is this?
  173. Local Workspace MCP runs entirely on your computer. Two parts:
  174. 1. **Web editor** at `http://127.0.0.1:43787` — file tree, editing, autosave, create/rename/delete.
  175. 2. **MCP server** — the protocol any MCP-capable AI agent uses to call *tools*: desktop apps, CLI agents, IDE extensions, and hosted web agents. Over MCP an AI can read files, write code, patch part of a file, scaffold folders, search text, and delete files directly on your disk.
  176. No cloud, no account, no database, no telemetry. Just Node.js and two dependencies.
  177. To use it from a client on another device, pick one of the public access paths below — starting with a free `cloudflared` tunnel (no account, no domain, no router port forwarding).
  178. ### Why use it
  179. | Advantage | Details |
  180. |---|---|
  181. | **One workspace, many AIs** | Every MCP client shares the same folder. Switch AI without moving files. |
  182. | **Straight to disk** | The AI writes real files, not chat snippets. Atomic writes, parent folders created. |
  183. | **11 ready-made tools** | Read, write, patch, scaffold, search, move, delete. |
  184. | **Two transports** | `stdio` (safest, no network) and HTTP `/mcp` for remote. |
  185. | **Public without an account** | Cloudflare quick tunnel: no domain, no signup, no build step. |
  186. | **Editor that stays out of the way** | 700 ms autosave, Ctrl+S, Tab = 2 spaces, Ln/Col. |
  187. | **Sandboxed** | Locked to one folder; path traversal and escaping symlinks are rejected. |
  188. | **Auditable** | Every write, edit, move and delete is appended to `.logs/activity.jsonl`. |
  189. | **Lightweight** | No framework, no DB, no bundler. `npm install` then `npm start`. |
  190. | **Cross-platform** | Windows, macOS, Linux. |
  191. ### How to run (beginner steps)
  192. **What you need:** a Windows/macOS/Linux computer, internet, and **Node.js 18.17 or newer**. Download the **LTS** build from https://nodejs.org and click Next until it finishes. Check by opening a terminal and typing `node -v`.
  193. **1. Get the code**
  194. Easiest: open the repo page on GitHub → **Code** → **Download ZIP** → extract to a normal folder (for example `Documents\local-workspace-mcp`). Do not put it in `C:\Windows` or `C:\Program Files`.
  195. If you already have git:
  196. ```bash
  197. git clone https://github.com/rinaldisign/local-workspace-mcp.git
  198. ```
  199. **2. Install dependencies (once)**
  200. Open a terminal in that folder, then:
  201. ```bash
  202. npm install
  203. ```
  204. Windows: if you see `npm.ps1 cannot be loaded`, run `npm.cmd install` instead.
  205. **3. Start the app**
  206. - Windows: double-click **`start.bat`** and leave the window open.
  207. - macOS/Linux: `chmod +x start.sh` then `./start.sh`.
  208. - Or from any terminal: `npm start`.
  209. It prints something like:
  210. ```
  211. Editor UI : http://127.0.0.1:43787
  212. MCP (local) : http://127.0.0.1:43787/mcp
  213. Workspace : ...
  214. TOKEN : 3f9c...
  215. ```
  216. **4. Open the editor in a browser**
  217. Go to `http://127.0.0.1:43787`. When it asks for the token, copy the `TOKEN` line from the window (or the `.token` file). The browser keeps it, so this is a one-time step.
  218. **5. Pick your working folder**
  219. Put an absolute path in the `folder` box in the header and click **use**. If the folder does not exist you will be asked whether to create it. The choice is saved to `config.json` and reused next time.
  220. Priority: `config.json` → `WORKSPACE_DIR` in `.env` → `./workspace`. Drive roots (`C:\`) and system folders are refused.
  221. **6. Connect an AI** — see *Connect an AI* below. For a client on another device (for example a hosted web agent), choose and start a public access path first.
  222. ### Public access: for web-based AI agents
  223. This section is only for **web-based AI agents** running on the internet: the
  224. server listens on `127.0.0.1`, so it needs a public HTTPS URL. Requirements,
  225. commands, and verification for every path:
  226. **[docs/public-access.md](docs/public-access.md)**.
  227. | Situation | Path | Requires | Stable URL |
  228. |---|---|---|---|
  229. | Own a domain on Cloudflare | Cloudflare Named Tunnel | Cloudflare account + domain | yes |
  230. | No domain | Cloudflare Quick Tunnel | `cloudflared` only | no (random) |
  231. | No domain, want stable | Tailscale Funnel | free Tailscale account | yes |
  232. | Alternative | ngrok | ngrok account | paid only |
  233. | Full control | VPS + Caddy | VPS + domain | yes |
  234. Fastest path with no account and no domain (**Cloudflare Quick Tunnel**):
  235. **1. Install `cloudflared` (once)**
  236. - Windows: `winget install --id Cloudflare.cloudflared`
  237. - macOS: `brew install cloudflared`
  238. - Linux: download the `.deb`/`.rpm` from https://github.com/cloudflare/cloudflared/releases
  239. Check with `cloudflared --version`.
  240. **2. Start the tunnel (new window, keep it open)**
  241. - Windows: double-click **`tunnel-cf.bat`**
  242. - macOS/Linux: `./tunnel-cf.sh`
  243. - Or from any terminal: `npm run tunnel`
  244. Wait a few seconds for a line like:
  245. ```
  246. Your quick Tunnel has been created! Visit it at:
  247. https://random-words.trycloudflare.com
  248. ```
  249. **3. Build the MCP URL**
  250. ```
  251. https://random-words.trycloudflare.com/mcp?token=<TOKEN>
  252. ```
  253. `<TOKEN>` is the contents of `.token`.
  254. **4. Quick test (optional)**
  255. ```bash
  256. curl "https://random-words.trycloudflare.com/health"
  257. ```
  258. A good answer is `{"ok":true,...}`. If you get `502` or `no tunnel`, wait a few seconds and try again.
  259. **Important notes**
  260. - The quick-tunnel URL **changes** every time `cloudflared` restarts. Update the connector when it does.
  261. - The tunnel dies if its window is closed, the computer sleeps, or the network drops.
  262. - Want a URL that never changes? Create a **named tunnel** in Cloudflare (needs an account + domain) or use Tailscale Funnel.
  263. - Fallback without Cloudflare: Tailscale Funnel (free account, stable URL) or ngrok.
  264. ### Connect an AI
  265. Any MCP client works. There are two common configuration shapes; use the one
  266. your client documents.
  267. **`mcpServers` shape — stdio (safest: no network, no token):**
  268. ```json
  269. {
  270. "mcpServers": {
  271. "local-workspace": {
  272. "command": "node",
  273. "args": ["/path/to/local-workspace-mcp/mcp-stdio.js"]
  274. }
  275. }
  276. }
  277. ```
  278. **`mcp` + `type: local` shape — stdio:**
  279. ```json
  280. {
  281. "mcp": {
  282. "local-workspace": {
  283. "type": "local",
  284. "command": ["node", "/path/to/local-workspace-mcp/mcp-stdio.js"],
  285. "enabled": true
  286. }
  287. }
  288. }
  289. ```
  290. **`mcp` + `type: remote` shape — through the tunnel:**
  291. ```json
  292. {
  293. "mcp": {
  294. "local-workspace-http": {
  295. "type": "remote",
  296. "url": "https://random-words.trycloudflare.com/mcp",
  297. "headers": { "Authorization": "Bearer <TOKEN>" },
  298. "enabled": true
  299. }
  300. }
  301. }
  302. ```
  303. **Hosted connector:** open the client's connector menu, choose *Add custom
  304. connector*, paste `https://<host>/mcp?token=<TOKEN>`, and set authentication to
  305. **None** (the token is already in the URL). If the UI has a header field,
  306. `Authorization: Bearer <TOKEN>` also works.
  307. Hosted connectors usually have no header field, so the token has to go in
  308. `?token=`. That means it also shows up in the tunnel log — fine for personal
  309. use, not for production.
  310. **Other clients:** same idea. Use `.../mcp` and send the token as an
  311. `Authorization: Bearer <TOKEN>` header or a `?token=<TOKEN>` query, whichever
  312. the client supports.
  313. > **Important:** the *workspace* field is a local folder on your computer (for
  314. > example `/Users/you/dev/project-alpha` or `D:\project\alpha`). The GitHub URL
  315. > is only used once to get the code (`git clone`); it is never the workspace
  316. > value.
  317. Then just ask: *"make a landing page in my workspace"* — the AI calls
  318. `create_tree` / `save_code` and the files appear on disk.
  319. ### Security
  320. - **Token mode is the default** (`OPEN_MODE=false`). Keep it.
  321. - `OPEN_MODE=true` disables auth entirely: anyone who can reach the URL can read, write and delete files. Local testing only — **never** alongside a public tunnel.
  322. - A tunnel URL is public, not secret. Only the token restricts access.
  323. - A token in the query string (`?token=`) is recorded in the tunnel log. That is normal for personal use; rotate it by deleting `.token` and restarting.
  324. - The server binds to `127.0.0.1` only, so it is not reachable from your LAN.
  325. - Do not keep credentials in the workspace while a tunnel is live; traffic passes through a third-party server.
  326. - Narrow the surface with `ALLOWED_EXTENSIONS` and `MAX_FILE_BYTES`. Every change is logged to `.logs/activity.jsonl`.
  327. Full details: [SECURITY.md](SECURITY.md).
  328. ---
  329. ## Reference
  330. ### MCP tools
  331. | Tool | What it does |
  332. |---|---|
  333. | `workspace_info` | absolute path, limits, allowed extensions, folder categories |
  334. | `list_files` | recursive tree (bounded) |
  335. | `read_file` | read one text file |
  336. | `write_file` | write a full file (atomic, parent dirs created) |
  337. | `edit_file` | replace unique text, or `replaceAll` |
  338. | `save_code` | save into a category folder by extension |
  339. | `create_tree` | scaffold many files/folders at once |
  340. | `create_folder` | recursive `mkdir` |
  341. | `move_path` | move / rename |
  342. | `delete_path` | delete file or folder |
  343. | `search_files` | text search across the workspace |
  344. `save_code` category mapping:
  345. | Extension | Folder |
  346. |---|---|
  347. | `.html` | `pages/` |
  348. | `.css` | `styles/` |
  349. | `.js` `.ts` `.jsx` `.tsx` | `scripts/` |
  350. | `.json` `.csv` `.sql` | `data/` |
  351. | `.md` `.txt` | `docs/` |
  352. | `.svg` `.png` `.jpg` … | `assets/` |
  353. | `.yml` `.toml` `.env` | `config/` |
  354. | anything else | `misc/` |
  355. ### REST API
  356. All `/api/*` routes need `Authorization: Bearer <TOKEN>` (skipped in `OPEN_MODE`) and return JSON `{ ok: true | false }`.
  357. | Method | Path | Body |
  358. |---|---|---|
  359. | GET | `/health` | – (public, includes `openMode`) |
  360. | GET | `/api/info` | – |
  361. | GET \| POST | `/api/settings` | `{ workspace, create? }` |
  362. | GET | `/api/tree?path=` | – |
  363. | GET | `/api/file?path=` | – |
  364. | POST | `/api/file` | `{ path, content }` |
  365. | POST | `/api/edit` | `{ path, oldText, newText, replaceAll? }` |
  366. | POST | `/api/structure` | `{ entries: [{ path, type, content }] }` |
  367. | POST | `/api/folder` | `{ path }` |
  368. | POST | `/api/move` | `{ from, to }` |
  369. | POST | `/api/delete` | `{ path }` |
  370. | POST | `/api/search` | `{ query, path?, maxResults? }` |
  371. | ALL | `/mcp` | MCP JSON-RPC |
  372. Quick check:
  373. ```bash
  374. curl http://127.0.0.1:43787/api/info -H "Authorization: Bearer <TOKEN>"
  375. curl -s https://<tunnel-host>/mcp?token=<TOKEN> \
  376. -H 'Accept: application/json, text/event-stream' \
  377. -H 'Content-Type: application/json' \
  378. -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
  379. ```
  380. ### Configuration / Konfigurasi
  381. Copy `.env.example` to `.env` and edit:
  382. | Variable | Default | Meaning |
  383. |---|---|---|
  384. | `PORT` | `43787` | HTTP port |
  385. | `HOST` | `127.0.0.1` | bind address (keep loopback for tunnels) |
  386. | `WORKSPACE_DIR` | `./workspace` | initial workspace folder |
  387. | `AUTH_TOKEN` | – | fixed token (otherwise generated into `.token`) |
  388. | `OPEN_MODE` | `false` | `true` disables auth entirely |
  389. | `MAX_FILE_BYTES` | `2097152` | max file size (2 MB) |
  390. | `MAX_TREE_ENTRIES` | `5000` | max tree entries returned |
  391. | `ALLOWED_EXTENSIONS` | built-in list | comma-separated writable extensions |
  392. Never committed (see `.gitignore`): `.env`, `.token`, `config.json`, `.logs/`, `workspace/`, `node_modules/`.
  393. ### Troubleshooting
  394. | Symptom | Fix |
  395. |---|---|
  396. | `npm.ps1 cannot be loaded` (Windows) | use `npm.cmd install`, or `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned` |
  397. | `node` or `npm` not recognized | install Node.js LTS from https://nodejs.org, then reopen the terminal |
  398. | Port already in use | change `PORT` in `.env` and restart |
  399. | UI keeps asking for a token | paste the value from `.token`, or the `TOKEN` line in the terminal |
  400. | AI writes but nothing appears | the AI writes to the workspace folder, not this repo — check the `folder` box |
  401. | `Extension .xyz is not allowed` | add it to `ALLOWED_EXTENSIONS` |
  402. | `cloudflared` not recognized | install it (`winget install --id Cloudflare.cloudflared`, `brew install cloudflared`), then reopen the terminal |
  403. | Tunnel URL stopped working / `502` | the tunnel window closed or the machine slept. Start it again and use the new URL |
  404. | Hosted connector: *"A service needed to create the app is temporarily unavailable"* | it could not reach the MCP URL. Check, in order: tunnel window is open, `curl <url>/health` returns `{"ok":true}`, `?token=<TOKEN>` is in the URL, and the URL is the newest one |
  405. | `502` or no tunnel URL appears | wait a few seconds; check the network; rerun the tunnel |
  406. | `ssh: command not found` | not needed for Cloudflare; only relevant if you add your own SSH-based bridge |
  407. ## Project layout / Struktur proyek
  408. ```
  409. server.js HTTP: static UI + REST + MCP
  410. mcp-stdio.js stdio transport entry point
  411. mcp-core.js 11 MCP tools
  412. lib/config.js env loader, token, OPEN_MODE, config.json
  413. lib/fs-service.js filesystem core (sandbox, atomic writes, search)
  414. public/index.html single-page editor
  415. public/app.js editor logic (autosave, tree, modals)
  416. public/styles.css theme
  417. examples/mcp-config.json stdio config example (mcpServers shape)
  418. examples/mcp-config-http.json HTTP config example
  419. docs/public-access.md every way to expose the server, with requirements
  420. start.bat|.sh start the app
  421. tunnel-cf.bat|.sh start the Cloudflare tunnel
  422. docs/hero.png repository banner
  423. ```
  424. ## License / Lisensi
  425. MIT — see [LICENSE](LICENSE).
  426. ## Disclaimer
  427. The banner image is fan art that includes third-party AI product names and logos for illustration only. This project is not affiliated with, endorsed by, or sponsored by OpenAI, Anthropic, Google, Microsoft, DeepSeek, Perplexity, or Meta. Cloudflare, Tailscale, and ngrok are independent services with their own terms.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.