recovery-probe 1.0.0 → 1.0.2
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 +14 -0
- package/dist/core/server.d.mts +3 -1
- package/dist/core/server.mjs +8 -0
- package/dist/targets/cdp-bridge/bridge.mjs +10 -1
- package/dist/targets/cdp-bridge/websocket.d.mts +6 -0
- package/dist/targets/cdp-bridge/websocket.mjs +29 -10
- package/dist/tools/mcp/server.mjs +12 -2
- package/dist/transports/net/control.mjs +7 -1
- package/dist/transports/net/rules.mjs +2 -1
- package/docs/android.md +1 -0
- package/docs/ipc.md +1 -1
- package/docs/mcp-demo.md +31 -0
- package/docs/mcp.md +9 -5
- package/docs/net.md +3 -2
- package/docs/observe.md +2 -0
- package/examples/mcp-demo.mjs +117 -0
- package/package.json +7 -4
- package/server.json +33 -0
package/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,20 @@ All notable changes to Recovery Probe are documented here. The project follows [
|
|
|
4
4
|
|
|
5
5
|
Version 0.2.0 is the first npm release. Earlier 0.1.x revisions were repository-only prototypes.
|
|
6
6
|
|
|
7
|
+
## 1.0.2 (2026-10-28)
|
|
8
|
+
|
|
9
|
+
- Add MCP Registry ownership and launch metadata, with stable-tag publication using GitHub OIDC after verifying the npm package.
|
|
10
|
+
- Document unattended MCP startup, project working directories and optional dependencies.
|
|
11
|
+
- Add a reproducible stdio MCP demonstration of a broken retry, the corrected controller and before/after report comparison.
|
|
12
|
+
|
|
13
|
+
## 1.0.1 (2026-10-28)
|
|
14
|
+
|
|
15
|
+
- Reject browser-origin WebSocket connections and untrusted Host headers on the Android CDP bridge before opening an upstream connection. Validate the network proxy control API's Host header to block DNS rebinding.
|
|
16
|
+
- Bound complete inbound CDP WebSocket messages, including continuation frames, and close oversized messages with code 1009.
|
|
17
|
+
- Suppress MCP tool responses after cancellation and emit `structuredContent` only for object results.
|
|
18
|
+
- Match network host names with or without a final DNS dot. Document wildcard apex behavior, unrestricted local CONNECT tunneling, and the `webContents.send` scope of IPC push counting.
|
|
19
|
+
|
|
20
|
+
|
|
7
21
|
## 1.0.0 (2026-10-27)
|
|
8
22
|
|
|
9
23
|
The first release with an explicit 1.x compatibility commitment. It removes the old command spellings and brings in everything since 0.6.0: the 0.7.0 and 0.8.0 previews below. The README defines the supported interfaces and experimental exceptions, and explains that failed checks can save unredacted screen-text quotes of up to 200 characters.
|
package/dist/core/server.d.mts
CHANGED
|
@@ -1,4 +1,6 @@
|
|
|
1
|
-
import type { Server } from 'node:http';
|
|
1
|
+
import type { IncomingMessage, Server } from 'node:http';
|
|
2
|
+
/** Reject DNS aliases and ambiguous authorities before exposing local controls. */
|
|
3
|
+
export declare function hasLoopbackHost(request: IncomingMessage): boolean;
|
|
2
4
|
/** Listens on 127.0.0.1 and returns the port; port 0 picks a free one. */
|
|
3
5
|
export declare function listenOnLoopback(server: Server, port: number): Promise<number>;
|
|
4
6
|
/** Closes the server and the connections it still holds. */
|
package/dist/core/server.mjs
CHANGED
|
@@ -1,3 +1,11 @@
|
|
|
1
|
+
/** Reject DNS aliases and ambiguous authorities before exposing local controls. */
|
|
2
|
+
export function hasLoopbackHost(request) {
|
|
3
|
+
const hosts = request.headersDistinct.host;
|
|
4
|
+
if (hosts?.length !== 1 || !request.socket.localPort)
|
|
5
|
+
return false;
|
|
6
|
+
const port = request.socket.localPort;
|
|
7
|
+
return hosts[0] === `127.0.0.1:${port}` || hosts[0] === `localhost:${port}`;
|
|
8
|
+
}
|
|
1
9
|
/** Listens on 127.0.0.1 and returns the port; port 0 picks a free one. */
|
|
2
10
|
export async function listenOnLoopback(server, port) {
|
|
3
11
|
await new Promise((resolve, reject) => {
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { createServer, } from 'node:http';
|
|
2
|
-
import { closeServer, listenOnLoopback } from '../../core/server.mjs';
|
|
2
|
+
import { closeServer, hasLoopbackHost, listenOnLoopback, } from '../../core/server.mjs';
|
|
3
3
|
import { BRIDGE_ID_BASE, TargetFilter } from './filter.mjs';
|
|
4
4
|
import { acceptWebSocket } from './websocket.mjs';
|
|
5
5
|
/** A page with nothing loaded, as Android keeps for a WebView that has no window yet. */
|
|
@@ -30,6 +30,10 @@ export async function startCdpBridge({ upstream, hide = isBlankPage, port = 0, }
|
|
|
30
30
|
};
|
|
31
31
|
}
|
|
32
32
|
async function answer(context, request, response) {
|
|
33
|
+
if (!hasLoopbackHost(request)) {
|
|
34
|
+
response.writeHead(403).end('Forbidden');
|
|
35
|
+
return;
|
|
36
|
+
}
|
|
33
37
|
try {
|
|
34
38
|
// Clients ask for both /json/version and /json/version/.
|
|
35
39
|
const path = new URL(request.url ?? '/', 'http://bridge').pathname.replace(/\/$/, '');
|
|
@@ -64,6 +68,11 @@ async function visibleTargets(context) {
|
|
|
64
68
|
}
|
|
65
69
|
/** Connects one client to the device's browser endpoint, through a target filter. */
|
|
66
70
|
function bridgeClient(context, peers, request, socket) {
|
|
71
|
+
// Native CDP clients send no Origin. Even an empty or null browser origin is denied.
|
|
72
|
+
if (!hasLoopbackHost(request) || request.headers.origin !== undefined) {
|
|
73
|
+
socket.end('HTTP/1.1 403 Forbidden\r\nConnection: close\r\n\r\n');
|
|
74
|
+
return;
|
|
75
|
+
}
|
|
67
76
|
if (new URL(request.url ?? '/', 'http://bridge').pathname !==
|
|
68
77
|
'/devtools/browser') {
|
|
69
78
|
socket.end('HTTP/1.1 404 Not Found\r\n\r\n');
|
|
@@ -6,3 +6,9 @@ export interface WebSocketPeer {
|
|
|
6
6
|
}
|
|
7
7
|
/** Accepts a WebSocket upgrade (RFC 6455) and delivers its text messages. */
|
|
8
8
|
export declare function acceptWebSocket(request: IncomingMessage, socket: Duplex, onMessage: (text: string) => void, onClose: () => void): WebSocketPeer;
|
|
9
|
+
export declare class ServerWebSocket implements WebSocketPeer {
|
|
10
|
+
#private;
|
|
11
|
+
constructor(socket: Duplex, onMessage: (text: string) => void, onClose: () => void, maxMessage?: number);
|
|
12
|
+
readonly send: (text: string) => void;
|
|
13
|
+
readonly close: (code?: number) => void;
|
|
14
|
+
}
|
|
@@ -27,13 +27,15 @@ function payloadLength(buffered) {
|
|
|
27
27
|
return { length, offset: 2 };
|
|
28
28
|
}
|
|
29
29
|
/** The first whole frame and its size in bytes, or undefined until it has all arrived. */
|
|
30
|
-
function readFrame(buffered) {
|
|
30
|
+
function readFrame(buffered, remaining) {
|
|
31
31
|
if (buffered.length < 2)
|
|
32
32
|
return undefined;
|
|
33
33
|
const header = payloadLength(buffered);
|
|
34
34
|
if (!header)
|
|
35
35
|
return undefined;
|
|
36
|
-
|
|
36
|
+
const opcode = buffered[0] & 0x0f;
|
|
37
|
+
const limit = opcode < 0x8 ? remaining : 125;
|
|
38
|
+
if (header.length > limit)
|
|
37
39
|
return 'too-large';
|
|
38
40
|
const masked = (buffered[1] & 0x80) !== 0;
|
|
39
41
|
const start = header.offset + (masked ? 4 : 0);
|
|
@@ -57,22 +59,26 @@ export function acceptWebSocket(request, socket, onMessage, onClose) {
|
|
|
57
59
|
`Sec-WebSocket-Accept: ${accept}\r\n\r\n`);
|
|
58
60
|
return new ServerWebSocket(socket, onMessage, onClose);
|
|
59
61
|
}
|
|
60
|
-
class ServerWebSocket {
|
|
62
|
+
export class ServerWebSocket {
|
|
61
63
|
#socket;
|
|
62
64
|
#onMessage;
|
|
63
65
|
#onClose;
|
|
66
|
+
#maxMessage;
|
|
64
67
|
#closed = false;
|
|
65
68
|
#buffered = Buffer.alloc(0);
|
|
66
69
|
#message = [];
|
|
67
|
-
|
|
70
|
+
#messageBytes = 0;
|
|
71
|
+
constructor(socket, onMessage, onClose, maxMessage = MAX_MESSAGE) {
|
|
68
72
|
this.#socket = socket;
|
|
69
73
|
this.#onMessage = onMessage;
|
|
70
74
|
this.#onClose = onClose;
|
|
75
|
+
this.#maxMessage = maxMessage;
|
|
71
76
|
socket.on('data', (chunk) => this.#receive(chunk));
|
|
72
77
|
socket.on('close', () => {
|
|
73
78
|
if (this.#closed)
|
|
74
79
|
return;
|
|
75
80
|
this.#closed = true;
|
|
81
|
+
this.#clear();
|
|
76
82
|
this.#onClose();
|
|
77
83
|
});
|
|
78
84
|
socket.on('error', () => socket.destroy());
|
|
@@ -81,11 +87,14 @@ class ServerWebSocket {
|
|
|
81
87
|
if (!this.#closed)
|
|
82
88
|
this.#frame(0x1, Buffer.from(text));
|
|
83
89
|
};
|
|
84
|
-
close = () => {
|
|
90
|
+
close = (code = 1000) => {
|
|
85
91
|
if (this.#closed)
|
|
86
92
|
return;
|
|
87
93
|
this.#closed = true;
|
|
88
|
-
|
|
94
|
+
const payload = Buffer.alloc(2);
|
|
95
|
+
payload.writeUInt16BE(code);
|
|
96
|
+
this.#frame(0x8, payload);
|
|
97
|
+
this.#clear();
|
|
89
98
|
this.#socket.end();
|
|
90
99
|
this.#onClose();
|
|
91
100
|
};
|
|
@@ -93,27 +102,37 @@ class ServerWebSocket {
|
|
|
93
102
|
this.#socket.write(Buffer.concat([frameHeader(opcode, payload.length), payload]));
|
|
94
103
|
}
|
|
95
104
|
#receive(chunk) {
|
|
105
|
+
if (this.#closed)
|
|
106
|
+
return;
|
|
96
107
|
this.#buffered = Buffer.concat([this.#buffered, chunk]);
|
|
97
|
-
|
|
98
|
-
const read = readFrame(this.#buffered);
|
|
108
|
+
while (!this.#closed) {
|
|
109
|
+
const read = readFrame(this.#buffered, this.#maxMessage - this.#messageBytes);
|
|
99
110
|
if (read === undefined)
|
|
100
111
|
return;
|
|
101
112
|
if (read === 'too-large')
|
|
102
|
-
return this.close();
|
|
113
|
+
return this.close(1009);
|
|
103
114
|
this.#buffered = this.#buffered.subarray(read.size);
|
|
104
115
|
if (read.frame.opcode === 0x8)
|
|
105
116
|
return this.close();
|
|
106
117
|
this.#handle(read.frame);
|
|
107
118
|
}
|
|
108
119
|
}
|
|
120
|
+
#clear() {
|
|
121
|
+
this.#buffered = Buffer.alloc(0);
|
|
122
|
+
this.#message = [];
|
|
123
|
+
this.#messageBytes = 0;
|
|
124
|
+
}
|
|
109
125
|
#handle({ fin, opcode, payload }) {
|
|
110
126
|
if (opcode === 0x9)
|
|
111
127
|
this.#frame(0xa, payload);
|
|
112
128
|
else if (opcode === 0x1 || opcode === 0x2 || opcode === 0x0) {
|
|
113
|
-
|
|
129
|
+
if (payload.length)
|
|
130
|
+
this.#message.push(payload);
|
|
131
|
+
this.#messageBytes += payload.length;
|
|
114
132
|
if (fin) {
|
|
115
133
|
const text = Buffer.concat(this.#message).toString('utf8');
|
|
116
134
|
this.#message = [];
|
|
135
|
+
this.#messageBytes = 0;
|
|
117
136
|
this.#onMessage(text);
|
|
118
137
|
}
|
|
119
138
|
}
|
|
@@ -121,13 +121,23 @@ class McpServer {
|
|
|
121
121
|
this.#running.set(id, controller);
|
|
122
122
|
try {
|
|
123
123
|
const result = await tool.run((params.arguments ?? {}), { signal: controller.signal });
|
|
124
|
+
if (controller.signal.aborted)
|
|
125
|
+
return undefined;
|
|
124
126
|
return reply(id, {
|
|
125
|
-
content: [
|
|
126
|
-
|
|
127
|
+
content: [
|
|
128
|
+
{ type: 'text', text: JSON.stringify(result, null, 2) ?? 'null' },
|
|
129
|
+
],
|
|
130
|
+
...(result !== null &&
|
|
131
|
+
typeof result === 'object' &&
|
|
132
|
+
!Array.isArray(result)
|
|
133
|
+
? { structuredContent: result }
|
|
134
|
+
: {}),
|
|
127
135
|
isError: false,
|
|
128
136
|
});
|
|
129
137
|
}
|
|
130
138
|
catch (error) {
|
|
139
|
+
if (controller.signal.aborted)
|
|
140
|
+
return undefined;
|
|
131
141
|
// A tool failure is a result the model can read and act on, not a protocol error.
|
|
132
142
|
return reply(id, {
|
|
133
143
|
content: [{ type: 'text', text: error.message }],
|
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { hasLoopbackHost } from '../../core/server.mjs';
|
|
1
2
|
import { CONTROL_HEADER, CONTROL_PATH } from './client.mjs';
|
|
2
3
|
const MAX_CONTROL_BODY = 64 * 1024;
|
|
3
4
|
const failure = (message, status) => Object.assign(new Error(message), { status });
|
|
@@ -23,7 +24,12 @@ export function controlListener(handle) {
|
|
|
23
24
|
response.writeHead(501).end('Recovery Probe tunnels HTTPS (CONNECT) only');
|
|
24
25
|
return;
|
|
25
26
|
}
|
|
26
|
-
// A
|
|
27
|
+
// A same-origin page after DNS rebinding can send the control header too.
|
|
28
|
+
if (!hasLoopbackHost(request)) {
|
|
29
|
+
reply(403, { error: 'Use the proxy loopback host and port' });
|
|
30
|
+
return;
|
|
31
|
+
}
|
|
32
|
+
// Other web pages cannot send this header without a preflight, never answered here.
|
|
27
33
|
if (request.headers[CONTROL_HEADER] !== 'network') {
|
|
28
34
|
reply(403, { error: `Send the ${CONTROL_HEADER}: network header` });
|
|
29
35
|
return;
|
|
@@ -3,7 +3,8 @@ import { ensure, isNonEmptyString } from '../../core/validate.mjs';
|
|
|
3
3
|
const FAULTS = new Set(['refuse', 'reset', 'stall', 'delay']);
|
|
4
4
|
const isWholeNumber = (value) => Number.isInteger(value) && value >= 0;
|
|
5
5
|
export function hostMatches(pattern, host) {
|
|
6
|
-
const name = host.toLowerCase();
|
|
6
|
+
const name = host.toLowerCase().replace(/\.$/, '');
|
|
7
|
+
pattern = pattern.toLowerCase().replace(/\.$/, '');
|
|
7
8
|
if (pattern === '*')
|
|
8
9
|
return true;
|
|
9
10
|
if (pattern.startsWith('*.'))
|
package/docs/android.md
CHANGED
|
@@ -34,6 +34,7 @@ npx recovery-probe android --package com.example.app --keep-awake
|
|
|
34
34
|
- **Page reads:** fetch and XHR made by the WebView can be observed and faulted, as in a desktop page.
|
|
35
35
|
- **Native reads are outside the page.** That covers requests made in Java or Kotlin code or an SDK, and calls through JavaScript bridges (`addJavascriptInterface`). Android apps do not read `HTTPS_PROXY`, so `recovery-probe net` does not reach them either.
|
|
36
36
|
- **Blank WebViews are hidden.** Apps often keep WebViews with nothing loaded and no window yet, for example to warm one up. Android pauses those, and they never answer DevTools, so a client that attaches to every page waits forever. The URL serves the app's DevTools through a small bridge that leaves out pages that were blank when it first saw them, and lets them run if they were waiting for a debugger. Everything else passes through unchanged.
|
|
37
|
+
- **The bridge accepts native CDP clients only.** WebSocket requests carrying any `Origin` header are rejected. Discovery and WebSocket requests must use `127.0.0.1:<port>` or `localhost:<port>` for the bridge's actual port; DNS aliases are rejected. Inbound WebSocket messages, including fragmented messages, are limited to 256 MiB.
|
|
37
38
|
- **Leftover forwards:** a forward is removed when the command stops. If the process is killed instead, remove it with `adb forward --remove tcp:PORT`.
|
|
38
39
|
|
|
39
40
|
## Keep the app drawing
|
package/docs/ipc.md
CHANGED
|
@@ -42,7 +42,7 @@ Replace channel names with the exact existing read channels. Include the second
|
|
|
42
42
|
|
|
43
43
|
Set `RECOVERY_PROBE_IPC=1` and `RECOVERY_PROBE_IPC_MODULE` to the absolute `.cjs` path from step 1 when starting the development app. No company application's production dependency needs changing. Do not expose controls through preload or contextBridge.
|
|
44
44
|
|
|
45
|
-
For fault-free observation the hook also accepts optional `classify`, `pushChannels` and `classifyPush` options, which count calls per method label on shared channels and main-to-renderer pushes without storing arguments or payloads. See [Actions, tracked rows and delayed UI updates](observe.md#actions-tracked-rows-and-delayed-ui-updates).
|
|
45
|
+
For fault-free observation the hook also accepts optional `classify`, `pushChannels` and `classifyPush` options, which count calls per method label on shared channels and main-to-renderer pushes through `webContents.send` without storing arguments or payloads. Pushes through `mainFrame.send` or `postMessage` are not counted. See [Actions, tracked rows and delayed UI updates](observe.md#actions-tracked-rows-and-delayed-ui-updates).
|
|
46
46
|
|
|
47
47
|
Registration is captured using the public `ipcMain.handle` API. Install before registration, once per process. Unaffected calls keep their original arguments, receiver and return value/Promise. The adapter observes completion without recording arguments, results or full errors. Calling `dispose()` disarms and restores the registration function; existing dispatchers become transparent. Restart the development app to remove them entirely.
|
|
48
48
|
|
package/docs/mcp-demo.md
ADDED
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
# A retry that looks right but does nothing
|
|
2
|
+
|
|
3
|
+
A healthy screen cannot prove that Retry works. This demonstration uses a synthetic profile page whose controller leaves its `pending` flag set when a request fails. The error message and Retry button appear, but clicking Retry returns immediately. The corrected controller clears `pending` in `finally`, allowing the next read to run.
|
|
4
|
+
|
|
5
|
+
The [controller](../examples/profile-controller.mjs) and [app](../examples/demo-server.mjs) are included in the npm package. The demonstration starts the real `recovery-probe mcp` process, performs the MCP handshake and calls its tools over stdio. No AI model, API key or external app is involved.
|
|
6
|
+
|
|
7
|
+
## Run from a clean project
|
|
8
|
+
|
|
9
|
+
Use Node.js 22 or newer, then:
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
mkdir recovery-probe-example
|
|
13
|
+
cd recovery-probe-example
|
|
14
|
+
npm init -y
|
|
15
|
+
npm install --save-dev recovery-probe playwright
|
|
16
|
+
npx playwright install chromium
|
|
17
|
+
node node_modules/recovery-probe/examples/mcp-demo.mjs
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
From a source checkout, use `npm ci`, `npx playwright install chromium`, then `npm run demo:mcp`.
|
|
21
|
+
|
|
22
|
+
The demonstration:
|
|
23
|
+
|
|
24
|
+
1. Discovers the profile GET request with `find_page_reads`.
|
|
25
|
+
2. Checks the broken controller with `check_read_recovery`. Each experiment first requires a healthy data marker, then injects a 503, a dropped connection or malformed JSON and clicks Retry.
|
|
26
|
+
3. Repeats the same checks against the corrected controller.
|
|
27
|
+
4. Calls `compare_reports` and requires `IMPROVED`, with all three failures marked `GONE`.
|
|
28
|
+
|
|
29
|
+
It exits unsuccessfully if the broken page passes, the corrected page fails, any fault is not applied, or the comparison does not match. The detailed tool results are saved in `artifacts/mcp-demo.json`; individual reports, reproduction scripts and fix briefs are under `.recovery-probe/`.
|
|
30
|
+
|
|
31
|
+
This is a controlled comparison of two supplied implementations, not an autonomous agent repairing an unknown bug. The passing result covers these reads, markers and faults only. It does not establish overall resilience or prove that fabricated data cannot satisfy a poorly chosen marker. Use checks tied to the data your users actually need.
|
package/docs/mcp.md
CHANGED
|
@@ -4,12 +4,12 @@ An AI coding agent can say "this handles a failed request" without ever seeing o
|
|
|
4
4
|
|
|
5
5
|
## Add it to an agent
|
|
6
6
|
|
|
7
|
-
The server runs over stdio: the agent starts `npx recovery-probe mcp` and talks to it. Add it wherever your agent keeps its MCP servers. Most agents take this JSON:
|
|
7
|
+
The server runs over stdio: the agent starts `npx -y recovery-probe mcp` and talks to it. Add it wherever your agent keeps its MCP servers. Most agents take this JSON:
|
|
8
8
|
|
|
9
9
|
```json
|
|
10
10
|
{
|
|
11
11
|
"mcpServers": {
|
|
12
|
-
"recovery-probe": { "command": "npx", "args": ["recovery-probe", "mcp"] }
|
|
12
|
+
"recovery-probe": { "command": "npx", "args": ["-y", "recovery-probe", "mcp"] }
|
|
13
13
|
}
|
|
14
14
|
}
|
|
15
15
|
```
|
|
@@ -22,7 +22,7 @@ Some use a different shape for the same entry. VS Code's `.vscode/mcp.json` uses
|
|
|
22
22
|
"recovery-probe": {
|
|
23
23
|
"type": "stdio",
|
|
24
24
|
"command": "npx",
|
|
25
|
-
"args": ["recovery-probe", "mcp"]
|
|
25
|
+
"args": ["-y", "recovery-probe", "mcp"]
|
|
26
26
|
}
|
|
27
27
|
}
|
|
28
28
|
}
|
|
@@ -33,10 +33,10 @@ Agents configured with TOML use:
|
|
|
33
33
|
```toml
|
|
34
34
|
[mcp_servers.recovery-probe]
|
|
35
35
|
command = "npx"
|
|
36
|
-
args = ["recovery-probe", "mcp"]
|
|
36
|
+
args = ["-y", "recovery-probe", "mcp"]
|
|
37
37
|
```
|
|
38
38
|
|
|
39
|
-
If your agent has an `mcp add` command, give it the name `recovery-probe` and the command `npx recovery-probe mcp`.
|
|
39
|
+
If your agent has an `mcp add` command, give it the name `recovery-probe` and the command `npx -y recovery-probe mcp`.
|
|
40
40
|
|
|
41
41
|
Install the package in the project, as for the other commands. The browser tools also need Playwright and Chromium:
|
|
42
42
|
|
|
@@ -45,6 +45,10 @@ npm install --save-dev recovery-probe playwright
|
|
|
45
45
|
npx playwright install chromium
|
|
46
46
|
```
|
|
47
47
|
|
|
48
|
+
Run the server with your project as its working directory (the MCP client’s `cwd` setting, where supported). Install the dependencies in that same project; a temporary `npx` download alone does not install the optional browser dependencies. For a fixed executable path, use `node /absolute/path/to/project/node_modules/recovery-probe/bin/recovery-probe.mjs mcp`. Node.js 22 or newer must be available to the agent.
|
|
49
|
+
|
|
50
|
+
See [the reproducible MCP demonstration](mcp-demo.md) for a clean installation and a before/after check through the real stdio server.
|
|
51
|
+
|
|
48
52
|
## Tools
|
|
49
53
|
|
|
50
54
|
| Tool | What it does |
|
package/docs/net.md
CHANGED
|
@@ -7,6 +7,7 @@ Some apps make their own HTTPS requests outside the page: an SDK, the Electron m
|
|
|
7
7
|
- **Whole connections only.** HTTPS stays end to end, so the proxy sees each connection's host and port and nothing else. It cannot return an HTTP status, change a response or fail one path on a host.
|
|
8
8
|
- **The app has to use the proxy.** Clients that read `HTTPS_PROXY` include Rust's reqwest (by default), Go's `net/http`, curl and Python's requests. Node's built-in `fetch` reads it only with `NODE_USE_ENV_PROXY=1` (Node 24 or later). Chromium and Electron renderers ignore it; use the [page's HTTP faults](desktop.md) for those.
|
|
9
9
|
- **Open connections are reused.** A rule that starts mid-session reaches a client only once it connects again. Set `dropOpen` to close the open connections to the host when the rule starts.
|
|
10
|
+
- **Local processes can tunnel to any host and port**, including other loopback services. The proxy binds only to `127.0.0.1`; it is a development proxy, not a destination allowlist or a security boundary between local processes.
|
|
10
11
|
- It reports what it did to connections, not whether the app recovered. Check the screen with `observe`, discovery or your own assertions.
|
|
11
12
|
|
|
12
13
|
Use it only with development or test targets you control.
|
|
@@ -53,7 +54,7 @@ Rule windows count from the first connection through the proxy, so they line up
|
|
|
53
54
|
| `fromMs`, `untilMs` | When the rule applies |
|
|
54
55
|
| `dropOpen` | Close the open connections to the host when the rule starts |
|
|
55
56
|
|
|
56
|
-
The first rule that matches a connection applies.
|
|
57
|
+
The first rule that matches a connection applies. Host matching ignores case and a final DNS dot: `api.example.com.` matches `api.example.com`. `*.example.com` matches subdomains at any depth but never the apex `example.com`; add a separate rule for the apex if needed.
|
|
57
58
|
|
|
58
59
|
## Results
|
|
59
60
|
|
|
@@ -65,7 +66,7 @@ The first rule that matches a connection applies.
|
|
|
65
66
|
|
|
66
67
|
Without `--rules`, `net` only passes connections through until something arms faults through its control. [`observe --network URL`](observe.md#network-steps) does that from network steps, so the screen is sampled while hosts are away and after they come back. Code can use the same control with `connectNetworkFaults(url)`.
|
|
67
68
|
|
|
68
|
-
The control listens on the proxy's own loopback address and
|
|
69
|
+
The control listens on the proxy's own loopback address and requires both the `x-recovery-probe: network` header and a `Host` of `127.0.0.1:<port>` or `localhost:<port>` using the proxy's actual port. The Host check rejects DNS rebinding; other web pages cannot send the control header without a preflight, which the proxy never answers.
|
|
69
70
|
|
|
70
71
|
## Use it from code
|
|
71
72
|
|
package/docs/observe.md
CHANGED
|
@@ -145,6 +145,8 @@ When one IPC channel carries many kinds of calls (for example an SDK bridge), co
|
|
|
145
145
|
|
|
146
146
|
Main-to-renderer pushes can be observed as data-change events. List their channels in the hook's `pushChannels`, optionally with `classifyPush(channel, args)`, and select them with `dataEvents`. The hook wraps `send` on the target window's WebContents only while an observation lease is active, counts sends and their times, never stores payloads, and removes the wrapper at the end of the lease. Fault plans never observe pushes.
|
|
147
147
|
|
|
148
|
+
These counts cover calls through `webContents.send` only. Calls through `webContents.mainFrame.send`, `postMessage`, other frames, or a reference to `send` saved before the wrapper was installed are not counted. A zero push count does not prove that no message was sent through those paths.
|
|
149
|
+
|
|
148
150
|
```js
|
|
149
151
|
installIpcProbe(ipcMain, {
|
|
150
152
|
enabled: true, channels: ['app:invoke'], sender: () => mainWindow?.webContents,
|
|
@@ -0,0 +1,117 @@
|
|
|
1
|
+
import assert from 'node:assert/strict'
|
|
2
|
+
import { spawn } from 'node:child_process'
|
|
3
|
+
import { once } from 'node:events'
|
|
4
|
+
import { mkdir, writeFile } from 'node:fs/promises'
|
|
5
|
+
import { createInterface } from 'node:readline'
|
|
6
|
+
import { fileURLToPath } from 'node:url'
|
|
7
|
+
import { startDemoServer } from './demo-server.mjs'
|
|
8
|
+
|
|
9
|
+
// Use the packaged executable, including when this example is run by a consumer.
|
|
10
|
+
const child = spawn(
|
|
11
|
+
process.execPath,
|
|
12
|
+
[fileURLToPath(new URL('../bin/recovery-probe.mjs', import.meta.url)), 'mcp'],
|
|
13
|
+
{ stdio: ['pipe', 'pipe', 'inherit'] },
|
|
14
|
+
)
|
|
15
|
+
const exited = once(child, 'exit')
|
|
16
|
+
const lines = createInterface({ input: child.stdout })
|
|
17
|
+
const pending = new Map()
|
|
18
|
+
let nextId = 0
|
|
19
|
+
lines.on('line', (line) => {
|
|
20
|
+
const reply = JSON.parse(line)
|
|
21
|
+
pending.get(reply.id)?.(reply)
|
|
22
|
+
})
|
|
23
|
+
/** @returns {Promise<any>} */
|
|
24
|
+
async function request(method, params = {}) {
|
|
25
|
+
const id = ++nextId
|
|
26
|
+
let timer
|
|
27
|
+
try {
|
|
28
|
+
const reply = await new Promise((resolve, reject) => {
|
|
29
|
+
pending.set(id, resolve)
|
|
30
|
+
timer = setTimeout(() => reject(Error(`Timed out: ${method}`)), 90000)
|
|
31
|
+
child.stdin.write(
|
|
32
|
+
`${JSON.stringify({ jsonrpc: '2.0', id, method, params })}\n`,
|
|
33
|
+
)
|
|
34
|
+
})
|
|
35
|
+
assert.equal(reply.error, undefined, JSON.stringify(reply.error))
|
|
36
|
+
return reply.result
|
|
37
|
+
} finally {
|
|
38
|
+
clearTimeout(timer)
|
|
39
|
+
pending.delete(id)
|
|
40
|
+
}
|
|
41
|
+
}
|
|
42
|
+
async function call(name, args) {
|
|
43
|
+
const result = await request('tools/call', { name, arguments: args })
|
|
44
|
+
assert.equal(result.isError, false, JSON.stringify(result.content))
|
|
45
|
+
return result.structuredContent
|
|
46
|
+
}
|
|
47
|
+
const app = await startDemoServer()
|
|
48
|
+
try {
|
|
49
|
+
await request('initialize', {
|
|
50
|
+
protocolVersion: '2025-06-18',
|
|
51
|
+
capabilities: {},
|
|
52
|
+
clientInfo: { name: 'recovery-probe-demo', version: '1' },
|
|
53
|
+
})
|
|
54
|
+
child.stdin.write(
|
|
55
|
+
`${JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized' })}\n`,
|
|
56
|
+
)
|
|
57
|
+
const listed = await request('tools/list')
|
|
58
|
+
assert.ok(listed.tools.some(({ name }) => name === 'check_read_recovery'))
|
|
59
|
+
const reads = await call('find_page_reads', {
|
|
60
|
+
url: `${app.url}/fixed`,
|
|
61
|
+
durationMs: 500,
|
|
62
|
+
})
|
|
63
|
+
assert.ok(
|
|
64
|
+
reads.endpoints.some(
|
|
65
|
+
({ endpoint }) => endpoint === `${app.url}/api/profile`,
|
|
66
|
+
),
|
|
67
|
+
)
|
|
68
|
+
const check = (page) =>
|
|
69
|
+
call('check_read_recovery', {
|
|
70
|
+
url: `${app.url}/${page}`,
|
|
71
|
+
endpoint: `${app.url}/api/profile`,
|
|
72
|
+
readySelector: '#profile',
|
|
73
|
+
readyText: 'Synthetic Example',
|
|
74
|
+
recovery: 'retry',
|
|
75
|
+
retrySelector: '#retry',
|
|
76
|
+
faults: ['http-error', 'connection-failure', 'invalid-json'],
|
|
77
|
+
timeoutMs: 2000,
|
|
78
|
+
})
|
|
79
|
+
const broken = await check('broken')
|
|
80
|
+
const fixed = await check('fixed')
|
|
81
|
+
assert.equal(broken.ok, false)
|
|
82
|
+
assert.equal(fixed.ok, true)
|
|
83
|
+
for (const result of broken.results) {
|
|
84
|
+
assert.equal(result.outcome, 'fail')
|
|
85
|
+
assert.ok(result.applied > 0)
|
|
86
|
+
}
|
|
87
|
+
for (const result of fixed.results) {
|
|
88
|
+
assert.equal(result.outcome, 'pass')
|
|
89
|
+
assert.ok(result.applied > 0)
|
|
90
|
+
}
|
|
91
|
+
const comparison = await call('compare_reports', {
|
|
92
|
+
before: [broken.report],
|
|
93
|
+
after: [fixed.report],
|
|
94
|
+
})
|
|
95
|
+
assert.equal(comparison.verdict, 'IMPROVED')
|
|
96
|
+
assert.equal(comparison.changes.length, 3)
|
|
97
|
+
assert.ok(comparison.changes.every(({ status }) => status === 'GONE'))
|
|
98
|
+
const evidence = {
|
|
99
|
+
expectedDemonstrationVerified: true,
|
|
100
|
+
broken,
|
|
101
|
+
fixed,
|
|
102
|
+
comparison,
|
|
103
|
+
}
|
|
104
|
+
await mkdir('artifacts', { recursive: true })
|
|
105
|
+
await writeFile(
|
|
106
|
+
'artifacts/mcp-demo.json',
|
|
107
|
+
`${JSON.stringify(evidence, null, 2)}\n`,
|
|
108
|
+
)
|
|
109
|
+
console.log(JSON.stringify(evidence, null, 2))
|
|
110
|
+
} finally {
|
|
111
|
+
child.stdin.end()
|
|
112
|
+
const shutdown = setTimeout(() => child.kill(), 5000)
|
|
113
|
+
await exited
|
|
114
|
+
clearTimeout(shutdown)
|
|
115
|
+
lines.close()
|
|
116
|
+
await app.close()
|
|
117
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "recovery-probe",
|
|
3
|
-
"version": "1.0.
|
|
3
|
+
"version": "1.0.2",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"description": "Test whether web and Electron desktop apps show the right data when a read fails, from the command line, your tests or an AI coding agent.",
|
|
6
6
|
"license": "MIT",
|
|
@@ -56,7 +56,8 @@
|
|
|
56
56
|
"CONTRIBUTING.md",
|
|
57
57
|
"SECURITY.md",
|
|
58
58
|
"README.md",
|
|
59
|
-
"LICENSE"
|
|
59
|
+
"LICENSE",
|
|
60
|
+
"server.json"
|
|
60
61
|
],
|
|
61
62
|
"sideEffects": false,
|
|
62
63
|
"engines": {
|
|
@@ -136,6 +137,8 @@
|
|
|
136
137
|
"prepublishOnly": "npm run test:unit && npm run test:package",
|
|
137
138
|
"demo": "npm run build --silent && node dist/cli/core-demo.mjs",
|
|
138
139
|
"demo:browser": "npm run build --silent && node bin/recovery-probe.mjs demo",
|
|
139
|
-
"benchmark:observe": "npm run build --silent && node scripts/benchmark-observe.mjs"
|
|
140
|
-
|
|
140
|
+
"benchmark:observe": "npm run build --silent && node scripts/benchmark-observe.mjs",
|
|
141
|
+
"demo:mcp": "npm run build && node examples/mcp-demo.mjs"
|
|
142
|
+
},
|
|
143
|
+
"mcpName": "io.github.BojanKovachki/recovery-probe"
|
|
141
144
|
}
|
package/server.json
ADDED
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
|
|
3
|
+
"name": "io.github.BojanKovachki/recovery-probe",
|
|
4
|
+
"description": "Fail reads in web and Electron test apps, inspect recovery, and compare before/after evidence.",
|
|
5
|
+
"repository": {
|
|
6
|
+
"url": "https://github.com/BojanKovachki/recovery-probe",
|
|
7
|
+
"source": "github"
|
|
8
|
+
},
|
|
9
|
+
"version": "1.0.2",
|
|
10
|
+
"packages": [
|
|
11
|
+
{
|
|
12
|
+
"registryType": "npm",
|
|
13
|
+
"identifier": "recovery-probe",
|
|
14
|
+
"version": "1.0.2",
|
|
15
|
+
"runtimeHint": "npx",
|
|
16
|
+
"runtimeArguments": [
|
|
17
|
+
{
|
|
18
|
+
"type": "positional",
|
|
19
|
+
"value": "-y"
|
|
20
|
+
}
|
|
21
|
+
],
|
|
22
|
+
"packageArguments": [
|
|
23
|
+
{
|
|
24
|
+
"type": "positional",
|
|
25
|
+
"value": "mcp"
|
|
26
|
+
}
|
|
27
|
+
],
|
|
28
|
+
"transport": {
|
|
29
|
+
"type": "stdio"
|
|
30
|
+
}
|
|
31
|
+
}
|
|
32
|
+
]
|
|
33
|
+
}
|