machine-bridge-mcp 0.2.5 → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,94 @@
+# 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
+
+- Add an exact-version npm `allowScripts` policy for the reviewed Wrangler runtime/build binaries (`esbuild@0.28.1`, `sharp@0.34.5`, and `workerd@1.20260708.1`) and explicitly deny the optional `fsevents` install script. Dependency upgrades therefore require renewed script approval.
+
+### 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
+
+### Fixed
+
+- Keep the healthy daemon active until a replacement connection completes its authenticated `hello` handshake; enforce the candidate deadline with a Durable Object alarm so it survives WebSocket hibernation, and reject stale or non-handshaking candidates without disrupting the active connection.
+- Send the candidate acknowledgement before closing the previous daemon, expire failed acknowledgements, clean up duplicate authenticated sockets on subsequent handshakes, and reject pre-handshake messages without changing active tool metadata.
+
+## 0.3.1 - 2026-07-10
+
+### Security
+
+- Replace reversible unsalted source-address hashes used for OAuth registration limits and password throttling with deployment-keyed HMAC identifiers; stop persisting User-Agent-derived identities, remove legacy unsalted identifiers during store migration, and fail closed if no identity key is configured.
+
+### Fixed
+
+- Preserve timeout escalation after the direct child exits so a process-group `SIGKILL` still removes descendants that ignore `SIGTERM`; add a regression test for the orphan-process boundary.
+- Replace legacy unsalted source-identity hashes with deployment-keyed HMAC identifiers, prune legacy stored identifiers, and add integration coverage for registration quotas and login throttling.
+
+## 0.3.0 - 2026-07-10
+
+### Security
+
+- Confine filesystem tools to the canonical workspace by default; add explicit `--unrestricted-paths` opt-in and symbolic-link escape protection.
+- Make `write_file` bounded and atomic, reject symbolic-link/non-regular destinations, and enforce optimistic hashes consistently.
+- Add recursive log-field and token redaction, control-character neutralization, owner-only service logs, and bounded log trimming.
+- Harden OAuth with strict PKCE/resource/client/redirect validation, validated client disclosure on the consent page, password-failure throttling, bounded dynamic registration, per-source and per-client limits, inactive-client cleanup, strict HTTP methods/UTF-8 handling, and security response headers.
+- Minimize unauthenticated and relay metadata disclosure: remove workspace name/path hash/process ID from the daemon handshake, reduce default observability sampling, and bind pending calls to their originating daemon socket.
+- Bound Worker/daemon request sizes and concurrency; serialize OAuth mutations; isolate WebSocket generations; serialize per-workspace startup/deploy/rotation operations; terminate timed-out or disconnected child processes and bound Wrangler subprocesses.
+
+### Changed
+
+- Raise the minimum Node.js version to 22 because the current Wrangler release no longer runs on Node 20; require the installed Wrangler dependency instead of falling back to an implicit network `npx` execution.
+- Remove the experimental local OpenAI-compatible `/v1` API and MCP sampling proxy.
+- Detect nested Git repositories for `git_status` and `git_diff`, while disabling repository-configured external diff, text conversion, and filesystem-monitor hooks for bridge Git operations.
+- Use atomic local state/config writes, bounded corrupt-state backups, strict adoption/migration of dedicated state roots, and guarded state-root deletion during uninstall, including refusal while active daemon/startup locks remain.
+- Reject unknown, duplicate, malformed, and command-inapplicable CLI options; fix boolean options consuming positional workspaces.
+- Verify the expected Worker version before accepting a deployment hash.
+- Reduce the default Worker request-body limit to 8 MiB; bound command length, directory results, recursive traversal, and path-result payloads; provide exact-origin CORS while rejecting implicit loopback browser origins.
+- Update Wrangler to 4.110.x, TypeScript to 5.9.x, and Node type definitions to the supported Node 22 API line.
+
+### Tests and documentation
+
+- Expand self-tests across path boundaries, symlinks, writes, UTF-8, nested Git, environment isolation, locking, CLI parsing, state recovery/removal guards, logging, service logs, and Worker hardening invariants.
+- Add a live local Worker OAuth/MCP integration test, verified Node 22/24 compatibility, a Worker build dry-run, dependency audit, security policy, and architecture document.
+
+## 0.2.5
+
+- Previous release.

package/README.md

@@ -1,238 +1,217 @@
 # machine-bridge-mcp
 
-`machine-bridge-mcp` turns your machine into a Remote MCP server through a small hosted relay and a local outbound daemon.
+`machine-bridge-mcp` exposes a selected local workspace to MCP clients through one shared, policy-controlled runtime.
 
-The recommended deployment command is short and stable for autostart:
+It supports two transports:
 
-```zsh
-npm install -g machine-bridge-mcp@latest && machine-mcp
-```
-
-No-global-install alternative:
+```text
+Remote clients such as ChatGPT
+        HTTPS + OAuth 2.1 / PKCE
+                  |
+       Cloudflare Worker + Durable Object
+                  ^
+                  | outbound authenticated WebSocket
+                  |
+             local runtime
 
-```zsh
-npx machine-bridge-mcp@latest
+Local clients such as Claude Desktop, Cursor, and Codex CLI
+                  |
+                 stdio
+                  |
+             local runtime
 ```
 
-Source checkout:
+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.
 
-```zsh
-./mbm          # macOS/Linux
-.\mbm.cmd      # Windows cmd
-```
+## Security posture first
 
-## What it does on first run
+A new workspace starts with the `review` profile:
 
-1. Asks for a workspace path. Press Enter to use the current directory.
-2. Remembers that workspace for later runs.
-3. Generates a stable MCP connection password and daemon secret.
-4. Checks `wrangler whoami`; if needed, opens `wrangler login`.
-5. Deploys the hosted Worker relay with `wrangler deploy --secrets-file`.
-6. Installs login autostart for the local daemon and default local API.
-7. Starts the local daemon and local OpenAI-compatible API.
-8. Prints MCP connection details on first run, plus local API settings:
+- 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.
 
-```text
-MCP Server URL: https://<worker>.<account>.workers.dev/mcp
-MCP connection password: mcp_password_...
-API Base URL: http://127.0.0.1:8765/v1
-API key: local_api_key_...
-```
+Existing pre-0.4 workspace profiles keep their saved permissions during upgrade. Select a profile explicitly to change them.
 
-Keep the foreground process running for the current session. The installed autostart entry keeps the daemon and local API available after future logins.
+| 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 |
 
-The command is safe to run repeatedly:
+`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.
 
-```zsh
-npm install -g machine-bridge-mcp@latest && machine-mcp
-```
+## Install
 
-On repeat runs, the CLI reuses existing state and secrets unless you request rotation, skips Worker redeploys when the deployed Worker is healthy and Worker source/config/secrets are unchanged, refreshes the autostart entry, stops any currently loaded autostart daemon before starting the foreground daemon, and refuses to start a second daemon for the same workspace if another foreground instance is already running. Local-only package, CLI, logging, and local API changes do not by themselves force a Worker redeploy.
+Node.js 22 or newer is required.
 
-MCP connection details are printed on first run, after secret rotation, when the MCP URL changes, or when you explicitly pass `--print-mcp-credentials`. Routine runs print that MCP details are unchanged.
-
-## Local OpenAI-compatible API
-
-The project exposes two connected integration surfaces:
-
-- **ChatGPT web / ChatGPT apps:** use the Remote MCP Server URL and MCP connection password printed by `machine-mcp`. In this mode, ChatGPT calls tools on your machine through the Worker + local daemon bridge.
-- **Desktop clients such as Cherry Studio, Chatbox, or Continue:** use the optional local OpenAI-compatible `/v1` API. `POST /v1/chat/completions` is backed by MCP sampling: the local API asks the hosted Worker to send `sampling/createMessage` to the already-connected ChatGPT MCP client, then wraps the MCP sampling result as an OpenAI-compatible chat completion response.
-
-No separate model API setup is required or used in this path; the local API never asks for a model base URL or model API key. Generation depends on the ChatGPT-side MCP client actually being connected and able to receive server-to-client sampling requests. If ChatGPT is not connected, has no open MCP stream for server-to-client messages, or did not advertise the MCP `sampling` capability, generation returns an explicit OpenAI-shaped error saying that the missing piece is the MCP client stream or sampling capability.
+```sh
+npm install -g machine-bridge-mcp@latest
+```
 
-Start the normal daemon and local API:
+From a source checkout:
 
-```zsh
-machine-mcp
+```sh
+npm install
+./mbm                 # macOS/Linux
+.\mbm.cmd             # Windows cmd
 ```
 
-Start only the local API from remembered state:
+## Remote MCP for ChatGPT
+
+Start the bridge from the project directory or select a workspace explicitly:
 
-```zsh
-machine-mcp api
+```sh
+machine-mcp --workspace /path/to/project --profile review
 ```
 
-Disable the default local API for a daemon run:
+On first remote start, the CLI:
 
-```zsh
-machine-mcp --no-api
-```
+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.
 
-When the API is running, the CLI prints client settings like:
+Use the printed values in the MCP client:
 
 ```text
-API Base URL: http://127.0.0.1:8765/v1
-API key: local_api_key_...
-Client type: OpenAI-compatible
-Model: chatgpt-mcp
-Backend: ChatGPT MCP sampling via the connected ChatGPT app
+MCP Server URL: https://<worker>.<account>.workers.dev/mcp
+MCP connection password: mcp_password_...
 ```
 
-Use the API Base URL, API key, and model in your desktop client. Separately, connect ChatGPT to the printed MCP Server URL/password so the Worker has an MCP client stream that can receive `sampling/createMessage`.
+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.
 
-If port `8765` conflicts with another local app, choose a different port explicitly:
-
-```zsh
-machine-mcp --api-port 8766
-machine-mcp api --api-port 8766
-```
+## Local stdio MCP for Claude, Cursor, Codex, and compatible clients
 
-`--port` is also accepted on the `api` command:
+Generate ready-to-paste configuration:
 
-```zsh
-machine-mcp api --port 8766
+```sh
+machine-mcp client-config --client all --workspace /path/to/project --profile agent
 ```
 
-By default, the local API binds to `127.0.0.1`, starts with `machine-mcp`, and stores a per-workspace local API key in the same owner-only state profile used by the MCP credentials. Explicit `--api-host`, `--api-port`, and `--api-model` values are persisted for the workspace so autostart uses the same API settings. `--api-model` only controls the local model id advertised by `GET /v1/models`; the actual model is chosen by the connected MCP client, and any different `model` value in a chat-completions request is passed as an MCP model preference hint.
+Or run stdio directly:
 
-Rotate the local desktop-client API key with:
-
-```zsh
-machine-mcp api --rotate-api-key
+```sh
+machine-mcp stdio --workspace /path/to/project --profile agent
 ```
 
-Environment variables supported for the current process: `MBM_API_HOST`, `MBM_API_PORT`, `MBM_API_KEY`, and `MBM_API_MODEL`. Environment overrides are not persisted to state; use `--api-host`, `--api-port`, `--api-key`, or `--api-model` when you want a setting saved for future runs and autostart.
-
-Supported local API routes:
+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.
 
-- `GET /health` without authentication
-- `GET /v1/models` with `Authorization: Bearer <local_api_key>` or `x-api-key`
-- `POST /v1/chat/completions`
+See [docs/CLIENTS.md](docs/CLIENTS.md) for client-specific configuration and remote/local trade-offs.
 
-`POST /v1/responses`, `POST /v1/completions`, and `POST /v1/embeddings` return `501 unsupported_endpoint`; MCP sampling is a chat-message path and does not expose embeddings or the full Responses API. Logs record route, status, latency, and safe configuration metadata; request and response bodies and API keys are not logged.
+## Policy controls
 
-## Re-select workspace
-
-```zsh
-machine-mcp workspace set
-```
+Profiles can be narrowed with explicit flags:
 
-Or provide it directly:
-
-```zsh
-machine-mcp workspace set /path/to/new/default
+```text
+--profile review|edit|agent|full
+--exec-mode off|direct|shell
+--no-write
+--no-exec
+--full-env
+--unrestricted-paths
+--absolute-paths
 ```
 
-Show the remembered workspace:
+Important distinctions:
 
-```zsh
-machine-mcp workspace show
-```
+- `--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.
 
-## Autostart service
+## Tools
 
-Supported platforms:
+The exact `tools/list` response reflects the active local policy. Definitions come from one shared catalog used by both Worker and stdio transports.
 
-- macOS: user LaunchAgent
-- Linux: `systemd --user` with best-effort `loginctl enable-linger`
-- Windows: Scheduled Task at logon
+### Workspace and content
 
-Commands:
+- `server_info`
+- `project_overview`
+- `list_roots`
+- `list_dir`
+- `list_files`
+- `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`
 
-```zsh
-machine-mcp service status
-machine-mcp service install
-machine-mcp service start
-machine-mcp service stop
-machine-mcp service uninstall
-```
+### Mutation
 
-`start` installs autostart by default. Skip that behavior with:
+- `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
 
-```zsh
-machine-mcp --no-autostart
-```
+### Git
 
-Autostart runs the daemon with `--daemon-only --no-print-credentials`, so service logs do not contain the MCP connection password. If you start with `--no-write`, `--no-exec`, or `--full-env`, those policy flags are preserved in the autostart entry. macOS/Linux service definitions restart only on process failure; a normal duplicate-instance exit is not treated as a crash loop.
+- `git_status`
+- `git_diff` — working tree or staged
+- `git_log` — structured commits; author email omitted unless explicitly requested
+- `git_show`
 
-## Secrets rotation
+Repository-configured external diff, text conversion, and filesystem-monitor helpers are disabled for bridge Git inspection.
 
-```zsh
-machine-mcp rotate-secrets
-machine-mcp
-```
+### Processes
 
-`rotate-secrets` creates a new MCP connection password, daemon secret, and OAuth token version. The next deploy rejects previously issued OAuth access tokens.
+- `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
 
-## Uninstall
+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.
 
-Delete known deployed Worker(s), remove autostart entries, and remove local state:
+## Path and write behavior
 
-```zsh
-machine-mcp uninstall
-```
+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.
 
-Non-interactive:
+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.
 
-```zsh
-machine-mcp uninstall --yes
-```
+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.
 
-Keep the deployed Worker but remove local state/autostart:
+## Commands
 
-```zsh
-machine-mcp uninstall --keep-worker
+```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]
 ```
 
-If installed globally, remove the npm package afterwards:
+Each canonical workspace has an independent profile, Worker name, credential set, state file, startup lock, and daemon lock.
 
-```zsh
-npm uninstall -g machine-bridge-mcp
-```
+## Autostart
 
-## Defaults and permissions
+Remote mode supports:
 
-This project optimizes for easy use with official Remote MCP clients:
+- macOS user LaunchAgent;
+- Linux `systemd --user`, with best-effort lingering;
+- Windows Scheduled Task at logon.
 
-- `write_file` is enabled by default.
-- `exec_command` is enabled by default.
-- Absolute paths are allowed.
-- Parent-directory paths such as `../other-project/file.ts` are allowed.
-- Sensitive-looking files such as `.env`, private keys, token files, and dot-directories are not hidden by default.
-- Relative paths use the selected workspace as cwd.
-- Shell commands run with a minimal environment by default; use `--full-env` to pass the parent process environment.
+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.
 
-Narrower session:
+## Secret rotation
 
-```zsh
-machine-mcp --no-write --no-exec
+```sh
+machine-mcp rotate-secrets --no-print-credentials
+machine-mcp
 ```
 
-## MCP tools
+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.
 
-- `server_info`
-- `project_overview`
-- `list_roots`
-- `list_dir`
-- `list_files`
-- `read_file`
-- `write_file`
-- `search_text`
-- `git_status`
-- `git_diff`
-- `exec_command`
-
-## State and logs
+## State and observability
 
 Default state roots:
 
@@ -240,54 +219,33 @@ Default state roots:
 - Linux with `XDG_STATE_HOME`: `$XDG_STATE_HOME/machine-bridge-mcp`
 - Windows: `%APPDATA%\machine-bridge-mcp`
 
-State contains the MCP password, daemon secret, and local API key. Status/doctor output redacts secrets. The normal foreground `start` command prints the MCP password only when a ChatGPT app is likely to need reconnection: first run, secret rotation, MCP URL changes, or `--print-mcp-credentials`. The local API base URL and API key print on normal foreground starts because desktop AI clients need them. Use `--no-print-credentials` to redact console credentials. State files, temporary Worker secret files, lock files, and log directories are created under the user state root with owner-only permissions where the platform supports POSIX modes.
-
-The Worker rejects browser requests with an `Origin` header unless the origin is the Worker itself or a loopback HTTP origin. To allow additional browser-based MCP clients, set `MBM_ALLOWED_ORIGINS` to a comma-separated list of exact origins in `wrangler.jsonc` or Cloudflare Worker settings.
+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.
 
-Override state root:
+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).
 
-```zsh
-machine-mcp --state-dir /path/to/state
-```
+## Development and verification
 
-## Architecture
-
-```mermaid
-flowchart LR
-  C["ChatGPT / MCP client"] -- "HTTPS /mcp + OAuth" --> W["Hosted Worker relay"]
-  C -- "GET SSE stream for server-to-client MCP" --> W
-  W --> DO["Durable Object broker"]
-  D["Local daemon"] -- "outbound WebSocket" --> W
-  D --> M["Local filesystem and shell"]
-  API["Local /v1/chat/completions"] -- "POST /api/mcp/sampling" --> W
-  DO -- "sampling/createMessage" --> C
-  CLI["machine-mcp CLI"] --> API
-  CLI --> W
-  CLI --> D
-  CLI --> S["Autostart service"]
+```sh
+npm ci
+npm run check
+npm run worker:dry-run
+npm audit --omit=dev --audit-level=high
+npm pack --dry-run
 ```
 
-Why this architecture:
+`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.
 
-- No inbound local port is exposed to the internet.
-- No local tunnel process is required.
-- The public MCP URL is stable after deployment.
-- The Worker stores OAuth client/code/token metadata and relays tool calls.
-- The local daemon is the only process touching files or executing commands.
-- The local `/v1` API binds to loopback by default, starts automatically with the daemon, and can be disabled with `--no-api`.
-- Autostart keeps the daemon and local API alive across logins without requiring MCP clients to change URLs.
+See [docs/TESTING.md](docs/TESTING.md), [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md), and [SECURITY.md](SECURITY.md).
 
-## Development
+## Uninstall
 
-```zsh
-npm install
-npm run check
+```sh
+machine-mcp uninstall
+npm uninstall -g machine-bridge-mcp
 ```
 
-`npm run check` generates Worker runtime types, type-checks the Worker, checks local JS syntax, and runs daemon self-tests.
+Use `--keep-worker` to retain deployed Workers while removing local state and autostart.
 
-Worker build dry-run:
+## License
 
-```zsh
-npx wrangler deploy --dry-run
-```
+MIT