machine-bridge-mcp 0.3.3 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## 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 +42,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,251 @@
 # 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
+## Security posture first
 
-Recommended global installation:
+A new workspace starts with the `review` profile:
 
-```zsh
-npm install -g machine-bridge-mcp@latest
-machine-mcp
-```
+- read-only filesystem and Git tools;
+- no file mutation;
+- no process execution;
+- workspace-confined filesystem access;
+- relative paths in tool results;
+- no parent shell environment inherited by commands.
 
-Without a global installation:
+Existing pre-0.4 workspace profiles keep their saved permissions during upgrade. Select a profile explicitly to change them.
 
-```zsh
-npx machine-bridge-mcp@latest
+| Profile | File edits | Direct argv processes | Shell commands | Intended use |
+|---|---:|---:|---:|---|
+| `review` | No | No | No | Inspection and review |
+| `edit` | Yes | No | No | Controlled file changes |
+| `agent` | Yes | Yes | No | Coding agents and test commands |
+| `full` | Yes | Yes | Yes | Deliberate full local automation |
+
+`run_process` and process sessions avoid command-shell parsing, but they are **not an operating-system sandbox**. An allowed executable can still access anything available to the local user. `exec_command` is more exposed because it additionally permits shell syntax and expansion. Use a container, VM, or dedicated low-privilege OS account for hostile repositories or untrusted instructions.
+
+## 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 --profile review
+```
+
+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.
+## Local stdio MCP for Claude, Cursor, Codex, and compatible clients
 
-A narrower session:
+Generate ready-to-paste configuration:
 
-```zsh
-machine-mcp --no-write --no-exec
+```sh
+machine-mcp client-config --client all --workspace /path/to/project --profile agent
 ```
 
-Explicitly permit filesystem paths outside the workspace:
+Or run stdio directly:
 
-```zsh
-machine-mcp --unrestricted-paths
+```sh
+machine-mcp stdio --workspace /path/to/project --profile agent
 ```
 
-Pass the complete parent process environment to shell commands only when required:
+The stdio server writes only JSON-RPC messages to stdout. Operational logs go to stderr. It supports MCP initialization/version negotiation, tool discovery, calls, cancellation, structured tool output, native image content, and process sessions.
 
-```zsh
-machine-mcp --full-env
-```
-
-`--unrestricted-paths` and `--full-env` materially increase the data-exposure boundary. See [SECURITY.md](SECURITY.md) before enabling them.
+See [docs/CLIENTS.md](docs/CLIENTS.md) for client-specific configuration and remote/local trade-offs.
 
-## Commands
-
-```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:
+Profiles can be narrowed with explicit flags:
 
 ```text
---workspace PATH
---worker-name NAME
---force-worker
---rotate-secrets
---daemon-only
---no-autostart
---no-print-credentials
---print-mcp-credentials
+--profile review|edit|agent|full
+--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
-```
-
-Each canonical workspace path receives an independent profile, Worker name, secret set, and daemon lock.
-
-## 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
+--absolute-paths
 ```
 
-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.
+Important distinctions:
 
-## Secret rotation
+- `--unrestricted-paths` expands direct filesystem tools beyond the selected workspace.
+- `--absolute-paths` changes returned path metadata; it does not grant additional access.
+- `--full-env` passes the complete parent environment to processes. Without it, commands receive an isolated HOME, temp directory, 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.
 
-```zsh
-machine-mcp rotate-secrets
-machine-mcp
-```
+## Tools
 
-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.
+The exact `tools/list` response reflects the active local policy. Definitions come from one shared catalog used by both Worker and stdio transports.
 
-## 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.
+By default, 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.
 
-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
+Returned paths are workspace-relative by default. This reduces unnecessary disclosure of usernames and local directory layouts. Enable `--absolute-paths` only when a client genuinely needs absolute paths.
 
-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 fails closed to the `review` profile 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.
 
-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.
+## State and observability
+
+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` 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. A ready-to-enable GitHub Actions template is included at `docs/examples/github-actions-ci.yml` for Linux, macOS, and Windows with supported Node versions. Activating it requires a GitHub credential authorized to modify workflow files.
+
+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
 ```
 
-`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.
+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