From 3df55a608341f63dcaf526317d65851914bfd640 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 15 Aug 2026 17:09:11 +0000 Subject: [PATCH] docs: add Desktop Commander MCP setup guide Document attaching the Desktop Commander MCP server to the two clients used with this repository, and record why the transport differs between them. - docs/DESKTOP_COMMANDER.md: local stdio setup for the Claude Code CLI, remote relay device setup (`npx ... remote`) for cloud-hosted sessions such as Cowork, flag reference, uninstall, and the operational boundary against Project-Her's read-only MCP server. - .mcp.json.example: copyable config pinning both `project-her` and `desktop-commander`. The live .mcp.json is gitignored so an unrestricted shell server stays opt-in per user rather than prompting everyone who clones the repository. - Cross-link from README.md and docs/PROJECT_HER.md. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01AAzsKTVzsQaiJR6BDCmvpV --- .gitignore | 1 + .mcp.json.example | 12 ++++ README.md | 10 +++ docs/DESKTOP_COMMANDER.md | 131 ++++++++++++++++++++++++++++++++++++++ docs/PROJECT_HER.md | 6 ++ 5 files changed, 160 insertions(+) create mode 100644 .mcp.json.example create mode 100644 docs/DESKTOP_COMMANDER.md diff --git a/.gitignore b/.gitignore index f239933..7b26a15 100644 --- a/.gitignore +++ b/.gitignore @@ -9,3 +9,4 @@ vo/ *.wav !examples/**/*.wav examples/voice-profiles/*/out/ +.mcp.json diff --git a/.mcp.json.example b/.mcp.json.example new file mode 100644 index 0000000..787b558 --- /dev/null +++ b/.mcp.json.example @@ -0,0 +1,12 @@ +{ + "mcpServers": { + "project-her": { + "command": "project-her-mcp", + "args": ["--config", "./project-her.json"] + }, + "desktop-commander": { + "command": "npx", + "args": ["-y", "@wonderwhy-er/desktop-commander@latest"] + } + } +} diff --git a/README.md b/README.md index 4d3e368..e6d957d 100644 --- a/README.md +++ b/README.md @@ -310,6 +310,16 @@ rollback artifact. The library exposes `PcmGate`, `candidate_record`, `validate_pcm_artifact`, `canonical_source_sha256`, and `promote_artifact` for that evidence path. +## Editor and agent setup + +[`docs/DESKTOP_COMMANDER.md`](docs/DESKTOP_COMMANDER.md) covers attaching the +Desktop Commander MCP server to the Claude Code CLI (local stdio) and to +cloud-hosted sessions such as Cowork (remote relay device), and how that +differs from Project-Her's own read-only MCP server. Copy +[`.mcp.json.example`](.mcp.json.example) to `.mcp.json` to enable both servers +for this repository; the live file is gitignored so the shell server stays +opt-in per user. + ## License Project-Her and VOForge source are MIT under [`LICENSE`](LICENSE). Voice audio is generated through third-party models diff --git a/docs/DESKTOP_COMMANDER.md b/docs/DESKTOP_COMMANDER.md new file mode 100644 index 0000000..77e1d4e --- /dev/null +++ b/docs/DESKTOP_COMMANDER.md @@ -0,0 +1,131 @@ +# Desktop Commander setup + +[Desktop Commander](https://github.com/wonderwhy-er/DesktopCommanderMCP) +(`@wonderwhy-er/desktop-commander`, v0.2.47 at the time of writing) is a +general-purpose MCP server exposing terminal execution and file editing. This +page records how to attach it to the two clients used with this repository — +the Claude Code CLI and cloud-hosted Claude sessions such as Cowork — and where +the boundary between them lies. + +It is a **companion to**, not a replacement for, the Project-Her MCP server +documented in [`PROJECT_HER.md`](PROJECT_HER.md). The two answer different +questions: `project-her` exposes validated, root-confined, read-only-by-default +voice tooling; Desktop Commander exposes an unrestricted shell. Keep that +distinction in mind when granting either one. + +## Which transport you need + +Desktop Commander ships one binary with three entry points. The subcommand you +want depends entirely on **where the model is running**, not on which product +badge it carries. + +| Client | Runs on | Transport | Command | +|---|---|---|---| +| Claude Code CLI (your machine) | your machine | local stdio | `claude mcp add ...` | +| Cowork / Claude web (cloud session) | Anthropic infrastructure | remote relay device | `npx ... remote` | +| Cowork desktop (local session) | your machine | local stdio | `claude mcp add ...` | + +A cloud-hosted session cannot spawn a process on your laptop, so the stdio +config is unreachable from it. That gap is exactly what `remote` fills: it +turns your machine into a registered device that a relay can dispatch tool +calls to. + +## 1. Claude Code CLI (local stdio) + +```bash +claude mcp add --scope user desktop-commander -- npx -y @wonderwhy-er/desktop-commander@latest +``` + +`--scope user` installs it for every project. Drop the flag to scope it to the +current project only. Claude Code launches the server as a child process over +stdio and shuts it down with the session; nothing leaves your machine. + +To pin Desktop Commander alongside `project-her` for **this** repository, copy +the checked-in template: + +```bash +cp .mcp.json.example .mcp.json +``` + +`.mcp.json` is deliberately **not** committed. A checked-in `.mcp.json` would +prompt every person who clones this repository to enable an unrestricted shell +server, which contradicts the consent-and-confirmation posture the rest of +Project-Her is built on. Opting in is left to each user. Adjust the +`--config` path in the copy to point at your own `project-her.json`. + +## 2. Cowork and Claude web (remote relay device) + +```bash +npx @wonderwhy-er/desktop-commander@latest remote +``` + +Run this **on the machine you want the model to reach** — your own desktop. +The flow, as implemented in `dist/remote-device/`: + +1. An OAuth 2.0 device-authorization flow starts (PKCE, `S256` challenge). The + CLI prints a verification URL and a short user code, and tries to open your + browser. +2. You approve the device in the browser; the CLI polls until authorization + lands and a device ID is assigned. +3. The process holds an authenticated channel to `https://mcp.desktopcommander.app` + and prints `✅ Device ready` with your account email, device ID, and device + name. +4. Tool calls arriving over that channel execute locally under your user + account, and results are returned to the model. + +Then add Desktop Commander as a connector in your client, following the pairing +flow at [mcp.desktopcommander.app](https://mcp.desktopcommander.app). The +connector-registration step lives in Anthropic's client UI and the vendor's +onboarding, not in this repository — follow whatever those present. + +### Flags + +| Flag | Effect | +|---|---| +| `--persist-session` | Saves the session so restarts skip re-authorization | +| `--disable-no-sleep` | Skips `caffeinate` (macOS only; otherwise the process keeps the Mac awake while connected) | +| `--debug` | Enables verbose `console.debug` output, which is suppressed by default | + +### Operational boundary + +- The relay only works **while the process runs**. `Ctrl+C` ends access; there + is no background daemon left behind. +- Commands run with your full user permissions. There is no per-tool + confirmation gate equivalent to the `{"confirm": true}` requirement that + Project-Her's render tool enforces. +- Traffic egresses to a third-party relay (`mcp.desktopcommander.app`). That is + a different trust boundary from the local stdio setup in section 1, and from + Project-Her's stdio-only, no-network MCP server. Prefer section 1 whenever + the model is already running locally. + +## 3. What this does *not* apply to + +Claude Code sessions running in a **remote/web execution container** — the +ephemeral cloud sandbox used by Claude Code on the web — should not use either +path: + +- The container already grants the agent shell and file access through its + native tools, so a local stdio Desktop Commander is redundant. +- Running `remote` inside the container would register the **throwaway + sandbox** as the device, not your desktop, and the pairing dies with the + container. + +Set Desktop Commander up on the machine you actually want reached. + +## Uninstalling + +```bash +npx @wonderwhy-er/desktop-commander@latest remove +``` + +This backs up the Claude configuration before editing it and removes the +`desktop-commander` entry. For the Claude Code CLI, `claude mcp remove +desktop-commander` is the direct equivalent. A `.mcp.json` you copied from the +template is removed by deleting the file. + +## References + +- Desktop Commander: +- Remote MCP service: +- Claude Code MCP documentation: +- Project-Her MCP server: [`PROJECT_HER.md`](PROJECT_HER.md) diff --git a/docs/PROJECT_HER.md b/docs/PROJECT_HER.md index 4a8c014..360c3e0 100644 --- a/docs/PROJECT_HER.md +++ b/docs/PROJECT_HER.md @@ -153,6 +153,12 @@ remain visible to a human: - - +To attach this server to a client alongside the general-purpose Desktop +Commander shell server, see [`DESKTOP_COMMANDER.md`](DESKTOP_COMMANDER.md). +Desktop Commander is an unrestricted terminal and file-editing server and does +not inherit any of the root confinement, render gating, or confirmation +controls described above. + ## License matrix | Component | Governing boundary |