Skip to content

fix(init): OpenCode + Gemini CLI use stdio shim (audit follow-up) - #118

Merged
piwi3910 merged 1 commit into
mainfrom
fix/init-opencode-gemini-stdio
May 6, 2026
Merged

piwi3910 merged 1 commit into
mainfrom
fix/init-opencode-gemini-stdio

Conversation

@piwi3910

@piwi3910 piwi3910 commented May 5, 2026

Copy link
Copy Markdown
Contributor

Stacked on top of #116 (Codex stdio fix). After #116 lands, this rebases on main automatically.

Following the Codex-CLI handshake bug, audited every host the installer configures. Two more had broken / fragile MCP config:

OpenCode — broken

  • Remote-MCP rejects SSE servers (sst/opencode#834)
  • Streamable HTTP not shipped yet (#8058)
  • Config schema differs from every other host: top-level mcp (not mcpServers), stdio entries shaped {type: "local", command, args, environment}

Gemini CLI — fragile

  • SSE path historically drops Authorization headers (google-gemini/gemini-cli#2427); fix shipped via #13762 but older installs still in the wild silently strip our bearer → server 401s.

Implementation

Extended McpAdapter with stdioEnvKey + stdioTypeField so OpenCode's quirks are modelled in the registry, not as per-host special-cases in buildMcpEntry.

Audit results

Host Status
Claude Code ✅ correct as-is
Claude Desktop ✅ correct as-is
Cursor ⚠️ works; watch forum #154390
OpenCode ❌ → fixed via stdio shim
Kilo Code ✅ auto-falls-back
GitHub Copilot ⚠️ may need .vscode/mcp.json path on some VS Code versions; current .mcp.json works
Gemini CLI ⚠️ → fixed defensively via stdio shim
Codex CLI ✅ via #116

73/73 init tests pass; new explicit assertions for the OpenCode + Gemini shapes.

Copilot AI review requested due to automatic review settings May 5, 2026 18:41
@piwi3910
piwi3910 enabled auto-merge (squash) May 5, 2026 18:41

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Updates @azrtydxb/novamem-init so more MCP hosts use the stdio shim instead of direct SSE, extending the host registry/model to represent per-host stdio quirks. It also adds tests for the new host-specific config shapes, plus an unrelated new skill file.

Changes:

  • Switches Codex, OpenCode, and Gemini installer entries to stdio-based MCP configs.
  • Extends McpAdapter/buildMcpEntry to support host-specific stdio env/type fields.
  • Adds install tests for Codex/OpenCode/Gemini config output and adds a new session-recap skill document.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

Show a summary per file
File Description
skills/session-recap/SKILL.md Adds a new standalone session recap skill with memory-writing guidance.
packages/init/test/install.test.ts Expands init tests for Codex/OpenCode/Gemini MCP config shapes.
packages/init/src/tools.ts Updates host registry entries and MCP adapter schema for stdio quirks.
packages/init/src/install/mcp.ts Generalizes stdio MCP entry generation for host-specific field names.
.changeset/codex-stdio.md Adds release note for the transport/config changes.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.


## What NOT to recap

- **Don't propose** entries that are already in memory. Run a quick `memory_search` against your candidate list first; for any candidate where you find an existing entry with cosine ≥ 0.85, either skip it (if the existing entry is current) or propose a `memory_update` instead (if the new wording is meaningfully better — same id, preserves edges + hits).
Comment on lines +1 to +12
---
name: session-recap
description: Run before ending a session to extract durable knowledge from the whole conversation and save it to novamem. Scans decisions, preferences, project state, bug post-mortems, and recurring constraints; proposes a list to memorize; on approval calls memory_remember for each. Use when the user says "wrap up", "save what we did", "memorize this session", "before I close this", "session recap", or runs `/session-recap`.
license: Apache-2.0
compatibility: Requires the novamem MCP server reachable + a user bearer token. See https://github.com/azrtydxb/novamem.
metadata:
author: novamem
version: "1.0"
homepage: https://github.com/azrtydxb/novamem
---

# Session recap → novamem
piwi3910 added a commit that referenced this pull request May 5, 2026
Closes #117. Adds the modern (2025-03-26) MCP transport alongside
the existing /mcp/sse + /mcp/messages legacy pair. Three verbs on
one endpoint:

  POST   /mcp   — JSON-RPC requests; `initialize` without
                  Mcp-Session-Id starts a session
  GET    /mcp   — opens server→client SSE channel for an existing session
  DELETE /mcp   — terminates a session

Session ownership is enforced on every POST/GET/DELETE: the userId
captured on the session-creating initialize is checked against
req.userId on subsequent calls (carry-over of the issue #57 fix
from the SSE side — a leaked session id can't be driven by a
different authenticated user).

Per-user concurrency cap and idle reaper match the SSE side
(MAX_SESSIONS_PER_USER=10, 30 min idle, 60 s sweep). Legacy
SSE + stdio shim continue to work unchanged.

Implementation uses @modelcontextprotocol/sdk's
StreamableHTTPServerTransport (already in deps at 1.29.0). The
SDK handles wire-protocol framing; our route just owns the
session map, auth gate, and cap enforcement.

Why this matters:
- OpenAI Codex CLI's MCP client (rmcp Rust crate) speaks Streamable
  HTTP only. We currently route it through the stdio shim
  (#116/#118); now it can connect natively.
- OpenCode + Gemini CLI on similarly fragile SSE remote paths can
  follow.
- Any future host that ships an MCP client without SSE support
  works out of the box.

5 new smoke tests in routes/mcp-streamable.test.ts:
- POST without Mcp-Session-Id + non-initialize → 400
- GET / DELETE without Mcp-Session-Id → 400
- POST initialize → 200 + session id in Mcp-Session-Id response header
- POST with unknown session id → 404

198/198 server tests pass. Docs updated in
packages/docs-site/api/mcp-tools.md.

Follow-up: flip Codex / OpenCode / Gemini in init's tools.ts back
to direct remote (Streamable HTTP) once this ships in a release.
Tracked separately so #116 + #118 can land as-is.
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.
@piwi3910
piwi3910 force-pushed the fix/init-opencode-gemini-stdio branch from 05115a9 to 7b87fce Compare May 6, 2026 02:38
@piwi3910
piwi3910 merged commit d6721bf into main May 6, 2026
11 checks passed
@piwi3910
piwi3910 deleted the fix/init-opencode-gemini-stdio branch May 6, 2026 02:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants