<p align="center">
  <img src="assets/logo/logo-256x256.png" width="140" alt="Moonlight logo" />
</p>

<h1 align="center">Moonlight MCP Plugin</h1>

<p align="center">
  <strong>An MCP plugin for OpenAI and ChatGPT — connect ChatGPT web, ChatGPT desktop, and ChatGPT computer use to your Mac.</strong><br />
  <em>228 MCP tools: local files, Git, processes, macOS native automation, browser control, durable goal continuation, and more.</em>
</p>

<p align="center">
  <a href="https://github.com/misternay/moonlight-mcp-plugin/releases/latest"><img alt="GitHub Release" src="https://img.shields.io/github/v/release/misternay/moonlight-mcp-plugin" /></a>
  <a href="LICENSE"><img alt="License" src="https://img.shields.io/badge/license-MIT-blue.svg" /></a>
  <img alt="Platform" src="https://img.shields.io/badge/platform-macOS%20arm64%20%7C%20x64-000000" />
  <img alt="MCP" src="https://img.shields.io/badge/MCP-228%20tools-6f42c1" />
</p>

<p align="center"><em>ภาษาไทย: [docs/USAGE_TH.md](docs/USAGE_TH.md)</em></p>

---

**Moonlight** is a macOS local gateway that exposes your Mac's files, projects,
processes, and native automation to **ChatGPT** as MCP tools — for **ChatGPT
web**, **ChatGPT desktop**, and **ChatGPT computer use**. It connects through
the official **OpenAI Secure MCP Tunnel** (outbound HTTPS only, **Desktop
loopback HTTP MCP**, no public port opened).

This is a fork of [lnwjud](https://github.com/engasnm111/lnwjud) by
**Adisorn NM** — the Windows runtime surface is removed and the project is
rebranded for the macOS + ChatGPT ecosystem. Credit to the original author for
the groundwork; see [License](#license).

## Quick start

### 1. Install the app

1. Download the DMG (arm64 or x64) from [Releases](https://github.com/misternay/moonlight-mcp-plugin/releases/latest).
2. Drag **Moonlight** into `/Applications` and launch it.
3. Releases are unsigned: right-click the app → **Open** (or `xattr -d com.apple.quarantine /Applications/Moonlight.app`). Verify with the published `SHA256SUMS.txt` / `PROVENANCE.json`.
4. Add the project folder ChatGPT should work on (Projects page).
5. Grant **Screen Recording** and **Accessibility** when prompted for native automation.

No system Node.js needed — the app bundles its own runtime.

### 2. Connect ChatGPT

1. In [OpenAI Platform](https://platform.openai.com/settings/organization/tunnels): create a tunnel, create a runtime API key (**Tunnels Read + Use**).
2. In Moonlight: **Settings → OpenAI Secure MCP Tunnel** → save key, paste tunnel ID, **Configure Tunnel**, **Start Tunnel**. The tunnel targets the Desktop loopback HTTP MCP (`sample_mcp_remote_no_auth` profile), not a separate headless runtime.
3. In ChatGPT web/desktop (Developer mode): **Plugins → add connection → Tunnel** → pick the tunnel.
4. In ChatGPT computer use: attach the same tunnel connection so the agent can operate your Mac's files and UI.
5. Confirm that the default runtime exposes **178 tools** (or **184** when Codex delegation is explicitly enabled) and run a read-only
   smoke test before trying writes.

```text
Use Moonlight to list registered workspaces, show Git status for the selected project, and summarize the top-level project tree. Do not modify anything.
```

## Features

- **Workspace & files** — register projects; search, read, edit files with paging and persistent indexing
- **Git** — status, diff, log, and policy-checked execution
- **Processes & Modern MCP Tasks** — owned process lifecycle with bounded logs, timeout, cancellation, and full Modern MCP Tasks Protocol (`io.modelcontextprotocol/tasks`) support (`tasks/get`, `tasks/update`, `tasks/cancel`) for asynchronous background execution
- **macOS native** — accessibility, input, window control, screen capture, notifications, clipboard, file dialogs, audio, scheduler (launchd)
- **Browser** — managed Chrome / CDP automation with Set-of-Marks annotated observations
- **Durable goals** — goal continuation with lease fencing and scheduled handoff
- **Live Logs & Work Log** — high-performance SQLite streaming, event loop yielding, candidate pre-filtering, fast non-blocking atomic file exports, and expandable untruncated activity inspection
- **Extensible** — local skill discovery, child MCP servers, compound/parallel workflows
- **Bundled OpenAI tunnel-client** — pre-packaged universal binary (`v0.0.14`) for macOS (arm64 & x64) with pinned SHA-256 verification and zero external dependencies

### Session resilience / แนวทางสำหรับผู้ปฏิบัติการ

Use **Capture Incident** in Control Center or Live Logs when a turn looks wrong.
Validate the configured tunnel health endpoint against the live runtime address:

```sh
profile="$HOME/Library/Application Support/tunnel-client"
tc="${MOONLIGHT_TUNNEL_CLIENT_PATH:-/Applications/Moonlight.app/Contents/Resources/tunnel-client/tunnel-client}"
[ -f "$tc" ] || exit 1
"$tc" doctor --profile moonlight --profile-dir "$profile" --explain || exit 1
address=$(grep -E 'health.*(listening|listen_addr).*(127\.0\.0\.1|localhost):[0-9]+' "$profile/moonlight-tunnel.log" | tail -1 | grep -oE '(127\.0\.0\.1|localhost):[0-9]+' | tail -1)
[ -n "$address" ] || exit 1
curl "http://$address/healthz"
```

## Security and operational model

Moonlight is powerful by design — use it only on machines and workspaces you trust.

- **Active Project** scope bounds mutations; the exact `delete_file` is the only mutation eligible for scoped auto-approval, and only when the target is proven recoverable inside the Active Project.
- **Approval** — with Full Bypass OFF, approval-required mutations need explicit chat confirmation plus an independent trusted host exact-action approval. Desktop dialogs are cancel-first; standalone/headless runtimes without a trusted host approval provider fail closed.
- **Recovery Trash** — deleted files and pre-replacement backups are recorded under `<dataRoot>/recovery-trash` (or encrypted checkpoints) before the authoritative mutation.
- **Full Bypass** — a separate opt-in control (default OFF) that skips application-level approval/scope checks for explicit targets; it cannot override OS permissions or input validation.
- **Loopback MCP** binds to 127.0.0.1; use the Secure MCP Tunnel for remote access. The tunnel profile stores only an `env:` key reference, never the key.

## Build from source

Requirements: macOS, Node.js 24 (nvm/nodejs.org, not Homebrew), Corepack + pnpm 10.15.0.

```sh
git clone https://github.com/misternay/moonlight-mcp-plugin.git
cd moonlight-mcp-plugin
corepack pnpm@10.15.0 install --frozen-lockfile
corepack pnpm@10.15.0 build
corepack pnpm@10.15.0 desktop        # dev desktop app
corepack pnpm@10.15.0 package:macos  # local DMG + ZIP (arm64 only)
```

Checks: `lint`, `typecheck`, `test:release`, `docs:tools:check`. Layout: `apps/desktop` (Electron), `apps/cli`, `packages/*`, `docs/`.

<!-- BEGIN GENERATED README TOOL REGISTRY -->
## Tools

The complete generated tool index (**230 total definitions; 178 advertised by default; 184 with Codex enabled**) lives in [docs/TOOL_CATALOG.md](docs/TOOL_CATALOG.md).

<!-- END GENERATED README TOOL REGISTRY -->

## Docs

- [Tools catalog (complete generated index)](docs/TOOL_CATALOG.md)
- [ภาษาไทย](docs/USAGE_TH.md) · [Architecture](docs/architecture/) · [Release process](docs/development/RELEASE_PROCESS.md) · [Contributing](CONTRIBUTING.md)

## License

This project is licensed under the [MIT License](LICENSE).

**Moonlight is a fork of [lnwjud](https://github.com/engasnm111/lnwjud)** by
**Adisorn NM** — original author credit goes to them and the original project,
which this fork builds on.