machine-bridge-mcp 0.3.3 → 0.4.2

package/CHANGELOG.md

@@ -1,5 +1,65 @@
 # Changelog
 
+## 0.4.2 - 2026-07-10
+
+### Fixed
+
+- Canonicalize the configured workspace and requested targets through the same asynchronous `realpath` path on Windows, while retaining a native synchronous initial value. This prevents Windows short-path/long-path aliases for the same temporary directory from being misclassified as a workspace escape.
+- Keep workspace confinement unchanged: only the representation comparison changed, and targets outside the canonical workspace remain rejected in restricted profiles.
+
+### Verification
+
+- Preserve the existing cross-platform path-boundary regression, which exposed the issue on the Windows GitHub Actions runner while Linux and macOS passed.
+- Make the minimal-environment shell regression use a cross-platform Node command instead of POSIX parameter-expansion syntax under PowerShell.
+- Convert test entry-point file URLs with `fileURLToPath()` so Windows does not interpret `/D:/...` URL paths as `C:\D:\...` filesystem paths.
+- Launch Wrangler's JavaScript entry point through the active Node executable in integration tests instead of directly spawning the Windows `.cmd` shim.
+
+## 0.4.1 - 2026-07-10
+
+### Changed
+
+- Make `full` the default policy for newly selected workspaces and generated client configurations, prioritizing immediate usability. The default now enables all tools, unrestricted direct filesystem paths, absolute path output, shell execution, process sessions, and the complete parent environment; existing saved workspace policies remain unchanged.
+- Reframe stdio as an optional local transport rather than a model provider or a replacement for native Claude, Cursor, Codex, or ChatGPT Desktop tooling. Expand client documentation to distinguish the MCP host/model from the Machine Bridge tool server and explain when stdio is redundant or useful.
+- Activate cross-platform GitHub Actions checks on Linux, macOS, and Windows, update official actions to the current major releases, disable checkout credential persistence, and retain production dependency/package auditing.
+
+### Tests and documentation
+
+- Add regression coverage for the maximum-permission default and for `client-config` emitting `full` when no profile is supplied.
+- Update architecture, operations, security, and client guidance for profile-dependent path display, filesystem scope, and environment inheritance.
+
+## 0.4.0 - 2026-07-10
+
+### Architecture and compatibility
+
+- Refactor the project into one transport-independent local runtime shared by the existing OAuth-protected Cloudflare relay and a new local MCP stdio server.
+- Update MCP negotiation to `2025-11-25` while retaining compatibility with `2025-06-18` and `2025-03-26`; validate protocol-version headers and implement cancellation in both transports.
+- Add ready-to-paste stdio configuration generation for Claude Desktop, Cursor, Codex CLI, and generic MCP clients.
+- Replace duplicated Worker/runtime tool declarations with one schema-and-annotation catalog, tested for drift and policy consistency.
+
+### Security and privacy
+
+- Make the least-privilege `review` profile the default for newly selected workspaces; preserve stored pre-0.4 permissions during upgrade.
+- Add explicit `review`, `edit`, `agent`, and `full` profiles plus `off`, direct-argv, and shell execution modes.
+- Return workspace-relative paths by default, redact canonical/platform-alias paths from tool errors, omit Git author email unless requested, and reduce operational failures to coarse error classes.
+- Replace the previous minimal environment with isolated HOME, temp, and cache directories; retain full parent environment only through explicit opt-in.
+- Reject duplicate in-flight JSON-RPC IDs, canonical patch-path collisions, stale edits, unsupported image signatures, oversized session data, and ambiguous patch context.
+- Make create-only writes atomic against concurrent destination creation and strengthen multi-file patch staging, revalidation, rollback, and mutation serialization.
+
+### Tools and runtime
+
+- Add bounded line-range reads, native MCP raster-image results, exact text editing, and structured multi-file add/update/move/delete patches.
+- Add staged diffs, structured Git log, bounded Git show, and privacy-aware author metadata.
+- Add direct argv execution and bounded interactive process sessions with retained offsets, stdin, output/exit waits, cancellation, tree termination, and disconnect cleanup.
+- Return structured tool content alongside text compatibility output and expose tool annotations for client planning.
+
+### Reliability, testing, and operations
+
+- Add live stdio integration coverage for initialization, tool discovery, structured/image content, edits, patches, direct execution, sessions, cancellation, and post-cancellation health.
+- Expand Worker integration coverage for latest protocol negotiation, disconnected tool advertisement, rich content, exact daemon tool sets, and remote cancellation.
+- Add catalog, policy-profile, canonical-collision, no-partial-patch, Git privacy, path-redaction, isolated-environment, and session tests.
+- Add a Linux/macOS/Windows GitHub Actions template, Node 22/24 coverage, package/audit checks, and Dependabot configuration.
+- Rewrite architecture, security, client, operations, and testing documentation around explicit trust boundaries and non-goals.
+
 ## 0.3.3 - 2026-07-10
 
 ### Security
@@ -9,6 +69,7 @@
 ### Changed
 
 - Exclude the development-only Worker integration test from the published npm package while retaining it in the repository and CI.
+- Add a fail-closed release command that synchronizes `main`, the version tag, the GitHub Release, and its npm tarball; block `npm publish` when those artifacts do not match.
 
 ## 0.3.2 - 2026-07-10
 

package/README.md

@@ -1,265 +1,252 @@
 # machine-bridge-mcp
 
-`machine-bridge-mcp` exposes a selected local workspace to Remote MCP clients through a Cloudflare Worker relay and an outbound-only local daemon.
+`machine-bridge-mcp` exposes a selected local workspace to MCP clients through one shared, policy-controlled runtime.
+
+It supports two transports:
 
 ```text
-Remote MCP client -> HTTPS/OAuth -> Cloudflare Worker + Durable Object
-                                      ^
-                                      | outbound WebSocket
-                                      |
-                               local daemon -> workspace/files/shell
+Remote clients such as ChatGPT
+        HTTPS + OAuth 2.1 / PKCE
+                  |
+       Cloudflare Worker + Durable Object
+                  ^
+                  | outbound authenticated WebSocket
+                  |
+             local runtime
+
+Local clients such as Claude Desktop, Cursor, and Codex CLI
+                  |
+                 stdio
+                  |
+             local runtime
 ```
 
-No inbound port is opened on the local machine. The Worker does not read local files or execute commands; it authenticates MCP clients and relays bounded tool calls to the daemon.
+The remote Worker authenticates and relays calls. It cannot directly read local files or start local processes. File, Git, image, patch, and process operations execute in the local runtime.
 
-## Install and start
+## Default behavior and policy profiles
 
-Recommended global installation:
+A newly selected workspace starts with the maximum-permission `full` profile for low-friction operation:
 
-```zsh
-npm install -g machine-bridge-mcp@latest
-machine-mcp
-```
+- all read, write, edit, patch, image, Git, direct-process, process-session, and shell tools are available;
+- direct filesystem tools may use paths outside the selected workspace;
+- tool results may return absolute paths;
+- child processes inherit the complete parent environment.
 
-Without a global installation:
+Existing workspace state keeps its saved policy during upgrade. Use `--profile full` to explicitly move an older workspace to the new maximum-permission behavior.
 
-```zsh
-npx machine-bridge-mcp@latest
+| Profile | File edits | Direct argv processes | Shell commands | Filesystem scope | Process environment |
+|---|---:|---:|---:|---|---|
+| `full` | Yes | Yes | Yes | Unrestricted | Full parent environment |
+| `agent` | Yes | Yes | No | Selected workspace | Isolated environment |
+| `edit` | Yes | No | No | Selected workspace | Isolated environment |
+| `review` | No | No | No | Selected workspace | Isolated environment |
+
+This default prioritizes usability, not least privilege. `run_process` and process sessions avoid command-shell parsing, but they are **not an operating-system sandbox**. `exec_command` additionally permits shell syntax and expansion. Use `--profile review`, `edit`, or `agent`, or use a container, VM, or dedicated low-privilege OS account when the client, repository, or instructions are not fully trusted.
+
+## Install
+
+Node.js 22 or newer is required.
+
+```sh
+npm install -g machine-bridge-mcp@latest
 ```
 
 From a source checkout:
 
-```zsh
+```sh
 npm install
-./mbm          # macOS/Linux
-.\mbm.cmd      # Windows cmd
+./mbm                 # macOS/Linux
+.\mbm.cmd             # Windows cmd
 ```
 
-On first run, the CLI:
+## Remote MCP for ChatGPT
 
-1. Selects and remembers a workspace.
-2. Generates an MCP connection password, daemon secret, and OAuth token version.
-3. Authenticates Wrangler if required.
-4. Deploys a per-workspace Worker.
-5. Installs a login autostart entry unless `--no-autostart` is used.
-6. Starts the outbound local daemon.
-7. Prints the Remote MCP URL and connection password.
+Start the bridge from the project directory or select a workspace explicitly:
 
-Keep the foreground process running for the current session. The installed service handles later logins.
+```sh
+machine-mcp --workspace /path/to/project
+```
+
+On first remote start, the CLI:
 
-## Connect an MCP client
+1. canonicalizes and remembers the workspace;
+2. creates independent credentials and state for that workspace;
+3. signs in to Cloudflare Wrangler when needed;
+4. deploys a per-workspace Worker;
+5. installs a platform-native login service unless `--no-autostart` is used;
+6. starts an outbound-only daemon connection;
+7. prints the Remote MCP URL and connection password.
 
-Use the values printed by `machine-mcp`:
+Use the printed values in the MCP client:
 
 ```text
 MCP Server URL: https://<worker>.<account>.workers.dev/mcp
 MCP connection password: mcp_password_...
 ```
 
-The password is shown on first setup, after secret rotation, when the MCP URL changes, or with `--print-mcp-credentials`. Use `--no-print-credentials` to redact it in terminal output.
-
-The former experimental local OpenAI-compatible `/v1` API has been removed. Use the Remote MCP endpoint directly.
-
-## Security defaults
-
-Version 0.3.0 changes the default filesystem boundary:
+The remote authorization flow uses an authorization code, PKCE S256, exact redirect/resource binding, expiring access tokens stored as hashes, and a token-version value for bulk revocation.
 
-- Relative paths are resolved from the selected workspace.
-- Reads, writes, directory traversal, searches, and Git operations are confined to that workspace by default.
-- Symbolic links cannot be used to escape the workspace boundary.
-- `write_file` and `exec_command` remain enabled by default.
-- Shell commands receive a minimal environment by default.
-- `write_file` is limited to 5 MiB, writes atomically, and refuses to overwrite symbolic links.
-- Files that look sensitive, including `.env` and key files, are readable when they are inside the selected workspace. The bridge does not infer sensitivity from filenames.
+## Optional local stdio MCP
 
-A narrower session:
+stdio is a local transport, not a model provider. Claude Desktop, Cursor, Codex CLI, ChatGPT Desktop, or another MCP host supplies its own model/session and launches `machine-bridge-mcp` as a subprocess. The MCP server only exposes tools and returns their results; it does not borrow the model running in ChatGPT web.
 
-```zsh
-machine-mcp --no-write --no-exec
-```
+Many coding clients already have strong native filesystem and terminal tools, so configuring this stdio server is optional. It is useful when you want the same Machine Bridge tool schemas, patch behavior, process sessions, policy profiles, and logs across several clients, or when you want local access without deploying Cloudflare. If the client's built-in tools already meet your needs, there is no reason to add this server.
 
-Explicitly permit filesystem paths outside the workspace:
+Generate ready-to-paste configuration:
 
-```zsh
-machine-mcp --unrestricted-paths
+```sh
+machine-mcp client-config --client all --workspace /path/to/project
 ```
 
-Pass the complete parent process environment to shell commands only when required:
+Or run stdio directly:
 
-```zsh
-machine-mcp --full-env
+```sh
+machine-mcp stdio --workspace /path/to/project
 ```
 
-`--unrestricted-paths` and `--full-env` materially increase the data-exposure boundary. See [SECURITY.md](SECURITY.md) before enabling them.
-
-## Commands
+The stdio server writes only JSON-RPC messages to stdout and operational logs to stderr. See [docs/CLIENTS.md](docs/CLIENTS.md) for the host/model distinction and transport trade-offs.
 
-```text
-machine-mcp [start options]
-machine-mcp workspace show
-machine-mcp workspace set [PATH]
-machine-mcp service status|install|start|stop|uninstall
-machine-mcp status
-machine-mcp doctor
-machine-mcp rotate-secrets
-machine-mcp uninstall [--keep-worker] [--yes]
-```
+## Policy controls
 
-Important start options:
+The default is `full`. Narrow or customize it with explicit flags:
 
 ```text
---workspace PATH
---worker-name NAME
---force-worker
---rotate-secrets
---daemon-only
---no-autostart
---no-print-credentials
---print-mcp-credentials
+--profile full|agent|edit|review
+--exec-mode off|direct|shell
 --no-write
 --no-exec
 --full-env
 --unrestricted-paths
---state-dir DIR
---json
-```
-
-Unknown, duplicate, malformed, and command-inapplicable options are rejected. Boolean options do not consume a following positional workspace path; use `--option=false` when an explicit false value is needed.
-
-## Workspace selection
-
-```zsh
-machine-mcp workspace set
-machine-mcp workspace set /path/to/project
-machine-mcp workspace show
-machine-mcp workspace reset
+--absolute-paths
 ```
 
-Each canonical workspace path receives an independent profile, Worker name, secret set, and daemon lock.
+Important distinctions:
 
-## Autostart
-
-Supported providers:
-
-- macOS: user LaunchAgent
-- Linux: `systemd --user`, with best-effort user lingering
-- Windows: Scheduled Task at logon
-
-```zsh
-machine-mcp service status
-machine-mcp service install
-machine-mcp service start
-machine-mcp service stop
-machine-mcp service uninstall
-```
+- The default `full` profile already enables unrestricted paths, absolute path output, and the complete parent environment.
+- `--unrestricted-paths=false`, `--absolute-paths=false`, and `--full-env=false` can narrow those individual settings.
+- `--absolute-paths` changes returned path metadata; it does not independently grant additional access.
+- In isolated-environment profiles, commands receive private HOME, temp, and cache directories plus a small set of platform variables.
+- Files with sensitive-looking names are not automatically blocked inside the workspace. A workspace `.env` remains readable when read tools are enabled.
 
-Autostart runs `--daemon-only --no-print-credentials --quiet`. The selected write, execution, environment, and path-boundary policies are persisted in the service definition. Service log files are owner-only where supported and are trimmed at daemon startup to prevent unbounded growth.
+## Tools
 
-## Secret rotation
-
-```zsh
-machine-mcp rotate-secrets
-machine-mcp
-```
+The exact `tools/list` response reflects the active local policy. Definitions come from one shared catalog used by both Worker and stdio transports.
 
-The first command stops the installed autostart service, refuses to proceed if another foreground daemon remains active, and then rotates the MCP password, daemon secret, and OAuth token version in local state. The second redeploys the Worker; previously issued OAuth access tokens then fail validation.
-
-## MCP tools
+### Workspace and content
 
 - `server_info`
 - `project_overview`
 - `list_roots`
 - `list_dir`
 - `list_files`
-- `read_file`
-- `write_file`
+- `read_file` — whole UTF-8 files or bounded line ranges
+- `view_image` — bounded PNG, JPEG, GIF, or WebP as native MCP image content
 - `search_text`
-- `git_status`
-- `git_diff`
-- `exec_command`
 
-Tool availability reflects daemon policy after the daemon handshake. `git_status` and `git_diff` detect the repository containing the requested path, including nested repositories.
+### Mutation
 
-## State and logs
+- `write_file` — atomic whole-file write with create-only and SHA-256 checks
+- `edit_file` — exact text replacement with ambiguity rejection
+- `apply_patch` — bounded multi-file add/update/move/delete transaction with rollback
 
-Default state roots:
+### Git
 
-- macOS/Linux: `~/.local/state/machine-bridge-mcp`
-- Linux with `XDG_STATE_HOME`: `$XDG_STATE_HOME/machine-bridge-mcp`
-- Windows: `%APPDATA%\machine-bridge-mcp`
+- `git_status`
+- `git_diff` — working tree or staged
+- `git_log` — structured commits; author email omitted unless explicitly requested
+- `git_show`
 
-Override the root with `--state-dir DIR`. A new custom root must be empty; a non-empty unmarked root must contain recognizable legacy Machine Bridge state before it is adopted. Legacy text markers are migrated to the current structured marker. Uninstall refuses to recursively delete filesystem roots, the home directory, the current/package directory, source trees, recorded workspaces, unrelated files, or an unrecognized state root.
+Repository-configured external diff, text conversion, and filesystem-monitor helpers are disabled for bridge Git inspection.
 
-State contains credentials and therefore uses owner-only permissions where supported. State/config writes use temporary files, `fsync`, and atomic rename. Corrupt state files are retained as bounded `.corrupt-*` backups rather than silently overwritten. Status and doctor output redact secrets and personal Wrangler output; structured logs fully redact credential-like fields and neutralize control characters.
+### Processes
 
-Temporary Wrangler secret files are created under the owner-only profile directory and removed in a `finally` block. Stale files older than one hour are cleaned before deployment.
+- `run_process` — one-shot argv execution without a shell
+- `start_process`
+- `read_process`
+- `write_process`
+- `kill_process`
+- `exec_command` — shell execution, available only in `shell` mode
 
-## Worker protections
+Process sessions retain bounded stdout/stderr, support offsets and short waits, accept stdin, and are killed when the daemon connection is lost or replaced. They are pipe-based and do not emulate a terminal/PTY.
 
-The Worker currently enforces:
+## Path and write behavior
 
-- OAuth authorization code flow with PKCE S256.
-- Hashed access-token storage and token-version revocation.
-- Exact resource, client, and redirect URI binding.
-- Bounded registration metadata, clients, authorization codes, tokens, and failed-login records.
-- Per-source dynamic-client registration limits and password-failure throttling.
-- A consent page that displays the validated client and redirect URI.
-- Request-body and concurrent daemon-call limits.
-- Same-origin browser access by default, exact configured-origin CORS/preflight support, and rejection of unlisted cross-origin requests.
-- `no-store`, content-type protection, CSP, frame denial, and referrer suppression on authorization responses.
-- Minimal public health output; live daemon/workspace details require an authenticated MCP call.
+When workspace confinement is enabled (`agent`, `edit`, `review`, or an explicit override), existing paths are resolved with `realpath` and must remain inside the canonical workspace. New write paths validate the nearest existing ancestor, preventing missing-path writes through escaping symbolic-link directories. The default `full` profile permits direct filesystem paths outside the workspace.
 
-Browser requests are same-origin by default. Additional browser origins can be listed exactly in `MBM_ALLOWED_ORIGINS`; the Worker then returns matching CORS preflight and response headers. Loopback OAuth redirect URIs do not implicitly authorize loopback browser origins. Do not use wildcards or `null`.
+Writes use same-directory temporary files and atomic commit. Create-only writes use an atomic hard-link commit so a concurrent file cannot be silently overwritten. Patch operations are prevalidated, serialized, staged, rechecked, committed with backups, and rolled back on failure.
 
-## Uninstall
+The default `full` profile returns absolute paths. The `agent`, `edit`, and `review` profiles return workspace-relative paths to reduce unnecessary disclosure of usernames and local directory layouts.
 
-Delete known Workers, autostart entries, and local state:
+## Commands
 
-```zsh
-machine-mcp uninstall
+```text
+machine-mcp [start options]
+machine-mcp stdio [options]
+machine-mcp client-config [all|claude|cursor|codex|generic]
+machine-mcp workspace show|set|reset
+machine-mcp service status|install|start|stop|uninstall
+machine-mcp status
+machine-mcp doctor
+machine-mcp rotate-secrets
+machine-mcp uninstall [--keep-worker] [--yes]
 ```
 
-Non-interactive:
+Each canonical workspace has an independent profile, Worker name, credential set, state file, startup lock, and daemon lock.
 
-```zsh
-machine-mcp uninstall --yes
-```
+## Autostart
 
-Keep deployed Workers while removing local state and autostart:
+Remote mode supports:
 
-```zsh
-machine-mcp uninstall --keep-worker
-```
+- macOS user LaunchAgent;
+- Linux `systemd --user`, with best-effort lingering;
+- Windows Scheduled Task at logon.
 
-Remove a global npm installation separately:
+The service definition contains neither credentials nor a duplicate policy. It loads the selected policy from owner-only local state and uses the documented `full` default if policy state is absent. Service logs are owner-only where supported and trimmed before daemon startup.
 
-```zsh
-npm uninstall -g machine-bridge-mcp
+## Secret rotation
+
+```sh
+machine-mcp rotate-secrets --no-print-credentials
+machine-mcp
 ```
 
-## Architecture and failure behavior
+Rotation stops the installed service, refuses to proceed while another foreground daemon owns the workspace lock, rotates the MCP password, daemon secret, and OAuth token version, and requires redeployment. Previously issued access tokens then fail validation.
+
+## State and observability
 
-See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for trust boundaries, request lifecycles, limits, reconnect behavior, and the rationale for the Worker/Durable Object/daemon split.
+Default state roots:
+
+- macOS/Linux: `~/.local/state/machine-bridge-mcp`
+- Linux with `XDG_STATE_HOME`: `$XDG_STATE_HOME/machine-bridge-mcp`
+- Windows: `%APPDATA%\machine-bridge-mcp`
 
-Operationally:
+State/config writes use owner-only temporary files, flushes, and atomic rename. Malformed state is retained as a bounded corrupt backup before reconstruction. Uninstall validates markers, canonical paths, active locks, workspace/source exclusions, and known contents before recursive deletion.
 
-- A newer daemon connection replaces the older socket. The relay handshake does not upload the local workspace name, path hash, or process ID.
-- Pending calls are bound to the socket that received them, so a stale socket cannot complete or cancel calls on the replacement connection; active child processes are terminated when that connection is lost or replaced.
-- The daemon reconnects after transient Worker/network failures using bounded exponential backoff with jitter, and terminates active child processes when the active relay socket closes.
-- Tool calls and Wrangler subprocesses have bounded execution time and output; timed-out commands terminate their process tree where the platform permits.
-- Separate per-workspace startup and daemon locks prevent overlapping deploy/rotation operations and duplicate local daemons.
-- Uninstall stops and removes autostart first, refuses to proceed while an active startup or daemon process owns a lock, and preserves local state when Worker deletion fails so the operation can be retried.
-- Worker health checks verify the expected package/Worker version before a deployment hash is accepted.
+Operational logs record bounded metadata such as component, tool name, shortened call ID, duration, outcome, and error class. They do not intentionally log file contents, patch bodies, command strings, stdin, OAuth passwords, access tokens, or daemon secrets. See [docs/OPERATIONS.md](docs/OPERATIONS.md).
 
-## Development
+## Development and verification
 
-```zsh
+```sh
 npm ci
 npm run check
 npm run worker:dry-run
 npm audit --omit=dev --audit-level=high
+npm pack --dry-run
 ```
 
-`npm run check` generates Worker types, type-checks the Worker, checks all local JavaScript entry points, and runs regression tests for path confinement, symbolic-link escapes, atomic writes, UTF-8 handling, nested Git repositories, minimal environments, daemon locking, CLI parsing, state recovery/removal guards, log redaction, log trimming, Worker hardening guards, and a live local OAuth/MCP flow through Wrangler.
+`npm run check` covers generated Worker types, TypeScript, JavaScript syntax, the shared tool catalog, local path/write/process/state/log/service invariants, a live stdio MCP flow, and a live local OAuth/Worker/WebSocket/MCP flow. GitHub Actions runs the suite on Linux, macOS, and Windows with supported Node versions.
+
+See [docs/TESTING.md](docs/TESTING.md), [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md), and [SECURITY.md](SECURITY.md).
+
+## Uninstall
+
+```sh
+machine-mcp uninstall
+npm uninstall -g machine-bridge-mcp
+```
+
+Use `--keep-worker` to retain deployed Workers while removing local state and autostart.
+
+## License
 
-The release checks are validated on Node.js 22 and 24. Node.js 22 or newer is required by the current Wrangler toolchain. See [CHANGELOG.md](CHANGELOG.md) for release notes.
+MIT