machine-bridge-mcp 0.4.2 → 0.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +24 -0
- package/README.md +17 -9
- package/SECURITY.md +6 -4
- package/docs/ARCHITECTURE.md +12 -10
- package/docs/CLIENTS.md +6 -0
- package/docs/LOGGING.md +80 -0
- package/docs/OPERATIONS.md +25 -19
- package/docs/TESTING.md +7 -4
- package/package.json +4 -4
- package/src/local/cli.mjs +155 -77
- package/src/local/daemon.mjs +58 -41
- package/src/local/log.mjs +56 -15
- package/src/local/service.mjs +40 -21
- package/src/local/state.mjs +45 -20
- package/src/local/stdio.mjs +13 -37
- package/src/local/tools.mjs +28 -13
- package/src/shared/server-metadata.json +17 -0
- package/src/shared/tool-catalog.json +2 -2
- package/src/worker/index.ts +13 -11
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,29 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.5.0 - 2026-07-10
|
|
4
|
+
|
|
5
|
+
### Changed
|
|
6
|
+
|
|
7
|
+
- Replace routine per-tool success chatter with explicit log levels. Foreground mode defaults to `info`, autostart uses `warn`, fast successful calls are debug-only, and successful calls over 30 seconds remain visible as slow-call events. `--verbose` maps to `debug`; `--quiet` maps to `error`; `--log-level` accepts `error`, `warn`, `info`, or `debug`.
|
|
8
|
+
- Record policy origin and revision in state and daemon metadata. The exact legacy implicit-default policy shape is migrated once to the current maximum-permission `full` profile, while explicit named profiles and identified custom policies are preserved.
|
|
9
|
+
- Redact JSON connection credentials and standalone secret-rotation output by default. Printing the client connection password now requires the explicit reconnect flag; the daemon secret is never printed in full.
|
|
10
|
+
- Centralize server name, MCP protocol versions, and instructions in shared metadata consumed by both Worker and local transports.
|
|
11
|
+
- Reject obsolete removed-local-API flags instead of silently accepting them.
|
|
12
|
+
|
|
13
|
+
### Security and privacy
|
|
14
|
+
|
|
15
|
+
- Upgrade and pin `ws` to 8.21.0 to address current memory-disclosure and denial-of-service advisories; pin the reviewed Wrangler runtime version.
|
|
16
|
+
- Bind text, image, and search reads to an opened file handle, enforce limits against that handle, and avoid `stat`/read growth races.
|
|
17
|
+
- Bound state, configuration, marker, lock, service-command, log-message, and structured-log sizes. Reject symbolic-link state files, use no-follow reads where supported, and make service-log tail trimming UTF-8 and line safe.
|
|
18
|
+
- Remove stale temporary Worker secret files when their owner process is gone, not only after an age threshold.
|
|
19
|
+
- Document and expose that Machine Bridge has no sensitive-filename blacklist. Local `full` permits any OS-readable UTF-8 regular file, but cannot override operating-system or independent MCP-host/platform policy.
|
|
20
|
+
|
|
21
|
+
### Tests and operations
|
|
22
|
+
|
|
23
|
+
- Add regression coverage for legacy policy migration, sensitive-looking files outside the workspace, inherited full-profile environment, default daemon/stdio log suppression, log bounding, state write bounds, service warning-level configuration, and shared metadata drift.
|
|
24
|
+
- Audit both complete and production-only dependency graphs in GitHub Actions.
|
|
25
|
+
- Document npm's scoped install-script approval for Wrangler native dependencies and add a dedicated logging/observability reference.
|
|
26
|
+
|
|
3
27
|
## 0.4.2 - 2026-07-10
|
|
4
28
|
|
|
5
29
|
### Fixed
|
package/README.md
CHANGED
|
@@ -32,7 +32,7 @@ A newly selected workspace starts with the maximum-permission `full` profile for
|
|
|
32
32
|
- tool results may return absolute paths;
|
|
33
33
|
- child processes inherit the complete parent environment.
|
|
34
34
|
|
|
35
|
-
|
|
35
|
+
Policy state records whether it came from the default, an explicit named profile, or custom overrides. Version 0.5 migrates the exact pre-0.4 implicit-default shape to `full` once; explicit restrictive profiles and identified custom policies remain unchanged.
|
|
36
36
|
|
|
37
37
|
| Profile | File edits | Direct argv processes | Shell commands | Filesystem scope | Process environment |
|
|
38
38
|
|---|---:|---:|---:|---|---|
|
|
@@ -48,10 +48,12 @@ This default prioritizes usability, not least privilege. `run_process` and proce
|
|
|
48
48
|
Node.js 22 or newer is required.
|
|
49
49
|
|
|
50
50
|
```sh
|
|
51
|
-
npm install -g machine-bridge-mcp@latest
|
|
51
|
+
npm install -g --allow-scripts=esbuild,workerd,sharp machine-bridge-mcp@latest
|
|
52
52
|
```
|
|
53
53
|
|
|
54
|
-
|
|
54
|
+
Recent npm releases may otherwise warn that Wrangler's native dependencies (`esbuild`, `workerd`, and `sharp`) have install scripts awaiting approval. The scoped command above approves only those packages for this installation; it does not change the user's global npm policy. A plain install can still work when compatible prebuilt artifacts are already available, but `machine-mcp doctor` is the authoritative runtime check.
|
|
55
|
+
|
|
56
|
+
From a source checkout, the checked-in exact-version `allowScripts` policy approves the reviewed native dependencies:
|
|
55
57
|
|
|
56
58
|
```sh
|
|
57
59
|
npm install
|
|
@@ -118,6 +120,9 @@ The default is `full`. Narrow or customize it with explicit flags:
|
|
|
118
120
|
--full-env
|
|
119
121
|
--unrestricted-paths
|
|
120
122
|
--absolute-paths
|
|
123
|
+
--log-level error|warn|info|debug
|
|
124
|
+
--verbose
|
|
125
|
+
--quiet
|
|
121
126
|
```
|
|
122
127
|
|
|
123
128
|
Important distinctions:
|
|
@@ -126,7 +131,8 @@ Important distinctions:
|
|
|
126
131
|
- `--unrestricted-paths=false`, `--absolute-paths=false`, and `--full-env=false` can narrow those individual settings.
|
|
127
132
|
- `--absolute-paths` changes returned path metadata; it does not independently grant additional access.
|
|
128
133
|
- In isolated-environment profiles, commands receive private HOME, temp, and cache directories plus a small set of platform variables.
|
|
129
|
-
-
|
|
134
|
+
- The server has no filename blacklist. Under `full`, direct read tools may read any UTF-8 regular file that the local OS user can access, including files outside the workspace and names such as `.env`, `passwords.txt`, or private-key files.
|
|
135
|
+
- Maximum local policy does not override operating-system permissions, macOS TCC/SIP, Windows ACLs, container boundaries, or independent safety rules imposed by the MCP host/platform. A host-generated “sensitive file” denial is outside this server's enforcement layer.
|
|
130
136
|
|
|
131
137
|
## Tools
|
|
132
138
|
|
|
@@ -188,6 +194,7 @@ machine-mcp service status|install|start|stop|uninstall
|
|
|
188
194
|
machine-mcp status
|
|
189
195
|
machine-mcp doctor
|
|
190
196
|
machine-mcp rotate-secrets
|
|
197
|
+
machine-mcp --print-mcp-credentials
|
|
191
198
|
machine-mcp uninstall [--keep-worker] [--yes]
|
|
192
199
|
```
|
|
193
200
|
|
|
@@ -201,16 +208,16 @@ Remote mode supports:
|
|
|
201
208
|
- Linux `systemd --user`, with best-effort lingering;
|
|
202
209
|
- Windows Scheduled Task at logon.
|
|
203
210
|
|
|
204
|
-
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.
|
|
211
|
+
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. Background services run at log level `warn`: failures and connection problems are retained, while routine successful tool calls are omitted. Logs are owner-only where supported and bounded by tail trimming.
|
|
205
212
|
|
|
206
213
|
## Secret rotation
|
|
207
214
|
|
|
208
215
|
```sh
|
|
209
|
-
machine-mcp rotate-secrets
|
|
210
|
-
machine-mcp
|
|
216
|
+
machine-mcp rotate-secrets
|
|
217
|
+
machine-mcp --print-mcp-credentials
|
|
211
218
|
```
|
|
212
219
|
|
|
213
|
-
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.
|
|
220
|
+
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. Rotated values are redacted by default; only the client connection password can be printed through the explicit reconnect flag. Previously issued access tokens then fail validation.
|
|
214
221
|
|
|
215
222
|
## State and observability
|
|
216
223
|
|
|
@@ -222,7 +229,7 @@ Default state roots:
|
|
|
222
229
|
|
|
223
230
|
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.
|
|
224
231
|
|
|
225
|
-
|
|
232
|
+
Default foreground logs show startup/deployment transitions, relay connectivity, warnings/errors, and successful calls that exceed 30 seconds. Routine successful tool calls and correlation IDs appear only at `--log-level debug` or `--verbose`. Background services use `warn`. Log messages and structured fields are bounded, secret-like keys and known token formats are redacted, and tool arguments/results are not written. See [docs/LOGGING.md](docs/LOGGING.md) and [docs/OPERATIONS.md](docs/OPERATIONS.md).
|
|
226
233
|
|
|
227
234
|
## Development and verification
|
|
228
235
|
|
|
@@ -230,6 +237,7 @@ Operational logs record bounded metadata such as component, tool name, shortened
|
|
|
230
237
|
npm ci
|
|
231
238
|
npm run check
|
|
232
239
|
npm run worker:dry-run
|
|
240
|
+
npm audit --audit-level=high
|
|
233
241
|
npm audit --omit=dev --audit-level=high
|
|
234
242
|
npm pack --dry-run
|
|
235
243
|
```
|
package/SECURITY.md
CHANGED
|
@@ -51,7 +51,9 @@ Direct filesystem scope is profile-dependent. The default `full` profile is unre
|
|
|
51
51
|
|
|
52
52
|
The default `full` profile returns absolute paths. Narrower profiles return workspace-relative paths to reduce username and directory-layout disclosure. Path display and access scope remain separate controls.
|
|
53
53
|
|
|
54
|
-
|
|
54
|
+
The server does not maintain a sensitive-filename blacklist. Under `full`, direct read tools may access any UTF-8 regular file available to the local OS user, including files outside the selected workspace and names such as `.env`, password stores, private keys, credentials, database dumps, and production configuration. Narrower profiles confine direct filesystem tools but do not classify names inside that boundary.
|
|
55
|
+
|
|
56
|
+
Maximum local policy does not bypass Unix permissions, Windows ACLs, macOS TCC/SIP, container/VM boundaries, or security decisions made by the MCP host/platform. A host-side “sensitive file” refusal is independent of Machine Bridge and cannot be disabled by local policy configuration.
|
|
55
57
|
|
|
56
58
|
Processes are not confined by the filesystem-tool resolver. They can access paths, networks, processes, credential stores, and devices available to the local user.
|
|
57
59
|
|
|
@@ -67,7 +69,7 @@ These controls do not defend against a malicious process running under the same
|
|
|
67
69
|
|
|
68
70
|
Local state contains the MCP connection password and daemon secret. State, lock, temporary secret, runtime, and service-log files use owner-only permissions where supported. State writes are atomic. Logs recursively redact known credential fields and token formats and neutralize control characters.
|
|
69
71
|
|
|
70
|
-
First-run or explicit
|
|
72
|
+
First-run or explicit reconnect output can intentionally display the MCP connection password. JSON output and standalone secret rotation redact credentials by default; printing requires the explicit reconnect flag. The daemon secret is never printed in full. Avoid shared terminal logs, shell recordings, screenshots, CI output, or support tickets.
|
|
71
73
|
|
|
72
74
|
The default `full` profile passes the complete parent environment. Narrower profiles replace HOME, temp, and common cache paths and do not pass arbitrary parent variables. The isolated mode reduces accidental environment-secret leakage; it does not prevent code from explicitly accessing known resources.
|
|
73
75
|
|
|
@@ -101,7 +103,7 @@ Sessions use pipes, not a PTY. Do not assume terminal-oriented programs will beh
|
|
|
101
103
|
|
|
102
104
|
## Logs and privacy
|
|
103
105
|
|
|
104
|
-
|
|
106
|
+
Default operational logs record startup/connection transitions, failed calls, slow-call duration, and coarse error classes. Routine successful calls and shortened correlation IDs are debug-only. Tool arguments, command text, stdin, file/patch contents, and outputs are omitted. Messages and fields are bounded; unexpected daemon and Worker exceptions are reduced to error classes. Git author email is omitted from `git_log` unless explicitly requested.
|
|
105
107
|
|
|
106
108
|
No logging policy can prevent data from being returned to a client that explicitly invokes an enabled tool. The Worker necessarily relays remote tool arguments and results; this is not end-to-end encryption against the user's Cloudflare execution environment.
|
|
107
109
|
|
|
@@ -124,7 +126,7 @@ Also:
|
|
|
124
126
|
- patch the OS and use supported Node.js releases;
|
|
125
127
|
- enable MFA on Cloudflare, GitHub, and npm accounts;
|
|
126
128
|
- do not configure broad CORS origins;
|
|
127
|
-
-
|
|
129
|
+
- select `agent`, `edit`, or `review` instead of the default `full` when broad authority is unnecessary;
|
|
128
130
|
- inspect client names and OAuth redirect URIs;
|
|
129
131
|
- rotate secrets after suspected disclosure;
|
|
130
132
|
- inspect `status`, `doctor`, and service status;
|
package/docs/ARCHITECTURE.md
CHANGED
|
@@ -12,15 +12,15 @@ No transport is treated as a sandbox. Both transports invoke the same local runt
|
|
|
12
12
|
|
|
13
13
|
## Components
|
|
14
14
|
|
|
15
|
-
### Shared tool catalog
|
|
15
|
+
### Shared protocol metadata and tool catalog
|
|
16
16
|
|
|
17
|
-
`src/shared/tool-catalog.json` is the single source of truth for tool names, descriptions, input schemas, annotations, and policy availability. The Worker and
|
|
17
|
+
`src/shared/server-metadata.json` is the single source of truth for server identity, MCP protocol versions, and host instructions. `src/shared/tool-catalog.json` is the single source of truth for tool names, descriptions, input schemas, annotations, and policy availability. The Worker and local runtime import both directly. Catalog tests reject metadata drift, duplicate names, unknown availability classes, open schemas, missing annotations, profile drift, and second hand-maintained Worker definitions.
|
|
18
18
|
|
|
19
19
|
### CLI and state layer
|
|
20
20
|
|
|
21
21
|
The CLI canonicalizes workspaces, resolves policy profiles, maintains per-workspace state and credentials, serializes startup/deploy/rotation with locks, deploys the Worker, installs optional platform-native autostart, and starts either remote daemon or stdio mode.
|
|
22
22
|
|
|
23
|
-
A canonical workspace receives an independent profile, Worker name, secret set, daemon/startup locks, and state file. State schema version
|
|
23
|
+
A canonical workspace receives an independent profile, Worker name, secret set, daemon/startup locks, and state file. State schema version 4 records policy origin/revision in addition to the capability fields and retains removal of obsolete local API state.
|
|
24
24
|
|
|
25
25
|
### Local runtime
|
|
26
26
|
|
|
@@ -38,7 +38,7 @@ Remote mode attaches WebSocket connection/reconnect behavior. Stdio mode invokes
|
|
|
38
38
|
|
|
39
39
|
### Stdio MCP server
|
|
40
40
|
|
|
41
|
-
The stdio server implements newline-delimited JSON-RPC over stdin/stdout. It negotiates supported MCP versions, advertises policy-filtered tools, returns text plus structured content, supports native image content, maps cancellation notifications to runtime call IDs, and sends logs only to stderr.
|
|
41
|
+
The stdio server implements newline-delimited JSON-RPC over stdin/stdout. It negotiates supported MCP versions, advertises policy-filtered tools, returns text plus structured content, supports native image content, maps cancellation notifications to runtime call IDs, and sends level-filtered logs only to stderr.
|
|
42
42
|
|
|
43
43
|
### Cloudflare Worker and Durable Object
|
|
44
44
|
|
|
@@ -55,7 +55,7 @@ The daemon attachment deliberately omits workspace path/name/hash and process ID
|
|
|
55
55
|
|
|
56
56
|
### Autostart layer
|
|
57
57
|
|
|
58
|
-
The service layer emits launchd, systemd-user, or Windows Scheduled Task definitions. Credentials are not embedded in service definitions; the daemon loads owner-only state. The exact policy is stored in owner-only state; platform service definitions contain only the workspace and
|
|
58
|
+
The service layer emits launchd, systemd-user, or Windows Scheduled Task definitions. Credentials are not embedded in service definitions; the daemon loads owner-only state. The exact policy is stored in owner-only state; platform service definitions contain only the workspace/state-root selectors and a `warn` log-level setting.
|
|
59
59
|
|
|
60
60
|
## Trust boundaries
|
|
61
61
|
|
|
@@ -102,7 +102,7 @@ Duplicate in-flight JSON-RPC IDs for the same access token are rejected so cance
|
|
|
102
102
|
|
|
103
103
|
## Filesystem resolution and privacy
|
|
104
104
|
|
|
105
|
-
The workspace is canonicalized
|
|
105
|
+
The workspace is canonicalized and compared with targets through consistent platform-native/async `realpath` representations. Existing targets must remain inside the workspace unless the active policy is unrestricted. New targets walk to the nearest existing ancestor, validate its canonical path, and reconstruct the destination below that canonical ancestor.
|
|
106
106
|
|
|
107
107
|
Path behavior is profile-dependent. The default `full` profile permits unrestricted direct filesystem paths and returns absolute paths. The `agent`, `edit`, and `review` profiles enforce canonical workspace containment and return workspace-relative paths. Error strings redact canonical and common platform-alias forms of workspace, runtime, and home paths whenever absolute path display is disabled.
|
|
108
108
|
|
|
@@ -146,7 +146,7 @@ Pending calls retain their originating socket reference. A stale socket cannot c
|
|
|
146
146
|
|
|
147
147
|
## Persistence
|
|
148
148
|
|
|
149
|
-
Local state and global config are owner-only, versioned, and written through temporary files, flushes, and atomic rename. Malformed state becomes a bounded `.corrupt-*` backup. Custom roots are adopted only when empty or recognizable as legacy Machine Bridge state.
|
|
149
|
+
Local state and global config are owner-only, versioned, size-bounded, and written through temporary files, flushes, and atomic rename. Reads reject symbolic links and use no-follow descriptors where supported. Malformed or oversized state becomes a bounded-count `.corrupt-*` backup. Custom roots are adopted only when empty or recognizable as legacy Machine Bridge state.
|
|
150
150
|
|
|
151
151
|
Removal validates the state marker, canonical target, known contents, active locks, filesystem root/home/current/package/workspace/source exclusions, and Worker deletion outcome before recursive deletion.
|
|
152
152
|
|
|
@@ -154,15 +154,17 @@ OAuth metadata is pruned on access. Expired codes/tokens, old throttling records
|
|
|
154
154
|
|
|
155
155
|
## Observability
|
|
156
156
|
|
|
157
|
-
Public health exposes only server identity and version. Authenticated `server_info` exposes bounded runtime status
|
|
157
|
+
Public health exposes only server identity and version. Authenticated `server_info` exposes bounded runtime status and policy origin/revision.
|
|
158
158
|
|
|
159
|
-
|
|
159
|
+
Foreground logging defaults to `info`; autostart uses `warn`. Routine successful calls and shortened random correlation IDs are debug-only. `info` retains deployment/connection transitions and successful calls slower than 30 seconds. Failures log tool name, duration, and coarse error class without arguments or outputs. Unexpected local and Worker errors are reduced to classes in normal logs. Messages, strings, arrays, object depth/key counts, and serialized fields are bounded.
|
|
160
|
+
|
|
161
|
+
Cloudflare sampling is size control rather than an audit log. The project intentionally does not claim complete forensic logging. See [LOGGING.md](LOGGING.md).
|
|
160
162
|
|
|
161
163
|
## Explicit non-goals
|
|
162
164
|
|
|
163
165
|
- operating-system sandboxing of arbitrary executables;
|
|
164
166
|
- preventing an authorized client from requesting data available to enabled tools;
|
|
165
|
-
- automatically deciding which
|
|
167
|
+
- automatically deciding which local files are sensitive or overriding MCP-host/platform safety policy;
|
|
166
168
|
- surviving daemon restart with process sessions;
|
|
167
169
|
- PTY/terminal emulation;
|
|
168
170
|
- model-level prompt-injection prevention;
|
package/docs/CLIENTS.md
CHANGED
|
@@ -123,3 +123,9 @@ Enter the printed `/mcp` URL in the remote MCP connector. During OAuth authoriza
|
|
|
123
123
|
- `review` is read-only and workspace-confined.
|
|
124
124
|
|
|
125
125
|
A client configuration is an authorization decision. Anyone who controls an authorized host can invoke every tool exposed by the selected profile.
|
|
126
|
+
|
|
127
|
+
## Host-side safety rules
|
|
128
|
+
|
|
129
|
+
The local `full` profile controls Machine Bridge's own tool catalog, path resolver, path display, process environment, and shell availability. It does not control the MCP host's model policy, approval UI, connector gateway, or platform execution filters.
|
|
130
|
+
|
|
131
|
+
Machine Bridge itself does not block files because their names look sensitive. If `server_info` reports `full` and a direct `read_file` request is still rejected as a “sensitive file” by the execution layer, that refusal comes from the host/platform rather than this server. Changing `--profile`, `--unrestricted-paths`, or `--absolute-paths` cannot override it. Use a trusted local client or an operator-controlled local command only where doing so is consistent with the host's terms and the user's security intent.
|
package/docs/LOGGING.md
ADDED
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
# Logging and observability
|
|
2
|
+
|
|
3
|
+
## Goals
|
|
4
|
+
|
|
5
|
+
Operational logs should answer four questions without becoming a transcript of user activity:
|
|
6
|
+
|
|
7
|
+
1. Did deployment and relay connection succeed?
|
|
8
|
+
2. Is the daemon reconnecting, superseded, or unhealthy?
|
|
9
|
+
3. Did a tool call fail, time out, or become unusually slow?
|
|
10
|
+
4. Which component and coarse error class should be investigated?
|
|
11
|
+
|
|
12
|
+
Logs are not a command history, content audit trail, or substitute for MCP client approvals.
|
|
13
|
+
|
|
14
|
+
## Levels
|
|
15
|
+
|
|
16
|
+
The CLI accepts:
|
|
17
|
+
|
|
18
|
+
```text
|
|
19
|
+
--log-level error|warn|info|debug
|
|
20
|
+
--quiet # alias for error
|
|
21
|
+
--verbose # alias for debug
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
The default foreground level is `info`. Platform autostart services use `warn`.
|
|
25
|
+
|
|
26
|
+
| Level | Intended events |
|
|
27
|
+
|---|---|
|
|
28
|
+
| `error` | Broken request handlers, relay transport errors, unrecoverable local failures |
|
|
29
|
+
| `warn` | Failed tool calls, disconnections, malformed/oversized relay messages, superseded daemons |
|
|
30
|
+
| `info` | Deployment/startup transitions, successful relay connection, successful calls slower than 30 seconds |
|
|
31
|
+
| `debug` | Routine successful calls, shortened correlation IDs, reconnect timing, cancellation correlation |
|
|
32
|
+
|
|
33
|
+
Routine successful calls are deliberately absent from `info`. A normal sequence of hundreds of tool invocations should not fill the user's terminal or service logs.
|
|
34
|
+
|
|
35
|
+
## Event fields
|
|
36
|
+
|
|
37
|
+
Default warning/error and slow-call events may include:
|
|
38
|
+
|
|
39
|
+
- component;
|
|
40
|
+
- tool name;
|
|
41
|
+
- duration in milliseconds;
|
|
42
|
+
- coarse error class;
|
|
43
|
+
- relay close code;
|
|
44
|
+
- bounded reconnect delay.
|
|
45
|
+
|
|
46
|
+
Shortened random call identifiers are debug-only. They are useful only for correlating adjacent local events and are not stable audit identifiers.
|
|
47
|
+
|
|
48
|
+
The implementation intentionally omits:
|
|
49
|
+
|
|
50
|
+
- tool arguments;
|
|
51
|
+
- command text or argv;
|
|
52
|
+
- stdin, stdout, and stderr;
|
|
53
|
+
- file, patch, or image content;
|
|
54
|
+
- OAuth request bodies;
|
|
55
|
+
- connection passwords, daemon secrets, authorization codes, and access tokens.
|
|
56
|
+
|
|
57
|
+
Unexpected daemon and Worker failures are reduced to coarse error classes in normal logs. Client-facing tool errors may contain more detail according to the active path-display policy, but those details are not copied into normal operational logs.
|
|
58
|
+
|
|
59
|
+
## Bounding and redaction
|
|
60
|
+
|
|
61
|
+
Messages, strings, object depth, object key counts, array item counts, and serialized field payloads are bounded. Control characters are neutralized. Fields with secret-like names and known token formats are recursively redacted.
|
|
62
|
+
|
|
63
|
+
This is defense in depth, not content classification. A previously unknown secret format embedded in an ordinary non-secret-named field may evade pattern redaction. For that reason, tool arguments and outputs are omitted rather than merely filtered.
|
|
64
|
+
|
|
65
|
+
## Files
|
|
66
|
+
|
|
67
|
+
Autostart logs are stored below the state root:
|
|
68
|
+
|
|
69
|
+
```text
|
|
70
|
+
logs/daemon.out.log
|
|
71
|
+
logs/daemon.err.log
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
They are owner-only where the platform supports Unix-style permissions. Existing files are tail-trimmed on UTF-8/line boundaries before daemon startup. Because background services use `warn`, normal successful tool traffic should not cause sustained log growth.
|
|
75
|
+
|
|
76
|
+
## MCP host boundary
|
|
77
|
+
|
|
78
|
+
Machine Bridge does not classify filenames as sensitive and does not block `.env`, password, key, or credential-looking names. The active local policy and operating-system permissions determine what the server itself can read.
|
|
79
|
+
|
|
80
|
+
An MCP host, model provider, desktop application, or platform execution layer may independently deny a request involving credentials or sensitive files. Such a denial occurs before or outside Machine Bridge's file resolver and cannot be disabled by selecting the local `full` profile. Use `server_info`, `machine-mcp status`, and `machine-mcp doctor` to distinguish the active local policy from host-side enforcement.
|
package/docs/OPERATIONS.md
CHANGED
|
@@ -14,24 +14,20 @@ machine-mcp service status
|
|
|
14
14
|
|
|
15
15
|
Remote autostart logs are stored under the state root in `logs/daemon.out.log` and `logs/daemon.err.log`. Files are owner-only where supported and tail-trimmed before daemon startup.
|
|
16
16
|
|
|
17
|
-
|
|
17
|
+
Logging is level-based:
|
|
18
18
|
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
19
|
+
```text
|
|
20
|
+
error unrecoverable local/transport failures
|
|
21
|
+
warn failed calls, disconnects, malformed relay events
|
|
22
|
+
info startup/deploy/connect transitions and calls slower than 30 seconds
|
|
23
|
+
debug routine successful calls, shortened correlation IDs, cancellation/reconnect details
|
|
24
|
+
```
|
|
25
25
|
|
|
26
|
-
|
|
26
|
+
Foreground mode defaults to `info`; autostart uses `warn`. Use `--verbose` or `--log-level debug` only for diagnosis. `--quiet` is an alias for `--log-level error`.
|
|
27
27
|
|
|
28
|
-
|
|
29
|
-
- write, edit, or patch payloads;
|
|
30
|
-
- command argv, shell text, stdin, stdout, and stderr;
|
|
31
|
-
- MCP connection passwords, daemon secrets, authorization codes, and access tokens;
|
|
32
|
-
- full request bodies.
|
|
28
|
+
Normal logs intentionally omit tool arguments, file/patch/image content, command text and argv, stdin/stdout/stderr, OAuth request bodies, connection credentials, authorization codes, and tokens. Unexpected daemon and Worker failures use coarse error classes rather than raw exception messages. Messages and structured fields are bounded and secret-like fields/token formats are redacted.
|
|
33
29
|
|
|
34
|
-
|
|
30
|
+
See [LOGGING.md](LOGGING.md) for the event contract and MCP-host boundary. Cloudflare observability is sampled and is not a complete audit log.
|
|
35
31
|
|
|
36
32
|
## Reconnect and replacement
|
|
37
33
|
|
|
@@ -62,22 +58,32 @@ Defense-in-depth limits include:
|
|
|
62
58
|
|
|
63
59
|
## Upgrade behavior
|
|
64
60
|
|
|
65
|
-
Version 0.
|
|
61
|
+
Version 0.5 records policy origin and revision. A state entry matching the exact legacy implicit-default shape—write enabled, shell enabled, workspace-confined paths, isolated environment, and relative output—is migrated once to the current `full` default. Explicit named profiles and identified custom policies are preserved.
|
|
62
|
+
|
|
63
|
+
`full` enables writes, direct processes, process sessions, shell execution, unrestricted direct filesystem paths, absolute path output, and the complete parent environment. It does not override operating-system access controls or independent MCP-host/platform policy.
|
|
64
|
+
|
|
65
|
+
Inspect effective policy with:
|
|
66
66
|
|
|
67
67
|
```sh
|
|
68
|
-
machine-mcp
|
|
68
|
+
machine-mcp status
|
|
69
|
+
machine-mcp doctor
|
|
69
70
|
```
|
|
70
71
|
|
|
71
|
-
|
|
72
|
+
Select a policy explicitly with:
|
|
73
|
+
|
|
74
|
+
```sh
|
|
75
|
+
machine-mcp --workspace /path/to/project --profile full
|
|
76
|
+
machine-mcp --workspace /path/to/project --profile agent
|
|
77
|
+
```
|
|
72
78
|
|
|
73
|
-
A remote policy change is saved locally, propagated in the daemon handshake, and
|
|
79
|
+
A remote policy change is saved locally, propagated in the daemon handshake, and loaded by autostart from owner-only state.
|
|
74
80
|
|
|
75
81
|
## Incident response
|
|
76
82
|
|
|
77
83
|
After suspected credential or client compromise:
|
|
78
84
|
|
|
79
85
|
1. stop foreground and autostart daemons;
|
|
80
|
-
2. run `machine-mcp rotate-secrets
|
|
86
|
+
2. run `machine-mcp rotate-secrets`;
|
|
81
87
|
3. restart without broad flags and redeploy;
|
|
82
88
|
4. inspect Cloudflare account access, Worker configuration, local state permissions, and service logs;
|
|
83
89
|
5. remove the Worker and local state if continued remote access is unnecessary.
|
package/docs/TESTING.md
CHANGED
|
@@ -24,8 +24,9 @@ The suite includes:
|
|
|
24
24
|
- isolated command HOME/temp/cache behavior;
|
|
25
25
|
- one-shot timeout, descendant termination, cancellation, and process-session interaction;
|
|
26
26
|
- daemon/startup locking and state corruption recovery;
|
|
27
|
-
- guarded state-root removal and legacy-
|
|
28
|
-
-
|
|
27
|
+
- guarded state-root removal, schema migration, policy-origin persistence, and legacy implicit-default migration;
|
|
28
|
+
- no filename-based sensitive-file denial under unrestricted policy;
|
|
29
|
+
- log redaction, control-character handling, message/field bounds, default success-log suppression, and service warning-level configuration;
|
|
29
30
|
- CLI parsing, policy profiles, and client configuration boundaries;
|
|
30
31
|
- live stdio MCP initialization, discovery, calls, rich content, sessions, cancellation, and continued responsiveness;
|
|
31
32
|
- live local Worker OAuth registration, consent, PKCE, token replay rejection, throttling, CORS, protocol negotiation, dynamic tool advertisement, rich content, daemon replacement, and cancellation.
|
|
@@ -34,12 +35,13 @@ The suite includes:
|
|
|
34
35
|
|
|
35
36
|
```sh
|
|
36
37
|
npm run worker:dry-run
|
|
38
|
+
npm audit --audit-level=high
|
|
37
39
|
npm audit --omit=dev --audit-level=high
|
|
38
40
|
npm pack --dry-run
|
|
39
41
|
npm run version:check
|
|
40
42
|
```
|
|
41
43
|
|
|
42
|
-
GitHub Actions executes the main suite on Linux, macOS, and Windows. Node 22 and 24 are covered on Linux; Node 22 is covered on macOS and Windows. A separate package-audit job
|
|
44
|
+
GitHub Actions executes the main suite on Linux, macOS, and Windows. Node 22 and 24 are covered on Linux; Node 22 is covered on macOS and Windows. A separate package-audit job audits both the complete dependency graph and the production-only graph, then performs a dry-run package build. Dependency and GitHub Actions updates are monitored by Dependabot.
|
|
43
45
|
|
|
44
46
|
## Test design rules
|
|
45
47
|
|
|
@@ -48,4 +50,5 @@ GitHub Actions executes the main suite on Linux, macOS, and Windows. Node 22 and
|
|
|
48
50
|
- Every bounded resource needs an over-limit test.
|
|
49
51
|
- Every multi-stage mutation needs a no-partial-commit test.
|
|
50
52
|
- Every remote call correlation change needs daemon replacement and cancellation coverage.
|
|
51
|
-
- Logs and public metadata should be tested for absence of sensitive fields, not only presence of expected fields.
|
|
53
|
+
- Logs and public metadata should be tested for absence of sensitive fields, arguments, outputs, and routine success noise—not only presence of expected fields.
|
|
54
|
+
- Cross-platform tests must avoid shell syntax, URL-path conversion, and executable-shim assumptions specific to one operating system.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "machine-bridge-mcp",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.5.0",
|
|
4
4
|
"description": "Cross-client MCP bridge for policy-controlled local files, Git, images, patches, and processes over stdio or OAuth-protected remote relay.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "MIT",
|
|
@@ -50,12 +50,12 @@
|
|
|
50
50
|
"catalog:test": "node tests/catalog-test.mjs"
|
|
51
51
|
},
|
|
52
52
|
"dependencies": {
|
|
53
|
-
"wrangler": "
|
|
54
|
-
"ws": "
|
|
53
|
+
"wrangler": "4.110.0",
|
|
54
|
+
"ws": "8.21.0"
|
|
55
55
|
},
|
|
56
56
|
"devDependencies": {
|
|
57
57
|
"@types/node": "^22.20.1",
|
|
58
|
-
"typescript": "^
|
|
58
|
+
"typescript": "^7.0.2"
|
|
59
59
|
},
|
|
60
60
|
"keywords": [
|
|
61
61
|
"mcp",
|