machine-bridge-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 machine-bridge-mcp contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,203 @@
+# machine-bridge-mcp
+
+`machine-bridge-mcp` turns your machine into a Remote MCP server through a small hosted relay and a local outbound daemon.
+
+The recommended deployment command is short and stable for autostart:
+
+```zsh
+npm install -g machine-bridge-mcp@latest && machine-mcp
+```
+
+No-global-install alternative:
+
+```zsh
+npx machine-bridge-mcp@latest
+```
+
+Source checkout:
+
+```zsh
+./mbm          # macOS/Linux
+.\mbm.cmd      # Windows cmd
+```
+
+## What it does on first run
+
+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.
+7. Starts the local daemon and prints:
+
+```text
+MCP Server URL: https://<worker>.<account>.workers.dev/mcp
+MCP connection password: mcp_password_...
+```
+
+Keep the foreground process running for the current session. The installed autostart entry keeps the daemon available after future logins.
+
+## Re-select workspace
+
+```zsh
+machine-mcp workspace set
+```
+
+Or provide it directly:
+
+```zsh
+machine-mcp workspace set /path/to/new/default
+```
+
+Show the remembered workspace:
+
+```zsh
+machine-mcp workspace show
+```
+
+## Autostart service
+
+Supported platforms:
+
+- macOS: user LaunchAgent
+- Linux: `systemd --user` with best-effort `loginctl enable-linger`
+- Windows: Scheduled Task at logon
+
+Commands:
+
+```zsh
+machine-mcp service status
+machine-mcp service install
+machine-mcp service start
+machine-mcp service stop
+machine-mcp service uninstall
+```
+
+`start` installs autostart by default. Skip that behavior with:
+
+```zsh
+machine-mcp --no-autostart
+```
+
+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.
+
+## Secrets rotation
+
+```zsh
+machine-mcp rotate-secrets
+machine-mcp
+```
+
+`rotate-secrets` creates a new MCP connection password, daemon secret, and OAuth token version. The next deploy rejects previously issued OAuth access tokens.
+
+## Uninstall
+
+Delete known deployed Worker(s), remove autostart entries, and remove local state:
+
+```zsh
+machine-mcp uninstall
+```
+
+Non-interactive:
+
+```zsh
+machine-mcp uninstall --yes
+```
+
+Keep the deployed Worker but remove local state/autostart:
+
+```zsh
+machine-mcp uninstall --keep-worker
+```
+
+If installed globally, remove the npm package afterwards:
+
+```zsh
+npm uninstall -g machine-bridge-mcp
+```
+
+## Defaults and permissions
+
+This project optimizes for easy use with official Remote MCP clients:
+
+- `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.
+
+Narrower session:
+
+```zsh
+machine-mcp --no-write --no-exec
+```
+
+## MCP tools
+
+- `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
+
+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`
+
+State contains the MCP password and daemon secret. Status/doctor output redacts secrets. The normal foreground `start` command prints the MCP password because users need to paste it into their MCP client.
+
+Override state root:
+
+```zsh
+machine-mcp --state-dir /path/to/state
+```
+
+## Architecture
+
+```mermaid
+flowchart LR
+  C["Remote MCP client"] -- "HTTPS /mcp + OAuth" --> W["Hosted Worker relay"]
+  W --> DO["Durable Object broker"]
+  D["Local daemon"] -- "outbound WebSocket" --> W
+  D --> M["Local filesystem and shell"]
+  CLI["machine-mcp CLI"] --> W
+  CLI --> D
+  CLI --> S["Autostart service"]
+```
+
+Why this architecture:
+
+- 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.
+- Autostart keeps the daemon alive across logins without requiring MCP clients to change URLs.
+
+## Development
+
+```zsh
+npm install
+npm run check
+```
+
+`npm run check` generates Worker runtime types, type-checks the Worker, checks local JS syntax, and runs daemon self-tests.
+
+Worker build dry-run:
+
+```zsh
+npx wrangler deploy --dry-run
+```

package/bin/machine-mcp.mjs

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { main } from "../src/local/cli.mjs";
+
+main().catch(error => {
+  const message = process.env.MBM_DEBUG === "1"
+    ? (error?.stack || error?.message || String(error))
+    : (error?.message || String(error));
+  console.error(`Error: ${message}`);
+  process.exitCode = 1;
+});

package/mbm

@@ -0,0 +1,9 @@
+#!/usr/bin/env sh
+set -eu
+DIR=$(CDPATH= cd "$(dirname "$0")" && pwd)
+cd "$DIR"
+if [ ! -d node_modules ] || [ ! -x node_modules/.bin/wrangler ]; then
+  echo "Installing local dependencies..."
+  npm install
+fi
+exec node bin/machine-mcp.mjs "$@"

package/mbm.cmd

@@ -0,0 +1,8 @@
+@echo off
+setlocal
+cd /d "%~dp0"
+if not exist node_modules\wrangler (
+  echo Installing local dependencies...
+  call npm install || exit /b %errorlevel%
+)
+node bin\machine-mcp.mjs %*

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "machine-bridge-mcp",
+  "version": "0.1.0",
+  "description": "One-command hosted Remote MCP bridge to a local machine daemon.",
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "bin": {
+    "machine-bridge-mcp": "bin/machine-mcp.mjs",
+    "machine-mcp": "bin/machine-mcp.mjs",
+    "mbm": "bin/machine-mcp.mjs"
+  },
+  "files": [
+    "mbm",
+    "mbm.cmd",
+    "bin",
+    "src/local",
+    "src/worker/index.ts",
+    "wrangler.jsonc",
+    "tsconfig.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node bin/machine-mcp.mjs start",
+    "doctor": "node bin/machine-mcp.mjs doctor",
+    "self-test": "node src/local/self-test.mjs",
+    "worker:types": "wrangler types src/worker/worker-configuration.d.ts",
+    "typecheck": "npm run worker:types && tsc -p tsconfig.json --noEmit",
+    "syntax": "sh -n mbm && node --check bin/machine-mcp.mjs && node --check src/local/cli.mjs && node --check src/local/daemon.mjs && node --check src/local/state.mjs && node --check src/local/shell.mjs && node --check src/local/service.mjs && node --check src/local/self-test.mjs",
+    "check": "npm run typecheck && npm run syntax && npm run self-test"
+  },
+  "dependencies": {
+    "wrangler": "^4.24.3",
+    "ws": "^8.18.3"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.1",
+    "typescript": "^5.8.3"
+  },
+  "keywords": [
+    "mcp",
+    "remote-mcp",
+    "cloudflare-workers",
+    "durable-objects",
+    "wrangler",
+    "local-machine"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/YuLeiFuYun/machine-bridge-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/YuLeiFuYun/machine-bridge-mcp/issues"
+  },
+  "homepage": "https://github.com/YuLeiFuYun/machine-bridge-mcp#readme"
+}