Skip to content

Commit 7b87fce

Browse files
committed
fix(init): correct MCP transport for OpenCode + Gemini CLI
Following the Codex audit, two more hosts had broken / fragile MCP config: **OpenCode** (BROKEN) - Remote-MCP path rejects SSE servers (anomalyco/opencode#834: \"Server error: UnknownError\" on every handshake) - Streamable HTTP not shipped yet (#8058) - Config schema differs: top-level `mcp` (not `mcpServers`), stdio entries shaped `{type: \"local\", command, args, environment}` (env-key is `environment`, not `env`) Routed through the stdio shim, with rootKey=\"mcp\", stdioTypeField=\"local\", stdioEnvKey=\"environment\". **Gemini CLI** (FRAGILE) - SSE path historically drops `Authorization` headers (google-gemini/gemini-cli#2427); the fix shipped (#13762) but older installs still in the wild silently strip our bearer → server 401s. Routed through the stdio shim — env vars are guaranteed-forwarded regardless of CLI version. To support OpenCode's quirky shape without per-host special cases in buildMcpEntry, extended McpAdapter with two optional fields: - stdioEnvKey: \"env\" | \"environment\" (default \"env\") - stdioTypeField: string (default unset; OpenCode wants \"local\") Other hosts audited + confirmed correct: Claude Code, Claude Desktop, Cursor, Kilo Code, GitHub Copilot. 73/73 init tests pass — new explicit assertions for the OpenCode and Gemini shapes.
1 parent d70b399 commit 7b87fce

4 files changed

Lines changed: 100 additions & 13 deletions

File tree

‎.changeset/codex-stdio.md‎

Lines changed: 27 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -3,15 +3,33 @@
33
"@azrtydxb/novamem-mcp": patch
44
---
55

6-
fix(init): use stdio shim for OpenAI Codex CLI
6+
fix(init): correct MCP transport for hosts with broken SSE paths
77

8-
Codex CLI's MCP client speaks Streamable HTTP; novamem only exposes
9-
the legacy SSE transport at /mcp/sse. Configuring Codex with
10-
transport=sse caused a cryptic handshake failure on first start:
8+
Following the Codex-CLI handshake bug, audited every host the
9+
installer configures. Three fixes shipped together:
1110

12-
Deserialize error: data did not match any variant of untagged enum
13-
JsonRpcMessage, when send initialize request
11+
1. **Codex CLI** — its MCP client speaks Streamable HTTP, not SSE.
12+
Pointing it at `/mcp/sse` produced "Deserialize error: data did
13+
not match any variant of untagged enum JsonRpcMessage". Routed
14+
through the `@azrtydxb/novamem-mcp` stdio shim.
1415

15-
Switch Codex to the stdio shim (`@azrtydxb/novamem-mcp`) — same
16-
fix as Claude Desktop. The shim proxies stdio↔SSE internally so it
17-
works regardless of what HTTP transport the host expects.
16+
2. **OpenCode** — confirmed broken: its remote-MCP path rejects
17+
SSE servers (sst/opencode#834) and Streamable HTTP isn't shipped
18+
yet (#8058). Plus its config schema differs from every other
19+
host — top-level `mcp` (not `mcpServers`), stdio entries shaped
20+
`{type: "local", command, args, environment}` (not `env`).
21+
Extended `McpAdapter` with `stdioEnvKey` + `stdioTypeField`
22+
to model this without per-host special cases in buildMcpEntry.
23+
24+
3. **Gemini CLI** — the SSE path historically dropped `Authorization`
25+
headers (google-gemini/gemini-cli#2427); the fix (#13762) shipped
26+
but older installs still strip our bearer and the server 401s.
27+
Routed through the stdio shim — env vars are guaranteed-forwarded
28+
regardless of CLI version.
29+
30+
Other hosts audited and confirmed correct as-is: Claude Code, Claude
31+
Desktop, Cursor (with a pinned watch on cursor.com forum #154390),
32+
Kilo Code (auto-falls-back), GitHub Copilot.
33+
34+
73/73 init tests pass; new tests assert the OpenCode + Gemini
35+
shapes explicitly.

‎packages/init/src/install/mcp.ts‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -64,14 +64,20 @@ export function buildMcpEntry(adapter: NonNullable<ToolEntry["mcp"]>, p: McpInst
6464
const spec = p.shimVersion
6565
? `@azrtydxb/novamem-mcp@${p.shimVersion}`
6666
: "@azrtydxb/novamem-mcp";
67-
return {
67+
const envKey = adapter.stdioEnvKey ?? "env";
68+
const entry: Record<string, unknown> = {
6869
command: "npx",
6970
args: ["-y", spec],
70-
env: {
71+
[envKey]: {
7172
NOVAMEM_BASE_URL: trimTrailingSlash(p.baseUrl),
7273
NOVAMEM_TOKEN: p.bearer,
7374
},
7475
};
76+
// Hosts like OpenCode require an explicit `type: "local"` to identify
77+
// stdio servers. Inject when the adapter declares it; omit otherwise
78+
// (Claude Desktop / Codex parse fine without it).
79+
if (adapter.stdioTypeField) entry.type = adapter.stdioTypeField;
80+
return entry;
7581
}
7682

7783
/**

‎packages/init/src/tools.ts‎

Lines changed: 33 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,14 @@ export interface McpAdapter {
2424
serverKey?: string;
2525
/** Transport our entry advertises. Default: "sse". */
2626
transport?: "sse" | "stdio";
27+
/** Field name a host expects for stdio env-var maps. Default: "env".
28+
* OpenCode uses "environment". */
29+
stdioEnvKey?: "env" | "environment";
30+
/** Some hosts disambiguate stdio entries with a `type` field. Example:
31+
* OpenCode uses `type: "local"` for stdio, `type: "remote"` for HTTP.
32+
* Set to inject `{type: <value>}` into the stdio entry; leave unset
33+
* to omit (Claude Desktop / Codex don't need it). */
34+
stdioTypeField?: string;
2735
}
2836

2937
export interface CommandAdapter {
@@ -122,7 +130,20 @@ export const TOOLS: readonly ToolEntry[] = [
122130
scope: "project",
123131
skillsBase: ".opencode",
124132
detect: [".opencode"],
125-
mcp: { path: ".opencode/opencode.json", format: "json", transport: "sse" },
133+
// OpenCode's remote-MCP path is broken for SSE servers (sst/opencode
134+
// #834: \"Server error: UnknownError\" on every SSE handshake) and
135+
// Streamable HTTP isn't shipped yet (#8058). Plus their config schema
136+
// uses `mcp` (not `mcpServers`) as the top-level key, with stdio
137+
// entries shaped `{type: "local", command, args, environment}` —
138+
// not `env`. Route through the stdio shim until either lands.
139+
mcp: {
140+
path: ".opencode/opencode.json",
141+
format: "json",
142+
rootKey: "mcp",
143+
transport: "stdio",
144+
stdioTypeField: "local",
145+
stdioEnvKey: "environment",
146+
},
126147
commands: { dir: ".opencode/commands", format: "claude-md" },
127148
},
128149
{
@@ -170,7 +191,17 @@ export const TOOLS: readonly ToolEntry[] = [
170191
scope: "user",
171192
skillsBase: ".gemini",
172193
detect: [".gemini"],
173-
mcp: { path: ".gemini/settings.json", format: "json", transport: "sse" },
194+
// Gemini CLI's `url`-keyed remote SSE entry historically dropped
195+
// configured `headers` (google-gemini/gemini-cli#2427); the fix
196+
// (#13762) shipped, but older installs still in the wild silently
197+
// strip our `Authorization: Bearer …` and the server 401s.
198+
// Route through the stdio shim — env vars are guaranteed-forwarded
199+
// and the protocol is the same regardless of CLI version.
200+
mcp: {
201+
path: ".gemini/settings.json",
202+
format: "json",
203+
transport: "stdio",
204+
},
174205
commands: { dir: ".gemini/commands", format: "gemini-toml" },
175206
},
176207
{

‎packages/init/test/install.test.ts‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -122,6 +122,38 @@ describe("installMcp", () => {
122122
expect(raw).toContain('NOVAMEM_BASE_URL = "http://x:7778"');
123123
expect(raw).toContain('NOVAMEM_TOKEN = "nm_t"');
124124
});
125+
it("writes OpenCode JSON with mcp root key + type:local + environment env-key", async () => {
126+
// OpenCode's SSE path is broken; we route via stdio shim. Its config
127+
// schema is also unique: top-level `mcp` (not `mcpServers`), entries
128+
// shaped `{type: "local", command, args, environment}`.
129+
const tool = findTool("opencode")!;
130+
const r = await installMcp(tool, ctx, { baseUrl: "http://x:7778", bearer: "nm_t" });
131+
expect(r.changed).toBe(true);
132+
const written = JSON.parse(await readFile(r.configPath, "utf8")) as Record<string, unknown>;
133+
const root = written.mcp as Record<string, unknown> | undefined;
134+
expect(root).toBeDefined();
135+
const entry = root!.novamem as Record<string, unknown>;
136+
expect(entry.type).toBe("local");
137+
expect(entry.command).toBe("npx");
138+
expect(entry.environment).toMatchObject({
139+
NOVAMEM_BASE_URL: "http://x:7778",
140+
NOVAMEM_TOKEN: "nm_t",
141+
});
142+
expect(written.mcpServers).toBeUndefined();
143+
});
144+
it("writes Gemini settings.json via stdio shim", async () => {
145+
const tool = findTool("gemini")!;
146+
const r = await installMcp(tool, ctx, { baseUrl: "http://x:7778", bearer: "nm_t" });
147+
expect(r.changed).toBe(true);
148+
const written = JSON.parse(await readFile(r.configPath, "utf8")) as Record<string, unknown>;
149+
const entry = (written.mcpServers as Record<string, unknown>).novamem as Record<string, unknown>;
150+
expect(entry.command).toBe("npx");
151+
expect(entry.env).toMatchObject({
152+
NOVAMEM_BASE_URL: "http://x:7778",
153+
NOVAMEM_TOKEN: "nm_t",
154+
});
155+
expect(entry.url).toBeUndefined();
156+
});
125157
it("skips tools with no MCP adapter", async () => {
126158
const tool = findTool("trae")!;
127159
const r = await installMcp(tool, ctx, { baseUrl: "http://x:7778", bearer: "nm_t" });

0 commit comments

Comments
 (0)