feat(clients): register ZCode during setup (#1564)

* feat(clients): register ZCode during setup

- SupportedClients: zcode definition (~/.zcode/cli/config.json, format
  zcode, personal skills at ~/.zcode/skills)
- ClientConfigurationDocument: zcode dialect reads/writes the nested
  mcp.servers table; withClientServers now tolerates a missing outer
  table for fresh documents
- docs: add ZCode to the supported-clients table with configuration notes
- tests: zcodeClientConfiguration.test.ts (path resolution, nested
  upsert, fresh/empty configs, uninstall)

Verified: tsc --noEmit clean; vitest run
tests/boundary/filesystem/zcodeClientConfiguration.test.ts 6/6.

* fix(clients): preserve ZCode fallback servers and honor enable flag

Review follow-up (#1564), two integration gaps:

- ZCode reads the user-scope ~/.agents/mcp.json fallback only while the
  native .zcode config defines no servers at all, with no merging. Setup
  now copies the fallback's mcpServers entries into the native table when
  writing the first native server, so registrations that only live in
  the fallback keep loading; the fallback file is left untouched. A
  malformed fallback fails setup closed (configure and preflight)
  instead of being silently suppressed.
- ZCode disables a server with "enable": false on its entry, which the
  generic status parsing (disabled/enabled) did not recognize: doctor
  reported such a registration as aligned although ZCode never starts
  it. The ZCode dialect now treats enable: false as disabled (state
  stale) and setup rewrites the entry on rerun.

Docs describe both behaviors; the bundled REA skill's supported client
list includes zcode.

Verified: tsc --noEmit clean; vitest run
tests/boundary/filesystem/zcodeClientConfiguration.test.ts 10/10;
npm run check:fast green; npm run verify:test-discovery 733 files.

* fix(clients): reject non-regular ZCode fallback files before reading

Resolve the fallback through the client-config transaction path and the
regular-file admission before parsing it, so a FIFO or other non-regular
file at ~/.agents/mcp.json fails setup closed instead of blocking the
read indefinitely. Directory and FIFO fallback cases are covered in
tests, and the preflight remediation names unreadable fallbacks too.

---------

Co-authored-by: morluto <76467478+morluto@users.noreply.github.com>
This commit is contained in:
Iven Koo
2026-10-12 22:51:40 +08:00
committed by GitHub
co-authored by morluto
parent e4d3e1399d
commit 51d6c87cdb
10 changed files with 638 additions and 14 deletions
+45 -2
View File
@@ -86,6 +86,7 @@ export const clientConfigurationServersKey = (
case "hermes":
return "mcp_servers";
case "opencode":
case "zcode":
return "mcp";
case "vscode":
return "servers";
@@ -116,6 +117,8 @@ const parseDocument = (
if (isEmptyClientConfigurationText(text)) return {};
// Hermes stores MCP servers in `mcp_servers` inside a YAML document.
if (format === "hermes") return objectSchema.parse(parseYaml(text));
// ZCode loads nonempty native files with strict JSON.parse.
if (format === "zcode") return objectSchema.parse(JSON.parse(text));
const errors: ParseError[] = [];
// Accept a UTF-8 BOM without shifting diagnostics or editing the original text.
const jsonText = text.startsWith("\uFEFF") ? ` ${text.slice(1)}` : text;
@@ -142,6 +145,23 @@ const requireObject = (
});
};
/** ZCode reads the same-scope fallback as strict JSON with a mcpServers table. */
export const parseZcodeFallbackConfiguration = (
text: string,
): ClientConfigurationDocument => {
const document = requireObject(JSON.parse(text), "ZCode fallback root");
return {
document,
servers:
document.mcpServers === undefined
? {}
: requireObject(document.mcpServers, "ZCode fallback mcpServers"),
serversPath: ["mcpServers"],
dialect: "json",
legacyServers: {},
};
};
/** Members of OpenCode V2's `mcp` object that are not server names. */
const OPENCODE_V2_MCP_SETTINGS = new Set(["servers", "timeout"]);
@@ -169,6 +189,21 @@ export const parseClientConfiguration = (
const value = document[serversKey];
const servers =
value === undefined ? {} : requireObject(value, `"${serversKey}"`);
// ZCode reads stdio servers from the nested `mcp.servers` table of
// `~/.zcode/cli/config.json`; entries carry `command`, `args`, and `env`.
if (format === "zcode") {
const nested = servers.servers;
return {
document,
servers:
nested === undefined
? {}
: requireObject(nested, `"${serversKey}.servers"`),
serversPath: [serversKey, "servers"],
dialect: format,
legacyServers: {},
};
}
const native = servers.servers;
// A V1 server named `servers` has a string `type` discriminator; the V2
// table may instead hold a server object named `type`.
@@ -228,8 +263,16 @@ export const withClientServers = (
: editDshDocument(parsed);
const [key = "", nested] = parsed.serversPath;
if (nested === undefined) return { ...parsed.document, [key]: servers };
const outer = { ...objectSchema.parse(parsed.document[key]) };
if (removeLegacy !== undefined && !OPENCODE_V2_MCP_SETTINGS.has(removeLegacy))
// A fresh document may not hold the outer table yet (for example a new
// ZCode `config.json` without an `mcp` object), so treat absence as empty.
const outerValue = parsed.document[key];
const outer =
outerValue === undefined ? {} : { ...objectSchema.parse(outerValue) };
if (
parsed.dialect === "opencode_v2" &&
removeLegacy !== undefined &&
!OPENCODE_V2_MCP_SETTINGS.has(removeLegacy)
)
delete outer[removeLegacy];
return { ...parsed.document, [key]: { ...outer, [nested]: servers } };
};