# Musu Remote MCP for Windows

A Windows-native remote development MCP server for a trusted personal workstation. It runs on Node.js and PowerShell 7 without Docker, exposes OAuth 2.1 over Streamable HTTP, and protects mutations with byte-exact checkpoints and durable jobs.

This repository is the Windows edition of [remote_dev_mcp](https://github.com/yellowhama/remote_dev_mcp). It retains attribution to [kstost/cokacremote](https://github.com/kstost/cokacremote).

## Capabilities

- Native Windows 11 execution with Node.js 22.13+
- PowerShell 7 command and script execution with UTF-8 output preservation
- 23 MCP tools, OAuth CIMD+DCR/PKCE/refresh/revocation, client-owned jobs
- Target checkpoints for direct edits and full checkpoints before shell/script/patch jobs
- Content-addressed backups, bounded queues, idempotency keys, restart recovery
- Windows path, drive-letter, junction/symlink, hard-link, and process-tree handling
- Kill-on-close Windows Job Object containment for every command tree
- Authenticated Prometheus metrics and Windows Application Event Log lifecycle events
- Verified foreground operation and beta Windows service operation through pinned WinSW
- Cloudflare named tunnel guidance for a fixed HTTPS endpoint

## Security boundary

This server intentionally executes arbitrary commands. In native mode, those commands receive every permission of the Windows account running the MCP service. Docker mount and capability isolation are absent. Configure only the directories that the service account may edit, grant that account the minimum NTFS access it needs, and connect only trusted MCP clients.

The recommended service installation separates the OAuth gateway and execution worker into `NT SERVICE\MusuRemoteMcpGateway` and `NT SERVICE\MusuRemoteMcpWorker`. Explicit deny ACLs keep the gateway out of editable roots/backups and the worker out of OAuth state. Requests cross loopback with a short-lived HMAC assertion bound to client ID, nonce, timestamp, and body. The worker still executes arbitrary code with all rights granted to its dedicated identity, so this remains a trusted single-operator system rather than a hostile-code sandbox. Read [SECURITY.md](SECURITY.md).

## Requirements

- 64-bit Windows 11 or Windows Server 2022+
- [Node.js](https://nodejs.org/en/download) 22.13 or newer, installed system-wide for service mode
- PowerShell 7 or newer, installed system-wide for service mode
- Git available on `PATH` for patch operations
- Administrator access only when installing the Windows service or Cloudflare service
- A fixed HTTPS URL for ChatGPT; Cloudflare named tunnel is the documented path

Docker Desktop is not required.

## Documentation index

- [Code and document index](docs/CODE_AND_DOCUMENT_INDEX.md)
- [Windows architecture](docs/ARCHITECTURE.md)
- [Operations and incident response](docs/OPERATIONS.md)
- [Code audit](docs/CODE_AUDIT_20260913.md)
- [Optimization and maturity review](docs/OPTIMIZATION_AND_MATURITY_REVIEW_20260913.md)
- [Windows acceptance evidence](docs/WINDOWS_ACCEPTANCE_20260914.md)
- [Real ChatGPT compatibility evidence](docs/CHATGPT_COMPATIBILITY_EVIDENCE_20260914.md)
- [MUSU workspace switchover](docs/MUSU_WORKSPACE_SWITCHOVER_20260914.md)

## Install and run in the foreground

```powershell
git clone https://github.com/yellowhama/musu_remote_mcp_win.git
Set-Location musu_remote_mcp_win

pwsh -File .\windows\Install.ps1 `
  -EditableRoot 'F:\workspace\musu-active\musu-bee','F:\workspace\musu-active\llm-wiki' `
  -DefaultCwd 'F:\workspace\musu-active\musu-bee' `
  -StateRoot 'F:\musu-remote-mcp-data\state' `
  -BackupRoot 'F:\musu-remote-mcp-data\backups' `
  -PublicUrl 'https://mcp.example.com'

pwsh -File .\windows\Start-Local.ps1
```

The installer uses `npm ci`, builds the vendored TypeScript server, creates `config\windows.json`, initializes separate OAuth approval and metrics keys, and restricts the state directory ACL. It never prints either key value.

The approval key full path is the configured `stateRoot` plus `approval-key.txt`, for example:

```text
F:\musu-remote-mcp-data\state\approval-key.txt
```

The metrics-only key is stored beside it at `metrics-key.txt`. It can read `/metrics` and cannot authenticate to `/mcp`.

## Install as a Windows service (beta)

Open PowerShell 7 as Administrator and run the split-service installer:

```powershell
pwsh -File .\windows\Install-SplitService.ps1 `
  -EditableRoot 'F:\workspace\musu-active\musu-bee','F:\workspace\musu-active\llm-wiki' `
  -PublicUrl 'https://mcp.example.com' `
  -StateRoot 'F:\musu-remote-mcp-data\state' `
  -BackupRoot 'F:\musu-remote-mcp-data\backups'
```

Service mode downloads WinSW 2.12.0 and verifies this pinned SHA-256 before use:

```text
05B82D46AD331CC16BDC00DE5C6332C1EF818DF8CEEFCD49C726553209B3A0DA
```

The gateway alone can read the approval key and OAuth SQLite state. The worker alone can modify editable roots, checkpoints, and durable job state. Both can read a separate broker key directory; neither receives the other service's data permissions. The older `Install.ps1 -Service` combined mode remains for migration only.

To remove only the service registration while retaining source, state, and backups:

```powershell
pwsh -File .\windows\Uninstall-SplitService.ps1
```

## Cloudflare named tunnel

ChatGPT connects to a remote MCP endpoint, so local execution still needs a secure remote tunnel. Install `cloudflared`, create a named tunnel and fixed hostname, then point its ingress at `http://127.0.0.1:39391`.

Use [windows/cloudflared-config.yml.example](windows/cloudflared-config.yml.example) as the starting configuration. Cloudflare documents native Windows service installation with `cloudflared.exe service install`. Set the same fixed HTTPS hostname as `publicUrl` in `config\windows.json`.

Quick Tunnels are intended only for testing. Their hostname changes when restarted; they have no uptime guarantee, cap concurrent in-flight requests at 200, and do not support SSE. A named tunnel is required for the supported persistent configuration.

## Connect ChatGPT

1. Confirm `http://127.0.0.1:39391/health` returns HTTP 200 locally.
2. Confirm the named tunnel routes `https://your-host.example/health`.
3. In ChatGPT developer mode, create a custom MCP app at `https://your-host.example/mcp` and choose OAuth.
4. Enter the approval key only on this server's OAuth approval page.
5. Scan tools and confirm that 23 tools are present.
6. Start with a read-only request for the repository instruction file.

The authorization-server metadata advertises Client ID Metadata Document (CIMD) support while retaining Dynamic Client Registration (DCR) for existing ChatGPT clients. CIMD documents must use a canonical HTTPS URL and a public network destination; the server pins the resolved address, rejects redirects, and bounds retrieval time and size.

The 2026-09-14 acceptance run confirmed that a real ChatGPT custom MCP app selected CIMD, completed OAuth, discovered the server and all tools, and executed a read-only tool call through the split gateway and worker. The gateway preserves modern `Mcp-*` protocol headers when proxying requests and responses. DCR remains enabled until a broader compatibility window shows it is unused.

Authenticated operators can scrape `/metrics` with the dedicated metrics key or a valid OAuth credential. The fixed-cardinality metrics cover HTTP status and latency, authentication rejection, CIMD-versus-DCR resolution, managed processes, mutation queue depth, checkpoint outcomes/bytes/duration, and workspace free space. The metrics key is route-scoped and does not grant MCP tool access.

For a measured fresh ChatGPT connection, capture a baseline, create and exercise a new app, then capture the result:

```powershell
pwsh -File .\windows\Capture-ChatGPTCompatibility.ps1 -Phase Begin
# Complete OAuth, scan tools, and make at least one tool call in ChatGPT.
pwsh -File .\windows\Capture-ChatGPTCompatibility.ps1 -Phase End
```

On an elevated disposable VM, prepare an automatic post-boot verification and then reboot:

```powershell
pwsh -File .\windows\Test-RebootPersistence.ps1 -Phase Prepare -RestartComputer
pwsh -File .\windows\Test-RebootPersistence.ps1 -Phase Status
```

## Configuration

The installer creates the ignored file `config\windows.json`. The checked-in example documents every supported field.

| Field | Meaning |
|---|---|
| `publicUrl` | Fixed HTTPS origin used by OAuth metadata |
| `editableRoots` | Unique, non-overlapping absolute Windows paths |
| `defaultCwd` | Default working directory inside an editable root |
| `stateRoot` | Gateway OAuth state and approval key |
| `workerStateRoot` | Worker durable job state; defaults to `stateRoot-worker` |
| `brokerRoot` | HMAC broker key readable by both services; defaults to `stateRoot-broker` |
| `backupRoot` | Content-addressed backup objects and manifests |
| `port` | Loopback port, default `39391` |
| `workerPort` | Worker-only loopback port, default `port + 1` |
| `defaultShell` | PowerShell 7 executable; installer records its absolute path |

The native runtime rejects unknown fields, non-absolute paths, missing roots, overlapping roots, comma-containing roots, unsafe public URLs, and out-of-range ports before starting. It resolves Windows 8.3 aliases and other existing path aliases to canonical paths before applying containment checks.

## Mutation and recovery model

Direct file mutations snapshot exact targets before invoking the upstream tool. Shell, PowerShell, script, patch, move, copy, and remove jobs create a full checkpoint first. Job records are written durably and incomplete jobs found after restart become `interrupted_unknown`; they are never replayed automatically.

Snapshots are file-consistent rather than filesystem-atomic. They do not capture complete NTFS ACLs, alternate data streams, open database transactions, or every external effect of a command. Restore drills write to a new directory and never overwrite live roots.

## Verification

```powershell
npm ci
npm run build
npm test
```

Preview retention without changing files, then stop the MCP server and apply the reviewed plan:

```powershell
pwsh -File .\windows\Maintain.ps1
pwsh -File .\windows\Maintain.ps1 -Apply
```

Retention keeps the newest manifest even when it is older than the configured window, archives terminal jobs, removes only objects unreachable from retained manifests, and records a two-phase maintenance plan before deletion.
Before every direct or full checkpoint, the runtime also reserves the configured `retention.minFreeBytes` after accounting for the checkpoint's worst-case bytes. The installer defaults this watermark to 10 GiB.

GitHub Actions runs the same build and test flow on `windows-latest` with Node.js 24. The native smoke test starts the real OAuth server, checks health 200 and unauthenticated MCP 401, verifies key creation, and terminates the process tree.

See [the Dockerless research](docs/DOCKERLESS_WINDOWS_RESEARCH_20260913.md), [architecture](docs/ARCHITECTURE.md), [operations](docs/OPERATIONS.md), and [optimization and maturity review](docs/OPTIMIZATION_AND_MATURITY_REVIEW_20260913.md).

## License

MIT. Upstream license and attribution are preserved in [LICENSE](LICENSE), [NOTICE](NOTICE), and `vendor/`.