@mirsella/browser-mcp 1.0.0 → 2.0.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/.codex-plugin/plugin.json +1 -1
- package/README.md +16 -11
- package/package.json +12 -4
- package/plugin/browser-routing.ts +138 -169
- package/vendor/browser-mcp +0 -0
package/README.md
CHANGED
|
@@ -10,13 +10,18 @@ and Codex conversations. The plugin wraps
|
|
|
10
10
|
and routes each conversation through its own browser tabs while sharing cookies,
|
|
11
11
|
logins, local storage, cache, and extensions.
|
|
12
12
|
|
|
13
|
-
Package
|
|
14
|
-
|
|
15
|
-
|
|
13
|
+
Package 2.x targets OpenCode v2 (2.0.27 or newer). Package 1.x retains the
|
|
14
|
+
OpenCode v1 adapter (1.18 or newer, below 2). Codex uses the same Rust MCP
|
|
15
|
+
server and manifests in both releases. The native v2 adapter uses
|
|
16
|
+
`@opencode/plugin`; local directories also expose a physical `server` entrypoint.
|
|
17
|
+
|
|
18
|
+
Install `@mirsella/browser-mcp` for OpenCode v2, or `@mirsella/browser-mcp@opencode1`
|
|
19
|
+
for OpenCode v1. Existing Nix-managed and local-directory installations can keep
|
|
20
|
+
their configured paths.
|
|
16
21
|
|
|
17
22
|
## Requirements
|
|
18
23
|
|
|
19
|
-
- OpenCode
|
|
24
|
+
- OpenCode 2.0.27 or newer, or Codex with plugin and hook support
|
|
20
25
|
- Linux x64
|
|
21
26
|
- Bun
|
|
22
27
|
- A local Chromium-family browser
|
|
@@ -29,8 +34,8 @@ the browser automation skill available by default:
|
|
|
29
34
|
|
|
30
35
|
```json
|
|
31
36
|
{
|
|
32
|
-
"$schema": "https://opencode.ai/config.json",
|
|
33
|
-
"
|
|
37
|
+
"$schema": "https://opencode.ai/v2/config.json",
|
|
38
|
+
"plugins": ["@mirsella/browser-mcp"]
|
|
34
39
|
}
|
|
35
40
|
```
|
|
36
41
|
|
|
@@ -108,15 +113,15 @@ direct tools so those policies continue to work.
|
|
|
108
113
|
Settings:
|
|
109
114
|
|
|
110
115
|
- `enabled` (default `true`): start the server and load the skill. Set it to
|
|
111
|
-
`false` to disable both. An explicit `mcp.browser` entry takes precedence.
|
|
116
|
+
`false` to disable both. An explicit `mcp.servers.browser` entry takes precedence.
|
|
112
117
|
- `compactTools` (default `true`): keep `browser_dispatch` and `browser_help`
|
|
113
118
|
instead of the direct tools. Set it to `false` to always use direct tools:
|
|
114
119
|
|
|
115
120
|
```json
|
|
116
121
|
{
|
|
117
|
-
"$schema": "https://opencode.ai/config.json",
|
|
118
|
-
"
|
|
119
|
-
|
|
122
|
+
"$schema": "https://opencode.ai/v2/config.json",
|
|
123
|
+
"plugins": [
|
|
124
|
+
{ "package": "@mirsella/browser-mcp", "options": { "compactTools": false } }
|
|
120
125
|
]
|
|
121
126
|
}
|
|
122
127
|
```
|
|
@@ -218,7 +223,7 @@ action. Explicitly disabled or disconnected MCP entries stay disabled.
|
|
|
218
223
|
- A profile or socket lease error means another live package process owns it or a stale process is still running. Do not bypass the locks.
|
|
219
224
|
- A process on the configured CDP port must belong to the exact managed browser generation. Stop it or choose another port.
|
|
220
225
|
- If downstream startup fails, verify that `bunx` is available to OpenCode.
|
|
221
|
-
- The plugin refuses to replace an unrelated `mcp.browser` entry.
|
|
226
|
+
- The plugin refuses to replace an unrelated `mcp.servers.browser` entry.
|
|
222
227
|
|
|
223
228
|
## Security
|
|
224
229
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@mirsella/browser-mcp",
|
|
3
|
-
"version": "
|
|
3
|
+
"version": "2.0.0",
|
|
4
4
|
"description": "Session-isolated browser automation over MCP and Chrome DevTools Protocol",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"exports": {
|
|
@@ -50,14 +50,22 @@
|
|
|
50
50
|
"x64"
|
|
51
51
|
],
|
|
52
52
|
"engines": {
|
|
53
|
-
"opencode": ">=
|
|
53
|
+
"opencode": ">=2.0.27 <3"
|
|
54
54
|
},
|
|
55
55
|
"devDependencies": {
|
|
56
|
-
"@opencode
|
|
56
|
+
"@opencode/plugin": "2.0.28",
|
|
57
|
+
"@types/node": "24.0.0",
|
|
58
|
+
"typescript": "5.9.3"
|
|
57
59
|
},
|
|
58
60
|
"publishConfig": {
|
|
59
61
|
"access": "public",
|
|
60
|
-
"tag": "
|
|
62
|
+
"tag": "latest"
|
|
63
|
+
},
|
|
64
|
+
"peerDependencies": {
|
|
65
|
+
"@opencode/plugin": ">=2.0.27 <3"
|
|
66
|
+
},
|
|
67
|
+
"dependencies": {
|
|
68
|
+
"yaml": "2.8.1"
|
|
61
69
|
},
|
|
62
70
|
"main": "./server.ts",
|
|
63
71
|
"scripts": {
|
|
@@ -1,174 +1,143 @@
|
|
|
1
|
-
import
|
|
1
|
+
import { Plugin, Skill } from "@opencode/plugin";
|
|
2
|
+
import { execFile } from "node:child_process";
|
|
3
|
+
import { readdir, readFile } from "node:fs/promises";
|
|
2
4
|
import { fileURLToPath } from "node:url";
|
|
5
|
+
import { promisify } from "node:util";
|
|
6
|
+
import { parse } from "yaml";
|
|
3
7
|
|
|
4
|
-
const
|
|
5
|
-
const
|
|
6
|
-
const
|
|
7
|
-
const
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
browser_performance_analyze_insight browser_performance_start_trace browser_performance_stop_trace browser_press_key
|
|
13
|
-
browser_resize_page browser_take_heapsnapshot browser_take_screenshot browser_take_snapshot browser_type_text
|
|
14
|
-
browser_upload_file browser_wait_for
|
|
15
|
-
`
|
|
16
|
-
.trim()
|
|
17
|
-
.split(/\s+/);
|
|
8
|
+
const execute = promisify(execFile);
|
|
9
|
+
const binary = fileURLToPath(new URL("../vendor/browser-mcp", import.meta.url));
|
|
10
|
+
const skills = fileURLToPath(new URL("../skills/", import.meta.url));
|
|
11
|
+
const directTools = `click close_page drag emulate evaluate_script fill fill_form get_console_message
|
|
12
|
+
get_network_request handle_dialog hover lighthouse_audit list_console_messages list_network_requests
|
|
13
|
+
list_pages navigate_page new_page performance_analyze_insight performance_start_trace performance_stop_trace
|
|
14
|
+
press_key resize_page take_heapsnapshot take_screenshot take_snapshot type_text upload_file wait_for`
|
|
15
|
+
.split(/\s+/).map(name => `browser_${name}`);
|
|
18
16
|
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
};
|
|
25
|
-
|
|
26
|
-
type BrowserRoutingOptions = {
|
|
27
|
-
enabled?: boolean;
|
|
28
|
-
compactTools?: boolean;
|
|
29
|
-
};
|
|
30
|
-
|
|
31
|
-
function hasPartialBrowserPolicy(value: unknown): boolean {
|
|
32
|
-
if (!value || typeof value !== "object" || Array.isArray(value)) return false;
|
|
33
|
-
return Object.keys(value).some((pattern) => {
|
|
34
|
-
const expression = pattern
|
|
35
|
-
.replace(/[.+^${}()|[\]\\]/g, "\\$&")
|
|
36
|
-
.replaceAll("*", ".*")
|
|
37
|
-
.replaceAll("?", ".");
|
|
38
|
-
const regex = new RegExp(`^${expression}$`);
|
|
39
|
-
const matches = (tool: string) => regex.test(tool);
|
|
40
|
-
return DIRECT_TOOLS.some(matches) && !(matches(DISPATCH_TOOL) && DIRECT_TOOLS.every(matches));
|
|
41
|
-
});
|
|
42
|
-
}
|
|
43
|
-
|
|
44
|
-
function requiresDirectTools(config: ConfigWithPolicies): boolean {
|
|
45
|
-
if (hasPartialBrowserPolicy(config.permission) || hasPartialBrowserPolicy(config.tools)) {
|
|
46
|
-
return true;
|
|
47
|
-
}
|
|
48
|
-
return Object.values(config.agent ?? {}).some(
|
|
49
|
-
(agent) => hasPartialBrowserPolicy(agent.permission) || hasPartialBrowserPolicy(agent.tools),
|
|
50
|
-
);
|
|
17
|
+
function partialPolicy(agents: Array<{ permissions: readonly { action: string }[] }>) {
|
|
18
|
+
return agents.some(agent => agent.permissions.some(({ action }) => {
|
|
19
|
+
const regex = new RegExp(`^${action.replace(/[.+^${}()|[\]\\]/g, "\\$&").replaceAll("*", ".*").replaceAll("?", ".")}$`);
|
|
20
|
+
return directTools.some(tool => regex.test(tool))
|
|
21
|
+
&& !(regex.test("browser_dispatch") && directTools.every(tool => regex.test(tool)));
|
|
22
|
+
}));
|
|
51
23
|
}
|
|
52
24
|
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
};
|
|
173
|
-
|
|
174
|
-
export default { id: "@mirsella/browser-mcp", server } satisfies PluginModule;
|
|
25
|
+
export default Plugin.define({
|
|
26
|
+
id: "@mirsella/browser-mcp",
|
|
27
|
+
async setup(ctx) {
|
|
28
|
+
const { enabled = true, compactTools = true } = ctx.options;
|
|
29
|
+
if (typeof enabled !== "boolean") throw new Error("enabled must be a boolean");
|
|
30
|
+
if (typeof compactTools !== "boolean") throw new Error("compactTools must be a boolean");
|
|
31
|
+
let compact = compactTools;
|
|
32
|
+
let reconnectGeneration = 0;
|
|
33
|
+
let active = enabled;
|
|
34
|
+
await ctx.mcp.transform(editor => {
|
|
35
|
+
const existing = editor.get("browser");
|
|
36
|
+
if (existing?.type === "remote" || (existing && existing.command[0] !== binary)) {
|
|
37
|
+
throw new Error("Browser MCP cannot replace an incompatible mcp.servers.browser configuration");
|
|
38
|
+
}
|
|
39
|
+
active = !(existing?.disabled ?? !enabled);
|
|
40
|
+
editor.set("browser", {
|
|
41
|
+
...existing,
|
|
42
|
+
type: "local", command: compact ? [binary] : [binary, "--direct-tools"],
|
|
43
|
+
disabled: !active, codemode: false,
|
|
44
|
+
environment: { ...existing?.environment, BROWSER_MCP_RECONNECT_GENERATION: String(reconnectGeneration) },
|
|
45
|
+
timeout: { startup: 30_000, catalog: 30_000, execution: 600_000, ...existing?.timeout },
|
|
46
|
+
});
|
|
47
|
+
});
|
|
48
|
+
if (active) {
|
|
49
|
+
const entries = await readdir(skills, { withFileTypes: true });
|
|
50
|
+
const registered = await Promise.all(entries.filter(entry => entry.isDirectory()).map(async entry => {
|
|
51
|
+
const path = `${skills}${entry.name}/SKILL.md`;
|
|
52
|
+
const text = await readFile(path, "utf8");
|
|
53
|
+
const frontmatter = text.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
|
|
54
|
+
if (!frontmatter) throw new Error(`Missing skill frontmatter: ${path}`);
|
|
55
|
+
const meta = parse(frontmatter[1]);
|
|
56
|
+
if (!meta || typeof meta.name !== "string" || typeof meta.description !== "string") throw new Error(`Invalid skill metadata: ${path}`);
|
|
57
|
+
return Skill.Info.make({ id: Skill.ID.make(meta.name), name: Skill.Name.make(meta.name),
|
|
58
|
+
description: meta.description, path: Skill.Info.fields.path.make(path), content: text.slice(frontmatter[0].length) });
|
|
59
|
+
}));
|
|
60
|
+
await ctx.skill.transform(editor => { for (const skill of registered) editor.add(skill); });
|
|
61
|
+
}
|
|
62
|
+
await ctx.tool.hook("execute.before", input => {
|
|
63
|
+
if (!input.tool.startsWith("browser_")) return;
|
|
64
|
+
if (!input.sessionID) throw new Error("Browser tool call has no OpenCode session ID");
|
|
65
|
+
if (!input.input || typeof input.input !== "object" || Array.isArray(input.input)) throw new Error("Browser tool call has invalid arguments");
|
|
66
|
+
input.input = { ...input.input, __opencode_session_id: input.sessionID };
|
|
67
|
+
});
|
|
68
|
+
const controller = new AbortController();
|
|
69
|
+
let timer: ReturnType<typeof setTimeout> | undefined;
|
|
70
|
+
let recovering: Promise<void> | undefined;
|
|
71
|
+
let failures = 0;
|
|
72
|
+
// Runners that never list the server cannot be fixed by reloading;
|
|
73
|
+
// stay quiet until it has been seen at least once.
|
|
74
|
+
let seen = false;
|
|
75
|
+
const schedule = () => {
|
|
76
|
+
if (controller.signal.aborted) return;
|
|
77
|
+
timer = setTimeout(() => void recover(), failures ? Math.min(30_000, 1_000 * 2 ** Math.min(failures - 1, 5)) : 5_000);
|
|
78
|
+
timer.unref();
|
|
79
|
+
};
|
|
80
|
+
const recover = (): Promise<void> => {
|
|
81
|
+
if (controller.signal.aborted) return Promise.resolve();
|
|
82
|
+
if (recovering) return recovering;
|
|
83
|
+
if (timer) clearTimeout(timer);
|
|
84
|
+
recovering = (async () => {
|
|
85
|
+
try {
|
|
86
|
+
const server = (await ctx.mcp.list()).data.find(server => server.name === "browser");
|
|
87
|
+
if (!server) throw new Error("Browser MCP status is missing");
|
|
88
|
+
seen = true;
|
|
89
|
+
// A disabled connection is an explicit user choice; only recover failures.
|
|
90
|
+
if (server.status.status === "failed" && !controller.signal.aborted) {
|
|
91
|
+
console.warn("Browser MCP adapter failed; reloading its registration");
|
|
92
|
+
reconnectGeneration++;
|
|
93
|
+
await ctx.mcp.reload();
|
|
94
|
+
const restored = (await ctx.mcp.list()).data.find(server => server.name === "browser");
|
|
95
|
+
if (restored?.status.status !== "connected") throw new Error(`Browser MCP recovery failed: ${JSON.stringify(restored?.status)}`);
|
|
96
|
+
}
|
|
97
|
+
failures = 0;
|
|
98
|
+
} catch (error) {
|
|
99
|
+
if (!controller.signal.aborted) { failures++; if (seen) console.error("Browser MCP recovery failed; will retry", error); }
|
|
100
|
+
} finally { recovering = undefined; schedule(); }
|
|
101
|
+
})();
|
|
102
|
+
return recovering;
|
|
103
|
+
};
|
|
104
|
+
// Recovery must never stall a prompt: a wedged adapter keeps retrying in
|
|
105
|
+
// the background while chat continues within a short deadline.
|
|
106
|
+
const recoverSoon = async () => {
|
|
107
|
+
let deadline: ReturnType<typeof setTimeout> | undefined;
|
|
108
|
+
try {
|
|
109
|
+
await Promise.race([
|
|
110
|
+
recover(),
|
|
111
|
+
new Promise<void>(resolve => { deadline = setTimeout(resolve, 5_000); deadline.unref(); }),
|
|
112
|
+
]);
|
|
113
|
+
} finally {
|
|
114
|
+
if (deadline) clearTimeout(deadline);
|
|
115
|
+
}
|
|
116
|
+
};
|
|
117
|
+
// Catalog reads wait for plugin bootstrap. Do not await them inside setup.
|
|
118
|
+
const checkPolicy = async () => {
|
|
119
|
+
if (!compactTools || controller.signal.aborted) return;
|
|
120
|
+
const next = !partialPolicy((await ctx.agent.list()).data);
|
|
121
|
+
if (controller.signal.aborted || next === compact) return;
|
|
122
|
+
compact = next;
|
|
123
|
+
if (!compact) console.warn("Browser MCP uses direct tools to preserve per-action permissions");
|
|
124
|
+
await ctx.mcp.reload();
|
|
125
|
+
};
|
|
126
|
+
const policyReady = Promise.resolve().then(checkPolicy);
|
|
127
|
+
void policyReady.catch(error => console.error("Browser MCP permission initialization failed", error));
|
|
128
|
+
await ctx.session.hook("prompt", async () => { await policyReady; await checkPolicy(); await recoverSoon(); });
|
|
129
|
+
const events = async () => {
|
|
130
|
+
for await (const event of ctx.event.subscribe({ signal: controller.signal })) {
|
|
131
|
+
if (controller.signal.aborted) break;
|
|
132
|
+
if (event.type === "agent.updated") void checkPolicy().catch(error => console.error("Browser MCP permission update failed", error));
|
|
133
|
+
if ((event.type === "mcp.status.changed") && event.data.server === "browser") void recover();
|
|
134
|
+
if (event.type !== "session.deleted") continue;
|
|
135
|
+
try { await execute(binary, ["release-session", event.data.sessionID], { signal: controller.signal }); }
|
|
136
|
+
catch (error) { if (!controller.signal.aborted) console.error(`Failed to release browser session ${event.data.sessionID}`, error); }
|
|
137
|
+
}
|
|
138
|
+
};
|
|
139
|
+
void events().catch(error => { if (!controller.signal.aborted) console.error("Browser MCP event subscription failed", error); });
|
|
140
|
+
schedule();
|
|
141
|
+
return () => { controller.abort(); if (timer) clearTimeout(timer); };
|
|
142
|
+
},
|
|
143
|
+
});
|
package/vendor/browser-mcp
CHANGED
|
Binary file
|