Skip to content

Commit cfd3b95

Browse files
kchungclaude
andauthored
feat(native-mcp): one-command launcher and MCP registration for agent driving (#2272)
## Why Agents can only drive the native desktop app through macOS UI automation, which is slow and brittle. #1528 added an opt-in `native-mcp` bridge that lets MCP tools read and click the real webview's DOM. Nobody uses it: launching takes five hand-set inputs, and no MCP client is set up. ## What - `bin/node scripts/desktop-mcp.mjs` launches a test instance with all the required settings. `--print` shows its identifier and port. - `.mcp.json` registers the matching MCP client as `buzz-native`. - `docs/native-mcp.md` explains which identity the instance runs as and what agents must not do. ## How The launcher wraps `just desktop`. It derives a test identifier and bridge port from the worktree path, so each worktree gets its own instance. It also sets `BUZZODZ_PROFILE` per worktree, so the instance does not restore another debug build's org sign-in. `scripts/native-mcp-client.mjs` runs `@hypothesi/tauri-mcp-server`, pinned at 0.13.1 as a devDependency. The client connects to whichever app answers in the port range, and two worktrees can share a range. So the script points it at a loopback relay built on `ws`. The relay forwards commands only to an app that reports this worktree's identifier, a debug build and a `main` window. Otherwise each command fails with a clear error. No Rust, capability, or identity code changes. ## Risk Low. Only developers who run the new script are affected. Normal launches and release builds are untouched. After approval, Claude Code offers the `buzz-native` tools in every session in this repo, and they fail harmlessly when no test instance is running. The instance signs with the shared debug key, so an agent acts as the developer. The docs say to supervise live use, never let an agent sign out, and use a disposable account or VM for unsupervised automation. ## Testing On macOS, through `.mcp.json`, against the real app with the org sign-in config: - An agent started a session, opened a channel, clicked between sidebar tabs and took a screenshot. The live community and its channels loaded. - After the app quit mid-session, each later command failed at once with the relay's error instead of hanging. Against fake bridges, through the stock client: another app on the base port, a release build, no `main` window, an app swapped after connecting, a restart on another port, and a late launch. Each reached only the matching app or failed cleanly. A browser `Origin` gets 401. ## Open questions 1. **Shared key.** Every debug build uses the same Keychain key. Should test instances get their own throwaway key? That touches `crates/credential-store`, so it belongs in a separate PR. 2. **Explicit port.** A port passed to `driver_session` skips the relay. The docs say not to pass one. Closing that gap needs a client change. buzz-review-completed 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Signed-off-by: Kevin Chung <[email protected]> Co-authored-by: Claude Opus 5.5 <[email protected]>
1 parent 5174435 commit cfd3b95

11 files changed

Lines changed: 837 additions & 19 deletions

‎.mcp.json‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{
2+
"mcpServers": {
3+
"buzz-native": {
4+
"command": "bin/node",
5+
"args": ["scripts/native-mcp-client.mjs"]
6+
}
7+
}
8+
}

‎docs/contributing.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -137,7 +137,7 @@ need their own validation.
137137
An unavailable certificate fails the build rather than silently signing ad-hoc.
138138
This setting leaves `just desktop` and release builds unchanged. Explicit Tauri
139139
`--config` arguments still merge after the local defaults.
140-
- For opt-in automation of a disposable macOS native webview, see
140+
- For opt-in agent automation of the macOS native webview, see
141141
[Native webview automation](native-mcp.md).
142142
- `just design [args...]`: install locked dependencies, start the standalone
143143
design-system viewer, and open it in your browser. Arguments pass through to

‎docs/native-mcp.md‎

Lines changed: 69 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -6,33 +6,64 @@ The bridge is available only in macOS debug builds. Normal builds and launches
66
do not register it. Release builds and other platforms refuse an explicit opt-in.
77
This bridge is separate from the MCP servers that Buzz plugins can serve.
88

9-
## Use a disposable test instance
9+
## Choose the identity it runs as
1010

1111
The bridge can execute JavaScript and native commands with the app's authority.
12-
Use a disposable macOS account or VM with generated test keys and a local test
13-
relay. Do not use production or staging accounts. A different app identifier,
14-
port, or `BUZZODZ_PROFILE` does **not** isolate the shared debug Keychain identity.
15-
Do not replace a developer's active identity. See [identity custody](identity.md).
12+
A test instance signs with the shared debug Keychain identity, the same key
13+
`bin/just desktop` and `bin/just web` use. A different app identifier, port or
14+
`BUZZODZ_PROFILE` does **not** isolate it, so whatever an agent does through
15+
the bridge, it does as that key, in that key's communities. Do not replace a
16+
developer's active identity. See [identity custody](identity.md).
17+
18+
For automation you do not supervise, use a disposable macOS account or VM with
19+
generated test keys and a local test relay. To let an agent test against a live
20+
community as yourself:
21+
22+
- Writes such as messages, reactions and joins publish as the signed-in key.
23+
Tell the agent where it may write, such as a scratch channel. A join also adds
24+
the community to the account's list, which syncs to your other devices and
25+
is not removed by sync ([known communities](communities.md#known-communities)).
26+
- Do not let an agent sign out. Sign out deletes the shared debug identity for
27+
every debug build and removes saved organization sign-ins for every profile.
28+
- A person completes any organization sign-in in the browser. The bridge never
29+
receives the session token.
30+
31+
Each test instance keeps its app data under its identifier; nothing removes it.
1632
An opt-in launch also refuses a non-empty `BUZZ_DEV_VIEWER` legacy broker pin.
1733

1834
Build and launch with all of these settings:
1935

2036
- Cargo feature: `native-mcp`.
2137
- Tauri config overlay: `src-tauri/tauri.native-mcp.conf.json`.
2238
- A separate identifier overlay: `dev.local.buzz.foundation.nexus-test-` followed
23-
by 12 random lowercase hexadecimal digits.
39+
by 12 lowercase hexadecimal digits unique to the test instance.
2440
- Launch environment: `BUZZ_NATIVE_MCP_PORT`, an integer from `1024` through
2541
`65436`. Unset means off. Invalid settings fail before identity startup.
2642

27-
For an already isolated environment, from the repository root:
43+
From the repository root:
2844

2945
```sh
30-
BUZZ_DEV_VIEWER= BUZZ_NATIVE_MCP_PORT=19423 bin/just desktop --features native-mcp \
46+
bin/node scripts/desktop-mcp.mjs
47+
```
48+
49+
It applies all of the settings above, with an identifier suffix and bridge base
50+
port derived from the worktree path, and prints both; `--print` prints them
51+
without launching. Each worktree owns one test instance, and relaunches keep its
52+
app data. It also sets `BUZZODZ_PROFILE` to `native-mcp-` and the identifier
53+
suffix unless the environment sets one. Other arguments pass to `just desktop`,
54+
such as `--port` for Vite. A manual launch looks like this:
55+
56+
```sh
57+
BUZZ_DEV_VIEWER= BUZZ_NATIVE_MCP_PORT=19423 BUZZODZ_PROFILE=native-mcp-012345abcdef \
58+
bin/just desktop --features native-mcp \
3159
--config src-tauri/tauri.native-mcp.conf.json \
3260
--config '{"identifier":"dev.local.buzz.foundation.nexus-test-012345abcdef"}'
3361
```
3462

3563
Replace the example identifier suffix for each owned test instance. Keep `BUZZ_DEV_VIEWER` explicitly empty to disable any inherited legacy broker pin.
64+
The repository's `buzz-native` client accepts only the instance the launcher
65+
derives for this worktree, so it refuses one launched with another identifier
66+
or port.
3667
Do not add
3768
this configuration to ordinary desktop or release recipes. A helper that uses
3869
`TAURI_CONFIG` must merge the test overlay and its identifier into that JSON
@@ -46,13 +77,22 @@ and `huddle-window`. It is outside the auto-loaded `capabilities/` directory.
4677
It grants neither the bridge's default permission set nor `execute-command`.
4778
The existing signed host commands and plugin sandbox still apply.
4879

49-
## Connect and verify the target
80+
## Connect
81+
82+
The bridge binds only to `127.0.0.1` and takes the first free port of the 100
83+
from its base port. The repository's `.mcp.json` registers
84+
`@hypothesi/[email protected]` as `buzz-native`, through
85+
`scripts/native-mcp-client.mjs`. MCP clients that read project configuration,
86+
such as Claude Code, offer its tools after approval.
5087

51-
The bridge binds only to `127.0.0.1`. It scans up to 100 ports from the selected
52-
base port. Read the actual port from its startup log, then verify backend metadata
53-
before any action. Do not assume the base port is the selected port. Connect to
54-
that exact loopback port and verify the complete test identifier, debug build,
55-
and `main` window. Do not let discovery or reconnection select another instance.
88+
Two worktrees can share a port range, and the client connects to whichever app
89+
answers, so the script points it at a loopback relay. The relay forwards commands
90+
only to an app that reports this worktree's identifier, a debug build and a
91+
`main` window. Whenever it has no open connection to one, it looks again on the
92+
next command, and fails that command if none answers. When the app quits,
93+
commands it has not answered fail and the session stays connected, so it reaches
94+
the app again after a rebuild or relaunch. Start `driver_session` without a
95+
port: a port passed there bypasses the relay.
5696

5797
The pinned bridge revision is
5898
`1d5105e72835b28ca05a75bcd612b9127c12fe94` from
@@ -61,12 +101,24 @@ It rejects both `Origin` and `Sec-WebSocket-Origin` at the WebSocket handshake.
61101
Loopback clients without those headers still have full automation authority;
62102
this is a local test interface, not an authenticated service.
63103

64-
Use `@hypothesi/[email protected]` with this bridge. Backend metadata uses
65-
`invoke_tauri` with `{"command":"plugin:mcp-bridge|get_backend_state","args":{}}`.
66-
The bridge reports version `0.12.0` and omits plugin-version metadata, so the
104+
The client is a pinned devDependency. The bridge reports version `0.12.0` and
105+
omits plugin-version metadata, so the
67106
standard client can show an upgrade warning. Do not replace the pinned revision
68107
with a release that lacks the Origin check to remove that warning.
69108

109+
The bridge listens before the app has rendered its shell, so wait for the target
110+
element with `webview_wait_for` before the first action. Its `detached` state
111+
times out rather than resolving; check absence with `webview_execute_js`. The
112+
tools reach only the `main` window's web content: native dialogs and prompts,
113+
the Browser panel's website view, the huddle window and deep links need other
114+
automation.
115+
116+
A community that requires organization sign-in needs the launch environment to
117+
carry `BUZZ_BUILD_FEDERATED_IDENTITY_CONFIG` (see
118+
[configuration](configuration.md#federated-identity-build-input)). Saved
119+
sign-ins are keyed by `BUZZODZ_PROFILE`, not the app identifier; the launcher's
120+
profile keeps a test instance from restoring another debug build's session.
121+
70122
Verify session start, a DOM snapshot, an interaction, its resulting DOM state,
71123
and session stop against the real native app. Check that a browser-origin
72124
handshake is rejected. Stop the app after testing and verify that its listener

‎package.json‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -89,6 +89,7 @@
8989
},
9090
"devDependencies": {
9191
"@biomejs/biome": "2.5.14",
92+
"@hypothesi/tauri-mcp-server": "0.13.1",
9293
"@playwright/test": "1.63.0",
9394
"@tailwindcss/postcss": "4.3.3",
9495
"@tauri-apps/cli": "2.12.3",
@@ -109,6 +110,7 @@
109110
"typescript": "7.0.2",
110111
"undici": "7.29.1",
111112
"vite": "8.3.0",
112-
"vitest": "5.0.4"
113+
"vitest": "5.0.4",
114+
"ws": "8.18.3"
113115
}
114116
}

0 commit comments

Comments
 (0)