Skip to content

Commit 6e251ad

Browse files
authored
Keep the global MCP config loadable by both OpenCode lines (#466)
* Keep the global MCP config loadable by both OpenCode lines IntelliJ IDEA's AI could not start: its OpenCode ACP agent is 1.x (1.18.15) and rejects the v2-only spellings in the global config (permissions; the mcp.servers nesting). The repository's own guidance produced that shape, so the setup skill, the README snippet, and four AGENTS.md sites now lead with the flat mcp map plus permission -- the one shape both lines load. The skill also offers to flatten an existing mcp.servers nesting and cites anomalyco/opencode#49904 with a retire-when clause. OpenSpec change: openspec/changes/fix-the-global-mcp-config-guidance (skip_specs -- no capability spec describes the skill or the config shape) * Archive the global-MCP-config guidance change skip_specs: no delta to sync, so the archive is the change dir move.
1 parent a215501 commit 6e251ad

7 files changed

Lines changed: 254 additions & 64 deletions

File tree

‎.opencode/skills/setup-agent-tools/SKILL.md‎

Lines changed: 14 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -36,9 +36,11 @@ user before reading or editing files outside this repo.
3636
- If `gh` is missing, point the user at https://cli.github.com and stop this step.
3737
- If not authenticated, ask the user to run `gh auth login` (it is interactive — you cannot complete it) and wait.
3838
- If `shuymn/gh-mcp` is absent from `gh extension list`, run `gh extension install shuymn/gh-mcp`.
39-
- If `opencode mcp list` shows no `github` server, run `opencode mcp add github -- gh mcp`. This writes the user's
40-
global config; the `-- <command>` form is not shown in `opencode mcp add --help`, but it is the non-interactive
41-
path and preserves JSONC comments. An entry with no `disabled` key is enabled by default.
39+
- If `opencode mcp list` shows no `github` server, add it to the **flat** `mcp` map of the user's global config
40+
(`~/.config/opencode/opencode.jsonc`) — beside the existing servers, as
41+
`"github": { "type": "local", "command": ["gh", "mcp"] }`. An entry with no `disabled` key is enabled by default.
42+
Write the flat map, not an `mcp.servers` nesting: OpenCode 1.x consumers (the npm `latest` line, and the agent
43+
IntelliJ IDEA's AI launches) reject `mcp.servers`, while the flat map loads under both lines.
4244

4345
3. **Steroid (optional — IntelliJ IDEA only).**
4446
- Ask whether the user wants the agent to work through their live IDE. If not, skip this step — nothing in the repo
@@ -48,7 +50,8 @@ user before reading or editing files outside this repo.
4850
re-check.
4951
- Install the MCP Steroid plugin into the running IDE with `devrig install plugin`, or point the user at the
5052
JetBrains Marketplace; the IDE shows its own confirmation dialog.
51-
- If `opencode mcp list` shows no `steroid` server, run `opencode mcp add steroid -- devrig mcp` (or use the absolute
53+
- If `opencode mcp list` shows no `steroid` server, add
54+
`"steroid": { "type": "local", "command": ["devrig", "mcp"] }` to the same flat `mcp` map (use the absolute
5255
`devrig` path if the agent runs from a GUI, whose `PATH` may be minimal).
5356

5457
4. **Verify and hand back.**
@@ -57,6 +60,10 @@ user before reading or editing files outside this repo.
5760

5861
## Notes
5962

60-
- If `opencode mcp add` is unavailable, fall back to adding the entry under `mcp.servers` in the user's
61-
`~/.config/opencode/opencode.jsonc` directly (with their confirmation).
62-
- If a `github` or `steroid` server already exists, leave it and say so; do not duplicate it.
63+
- Prefer editing the flat `mcp` map directly. `opencode mcp add` also works, but it defaults to the **project** config —
64+
pass `--global` — and it writes the `servers` nesting, which 1.x consumers reject; if you use it, move the entry out
65+
of `servers` into the flat map afterwards. (`anomalyco/opencode#49904`; retire this caveat when `mcp add` emits the
66+
flat shape.)
67+
- If a `github` or `steroid` server already exists as a flat `mcp` entry, leave it and say so; do not duplicate it. If
68+
it sits under an `mcp.servers` nesting (a config written before this change), offer to move it into the flat map —
69+
that nesting is what makes the 1.x consumers refuse the file.

‎AGENTS.md‎

Lines changed: 66 additions & 54 deletions
Large diffs are not rendered by default.

‎README.md‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -343,13 +343,15 @@ and installs the `gh-mcp` extension, handing back only what it can't do for you
343343
The one that matters is **GitHub** (the agent reads PRs, issues, and CI checks); **Playwright** is already configured in
344344
the project, so there's nothing to set up.
345345

346-
By hand, the auth-bound server (GitHub) goes under `mcp.servers` in your **global** config
347-
(`~/.config/opencode/opencode.jsonc`), not the project config — a project entry can't use your credentials:
346+
By hand, the auth-bound server (GitHub) goes under the **flat** `mcp` map of your **global** config
347+
(`~/.config/opencode/opencode.jsonc`), not the project config — a project entry can't use your credentials, and the flat
348+
map (not the `mcp.servers` nesting) is what both OpenCode lines load: the 1.x agent IntelliJ IDEA's AI launches rejects
349+
`mcp.servers`, and the flat map loads under both.
348350

349351
- **Playwright** (project) — the agent's browser: it drives the running web UI and captures screenshots for the `vision`
350352
subagent. It needs only Node/`npx` (no credentials).
351353
- **GitHub** — read PRs, issues, and CI checks. Run `gh auth login` (the server reuses your `gh` credentials), install
352-
the `gh-mcp` extension (`gh extension install shuymn/gh-mcp`), then add it under `mcp.servers`:
354+
the `gh-mcp` extension (`gh extension install shuymn/gh-mcp`), then add it to that map:
353355
`"github": { "type": "local", "command": ["gh", "mcp"] }`.
354356

355357
MCP config is read at startup, so restart OpenCode after adding one.
Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
schema: spec-driven
2+
created: 2026-10-01
3+
skip_specs: true
Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
# Design
2+
3+
## Context
4+
5+
See `proposal.md` — Why. Facts measured while investigating the IDEA failure (2026-10-01):
6+
7+
- The global config has **two** consumers on this machine: the local CLI (`opencode` 2.0.21, Homebrew `opencode-v2`) and
8+
the OpenCode ACP agent IDEA's AI launches — **1.18.15**, installed from JetBrains' ACP registry
9+
(`~/Library/Caches/JetBrains/IntelliJIdea2026.2/acp-agents/opencode/1.18.15/opencode`). The 1.x line is also what npm
10+
`opencode-ai@latest` publishes (`1.18.34`; no `2.x` versions under that name).
11+
- 1.x rejects the v2-only spellings: a `permissions` array exits 1 with `Unrecognized key: permissions`, and an
12+
`mcp.servers` key with `Missing key mcp.servers.enabled`. A **flat `mcp` map plus `permission`** exits 0 under 1.x and
13+
loads under 2.x (which is what this repo's project config already uses).
14+
- `opencode mcp add` (2.0.21) defaults to the **project** config — `--global` writes the global one — and it writes the
15+
`servers` key: into an empty global config as `mcp.servers`, and into an existing flat `mcp` map as a nested
16+
`mcp.servers` _inside_ it. Either result breaks 1.x.
17+
- Upstream: `anomalyco/opencode#49904` (the `mcp add` placement; commented with the 1.x impact and reproduction),
18+
`#52177` (the V2 MCP docs page disagrees with the published schema and the runtime on this shape), `#43748` (the
19+
published `$schema` is a hybrid V1 shape).
20+
- **Two prior decisions reconciled this same drift.** `migrate-opencode-config-to-v2` (#391) deliberately changed the
21+
README's global snippet **from** the flat `mcp` object **to** `mcp.servers` (its task 2.2), and
22+
`fix-cloud-agent-config-for-v1` (#438) then re-established the one-shape V1 decision for the project config. This
23+
change follows #438's direction and reverses #391's README edit — the V2 docs page #391 followed is what `#52177` now
24+
reports as the outlier.
25+
- **The probe that established `mcp add`'s default also wrote into this repository.** With no `--global`,
26+
`opencode mcp add probe -- gh mcp` appended a `probe` server to `.opencode/opencode.json` (the project config); the
27+
stray entry was reverted with `git checkout --` (the file carried no other uncommitted edits). That write is why the
28+
guidance names the `--global` flag and the probe hazard is recorded in `AGENTS.md`.
29+
30+
## Goals / Non-Goals
31+
32+
**Goals:**
33+
34+
- The told path to a working global config produces one shape, and that shape is the flat `mcp` map plus `permission`.
35+
36+
**Non-Goals:**
37+
38+
- Changing any config file on a contributor's machine (the skill already asks before touching files outside the repo).
39+
- Upstream fixes (`#49904`, `#52177`, `#43748`) — reported/commented, not solved here.
40+
- The project config's own shape: it is already the flat/V1 shape, which is why the IDEA agent reads it.
41+
42+
## Decisions
43+
44+
- **Keep the global config in the V1 shape (flat `mcp`, `permission`) rather than the v2-native spellings.** It is the
45+
one shape both lines load; the v2 spellings buy nothing here and cost the 1.x consumer. Options considered: the
46+
v2-native shape (`mcp.servers`, `permissions`) — rejected, it breaks 1.x (`#49904`/`#43748` are the upstream
47+
symptoms); maintaining two configs (v1 for the agent, v2 for the CLI) — rejected, the CLI reads the V1 shape too.
48+
- **The skill adds the entry by editing the flat `mcp` map, not by `opencode mcp add`.** The command's output must be
49+
normalized anyway, and its written shape is itself under dispute (`#52177`). Options considered: `mcp add --global`
50+
then move the entry out of `servers` — kept as the fallback for a user who prefers the CLI, but not the primary path.
51+
Retire this decision when `#49904` makes `mcp add` emit the flat shape.
52+
- **Correct the `mcp add` claims where they stand instead of deleting them.** The `AGENTS.md` gotcha that probed
53+
`mcp add`'s behaviour ("writes the global config", "the `-- <command>` form is not shown in `--help`") is now stale
54+
for 2.0.21 — the command defaults to the project config and does list the form — and it is the very claim that led the
55+
skill astray; it is corrected in place.
56+
- **Re-probe and re-state the "legacy/native" passage (`AGENTS.md:2456-2457`) rather than leave it.** It calls the flat
57+
`mcp` form "legacy" and `mcp.servers.<name>` "native", which sits against the rule this change establishes, and pins a
58+
`disabled: false` detail to v2.0.15. Options considered: leaving it (rejected — a durable artifact contradicting the
59+
change's subject); deleting it (rejected — the normalized-document difference it records is still useful).
60+
61+
## Risks / Trade-offs
62+
63+
- **The upstream fix may land and make the flat-shape instruction redundant.** → The decision records the retirable
64+
condition (`#49904`), so the instruction can go back to the one-liner when `mcp add` emits the flat shape.
65+
- **A contributor may still run `mcp add` themselves.** → The skill says what it writes and how to correct it, so the
66+
result is recoverable rather than silently broken.
67+
68+
## Migration Plan
69+
70+
- Docs only: the skill, `README.md`, and `AGENTS.md`. No rollout; nothing to roll back.
Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# Proposal: Keep the global MCP config loadable by both OpenCode lines
2+
3+
## Why
4+
5+
IntelliJ IDEA's AI could not start: its ACP session launches OpenCode **1.18.15**, which rejects the v2-only spellings
6+
in the user's global config — `Unrecognized key: permissions`, then `mcp.servers` (`Missing key mcp.servers.enabled`).
7+
The repository's own setup path produces exactly that shape: the README's global snippet shows `mcp.servers`, and the
8+
`setup-agent-tools` skill's `opencode mcp add <name> -- <command…>` writes `mcp.servers` (and, on 2.0.21, targets the
9+
_project_ config unless `--global` is passed). A flat `mcp` map plus `permission` loads under both lines, so the docs
10+
must lead there. Upstream, the CLI half is `anomalyco/opencode#49904` and the docs/schema half `#52177`/`#43748`.
11+
12+
## What Changes
13+
14+
- `.opencode/skills/setup-agent-tools/SKILL.md` — the global-config recipe: pass `--global`, and add the server to the
15+
flat `mcp` map rather than the `mcp.servers` nesting; correct the two claims about `opencode mcp add` (that it writes
16+
the global config by default, and that the `-- <command>` form is absent from its `--help`); and offer to flatten an
17+
existing `mcp.servers` nesting into the flat map (the shape 1.x refuses), citing `anomalyco/opencode#49904` as the
18+
retire-when condition.
19+
- `README.md` — the global-config snippet: the GitHub server goes under the flat `mcp` map, not `mcp.servers`.
20+
- `AGENTS.md` — every site that names the command or the shape: the tooling-setup bullet
21+
(`opencode mcp add <name> -- <command…>` → the `--global` form plus the flat shape); the V1-shape paragraph of the
22+
config gotcha (extended to the global config, naming the 1.x/ACP consumer); the `mcp add` probe passage in "A CLI's
23+
`--help` and its docs are not its contract" (the command defaults to the project config; the `-- <command>` form _is_
24+
listed in 2.0.21's help); and the permission-proof `debug config` gotcha's normalized-document paragraph (its
25+
v2.0.15-pinned `disabled` and credential-rendering claims re-stated for 2.0.21).
26+
27+
## Capabilities
28+
29+
### New Capabilities
30+
31+
None.
32+
33+
### Modified Capabilities
34+
35+
None — `skip_specs: true`. No capability spec describes the `setup-agent-tools` skill or the global config's shape.
36+
37+
## Impact
38+
39+
- **Docs / definitions only**: the skill, the README, and `AGENTS.md`. No build, code, workflow, or runtime change.
40+
- **Effect**: a contributor following the setup gets a global config both OpenCode lines load, so IDEA's AI (which runs
41+
the 1.x agent) starts; the skill stops advertising a shape that breaks a first-class consumer.
Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# Tasks
2+
3+
## 1. Correct the global-config instructions
4+
5+
- [x] 1.1 `.opencode/skills/setup-agent-tools/SKILL.md`: for both the GitHub and the Steroid step, add the entry to the
6+
flat `mcp` map of the global config (via `--global` if `opencode mcp add` is used, then move the entry out of the
7+
`servers` key) and drop the stale "writes the global config" / "not shown in `--help`" claims. Update the Notes
8+
fallback (`mcp.servers` → the flat `mcp` map) and add the offer to flatten an existing `mcp.servers` nesting, with
9+
the `anomalyco/opencode#49904` retire-when. Verify by reading the file: no instruction tells the reader to write
10+
`mcp.servers`, and the fallback names the flat map. — verified: every `grep -nF 'mcp.servers'` hit is a warning
11+
against the nesting or the repair offer, none an instruction to write it; both steps and the Notes lead with the
12+
flat map.
13+
- [x] 1.2 `README.md`: the global-config snippet and its sentence — the GitHub server goes under the flat `mcp` map of
14+
the global config. Verify with `grep -nF 'mcp.servers' README.md`: every hit is a warning against the nesting,
15+
none an instruction to write it. — verified: the only hits are `:348-349`, both warnings (a plain
16+
`grep 'mcp.servers'` also matches the `[Tooling MCP Servers](#tooling-mcp-servers)` anchor, since `.` matches `-`;
17+
use `-F`).
18+
- [x] 1.3 `AGENTS.md`: the tooling-setup bullet (`opencode mcp add <name> -- <command…>` → the `--global` form plus the
19+
flat shape) and the config gotcha (extend the V1-shape requirement to the global config, naming the 1.x/ACP
20+
consumer) and the `mcp add` probe passage in "A CLI's `--help` and its docs are not its contract" (defaults to the
21+
project config; the `-- <command>` form _is_ listed in 2.0.21's help). Verify with `grep -n 'mcp add' AGENTS.md`
22+
and by reading each corrected sentence. — verified: all three sentences corrected (the tooling bullet, the
23+
V1-shape note in the config gotcha, and the `mcp add` probe passage of the CLI-`--help` gotcha).
24+
- [x] 1.4 The permission-proof `debug config` gotcha's normalized-document paragraph — re-probe the claim under the
25+
local 2.0.21 (`opencode debug config`, real `HOME`, grep only the relevant keys — do not print the document, which
26+
can carry credentials) and reconcile it with this change's rule: the paragraph calls the flat `mcp` form "legacy"
27+
and `mcp.servers.<name>` "native", while this change keeps the flat form, and its `disabled: false` detail is
28+
pinned to v2.0.15. Either re-label the characterization and re-state the observation for 2.0.21, or record in the
29+
design why the label stays accurate. Verify by reading the corrected sentence against the probe's output. —
30+
verified: 2.0.21's normalized document lifts the flat entry into `mcp.servers.<name>` with **no** `disabled` key
31+
materialized (`'disabled' in cfg` is false for all four servers) and masks the credential value
32+
(`GH_TOKEN: MASKED(asterisks)`); the passage now states both and drops the "legacy/native" labels.
33+
- [x] 1.5 Prove the documented shape loads under both lines: build the skill's shape in a scratch `HOME`
34+
(`/private/var/folders/.../T/opencode/...`, flat `mcp` + `permission`), run the 1.x ACP binary against it
35+
(`<bin> acp < <(sleep 6)`, background + liveness check) and confirm it starts, and run `opencode debug config`
36+
with the real `HOME` to confirm 2.x loads it; record both outputs. (The control — the same 1.x binary against an
37+
`mcp.servers` config exiting 1 — is the evidence already recorded in `design.md`.) — verified: 1.x stays alive
38+
after 5s against the documented shape (scratch `HOME`), and 2.x's `opencode debug config` exits 0 against the real
39+
global config, which is that shape.
40+
41+
## 2. Close-out
42+
43+
- [x] 2.1 Run `./gradlew spotlessApply` after the last edit to a Spotless-owned file, then
44+
`./gradlew check -PskipITs -Pcoverage.gate.enabled=false`; confirm green. — verified: `spotlessCheck` and the
45+
Docker-free `check` are green after the final edits (BUILD SUCCESSFUL).
46+
- [x] 2.2 Run the `lesson-capture` subagent over the diff, review findings, and change dir; apply its durable
47+
`AGENTS.md` proposals and record the applied net `AGENTS.md` delta on this task. — applied: two merged rules — the
48+
upstream-reference bullet gains the monitored-corpus requirement (a close-out reference cited only in a
49+
skill/definition/code comment is invisible to `upstreamReferences`, whose scan set is `AGENTS.md`, `README.md`,
50+
`docs/ideas.md`, `docs/adr/**`), with a pointer from the "Report an upstream gap" bullet; and the CLI-probe bullet
51+
gains the probe-write hazard (a probe whose default target is the repo runs from a scratch working directory, with
52+
`git status` after). The capture's proposed dedup was applied too: the tooling bullet's rationale moved to the
53+
V1-shape note, which keeps the `anomalyco/opencode#49904` citation in a scanned file. Three further candidates
54+
were already covered (the duplicate check, the `-F`/anchor rule, the point-in-time-snapshot rule) and were not
55+
added. Measured net for the capture's edits: **+8 AGENTS.md lines** (its hunks `+1/+0/+1/+3/+3`).

0 commit comments

Comments
 (0)