recovery-probe 1.0.1 → 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 CHANGED
@@ -4,6 +4,12 @@ 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
+
7
13
  ## 1.0.1 (2026-10-28)
8
14
 
9
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.
@@ -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 |
@@ -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.1",
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
+ }