@spaxe-dev/zen-mcp 0.3.1 → 0.3.3

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/dist/cli.js CHANGED
@@ -1,7 +1,7 @@
1
1
  #!/usr/bin/env node
2
2
 
3
3
  // src/cli.ts
4
- import { existsSync as existsSync9 } from "node:fs";
4
+ import { existsSync as existsSync10 } from "node:fs";
5
5
  import { Command, InvalidArgumentError } from "commander";
6
6
  import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
7
7
 
@@ -133,17 +133,21 @@ function loadConfig() {
133
133
  const envConsent = process.env.ZEN_MCP_REQUIRE_CONSENT;
134
134
  const envConsentTimeout = process.env.ZEN_MCP_CONSENT_TIMEOUT_SECONDS;
135
135
  const envLaunchArgs = process.env.ZEN_MCP_LAUNCH_ARGS;
136
- const fileReadOnly = fileBoolean(
136
+ const fileReadOnly = fileSafetyBoolean(
137
137
  fileConfig.readOnly,
138
+ "readOnly",
138
139
  DEFAULT_CONFIG.readOnly
139
140
  );
140
- const fileAuditLog = fileBoolean(
141
+ const fileAuditLog = fileSafetyBoolean(
141
142
  fileConfig.auditLog,
143
+ "auditLog",
142
144
  DEFAULT_CONFIG.auditLog
143
145
  );
144
- const fileDomains = Array.isArray(fileConfig.allowedDomains) ? fileConfig.allowedDomains.filter(
145
- (entry) => typeof entry === "string"
146
- ) : DEFAULT_CONFIG.allowedDomains;
146
+ const fileDomains = fileStringArray(
147
+ fileConfig.allowedDomains,
148
+ "allowedDomains",
149
+ DEFAULT_CONFIG.allowedDomains
150
+ );
147
151
  const domains = envDomains !== void 0 ? envDomains.split(",").map((entry) => entry.trim().toLowerCase()).filter(Boolean) : fileDomains;
148
152
  const launchArgs = Array.isArray(fileConfig.launchArgs) ? fileConfig.launchArgs.map(String).filter(Boolean) : DEFAULT_CONFIG.launchArgs;
149
153
  return {
@@ -151,11 +155,16 @@ function loadConfig() {
151
155
  ...fileConfig,
152
156
  zenPath: process.env.ZEN_MCP_ZEN_PATH || (typeof fileConfig.zenPath === "string" ? fileConfig.zenPath : void 0),
153
157
  profilePath: process.env.ZEN_MCP_PROFILE || (typeof fileConfig.profilePath === "string" ? fileConfig.profilePath : void 0),
154
- useDefaultProfile: envUseDefault !== void 0 ? parseBoolean(envUseDefault, DEFAULT_CONFIG.useDefaultProfile) : fileBoolean(
158
+ useDefaultProfile: envUseDefault !== void 0 ? envBoolean("ZEN_MCP_USE_DEFAULT_PROFILE", envUseDefault) : fileSafetyBoolean(
155
159
  fileConfig.useDefaultProfile,
160
+ "useDefaultProfile",
156
161
  DEFAULT_CONFIG.useDefaultProfile
157
162
  ),
158
- requireConsent: envConsent !== void 0 ? parseBoolean(envConsent, DEFAULT_CONFIG.requireConsent) : fileBoolean(fileConfig.requireConsent, DEFAULT_CONFIG.requireConsent),
163
+ requireConsent: envConsent !== void 0 ? envBoolean("ZEN_MCP_REQUIRE_CONSENT", envConsent) : fileSafetyBoolean(
164
+ fileConfig.requireConsent,
165
+ "requireConsent",
166
+ DEFAULT_CONFIG.requireConsent
167
+ ),
159
168
  consentTimeoutSeconds: envConsentTimeout !== void 0 && envConsentTimeout.trim() ? boundedInt(
160
169
  envConsentTimeout,
161
170
  1,
@@ -174,11 +183,11 @@ function loadConfig() {
174
183
  65535,
175
184
  DEFAULT_CONFIG.marionettePort
176
185
  ),
177
- readOnly: envReadOnly !== void 0 ? parseBoolean(envReadOnly, fileReadOnly) : fileReadOnly,
186
+ readOnly: envReadOnly !== void 0 ? envBoolean("ZEN_MCP_READ_ONLY", envReadOnly) : fileReadOnly,
178
187
  allowedDomains: domains.map(
179
188
  (domain) => domain.replace(/^\*?\./, "").toLowerCase()
180
189
  ),
181
- auditLog: envAuditLog !== void 0 ? parseBoolean(envAuditLog, fileAuditLog) : fileAuditLog,
190
+ auditLog: envAuditLog !== void 0 ? envBoolean("ZEN_MCP_AUDIT_LOG", envAuditLog) : fileAuditLog,
182
191
  watchMinIntervalSeconds: envWatchMin !== void 0 && envWatchMin.trim() ? boundedInt(
183
192
  envWatchMin,
184
193
  1,
@@ -202,9 +211,14 @@ function loadConfig() {
202
211
  3600,
203
212
  DEFAULT_CONFIG.askTimeoutSeconds
204
213
  ),
205
- autoLaunch: fileBoolean(fileConfig.autoLaunch, DEFAULT_CONFIG.autoLaunch),
206
- autoAttachWindows: fileBoolean(
214
+ autoLaunch: fileSafetyBoolean(
215
+ fileConfig.autoLaunch,
216
+ "autoLaunch",
217
+ DEFAULT_CONFIG.autoLaunch
218
+ ),
219
+ autoAttachWindows: fileSafetyBoolean(
207
220
  fileConfig.autoAttachWindows,
221
+ "autoAttachWindows",
208
222
  DEFAULT_CONFIG.autoAttachWindows
209
223
  )
210
224
  };
@@ -226,13 +240,29 @@ function readConfigFile() {
226
240
  );
227
241
  }
228
242
  }
229
- function parseBoolean(value, fallback) {
230
- if (/^(1|true|yes|on)$/i.test(value.trim())) return true;
231
- if (/^(0|false|no|off)$/i.test(value.trim())) return false;
232
- return fallback;
243
+ function envBoolean(name, value) {
244
+ const normalized = value.trim().toLowerCase();
245
+ if (/^(1|true|yes|on)$/.test(normalized)) return true;
246
+ if (/^(0|false|no|off)$/.test(normalized)) return false;
247
+ throw new Error(
248
+ `Invalid ${name} value "${value}": use 1/0, true/false, yes/no, or on/off.`
249
+ );
233
250
  }
234
- function fileBoolean(value, fallback) {
235
- return typeof value === "boolean" ? value : fallback;
251
+ function fileSafetyBoolean(value, field, fallback) {
252
+ if (value === void 0) return fallback;
253
+ if (typeof value === "boolean") return value;
254
+ throw new Error(
255
+ `Invalid config at ${configFilePath()}: "${field}" must be true or false. Fix or delete the file.`
256
+ );
257
+ }
258
+ function fileStringArray(value, field, fallback) {
259
+ if (value === void 0) return fallback;
260
+ if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string")) {
261
+ throw new Error(
262
+ `Invalid config at ${configFilePath()}: "${field}" must be an array of strings. Fix or delete the file.`
263
+ );
264
+ }
265
+ return value;
236
266
  }
237
267
  function boundedInt(value, min, max, fallback) {
238
268
  const parsed = typeof value === "number" ? value : Number(value);
@@ -261,7 +291,7 @@ import { WebSocketServer } from "ws";
261
291
  // src/shared/brand.ts
262
292
  var BRAND = "Zen MCP";
263
293
  var SERVER_NAME = "zen-mcp";
264
- var SERVER_VERSION = "0.3.0";
294
+ var SERVER_VERSION = "0.3.3";
265
295
  var BRIDGE_PROTOCOL_VERSION = 2;
266
296
 
267
297
  // src/shared/bridge-auth.ts
@@ -1144,10 +1174,17 @@ var BridgeHub = class {
1144
1174
  return this.request("containers.list", void 0, { windowId });
1145
1175
  }
1146
1176
  async openGlance(params, windowId) {
1147
- const result = await this.request("glance.open", params, {
1148
- windowId,
1149
- timeoutMs: 3e4
1150
- });
1177
+ if (params?.url) {
1178
+ this.#assertUrlAllowed(String(params.url), "Refusing to preview");
1179
+ }
1180
+ const result = await this.request(
1181
+ "glance.open",
1182
+ { ...params, allowedDomains: this.#allowedDomains },
1183
+ {
1184
+ windowId,
1185
+ timeoutMs: 3e4
1186
+ }
1187
+ );
1151
1188
  if (result.url) {
1152
1189
  this.#assertUrlAllowed(result.url, "Refusing to preview");
1153
1190
  }
@@ -1903,8 +1940,33 @@ var MUTATING_TOOLS = /* @__PURE__ */ new Set([
1903
1940
  "zen_tabs_group",
1904
1941
  "zen_show_evidence",
1905
1942
  "zen_show_evidence_batch",
1906
- "zen_clear_evidence"
1943
+ "zen_clear_evidence",
1944
+ "zen_progress",
1945
+ "zen_ask",
1946
+ "zen_notify"
1907
1947
  ]);
1948
+ function auditOutcomeForResult(tool, value) {
1949
+ const result = value !== null && typeof value === "object" ? value : void 0;
1950
+ const structuredOk = result && typeof result.ok === "boolean" ? result.ok : void 0;
1951
+ const fields = {
1952
+ ok: structuredOk ?? true,
1953
+ executed: true
1954
+ };
1955
+ if (!result) {
1956
+ return fields;
1957
+ }
1958
+ const total = result.total;
1959
+ const verified = result.verified;
1960
+ const failed = result.failed;
1961
+ const batchShaped = tool === "zen_show_evidence_batch" || total !== void 0 || verified !== void 0 || failed !== void 0;
1962
+ if (!batchShaped || typeof total !== "number" || !Number.isFinite(total) || typeof verified !== "number" || !Number.isFinite(verified) || typeof failed !== "number" || !Number.isFinite(failed)) {
1963
+ return fields;
1964
+ }
1965
+ fields.citationsVerified = verified;
1966
+ fields.citationsFailed = failed;
1967
+ fields.outcome = fields.ok && failed === 0 ? "success" : verified > 0 ? "partial" : "failed";
1968
+ return fields;
1969
+ }
1908
1970
  var MAX_STRING_CHARS = 500;
1909
1971
  var MAX_ARRAY_ENTRIES = 20;
1910
1972
  var MAX_DEPTH = 3;
@@ -2167,7 +2229,11 @@ var ToolGuard = class {
2167
2229
  at: next.at,
2168
2230
  tool: next.tool,
2169
2231
  ok: next.ok,
2232
+ executed: next.executed,
2170
2233
  durationMs: next.durationMs,
2234
+ ...next.citationsVerified !== void 0 ? { citationsVerified: next.citationsVerified } : {},
2235
+ ...next.citationsFailed !== void 0 ? { citationsFailed: next.citationsFailed } : {},
2236
+ ...next.outcome !== void 0 ? { outcome: next.outcome } : {},
2171
2237
  urls: next.urls,
2172
2238
  args: { truncated: true },
2173
2239
  ...next.error ? { error: next.error } : {}
@@ -2612,7 +2678,8 @@ var TOOL_OUTPUT_SCHEMAS = {
2612
2678
  },
2613
2679
  zen_tab_select: {
2614
2680
  tab: tabSchema,
2615
- activeSpaceId: z.string().nullable()
2681
+ activeSpaceId: z.string().nullable(),
2682
+ windowFocused: z.boolean().optional()
2616
2683
  },
2617
2684
  zen_glance: {
2618
2685
  opened: z.boolean(),
@@ -2627,7 +2694,9 @@ var TOOL_OUTPUT_SCHEMAS = {
2627
2694
  },
2628
2695
  zen_split_close: {
2629
2696
  unsplit: z.boolean(),
2630
- tabIds: z.array(z.string())
2697
+ tabIds: z.array(z.string()),
2698
+ closedResidue: z.number().optional(),
2699
+ limitation: z.string().optional()
2631
2700
  },
2632
2701
  zen_pin_tabs: {
2633
2702
  tabIds: z.array(z.string()),
@@ -2635,7 +2704,9 @@ var TOOL_OUTPUT_SCHEMAS = {
2635
2704
  },
2636
2705
  zen_essentials: {
2637
2706
  tabIds: z.array(z.string()),
2638
- changed: z.number()
2707
+ changed: z.number(),
2708
+ restored: z.number().optional(),
2709
+ limitation: z.string().optional()
2639
2710
  },
2640
2711
  zen_containers_list: {
2641
2712
  containers: z.array(containerInfoSchema)
@@ -2863,7 +2934,11 @@ var TOOL_OUTPUT_SCHEMAS = {
2863
2934
  at: z.string(),
2864
2935
  tool: z.string(),
2865
2936
  ok: z.boolean().optional(),
2937
+ executed: z.boolean().optional(),
2866
2938
  durationMs: z.number().optional(),
2939
+ citationsVerified: z.number().optional(),
2940
+ citationsFailed: z.number().optional(),
2941
+ outcome: z.enum(["success", "partial", "failed"]).optional(),
2867
2942
  args: z.unknown().optional(),
2868
2943
  error: z.looseObject({
2869
2944
  code: z.string().optional(),
@@ -4263,8 +4338,8 @@ function raceWithAbort(work, signal) {
4263
4338
  );
4264
4339
  });
4265
4340
  }
4341
+ var MAX_TAB_IDS_PER_CALL = 100;
4266
4342
  var SERVER_INSTRUCTIONS = `${BRAND} drives the user's Zen Browser from outside the page. Zen spaces are workspaces: tabs can live in a space the user is not looking at, and switching is instant for them.
4267
-
4268
4343
  Background research is the default workflow. Never take over the user's screen:
4269
4344
  1. Look first with zen_status, zen_spaces_list, and zen_tabs_list.
4270
4345
  2. zen_space_create with a short, descriptive name. It does not switch spaces by default. zen_template_apply("research") is faster when a ready-made layout fits.
@@ -4357,7 +4432,9 @@ function createZenMcpServer(runtime, config) {
4357
4432
  let urls = [];
4358
4433
  if (signal.aborted) {
4359
4434
  const error = new BridgeRequestError("cancelled", CANCELLED_MESSAGE2);
4360
- guard.audit(auditRecord(tool, started, args, urls, false, error));
4435
+ guard.audit(
4436
+ auditRecord(tool, started, args, urls, { ok: false, executed: false }, error)
4437
+ );
4361
4438
  logToolEvent("warning", tool, "cancelled", error.message);
4362
4439
  return errorResult(error);
4363
4440
  }
@@ -4366,7 +4443,9 @@ function createZenMcpServer(runtime, config) {
4366
4443
  "paused",
4367
4444
  "The user paused Zen MCP in the browser. No reads or changes are allowed until they press Resume. zen_events shows when access is restored."
4368
4445
  );
4369
- guard.audit(auditRecord(tool, started, args, urls, false, error));
4446
+ guard.audit(
4447
+ auditRecord(tool, started, args, urls, { ok: false, executed: false }, error)
4448
+ );
4370
4449
  logToolEvent("warning", tool, "paused", error.message);
4371
4450
  return errorResult(error);
4372
4451
  }
@@ -4376,7 +4455,14 @@ function createZenMcpServer(runtime, config) {
4376
4455
  guard.check(tool, args, urls);
4377
4456
  } catch (error) {
4378
4457
  guard.audit(
4379
- auditRecord(tool, started, args, urls, false, error)
4458
+ auditRecord(
4459
+ tool,
4460
+ started,
4461
+ args,
4462
+ urls,
4463
+ { ok: false, executed: false },
4464
+ error
4465
+ )
4380
4466
  );
4381
4467
  logToolEvent("warning", tool, errorCode(error), describeError2(error));
4382
4468
  return errorResult(error);
@@ -4389,7 +4475,9 @@ function createZenMcpServer(runtime, config) {
4389
4475
  if (signal.aborted) {
4390
4476
  throw new BridgeRequestError("cancelled", CANCELLED_MESSAGE2);
4391
4477
  }
4392
- guard.audit(auditRecord(tool, started, args, urls, true));
4478
+ guard.audit(
4479
+ auditRecord(tool, started, args, urls, auditOutcomeForResult(tool, value))
4480
+ );
4393
4481
  if (RESOURCE_CHANGING_TOOLS.has(tool)) {
4394
4482
  try {
4395
4483
  server.sendResourceListChanged();
@@ -4403,7 +4491,14 @@ function createZenMcpServer(runtime, config) {
4403
4491
  } catch (error) {
4404
4492
  const failure = signal.aborted ? new BridgeRequestError("cancelled", CANCELLED_MESSAGE2) : error;
4405
4493
  guard.audit(
4406
- auditRecord(tool, started, args, urls, false, failure)
4494
+ auditRecord(
4495
+ tool,
4496
+ started,
4497
+ args,
4498
+ urls,
4499
+ { ok: false, executed: false },
4500
+ failure
4501
+ )
4407
4502
  );
4408
4503
  const code = errorCode(failure);
4409
4504
  logToolEvent(
@@ -4618,7 +4713,7 @@ function createZenMcpServer(runtime, config) {
4618
4713
  title: "Close tabs",
4619
4714
  description: "Close one or more tabs by id. Closing tabs is destructive to the user's session; only close tabs the agent opened, or tabs the user explicitly named.",
4620
4715
  inputSchema: {
4621
- tabIds: z2.array(z2.string().min(1)).min(1).describe("Tab ids from zen_tabs_list.")
4716
+ tabIds: z2.array(z2.string().min(1)).min(1).max(MAX_TAB_IDS_PER_CALL).describe(`Tab ids from zen_tabs_list. At most ${MAX_TAB_IDS_PER_CALL} per call.`)
4622
4717
  },
4623
4718
  annotations: { readOnlyHint: false, destructiveHint: true }
4624
4719
  },
@@ -4834,7 +4929,9 @@ function createZenMcpServer(runtime, config) {
4834
4929
  description: "Create a Zen folder around existing tabs, optionally collapsed. Useful for grouping a batch of research tabs inside a space. Tabs must be in one space and cannot already belong to a folder or split view.",
4835
4930
  inputSchema: {
4836
4931
  label: z2.string().min(1).describe("Folder label."),
4837
- tabIds: z2.array(z2.string().min(1)).optional().describe("Tabs to move into the folder."),
4932
+ tabIds: z2.array(z2.string().min(1)).max(MAX_TAB_IDS_PER_CALL).optional().describe(
4933
+ `Tabs to move into the folder. At most ${MAX_TAB_IDS_PER_CALL} per call.`
4934
+ ),
4838
4935
  space: z2.string().optional().describe("Space id or name. Defaults to the tabs' space or the active space."),
4839
4936
  collapsed: z2.boolean().optional().describe("Create the folder collapsed.")
4840
4937
  },
@@ -4858,7 +4955,9 @@ function createZenMcpServer(runtime, config) {
4858
4955
  description: "Move existing tabs into an existing folder. The tabs must be in the folder's space and not already grouped.",
4859
4956
  inputSchema: {
4860
4957
  folderId: z2.string().min(1).describe("Folder id from zen_folders_list."),
4861
- tabIds: z2.array(z2.string().min(1)).min(1).describe("Tab ids to move.")
4958
+ tabIds: z2.array(z2.string().min(1)).min(1).max(MAX_TAB_IDS_PER_CALL).describe(
4959
+ `Tab ids to move. At most ${MAX_TAB_IDS_PER_CALL} per call.`
4960
+ )
4862
4961
  },
4863
4962
  annotations: { readOnlyHint: false }
4864
4963
  },
@@ -5865,11 +5964,23 @@ function createZenMcpServer(runtime, config) {
5865
5964
  value = await read();
5866
5965
  } catch (error) {
5867
5966
  guard.audit(
5868
- auditRecord(`resource:${uri}`, started, void 0, [], false, error)
5967
+ auditRecord(
5968
+ `resource:${uri}`,
5969
+ started,
5970
+ void 0,
5971
+ [],
5972
+ { ok: false, executed: false },
5973
+ error
5974
+ )
5869
5975
  );
5870
5976
  throw error;
5871
5977
  }
5872
- guard.audit(auditRecord(`resource:${uri}`, started, void 0, [], true));
5978
+ guard.audit(
5979
+ auditRecord(`resource:${uri}`, started, void 0, [], {
5980
+ ok: true,
5981
+ executed: true
5982
+ })
5983
+ );
5873
5984
  return value;
5874
5985
  });
5875
5986
  jsonResource("zen://status", "Zen status", () => runtime.status());
@@ -6009,12 +6120,16 @@ function registerJsonResource(server, uri, title, read) {
6009
6120
  }
6010
6121
  );
6011
6122
  }
6012
- function auditRecord(tool, started, args, urls, ok, error) {
6123
+ function auditRecord(tool, started, args, urls, fields, error) {
6013
6124
  return {
6014
6125
  at: (/* @__PURE__ */ new Date()).toISOString(),
6015
6126
  tool,
6016
- ok,
6127
+ ok: fields.ok,
6128
+ executed: fields.executed,
6017
6129
  durationMs: Date.now() - started,
6130
+ ...fields.citationsVerified !== void 0 ? { citationsVerified: fields.citationsVerified } : {},
6131
+ ...fields.citationsFailed !== void 0 ? { citationsFailed: fields.citationsFailed } : {},
6132
+ ...fields.outcome !== void 0 ? { outcome: fields.outcome } : {},
6018
6133
  ...args !== void 0 ? { args } : {},
6019
6134
  ...urls.length > 0 ? { urls: [...new Set(urls)].slice(0, 30) } : {},
6020
6135
  ...error !== void 0 ? { error: { code: errorCode(error), message: describeError2(error) } } : {}
@@ -6043,23 +6158,892 @@ function describeError2(error) {
6043
6158
  return name && name !== "Error" ? `${name}: ${message}` : message;
6044
6159
  }
6045
6160
 
6161
+ // src/onboard/clients.ts
6162
+ import { existsSync as existsSync7 } from "node:fs";
6163
+ import { homedir as homedir2 } from "node:os";
6164
+ import { dirname as dirname5, join as join7 } from "node:path";
6165
+ var MAX_CLIENT_CONFIG_BYTES = 20 * 1024 * 1024;
6166
+ var SERVER_ENTRY_NAME = "zen-mcp";
6167
+ var SERVER_ARGS = ["serve"];
6168
+ var CLINE_SETTINGS = join7(
6169
+ "User",
6170
+ "globalStorage",
6171
+ "saoudrizwan.claude-dev",
6172
+ "settings",
6173
+ "cline_mcp_settings.json"
6174
+ );
6175
+ var DEFINITIONS = [
6176
+ {
6177
+ id: "claude-code",
6178
+ label: "Claude Code",
6179
+ detail: "Anthropic's terminal agent",
6180
+ popular: true,
6181
+ format: "json",
6182
+ configPaths: (ctx) => [join7(ctx.home, ".claude.json")],
6183
+ detectPaths: (ctx) => [
6184
+ join7(ctx.home, ".claude.json"),
6185
+ join7(ctx.home, ".claude")
6186
+ ],
6187
+ json: {
6188
+ key: "mcpServers",
6189
+ entry: (ctx) => ({
6190
+ command: ctx.command,
6191
+ args: [...SERVER_ARGS]
6192
+ })
6193
+ }
6194
+ },
6195
+ {
6196
+ id: "claude-desktop",
6197
+ label: "Claude Desktop",
6198
+ detail: "The Claude desktop app",
6199
+ popular: true,
6200
+ format: "json",
6201
+ configPaths: (ctx) => [
6202
+ join7(ctx.configBase, "Claude", "claude_desktop_config.json")
6203
+ ],
6204
+ detectPaths: (ctx) => [join7(ctx.configBase, "Claude")],
6205
+ json: {
6206
+ key: "mcpServers",
6207
+ entry: (ctx) => ({
6208
+ command: ctx.command,
6209
+ args: [...SERVER_ARGS]
6210
+ })
6211
+ }
6212
+ },
6213
+ {
6214
+ id: "cursor",
6215
+ label: "Cursor",
6216
+ detail: "Cursor editor",
6217
+ popular: true,
6218
+ format: "json",
6219
+ configPaths: (ctx) => [join7(ctx.home, ".cursor", "mcp.json")],
6220
+ detectPaths: (ctx) => [join7(ctx.home, ".cursor")],
6221
+ json: {
6222
+ key: "mcpServers",
6223
+ entry: (ctx) => ({
6224
+ command: ctx.command,
6225
+ args: [...SERVER_ARGS]
6226
+ })
6227
+ }
6228
+ },
6229
+ {
6230
+ id: "vscode",
6231
+ label: "VS Code",
6232
+ detail: "GitHub Copilot agent mode",
6233
+ popular: true,
6234
+ format: "json",
6235
+ configPaths: (ctx) => [
6236
+ join7(ctx.configBase, "Code", "User", "mcp.json"),
6237
+ join7(ctx.configBase, "Code - Insiders", "User", "mcp.json")
6238
+ ],
6239
+ detectPaths: (ctx) => [
6240
+ join7(ctx.configBase, "Code", "User"),
6241
+ join7(ctx.configBase, "Code - Insiders", "User")
6242
+ ],
6243
+ json: {
6244
+ key: "servers",
6245
+ entry: (ctx) => ({
6246
+ type: "stdio",
6247
+ command: ctx.command,
6248
+ args: [...SERVER_ARGS]
6249
+ })
6250
+ }
6251
+ },
6252
+ {
6253
+ id: "codex",
6254
+ label: "Codex CLI",
6255
+ detail: "OpenAI Codex terminal agent",
6256
+ popular: true,
6257
+ format: "toml",
6258
+ configPaths: (ctx) => [
6259
+ join7(ctx.env.CODEX_HOME ?? join7(ctx.home, ".codex"), "config.toml")
6260
+ ],
6261
+ detectPaths: (ctx) => [
6262
+ ctx.env.CODEX_HOME ?? join7(ctx.home, ".codex")
6263
+ ],
6264
+ toml: {
6265
+ section: "mcp_servers",
6266
+ values: (ctx) => ({
6267
+ command: ctx.command,
6268
+ args: [...SERVER_ARGS]
6269
+ })
6270
+ }
6271
+ },
6272
+ {
6273
+ id: "gemini-cli",
6274
+ label: "Gemini CLI",
6275
+ detail: "Google's terminal agent",
6276
+ popular: true,
6277
+ format: "json",
6278
+ configPaths: (ctx) => [join7(ctx.home, ".gemini", "settings.json")],
6279
+ detectPaths: (ctx) => [join7(ctx.home, ".gemini")],
6280
+ json: {
6281
+ key: "mcpServers",
6282
+ entry: (ctx) => ({
6283
+ command: ctx.command,
6284
+ args: [...SERVER_ARGS]
6285
+ })
6286
+ }
6287
+ },
6288
+ {
6289
+ id: "windsurf",
6290
+ label: "Windsurf",
6291
+ detail: "Windsurf editor",
6292
+ popular: false,
6293
+ format: "json",
6294
+ configPaths: (ctx) => [
6295
+ join7(ctx.home, ".codeium", "windsurf", "mcp_config.json")
6296
+ ],
6297
+ detectPaths: (ctx) => [join7(ctx.home, ".codeium", "windsurf")],
6298
+ json: {
6299
+ key: "mcpServers",
6300
+ entry: (ctx) => ({
6301
+ command: ctx.command,
6302
+ args: [...SERVER_ARGS]
6303
+ })
6304
+ }
6305
+ },
6306
+ {
6307
+ id: "cline",
6308
+ label: "Cline",
6309
+ detail: "Cline extension for VS Code-compatible editors",
6310
+ popular: false,
6311
+ format: "json",
6312
+ configPaths: (ctx) => [
6313
+ join7(ctx.configBase, "Code", CLINE_SETTINGS),
6314
+ join7(ctx.configBase, "Cursor", CLINE_SETTINGS),
6315
+ join7(ctx.configBase, "Windsurf", CLINE_SETTINGS)
6316
+ ],
6317
+ detectPaths: (ctx) => [
6318
+ dirname5(join7(ctx.configBase, "Code", CLINE_SETTINGS)),
6319
+ dirname5(join7(ctx.configBase, "Cursor", CLINE_SETTINGS)),
6320
+ dirname5(join7(ctx.configBase, "Windsurf", CLINE_SETTINGS))
6321
+ ],
6322
+ json: {
6323
+ key: "mcpServers",
6324
+ entry: (ctx) => ({
6325
+ command: ctx.command,
6326
+ args: [...SERVER_ARGS]
6327
+ })
6328
+ }
6329
+ },
6330
+ {
6331
+ id: "zed",
6332
+ label: "Zed",
6333
+ detail: "Zed editor",
6334
+ popular: false,
6335
+ format: "json",
6336
+ configPaths: (ctx) => [
6337
+ join7(ctx.configBase, ctx.platform === "linux" ? "zed" : "Zed", "settings.json")
6338
+ ],
6339
+ detectPaths: (ctx) => [
6340
+ join7(ctx.configBase, ctx.platform === "linux" ? "zed" : "Zed")
6341
+ ],
6342
+ json: {
6343
+ key: "context_servers",
6344
+ entry: (ctx) => ({
6345
+ command: ctx.command,
6346
+ args: [...SERVER_ARGS]
6347
+ })
6348
+ }
6349
+ }
6350
+ ];
6351
+ function clientIds() {
6352
+ return DEFINITIONS.map((definition) => definition.id);
6353
+ }
6354
+ function catalog(ctx = {}) {
6355
+ const resolved = resolveContext(ctx);
6356
+ return DEFINITIONS.map((definition) => {
6357
+ const paths = definition.configPaths(resolved);
6358
+ return {
6359
+ id: definition.id,
6360
+ label: definition.label,
6361
+ detail: definition.detail,
6362
+ popular: definition.popular,
6363
+ detected: definition.detectPaths(resolved).some((path) => existsSync7(path)),
6364
+ configPath: paths.find((path) => existsSync7(path)) ?? paths[0],
6365
+ format: definition.format
6366
+ };
6367
+ });
6368
+ }
6369
+ function applyClient(id, ctx = {}) {
6370
+ const definition = DEFINITIONS.find((entry) => entry.id === id);
6371
+ if (!definition) {
6372
+ return {
6373
+ id,
6374
+ label: id,
6375
+ path: "",
6376
+ status: "failed",
6377
+ message: "unknown client"
6378
+ };
6379
+ }
6380
+ const resolved = resolveContext(ctx);
6381
+ const paths = definition.configPaths(resolved);
6382
+ const path = paths.find((candidate) => existsSync7(candidate)) ?? paths[0];
6383
+ const existed = existsSync7(path);
6384
+ try {
6385
+ const existing = existed ? readFileTextBounded(path, MAX_CLIENT_CONFIG_BYTES) : void 0;
6386
+ if (definition.format === "toml") {
6387
+ const toml = definition.toml;
6388
+ if (!toml) throw new Error("TOML settings are missing for this client");
6389
+ const next = mergeTomlServer(
6390
+ existing ?? "",
6391
+ `${toml.section}.${SERVER_ENTRY_NAME}`,
6392
+ toml.values(resolved)
6393
+ );
6394
+ atomicWritePrivate(path, next);
6395
+ } else {
6396
+ const json = definition.json;
6397
+ if (!json) throw new Error("JSON settings are missing for this client");
6398
+ const next = mergeJsonServer(existing, json.key, json.entry(resolved));
6399
+ atomicWritePrivate(path, next);
6400
+ }
6401
+ return {
6402
+ id: definition.id,
6403
+ label: definition.label,
6404
+ path,
6405
+ status: "ok",
6406
+ message: `${existed ? "Updated" : "Created"} ${path}`
6407
+ };
6408
+ } catch (error) {
6409
+ return {
6410
+ id: definition.id,
6411
+ label: definition.label,
6412
+ path,
6413
+ status: "failed",
6414
+ message: `${path}: ${error.message}`
6415
+ };
6416
+ }
6417
+ }
6418
+ function mergeJsonServer(existing, key, entry) {
6419
+ let text = existing;
6420
+ if (text && text.charCodeAt(0) === 65279) text = text.slice(1);
6421
+ if (!text || !text.trim()) {
6422
+ return `${JSON.stringify({ [key]: { [SERVER_ENTRY_NAME]: entry } }, null, 2)}
6423
+ `;
6424
+ }
6425
+ let parsed;
6426
+ try {
6427
+ parsed = JSON.parse(text);
6428
+ } catch (error) {
6429
+ try {
6430
+ return mergeJsoncServer(text, key, entry);
6431
+ } catch {
6432
+ throw new Error(
6433
+ `existing file is not valid JSON or JSONC (${error.message})`
6434
+ );
6435
+ }
6436
+ }
6437
+ if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
6438
+ throw new Error("existing file is not a JSON object");
6439
+ }
6440
+ const root = parsed;
6441
+ const current = root[key];
6442
+ if (current !== void 0 && (current === null || typeof current !== "object" || Array.isArray(current))) {
6443
+ throw new Error(`"${key}" is not a JSON object`);
6444
+ }
6445
+ root[key] = {
6446
+ ...current ?? {},
6447
+ [SERVER_ENTRY_NAME]: entry
6448
+ };
6449
+ return `${JSON.stringify(root, null, 2)}
6450
+ `;
6451
+ }
6452
+ function mergeJsoncServer(text, key, entry) {
6453
+ const rootStart = skipJsoncTrivia(text, 0);
6454
+ if (text[rootStart] !== "{") {
6455
+ throw new Error("the top level is not a JSON object");
6456
+ }
6457
+ const root = scanJsoncObject(text, rootStart);
6458
+ if (!root) throw new Error("the file has an unterminated object");
6459
+ const target = root.members.find((member) => member.key === key);
6460
+ if (!target) {
6461
+ return insertJsoncMember(text, root, key, {
6462
+ [SERVER_ENTRY_NAME]: entry
6463
+ });
6464
+ }
6465
+ if (text[target.valueStart] !== "{") {
6466
+ throw new Error(`"${key}" is not a JSON object`);
6467
+ }
6468
+ const serverMap = scanJsoncObject(text, target.valueStart);
6469
+ if (!serverMap) throw new Error(`"${key}" is not a complete object`);
6470
+ const current = serverMap.members.find(
6471
+ (member) => member.key === SERVER_ENTRY_NAME
6472
+ );
6473
+ if (!current) {
6474
+ return insertJsoncMember(text, serverMap, SERVER_ENTRY_NAME, entry);
6475
+ }
6476
+ const inline = !text.slice(current.valueStart, current.valueEnd).includes("\n");
6477
+ const replacement = inline ? JSON.stringify(entry) : indentJson(
6478
+ JSON.stringify(entry, null, 2),
6479
+ memberIndent(text, current.keyStart, serverMap)
6480
+ );
6481
+ return text.slice(0, current.valueStart) + replacement + text.slice(current.valueEnd);
6482
+ }
6483
+ function insertJsoncMember(text, object, name, entry) {
6484
+ let source = text;
6485
+ let close = object.close;
6486
+ const last = object.members[object.members.length - 1];
6487
+ if (last) {
6488
+ const between = source.slice(last.valueEnd, object.close);
6489
+ if (!between.includes(",")) {
6490
+ source = source.slice(0, last.valueEnd) + "," + source.slice(last.valueEnd);
6491
+ close += 1;
6492
+ }
6493
+ }
6494
+ const lineStart = source.lastIndexOf("\n", close - 1) + 1;
6495
+ const onOwnLine = lineStart > object.open && source.slice(lineStart, close).trim() === "";
6496
+ if (!onOwnLine) {
6497
+ const inline = JSON.stringify({ [name]: entry }).slice(1, -1);
6498
+ return `${source.slice(0, close)} ${inline} ${source.slice(close)}`;
6499
+ }
6500
+ const indent = last ? memberIndent(source, last.keyStart, object) : `${closeIndent(source, object)} `;
6501
+ const entryText = `${JSON.stringify(name)}: ${indentJson(
6502
+ JSON.stringify(entry, null, 2),
6503
+ indent
6504
+ )}`;
6505
+ return source.slice(0, lineStart) + `${indent}${entryText}
6506
+ ` + source.slice(lineStart);
6507
+ }
6508
+ function scanJsoncObject(text, open) {
6509
+ const members = [];
6510
+ let index = open + 1;
6511
+ let expectingMember = true;
6512
+ while (true) {
6513
+ index = skipJsoncTrivia(text, index);
6514
+ if (index >= text.length) return null;
6515
+ const char = text[index];
6516
+ if (char === "}") {
6517
+ return { open, close: index, members };
6518
+ }
6519
+ if (!expectingMember) {
6520
+ if (char !== ",") return null;
6521
+ index += 1;
6522
+ expectingMember = true;
6523
+ continue;
6524
+ }
6525
+ if (char !== '"') return null;
6526
+ const keyStart = index;
6527
+ const keyEnd = scanJsoncString(text, index);
6528
+ if (keyEnd < 0) return null;
6529
+ let key;
6530
+ try {
6531
+ key = JSON.parse(text.slice(keyStart, keyEnd));
6532
+ } catch {
6533
+ return null;
6534
+ }
6535
+ index = skipJsoncTrivia(text, keyEnd);
6536
+ if (text[index] !== ":") return null;
6537
+ index = skipJsoncTrivia(text, index + 1);
6538
+ const valueStart = index;
6539
+ const valueEnd = skipJsoncValue(text, index);
6540
+ if (valueEnd < 0) return null;
6541
+ members.push({ key, keyStart, valueStart, valueEnd });
6542
+ index = skipJsoncTrivia(text, valueEnd);
6543
+ expectingMember = false;
6544
+ }
6545
+ }
6546
+ function skipJsoncTrivia(text, index) {
6547
+ let cursor = index;
6548
+ while (cursor < text.length) {
6549
+ const char = text[cursor];
6550
+ if (/\s/.test(char)) {
6551
+ cursor += 1;
6552
+ } else if (char === "/" && text[cursor + 1] === "/") {
6553
+ cursor += 2;
6554
+ while (cursor < text.length && text[cursor] !== "\n") cursor += 1;
6555
+ } else if (char === "/" && text[cursor + 1] === "*") {
6556
+ cursor += 2;
6557
+ while (cursor < text.length && !(text[cursor] === "*" && text[cursor + 1] === "/")) {
6558
+ cursor += 1;
6559
+ }
6560
+ cursor += 2;
6561
+ } else {
6562
+ break;
6563
+ }
6564
+ }
6565
+ return Math.min(cursor, text.length);
6566
+ }
6567
+ function scanJsoncString(text, index) {
6568
+ let cursor = index + 1;
6569
+ while (cursor < text.length) {
6570
+ if (text[cursor] === "\\") {
6571
+ cursor += 2;
6572
+ } else if (text[cursor] === '"') {
6573
+ return cursor + 1;
6574
+ } else {
6575
+ cursor += 1;
6576
+ }
6577
+ }
6578
+ return -1;
6579
+ }
6580
+ function skipJsoncValue(text, index) {
6581
+ const char = text[index];
6582
+ if (char === '"') return scanJsoncString(text, index);
6583
+ if (char === "{" || char === "[") {
6584
+ let depth = 0;
6585
+ let cursor2 = index;
6586
+ while (cursor2 < text.length) {
6587
+ const current = text[cursor2];
6588
+ if (current === '"') {
6589
+ const end = scanJsoncString(text, cursor2);
6590
+ if (end < 0) return -1;
6591
+ cursor2 = end;
6592
+ continue;
6593
+ }
6594
+ if (current === "/" && (text[cursor2 + 1] === "/" || text[cursor2 + 1] === "*")) {
6595
+ cursor2 = skipJsoncTrivia(text, cursor2);
6596
+ continue;
6597
+ }
6598
+ if (current === "{" || current === "[") depth += 1;
6599
+ else if (current === "}" || current === "]") {
6600
+ depth -= 1;
6601
+ if (depth === 0) return cursor2 + 1;
6602
+ }
6603
+ cursor2 += 1;
6604
+ }
6605
+ return -1;
6606
+ }
6607
+ let cursor = index;
6608
+ while (cursor < text.length && !/[\s,\]}]/.test(text[cursor])) cursor += 1;
6609
+ return cursor > index ? cursor : -1;
6610
+ }
6611
+ function memberIndent(text, keyStart, object) {
6612
+ let start = keyStart;
6613
+ while (start > object.open && (text[start - 1] === " " || text[start - 1] === " ")) {
6614
+ start -= 1;
6615
+ }
6616
+ if (start > object.open && text[start - 1] === "\n") {
6617
+ return text.slice(start, keyStart);
6618
+ }
6619
+ const openLine = text.lastIndexOf("\n", object.open - 1) + 1;
6620
+ return `${" ".repeat(object.open - openLine + 2)}`;
6621
+ }
6622
+ function closeIndent(text, object) {
6623
+ const start = text.lastIndexOf("\n", object.close - 1) + 1;
6624
+ const between = text.slice(start, object.close);
6625
+ if (/^[ \t]*$/.test(between)) return between;
6626
+ const openLine = text.lastIndexOf("\n", object.open - 1) + 1;
6627
+ return " ".repeat(object.open - openLine);
6628
+ }
6629
+ function indentJson(value, indent) {
6630
+ return value.replace(/\n/g, `
6631
+ ${indent}`);
6632
+ }
6633
+ function mergeTomlServer(existing, table, values) {
6634
+ const lines = existing ? existing.replace(/\r\n/g, "\n").split("\n") : [];
6635
+ const header = `[${table}]`;
6636
+ const headerPattern = new RegExp(
6637
+ `^\\s*\\[\\s*(?:"${escapeRegExp(table)}"|'${escapeRegExp(table)}'|${escapeRegExp(
6638
+ table
6639
+ )})\\s*\\]\\s*(?:#.*)?$`
6640
+ );
6641
+ const block = [
6642
+ header,
6643
+ ...Object.entries(values).map(
6644
+ ([name, value]) => `${name} = ${tomlValue(value)}`
6645
+ )
6646
+ ];
6647
+ const start = lines.findIndex((line) => headerPattern.test(line));
6648
+ if (start >= 0) {
6649
+ let end = start + 1;
6650
+ while (end < lines.length && !/^\s*\[/.test(lines[end])) end += 1;
6651
+ lines.splice(start, end - start, ...block);
6652
+ } else {
6653
+ while (lines.length > 0 && lines[lines.length - 1].trim() === "") {
6654
+ lines.pop();
6655
+ }
6656
+ if (lines.length > 0) lines.push("");
6657
+ lines.push(...block);
6658
+ }
6659
+ return `${lines.join("\n")}
6660
+ `;
6661
+ }
6662
+ function agentSetupPrompt(command = "zen-mcp", ctx = {}) {
6663
+ const resolved = resolveContext({ ...ctx, command });
6664
+ const locations = DEFINITIONS.map((definition) => {
6665
+ const path = placeholderPath(definition.configPaths(resolved)[0], resolved);
6666
+ const detail = definition.id === "vscode" ? " (Insiders uses the same path under `Code - Insiders`)" : definition.id === "cline" ? " (same relative path under Cursor or Windsurf)" : "";
6667
+ const shape = definition.id === "vscode" ? ' top-level `servers`, entry needs `"type": "stdio"`' : definition.id === "zed" ? " top-level `context_servers`" : definition.id === "codex" ? " TOML table `[mcp_servers.zen-mcp]`" : " top-level `mcpServers`";
6668
+ return `- ${definition.label}: \`${path}\`${detail};${shape}.`;
6669
+ }).join("\n");
6670
+ return [
6671
+ "# Set up Zen MCP in this agent",
6672
+ "",
6673
+ "Add a local stdio MCP server named `zen-mcp` to the agent you are running in.",
6674
+ "Do the work yourself by running commands and editing the client's configuration.",
6675
+ "Do not ask me to run any of these commands. Only ask me when a step needs a",
6676
+ "browser approval or when no configuration file can be found.",
6677
+ "",
6678
+ "## Server definition",
6679
+ "",
6680
+ "- Name: zen-mcp",
6681
+ "- Transport: stdio, local process (no URL, no OAuth)",
6682
+ `- Command: ${command}`,
6683
+ `- Arguments: ${JSON.stringify(SERVER_ARGS)}`,
6684
+ "- Environment: none",
6685
+ "",
6686
+ "If the command is not on PATH, resolve it with `where <command>` on Windows or",
6687
+ "`command -v <command>` on macOS and Linux. Use the absolute path as the command",
6688
+ "and keep the arguments unchanged.",
6689
+ "",
6690
+ "## 1. Prefer the client's own command",
6691
+ "",
6692
+ "If the client has a first-class way to add a stdio server, use it instead of",
6693
+ "editing files. Example for Claude Code:",
6694
+ "",
6695
+ ` claude mcp add zen-mcp -- "${command}" serve`,
6696
+ "",
6697
+ "Then skip to step 4. An add command that expects a URL is the wrong tool.",
6698
+ "",
6699
+ "## 2. Find the configuration file",
6700
+ "",
6701
+ "Use the first location that exists for this client:",
6702
+ "",
6703
+ locations,
6704
+ "",
6705
+ "For any other client, look for a top-level `mcpServers`, `servers` or",
6706
+ "`context_servers` object in its settings, or follow its official MCP",
6707
+ "documentation. Ask me only if no configuration file can be found.",
6708
+ "",
6709
+ "## 3. Merge the entry",
6710
+ "",
6711
+ "- Preserve every existing server, key, comment and trailing comma.",
6712
+ "- Edit only the `zen-mcp` member. If it already exists, update it instead of",
6713
+ " adding a duplicate.",
6714
+ "- Never replace the whole file with a generated object.",
6715
+ "- For JSONC files (VS Code, Zed), splice the `zen-mcp` member in place so",
6716
+ " comments and formatting survive.",
6717
+ "- Do not reorder or reformat unrelated settings.",
6718
+ "",
6719
+ "Standard JSON clients use a top-level `mcpServers` object:",
6720
+ "",
6721
+ " {",
6722
+ ' "mcpServers": {',
6723
+ ' "zen-mcp": {',
6724
+ ' "command": "<command>",',
6725
+ ' "args": ["serve"]',
6726
+ " }",
6727
+ " }",
6728
+ " }",
6729
+ "",
6730
+ "VS Code uses `servers` and requires the transport type:",
6731
+ "",
6732
+ " {",
6733
+ ' "servers": {',
6734
+ ' "zen-mcp": {',
6735
+ ' "type": "stdio",',
6736
+ ' "command": "<command>",',
6737
+ ' "args": ["serve"]',
6738
+ " }",
6739
+ " }",
6740
+ " }",
6741
+ "",
6742
+ "Zed uses `context_servers` with the same command and args:",
6743
+ "",
6744
+ " {",
6745
+ ' "context_servers": {',
6746
+ ' "zen-mcp": {',
6747
+ ' "command": "<command>",',
6748
+ ' "args": ["serve"]',
6749
+ " }",
6750
+ " }",
6751
+ " }",
6752
+ "",
6753
+ "Codex CLI uses TOML:",
6754
+ "",
6755
+ " [mcp_servers.zen-mcp]",
6756
+ ' command = "<command>"',
6757
+ ' args = ["serve"]',
6758
+ "",
6759
+ "## 4. Validate",
6760
+ "",
6761
+ "- Parse the file in its own format and confirm there is exactly one `zen-mcp`",
6762
+ " entry with the command and arguments above.",
6763
+ "- Confirm no other server was removed, renamed or changed.",
6764
+ "- If the client has a list command such as `claude mcp list`, run it and confirm",
6765
+ " `zen-mcp` appears. Do not start the server manually just to test it.",
6766
+ "",
6767
+ "## 5. Reload",
6768
+ "",
6769
+ "Restart the client or run its reload command so it picks up the new server.",
6770
+ "Tell me which one you did.",
6771
+ "",
6772
+ "## 6. Report",
6773
+ "",
6774
+ "Reply with the client name, the file or command you changed, the validation",
6775
+ "result and the reload instruction. End with:",
6776
+ "",
6777
+ " \u250C\u2500 Zen MCP setup \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510",
6778
+ " \u2502 \u2713 Server zen-mcp (stdio) \u2502",
6779
+ " \u2502 \u2713 Config <file or command> \u2502",
6780
+ " \u2502 \u2502",
6781
+ " \u2502 Restart <client> to load the server. \u2502",
6782
+ " \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518",
6783
+ "",
6784
+ "## Constraints",
6785
+ "",
6786
+ "- Zen MCP runs locally over stdio. Do not add a remote URL, API key or OAuth",
6787
+ " flow, and do not change the command or arguments.",
6788
+ "- Do not install or patch anything inside Zen; the bridge is injected at",
6789
+ " runtime.",
6790
+ "- Do not launch a browser to test the server. On the first real browser tool",
6791
+ ' call, Zen shows an approval card. Tell me to click "Allow this session".'
6792
+ ].join("\n");
6793
+ }
6794
+ function resolveContext(ctx) {
6795
+ const platform = ctx.platform ?? process.platform;
6796
+ const home = ctx.home ?? homedir2();
6797
+ const env = ctx.env ?? process.env;
6798
+ const command = ctx.command?.trim() || "zen-mcp";
6799
+ const configBase = platform === "win32" ? env.APPDATA ?? join7(home, "AppData", "Roaming") : platform === "darwin" ? join7(home, "Library", "Application Support") : env.XDG_CONFIG_HOME ?? join7(home, ".config");
6800
+ return { command, home, platform, env, configBase };
6801
+ }
6802
+ function placeholderPath(path, ctx) {
6803
+ const windows = ctx.platform === "win32";
6804
+ const roots = [];
6805
+ const codexHome = ctx.env.CODEX_HOME;
6806
+ if (codexHome) {
6807
+ roots.push([codexHome, windows ? "%CODEX_HOME%" : "$CODEX_HOME"]);
6808
+ }
6809
+ if (windows) {
6810
+ roots.push([ctx.configBase, "%APPDATA%"]);
6811
+ } else if (ctx.env.XDG_CONFIG_HOME) {
6812
+ roots.push([ctx.configBase, "$XDG_CONFIG_HOME"]);
6813
+ }
6814
+ roots.push([ctx.home, windows ? "%USERPROFILE%" : "~"]);
6815
+ const normalize = (value) => {
6816
+ const slashed = value.replace(/\\/g, "/");
6817
+ return windows ? slashed.toLowerCase() : slashed;
6818
+ };
6819
+ const target = normalize(path);
6820
+ for (const [root, label] of roots) {
6821
+ const prefix = normalize(root);
6822
+ if (target === prefix) return label;
6823
+ if (target.startsWith(`${prefix}/`)) {
6824
+ const rest = path.slice(root.length);
6825
+ const separator = windows ? "\\" : "/";
6826
+ return label + rest.replace(windows ? /\//g : /\\/g, separator);
6827
+ }
6828
+ }
6829
+ return path;
6830
+ }
6831
+ function tomlValue(value) {
6832
+ if (Array.isArray(value)) {
6833
+ return `[${value.map((entry) => JSON.stringify(entry)).join(", ")}]`;
6834
+ }
6835
+ return JSON.stringify(value);
6836
+ }
6837
+ function escapeRegExp(value) {
6838
+ return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
6839
+ }
6840
+
6841
+ // src/onboard/picker.ts
6842
+ import { emitKeypressEvents } from "node:readline";
6843
+
6844
+ // src/onboard/theme.ts
6845
+ function createTheme(output) {
6846
+ const color = Boolean(output.isTTY) && !process.env.NO_COLOR && process.env.TERM !== "dumb";
6847
+ const wrap = (code) => (text) => color ? `\x1B[${code}m${text}\x1B[0m` : text;
6848
+ return {
6849
+ color,
6850
+ unicode: Boolean(output.isTTY),
6851
+ bold: wrap("1"),
6852
+ dim: wrap("2"),
6853
+ cyan: wrap("36"),
6854
+ green: wrap("32"),
6855
+ yellow: wrap("33"),
6856
+ red: wrap("31")
6857
+ };
6858
+ }
6859
+
6860
+ // src/onboard/picker.ts
6861
+ var SelectionCancelled = class extends Error {
6862
+ };
6863
+ var OTHER_ID = "other";
6864
+ function buildOptions(clients) {
6865
+ return [
6866
+ ...clients.map((client) => ({
6867
+ id: client.id,
6868
+ label: client.label,
6869
+ detail: client.detail,
6870
+ detected: client.detected,
6871
+ popular: client.popular,
6872
+ selected: client.detected
6873
+ })),
6874
+ {
6875
+ id: OTHER_ID,
6876
+ label: "Other MCP client",
6877
+ detail: "Print a setup prompt for any agent",
6878
+ detected: false,
6879
+ popular: false,
6880
+ other: true,
6881
+ selected: false
6882
+ }
6883
+ ];
6884
+ }
6885
+ function moveCursor(options, cursor, delta) {
6886
+ const size = options.length;
6887
+ return ((cursor + delta) % size + size) % size;
6888
+ }
6889
+ function toggleAll(options, selected) {
6890
+ return options.map(
6891
+ (option) => option.other ? option : { ...option, selected }
6892
+ );
6893
+ }
6894
+ function pickerResult(options) {
6895
+ return {
6896
+ selected: options.filter((option) => !option.other && option.selected).map((option) => option.id),
6897
+ other: options.some((option) => option.other && option.selected)
6898
+ };
6899
+ }
6900
+ async function pickClients(options, streams = {}) {
6901
+ const input = streams.input ?? process.stdin;
6902
+ const output = streams.output ?? process.stdout;
6903
+ if (!input.isTTY || !output.isTTY) {
6904
+ throw new Error("the client picker needs an interactive terminal");
6905
+ }
6906
+ const rows = [...options];
6907
+ let cursor = 0;
6908
+ let painted = 0;
6909
+ const theme = createTheme(output);
6910
+ const columns = output.columns ?? 80;
6911
+ const width = Math.max(44, Math.min(columns - 4, 64));
6912
+ const showDetail = columns >= 72;
6913
+ const detailLimit = Math.max(18, columns - 40);
6914
+ const rule = theme.dim("\u2500".repeat(width));
6915
+ const paint = (final = false) => {
6916
+ const lines = [];
6917
+ const count = rows.filter((row) => !row.other && row.selected).length;
6918
+ const otherSelected = rows.some((row) => row.other && row.selected);
6919
+ lines.push(
6920
+ ` ${theme.cyan("\u25C6")} ${theme.bold("ZEN MCP")} ${theme.dim("onboard")}`
6921
+ );
6922
+ lines.push(` ${rule}`);
6923
+ lines.push(` ${theme.dim("Connect Zen to the agents you use.")}`);
6924
+ lines.push("");
6925
+ rows.forEach((row, index) => {
6926
+ const previous = rows[index - 1];
6927
+ if (index === 0) {
6928
+ lines.push(` ${theme.dim("POPULAR")}`);
6929
+ } else if (row.other) {
6930
+ lines.push("");
6931
+ lines.push(` ${theme.dim("OTHER")}`);
6932
+ } else if (previous?.popular && !row.popular) {
6933
+ lines.push("");
6934
+ lines.push(` ${theme.dim("MORE CLIENTS")}`);
6935
+ }
6936
+ const marker = final ? " " : index === cursor ? theme.cyan("\u276F") : " ";
6937
+ const box = row.selected ? theme.green("[\u25CF]") : theme.dim("[ ]");
6938
+ const padding = row.label.padEnd(20);
6939
+ const label = index === cursor && !final ? theme.bold(padding) : padding;
6940
+ const tagName = row.detected ? "detected" : row.popular ? "popular" : "";
6941
+ const tag = tagName ? row.detected ? theme.green(tagName.padEnd(10)) : theme.dim(tagName.padEnd(10)) : " ".repeat(10);
6942
+ const detail = !showDetail ? "" : row.detail.length > detailLimit ? `${row.detail.slice(0, detailLimit - 1).trimEnd()}\u2026` : row.detail;
6943
+ lines.push(
6944
+ ` ${marker} ${box} ${label} ${tag} ${theme.dim(detail)}`.trimEnd()
6945
+ );
6946
+ });
6947
+ lines.push("");
6948
+ if (!rows.some((row) => row.detected)) {
6949
+ lines.push(
6950
+ ` ${theme.yellow("No clients detected.")} ${theme.dim(
6951
+ "Select one below, or choose Other."
6952
+ )}`
6953
+ );
6954
+ }
6955
+ const selection = count > 0 ? theme.green(`${count} selected${otherSelected ? " + other" : ""}`) : otherSelected ? theme.green("other client") : theme.dim("nothing selected");
6956
+ lines.push(` ${selection}`);
6957
+ lines.push(
6958
+ final ? ` ${theme.dim("Selection confirmed.")}` : ` ${theme.dim(
6959
+ "\u2191\u2193 move \xB7 space toggle \xB7 a all \xB7 enter confirm \xB7 esc cancel"
6960
+ )}`
6961
+ );
6962
+ if (painted > 0) {
6963
+ output.write(`\x1B[${painted}A`);
6964
+ output.write("\x1B[0J");
6965
+ }
6966
+ output.write(`${lines.join("\n")}
6967
+ `);
6968
+ painted = lines.length;
6969
+ };
6970
+ emitKeypressEvents(input);
6971
+ input.setRawMode(true);
6972
+ input.resume();
6973
+ output.write("\x1B[?25l");
6974
+ paint();
6975
+ return await new Promise((resolve3, reject) => {
6976
+ const cleanup = () => {
6977
+ input.off("keypress", onKey);
6978
+ input.setRawMode(false);
6979
+ input.pause();
6980
+ output.write("\x1B[?25h");
6981
+ };
6982
+ const finish = (result) => {
6983
+ cleanup();
6984
+ paint(true);
6985
+ resolve3(result);
6986
+ };
6987
+ const onKey = (_str, key) => {
6988
+ if (key.ctrl && key.name === "c") {
6989
+ cleanup();
6990
+ output.write("\n");
6991
+ reject(new SelectionCancelled("cancelled"));
6992
+ return;
6993
+ }
6994
+ if (key.name === "escape") {
6995
+ cleanup();
6996
+ output.write("\n");
6997
+ reject(new SelectionCancelled("cancelled"));
6998
+ return;
6999
+ }
7000
+ switch (key.name) {
7001
+ case "up":
7002
+ cursor = moveCursor(rows, cursor, -1);
7003
+ break;
7004
+ case "down":
7005
+ cursor = moveCursor(rows, cursor, 1);
7006
+ break;
7007
+ case "space":
7008
+ case "spacebar":
7009
+ rows[cursor] = { ...rows[cursor], selected: !rows[cursor].selected };
7010
+ break;
7011
+ case "a":
7012
+ if (!key.ctrl && !key.meta) {
7013
+ const everySelected = rows.filter((row) => !row.other).every((row) => row.selected);
7014
+ rows.splice(0, rows.length, ...toggleAll(rows, !everySelected));
7015
+ }
7016
+ break;
7017
+ case "return":
7018
+ case "enter":
7019
+ finish(pickerResult(rows));
7020
+ return;
7021
+ default:
7022
+ break;
7023
+ }
7024
+ paint();
7025
+ };
7026
+ input.on("keypress", onKey);
7027
+ });
7028
+ }
7029
+
6046
7030
  // src/zen/doctor.ts
6047
- import { existsSync as existsSync8 } from "node:fs";
7031
+ import { existsSync as existsSync9 } from "node:fs";
6048
7032
 
6049
7033
  // src/zen/launcher.ts
6050
7034
  import { randomUUID as randomUUID2 } from "node:crypto";
6051
7035
  import { execFileSync, spawn } from "node:child_process";
6052
7036
  import {
6053
7037
  closeSync as closeSync3,
6054
- existsSync as existsSync7,
7038
+ existsSync as existsSync8,
6055
7039
  mkdirSync as mkdirSync2,
6056
7040
  openSync as openSync3,
6057
7041
  readlinkSync,
6058
7042
  statSync as statSync3
6059
7043
  } from "node:fs";
6060
7044
  import net from "node:net";
6061
- import { homedir as homedir2 } from "node:os";
6062
- import { join as join7, resolve as resolve2 } from "node:path";
7045
+ import { homedir as homedir3 } from "node:os";
7046
+ import { join as join8, resolve as resolve2 } from "node:path";
6063
7047
  var logger = createLogger("launcher");
6064
7048
  var ZenLaunchError = class extends Error {
6065
7049
  name = "ZenLaunchError";
@@ -6067,7 +7051,7 @@ var ZenLaunchError = class extends Error {
6067
7051
  function resolvedProfilePath(config) {
6068
7052
  if (config.profilePath) return resolve2(config.profilePath);
6069
7053
  if (config.useDefaultProfile) return null;
6070
- return join7(config.dataDir ?? dataDirPath(), "agent-profile");
7054
+ return join8(config.dataDir ?? dataDirPath(), "agent-profile");
6071
7055
  }
6072
7056
  function buildLaunchArgs(config, extraArgs = []) {
6073
7057
  const profile = resolvedProfilePath(config);
@@ -6078,7 +7062,7 @@ function buildLaunchArgs(config, extraArgs = []) {
6078
7062
  }
6079
7063
  function findZenExecutable(config) {
6080
7064
  if (config.zenPath) {
6081
- if (!existsSync7(config.zenPath)) {
7065
+ if (!existsSync8(config.zenPath)) {
6082
7066
  throw new ZenLaunchError(
6083
7067
  `Configured Zen executable does not exist: ${config.zenPath}`
6084
7068
  );
@@ -6086,7 +7070,7 @@ function findZenExecutable(config) {
6086
7070
  return config.zenPath;
6087
7071
  }
6088
7072
  for (const candidate of zenCandidates()) {
6089
- if (!candidate || !existsSync7(candidate)) continue;
7073
+ if (!candidate || !existsSync8(candidate)) continue;
6090
7074
  try {
6091
7075
  if (!statSync3(candidate).isFile()) continue;
6092
7076
  } catch {
@@ -6102,20 +7086,20 @@ function zenCandidates() {
6102
7086
  switch (process.platform) {
6103
7087
  case "win32":
6104
7088
  return [
6105
- join7(process.env.ProgramFiles ?? "C:\\Program Files", "Zen Browser", "zen.exe"),
6106
- join7(
7089
+ join8(process.env.ProgramFiles ?? "C:\\Program Files", "Zen Browser", "zen.exe"),
7090
+ join8(
6107
7091
  process.env["ProgramFiles(x86)"] ?? "C:\\Program Files (x86)",
6108
7092
  "Zen Browser",
6109
7093
  "zen.exe"
6110
7094
  ),
6111
- join7(
6112
- process.env.LOCALAPPDATA ?? join7(homedir2(), "AppData", "Local"),
7095
+ join8(
7096
+ process.env.LOCALAPPDATA ?? join8(homedir3(), "AppData", "Local"),
6113
7097
  "Programs",
6114
7098
  "Zen Browser",
6115
7099
  "zen.exe"
6116
7100
  ),
6117
- join7(
6118
- process.env.LOCALAPPDATA ?? join7(homedir2(), "AppData", "Local"),
7101
+ join8(
7102
+ process.env.LOCALAPPDATA ?? join8(homedir3(), "AppData", "Local"),
6119
7103
  "Zen Browser",
6120
7104
  "zen.exe"
6121
7105
  )
@@ -6123,7 +7107,7 @@ function zenCandidates() {
6123
7107
  case "darwin":
6124
7108
  return [
6125
7109
  "/Applications/Zen Browser.app/Contents/MacOS/zen",
6126
- join7(homedir2(), "Applications", "Zen Browser.app", "Contents", "MacOS", "zen")
7110
+ join8(homedir3(), "Applications", "Zen Browser.app", "Contents", "MacOS", "zen")
6127
7111
  ];
6128
7112
  default:
6129
7113
  return [
@@ -6132,8 +7116,8 @@ function zenCandidates() {
6132
7116
  "/opt/zen/zen",
6133
7117
  "/usr/lib/zen/zen",
6134
7118
  "/var/lib/flatpak/exports/bin/app.zen_browser.zen",
6135
- join7(
6136
- homedir2(),
7119
+ join8(
7120
+ homedir3(),
6137
7121
  ".local/share/flatpak/exports/bin/app.zen_browser.zen"
6138
7122
  ),
6139
7123
  "/snap/bin/zen-browser"
@@ -6276,8 +7260,8 @@ function assertProfileAvailable(profilePath) {
6276
7260
  }
6277
7261
  function isProfileLocked(profilePath) {
6278
7262
  if (process.platform === "win32") {
6279
- const lock = join7(profilePath, "parent.lock");
6280
- if (!existsSync7(lock)) return false;
7263
+ const lock = join8(profilePath, "parent.lock");
7264
+ if (!existsSync8(lock)) return false;
6281
7265
  try {
6282
7266
  closeSync3(openSync3(lock, "r+"));
6283
7267
  return false;
@@ -6288,7 +7272,7 @@ function isProfileLocked(profilePath) {
6288
7272
  for (const name of [".parentlock", "lock", "parent.lock"]) {
6289
7273
  let target;
6290
7274
  try {
6291
- target = readlinkSync(join7(profilePath, name));
7275
+ target = readlinkSync(join8(profilePath, name));
6292
7276
  } catch {
6293
7277
  continue;
6294
7278
  }
@@ -6324,9 +7308,9 @@ async function runDoctor(config, options = {}) {
6324
7308
  const path = configFilePath();
6325
7309
  checks.push({
6326
7310
  name: "Config",
6327
- status: existsSync8(path) ? "ok" : "warn",
6328
- detail: existsSync8(path) ? `Loaded ${path}` : "No config file yet; built-in defaults are in use.",
6329
- hint: existsSync8(path) ? void 0 : "Run `zen-mcp setup` to detect Zen and write a config file."
7311
+ status: existsSync9(path) ? "ok" : "warn",
7312
+ detail: existsSync9(path) ? `Loaded ${path}` : "No config file yet; built-in defaults are in use.",
7313
+ hint: existsSync9(path) ? void 0 : "Run `zen-mcp setup` to detect Zen and write a config file."
6330
7314
  });
6331
7315
  try {
6332
7316
  checks.push({
@@ -6343,7 +7327,7 @@ async function runDoctor(config, options = {}) {
6343
7327
  });
6344
7328
  }
6345
7329
  const bridgeBundle = options.bridgeScriptPath ?? resolveBridgeScriptPath();
6346
- const bundleExists = existsSync8(bridgeBundle);
7330
+ const bundleExists = existsSync9(bridgeBundle);
6347
7331
  checks.push({
6348
7332
  name: "Bridge bundle",
6349
7333
  status: bundleExists ? "ok" : "fail",
@@ -6941,13 +7925,27 @@ var MarionetteClient = class {
6941
7925
  function wrapScript(body) {
6942
7926
  return [
6943
7927
  "const __zenMcpDone = arguments[arguments.length - 1];",
7928
+ // Gecko's Error.stack contains frames only, with no name or message line,
7929
+ // so report all three. Otherwise a sandbox failure arrives as line numbers
7930
+ // with no explanation.
7931
+ "const __zenMcpDescribe = (error) => {",
7932
+ " try {",
7933
+ " if (!error || typeof error !== 'object') return String(error);",
7934
+ " const name = error.name ? String(error.name) : 'Error';",
7935
+ " const message = error.message ? String(error.message) : String(error);",
7936
+ " const stack = error.stack ? String(error.stack) : '';",
7937
+ " return stack ? name + ': ' + message + '\\n' + stack : name + ': ' + message;",
7938
+ " } catch (describeError) {",
7939
+ " return 'Script threw an error that could not be described';",
7940
+ " }",
7941
+ "};",
6944
7942
  "(async () => {",
6945
7943
  body,
6946
7944
  "})().then(",
6947
7945
  " (value) => __zenMcpDone({ __zenMcpOk: true, value }),",
6948
7946
  " (error) => __zenMcpDone({",
6949
7947
  " __zenMcpOk: false,",
6950
- " error: String((error && (error.stack || error.message)) || error),",
7948
+ " error: __zenMcpDescribe(error),",
6951
7949
  " })",
6952
7950
  ");"
6953
7951
  ].join("\n");
@@ -7169,7 +8167,27 @@ var ZenRuntime = class {
7169
8167
  let nonce = null;
7170
8168
  try {
7171
8169
  nonce = await this.marionette.executeChrome(
7172
- 'return Services.env.get("ZEN_MCP_LAUNCH_NONCE") ?? null;',
8170
+ [
8171
+ // Marionette's chrome sandbox exposes these globals but cannot load
8172
+ // resource:// modules, so use them directly and fall back to the
8173
+ // component service when a build hides `Services`.
8174
+ 'const env = typeof Services !== "undefined" && Services.env',
8175
+ " ? Services.env",
8176
+ ' : typeof Cc !== "undefined" && typeof Ci !== "undefined"',
8177
+ ' ? Cc["@mozilla.org/process/environment;1"].getService(',
8178
+ " Ci.nsIEnvironment",
8179
+ " )",
8180
+ " : null;",
8181
+ "if (!env) {",
8182
+ " throw new Error(",
8183
+ ' "Chrome scope is unavailable, so the launch nonce could not be " +',
8184
+ ' "read. Zen 138 or newer is required, and the launcher must not " +',
8185
+ ' "drop MOZ_REMOTE_ALLOW_SYSTEM_ACCESS."',
8186
+ " );",
8187
+ "}",
8188
+ // nsIEnvironment returns an empty string for unset variables.
8189
+ 'return env.get("ZEN_MCP_LAUNCH_NONCE") || null;'
8190
+ ].join("\n"),
7173
8191
  { timeoutMs: 1e4 }
7174
8192
  );
7175
8193
  } catch (error) {
@@ -7233,7 +8251,7 @@ var ZenRuntime = class {
7233
8251
  if (outcome === "denied") {
7234
8252
  await this.#closeOwnedBrowser("access was declined in the browser");
7235
8253
  throw new ZenAccessError(
7236
- "Browser access was declined in Zen. The browser Zen MCP started was closed. Call zen_launch to ask again."
8254
+ "Browser access was declined in Zen. The browser Zen MCP started was closed. Restart the MCP server to ask again."
7237
8255
  );
7238
8256
  }
7239
8257
  throw new ZenAccessError(
@@ -7703,8 +8721,15 @@ var ZenRuntime = class {
7703
8721
  }
7704
8722
  };
7705
8723
  }
8724
+ let focused = false;
8725
+ let focusLimitation;
7706
8726
  if (focus) {
7707
- await this.hub.selectTab({ tabId: target.tab.id, focusWindow: true }, target.windowId).catch(() => void 0);
8727
+ const brought = await this.#bringTabForward(
8728
+ target.tab.id,
8729
+ target.windowId
8730
+ );
8731
+ focused = brought.focused;
8732
+ focusLimitation = brought.limitation;
7708
8733
  }
7709
8734
  this.#rememberEvidence(target.tab.id, target.windowId);
7710
8735
  let op;
@@ -7735,10 +8760,13 @@ var ZenRuntime = class {
7735
8760
  url: op.url || target.tab.url,
7736
8761
  title: op.title || target.tab.title || options.sourceTitle?.trim() || "",
7737
8762
  tabReused: target.reused,
7738
- focused: focus,
8763
+ focused,
7739
8764
  sourceUrl,
7740
8765
  claim
7741
8766
  };
8767
+ if (focusLimitation) {
8768
+ result.limitation = joinLimitation(result.limitation, focusLimitation);
8769
+ }
7742
8770
  const delivered = await this.hub.notify({
7743
8771
  title: evidenceCardTitle(result),
7744
8772
  detail: evidenceCardDetail(
@@ -7779,7 +8807,7 @@ var ZenRuntime = class {
7779
8807
  failed: total,
7780
8808
  openedTabs: 0,
7781
8809
  reusedTabs: 0,
7782
- focused: focus,
8810
+ focused: false,
7783
8811
  results: [],
7784
8812
  error
7785
8813
  });
@@ -7916,11 +8944,15 @@ var ZenRuntime = class {
7916
8944
  }
7917
8945
  const firstTargetIndex = targets.findIndex((target) => target !== null);
7918
8946
  const firstTarget = firstTargetIndex >= 0 ? targets[firstTargetIndex] : null;
8947
+ let firstFocused = false;
8948
+ let firstFocusLimitation;
7919
8949
  if (focus && firstTarget) {
7920
- await this.hub.selectTab(
7921
- { tabId: firstTarget.tab.id, focusWindow: true },
8950
+ const brought = await this.#bringTabForward(
8951
+ firstTarget.tab.id,
7922
8952
  firstTarget.windowId
7923
- ).catch(() => void 0);
8953
+ );
8954
+ firstFocused = brought.focused;
8955
+ firstFocusLimitation = brought.limitation;
7924
8956
  }
7925
8957
  const openedTabIds = /* @__PURE__ */ new Set();
7926
8958
  const reusedTabIds = /* @__PURE__ */ new Set();
@@ -7930,7 +8962,7 @@ var ZenRuntime = class {
7930
8962
  if (target.reused) reusedTabIds.add(target.tab.id);
7931
8963
  else openedTabIds.add(target.tab.id);
7932
8964
  }
7933
- const highlightMs = clampInt(options.highlightMs, 1e3, 12e4, 25e3);
8965
+ const highlightMs = clampInt(options.highlightMs, 1e3, 12e4, 2e4);
7934
8966
  const results = new Array(total);
7935
8967
  let next = 0;
7936
8968
  let completed = 0;
@@ -7981,16 +9013,23 @@ var ZenRuntime = class {
7981
9013
  error: evidenceFailureFromError(error)
7982
9014
  };
7983
9015
  }
7984
- results[index] = {
9016
+ const citationResult = {
7985
9017
  ...op,
7986
9018
  tabId: op.tabId ?? target.tab.id,
7987
9019
  url: op.url || target.tab.url,
7988
9020
  title: op.title || target.tab.title || citation.sourceTitle?.trim() || "",
7989
9021
  tabReused: target.reused,
7990
- focused: focus && firstTarget?.tab.id === target.tab.id,
9022
+ focused: firstFocused && firstTarget?.tab.id === target.tab.id,
7991
9023
  sourceUrl: citation.url,
7992
9024
  claim
7993
9025
  };
9026
+ if (firstFocusLimitation && firstTarget?.tab.id === target.tab.id) {
9027
+ citationResult.limitation = joinLimitation(
9028
+ citationResult.limitation,
9029
+ firstFocusLimitation
9030
+ );
9031
+ }
9032
+ results[index] = citationResult;
7994
9033
  } finally {
7995
9034
  completed += 1;
7996
9035
  options.onProgress?.(completed, total);
@@ -8007,7 +9046,7 @@ var ZenRuntime = class {
8007
9046
  const verified = results.filter((result) => result.verified === true).length;
8008
9047
  const unverified = matched - verified;
8009
9048
  const failed = total - matched;
8010
- let limitation;
9049
+ let limitation = firstFocusLimitation;
8011
9050
  const failures = results.filter((result) => !result.ok).slice(0, MAX_BATCH_CARD_FAILURES).map(
8012
9051
  (result) => `${truncateText(
8013
9052
  collapseText(result.claim || result.sourceUrl),
@@ -8029,7 +9068,10 @@ var ZenRuntime = class {
8029
9068
  windowId: cardWindow
8030
9069
  }).then((response) => response.delivered).catch(() => false);
8031
9070
  if (!delivered) {
8032
- limitation = "The in-browser summary card could not be shown.";
9071
+ limitation = joinLimitation(
9072
+ limitation,
9073
+ "The in-browser summary card could not be shown."
9074
+ );
8033
9075
  }
8034
9076
  return {
8035
9077
  ok: failed === 0 && unverified === 0,
@@ -8039,7 +9081,7 @@ var ZenRuntime = class {
8039
9081
  failed,
8040
9082
  openedTabs: openedTabIds.size,
8041
9083
  reusedTabs: reusedTabIds.size,
8042
- focused: focus,
9084
+ focused: firstFocused,
8043
9085
  results,
8044
9086
  ...limitation ? { limitation } : {}
8045
9087
  };
@@ -8090,6 +9132,38 @@ var ZenRuntime = class {
8090
9132
  ...failure ? { error: failure } : {}
8091
9133
  };
8092
9134
  }
9135
+ /**
9136
+ * Selects a tab and reports only what was observed: `focused` is true when
9137
+ * the bridge reports the tab as active. A failed selection becomes a
9138
+ * limitation instead of a thrown error so the evidence check itself can
9139
+ * still finish in the background.
9140
+ */
9141
+ async #bringTabForward(tabId, windowId) {
9142
+ try {
9143
+ const selected = await this.hub.selectTab(
9144
+ { tabId, focusWindow: true },
9145
+ windowId
9146
+ );
9147
+ if (selected.tab.active !== true) {
9148
+ return {
9149
+ focused: false,
9150
+ limitation: "Zen did not activate the source tab, so it may still be in the background."
9151
+ };
9152
+ }
9153
+ if (selected.windowFocused === false) {
9154
+ return {
9155
+ focused: true,
9156
+ limitation: "The source tab is active, but the Zen window could not be raised."
9157
+ };
9158
+ }
9159
+ return { focused: true };
9160
+ } catch (error) {
9161
+ return {
9162
+ focused: false,
9163
+ limitation: `Could not bring the source tab forward: ${errorText(error)}`
9164
+ };
9165
+ }
9166
+ }
8093
9167
  #urlPermitted(url) {
8094
9168
  return isUrlAllowed(url, this.config.allowedDomains);
8095
9169
  }
@@ -8593,6 +9667,19 @@ program.command("setup").description("Detect Zen, write a config file, and print
8593
9667
  "Marionette port. Zen currently always uses 2828.",
8594
9668
  (value) => parseInteger(value, "marionette port")
8595
9669
  ).option("--skip-doctor", "Write the config without running diagnostics.").action((options) => setup(options));
9670
+ program.command("onboard").description(
9671
+ "Pick MCP clients and add Zen MCP to their configuration."
9672
+ ).option(
9673
+ "--clients <ids>",
9674
+ "Comma-separated client ids or 'all'. Skips the interactive picker."
9675
+ ).option(
9676
+ "--command <command>",
9677
+ "Command clients should run. Defaults to `zen-mcp`."
9678
+ ).option("--other", "Also print a setup prompt for any other client.").addHelpText(
9679
+ "after",
9680
+ `
9681
+ Client ids: ${clientIds().join(", ")}, other.`
9682
+ ).action((options) => onboard(options));
8596
9683
  var configCommand = program.command("config").description("Show or change the saved configuration.");
8597
9684
  configCommand.command("show").description("Print the config file path and resolved values.").action(() => configShow());
8598
9685
  configCommand.command("set").description(`Set one key: ${CONFIG_KEYS.join(", ")}.`).argument("<key>", "Config key.").argument("<value>", "New value. Use an empty string to clear a path.").action((key, value) => configSet(key, value));
@@ -8723,7 +9810,7 @@ async function setup(options) {
8723
9810
  if (options.marionettePort !== void 0) {
8724
9811
  updates.marionettePort = options.marionettePort;
8725
9812
  }
8726
- const firstTime = !existsSync9(configFilePath());
9813
+ const firstTime = !existsSync10(configFilePath());
8727
9814
  if (!updates.zenPath && !loadConfig().zenPath) {
8728
9815
  try {
8729
9816
  updates.zenPath = findZenExecutable(loadConfig());
@@ -8759,6 +9846,121 @@ async function setup(options) {
8759
9846
  console.log(
8760
9847
  '\nIf Zen MCP is not on your PATH, point command at the absolute path of dist/cli.js and keep args as ["serve"].'
8761
9848
  );
9849
+ console.log(
9850
+ "Run `zen-mcp onboard` to add Zen MCP to a supported MCP client."
9851
+ );
9852
+ }
9853
+ async function onboard(options) {
9854
+ const context = { command: options.command?.trim() || "zen-mcp" };
9855
+ const theme = createTheme(process.stdout);
9856
+ const rule = theme.unicode ? "\u2500".repeat(56) : "-".repeat(56);
9857
+ const entries = catalog(context);
9858
+ const known = new Set(entries.map((entry) => entry.id));
9859
+ let selected;
9860
+ let includeOther = Boolean(options.other);
9861
+ if (options.clients?.trim()) {
9862
+ const tokens = options.clients.split(",").map((token) => token.trim()).filter(Boolean);
9863
+ const unknown = tokens.filter(
9864
+ (token) => token !== "other" && token !== "all" && !known.has(token)
9865
+ );
9866
+ if (unknown.length > 0) {
9867
+ console.error(`Unknown client(s): ${unknown.join(", ")}.`);
9868
+ console.error(`Valid clients: ${[...known].join(", ")}, other, all.`);
9869
+ process.exitCode = 1;
9870
+ return;
9871
+ }
9872
+ selected = tokens.includes("all") ? entries.map((entry) => entry.id) : tokens.filter((token) => token !== "other");
9873
+ includeOther = includeOther || tokens.includes("other");
9874
+ } else {
9875
+ if (!process.stdin.isTTY || !process.stdout.isTTY) {
9876
+ console.error("The client picker needs an interactive terminal.");
9877
+ console.error("Use --clients with a comma-separated list instead:");
9878
+ console.error(" zen-mcp onboard --clients claude-code,cursor,other");
9879
+ console.error(`Valid clients: ${[...known].join(", ")}, other.`);
9880
+ process.exitCode = 1;
9881
+ return;
9882
+ }
9883
+ let result;
9884
+ try {
9885
+ result = await pickClients(buildOptions(entries));
9886
+ } catch (error) {
9887
+ if (error instanceof SelectionCancelled) {
9888
+ console.log("Cancelled. No client configuration was changed.");
9889
+ process.exitCode = 130;
9890
+ return;
9891
+ }
9892
+ throw error;
9893
+ }
9894
+ selected = result.selected;
9895
+ includeOther = includeOther || result.other;
9896
+ }
9897
+ if (selected.length === 0 && !includeOther) {
9898
+ console.log(
9899
+ theme.dim(" Nothing selected. No client configuration was changed.")
9900
+ );
9901
+ return;
9902
+ }
9903
+ if (!existsSync10(configFilePath())) {
9904
+ const updates = {};
9905
+ try {
9906
+ updates.zenPath = findZenExecutable(loadConfig());
9907
+ } catch {
9908
+ }
9909
+ const path = saveConfig(updates);
9910
+ const mark = theme.unicode ? theme.green("\u2713") : "[ ok ]";
9911
+ console.log(` ${mark} Saved config ${theme.dim(path)}`);
9912
+ console.log("");
9913
+ }
9914
+ let failed = 0;
9915
+ if (selected.length > 0) {
9916
+ let connected = 0;
9917
+ console.log(` ${theme.bold("Client configuration")}`);
9918
+ console.log(` ${theme.dim(rule)}`);
9919
+ for (const id of selected) {
9920
+ const result = applyClient(id, context);
9921
+ if (result.status === "ok") {
9922
+ connected += 1;
9923
+ const mark = theme.unicode ? theme.green("\u2713") : "[ ok ]";
9924
+ console.log(
9925
+ ` ${mark} ${result.label.padEnd(18)} ${theme.dim(result.message)}`
9926
+ );
9927
+ } else {
9928
+ failed += 1;
9929
+ const mark = theme.unicode ? theme.red("\u2717") : "[FAIL]";
9930
+ console.log(
9931
+ ` ${mark} ${result.label.padEnd(18)} ${theme.red(result.message)}`
9932
+ );
9933
+ }
9934
+ }
9935
+ console.log("");
9936
+ console.log(
9937
+ ` ${failed === 0 ? theme.green(
9938
+ `${connected} client${connected === 1 ? "" : "s"} connected`
9939
+ ) : theme.yellow(`${connected} connected, ${failed} failed`)}`
9940
+ );
9941
+ }
9942
+ if (includeOther) {
9943
+ console.log("");
9944
+ console.log(` ${theme.bold("Other client")}`);
9945
+ console.log(` ${theme.dim(rule)}`);
9946
+ console.log(` ${theme.dim("Paste this prompt into your agent.")}`);
9947
+ console.log("");
9948
+ console.log(agentSetupPrompt(context.command));
9949
+ }
9950
+ console.log("");
9951
+ console.log(
9952
+ theme.dim(
9953
+ selected.length > 0 ? " Restart the selected clients so they load the server. On the first browser tool, approve the card in Zen." : " Restart the client after your agent updates its configuration. On the first browser tool, approve the card in Zen."
9954
+ )
9955
+ );
9956
+ if (!options.command) {
9957
+ console.log(
9958
+ theme.dim(
9959
+ " If `zen-mcp` is not on your PATH, rerun with --command <absolute path to dist/cli.js>."
9960
+ )
9961
+ );
9962
+ }
9963
+ if (failed > 0) process.exitCode = 1;
8762
9964
  }
8763
9965
  function configShow() {
8764
9966
  console.log(configFilePath());