Skip to content

Commit 1af6e3c

Browse files
committed
docs+config: connect OpenCode to notes-server (verified live)
- opencode.jsonc: project-local stdio registration with absolute uv path - docs/05 addendum: verified connection, mcp add v2.1.2 flag pass-through limitation (same error class as anomalyco/opencode#49085), V2 project-config detection confirmed, Code Mode naming + instructions injection verified live
1 parent 5db8df0 commit 1af6e3c

2 files changed

Lines changed: 67 additions & 0 deletions

File tree

‎mcp-experimentation/docs/05-connecting-opencode.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -146,6 +146,41 @@ Deny/allow per tool by the normalized name without disconnecting:
146146
| Notes seem to "reset" | A cwd-relative DB path got repointed — our default anchors to the project; check you did not set `NOTES_DB_PATH` somewhere else |
147147
| JSON config errors | Windows backslashes must be `\\` in JSON — forward slashes avoid the whole class of bugs |
148148

149+
## Verified on this machine (2026-10-25, OpenCode v2.1.2)
150+
151+
What we actually ran to connect this project — the config above is not
152+
hypothetical, it is the exact `opencode.jsonc` in this directory, and it
153+
works. Two things we learned live:
154+
155+
**1. `opencode mcp add` (v2.1.2) can't pass command flags through `--`.**
156+
157+
```sh
158+
opencode mcp add notes -- uv --directory "E:/..." run notes-server
159+
# ERROR Unrecognized flag: --directory in command opencode mcp add
160+
```
161+
162+
The v2 flag parser rejects arguments like `--directory` even after the `--`
163+
pass-through marker (same error class as the reported `--port` issues
164+
anomalyco/opencode#49085, #50530, #51512). The workaround is the hand-written
165+
config above — which is the documented-by-hand shape anyway. If your command
166+
needs no flags (`npx -y some-server`), `opencode mcp add` still works fine.
167+
168+
**2. Project-level MCP configs ARE detected in V2** (an old V1 issue, #4054,
169+
claimed otherwise) — proven by the connection coming up purely from this
170+
directory's `opencode.jsonc`. OpenCode merges configs walking from the
171+
filesystem root down to the current directory, so this server is visible
172+
whenever OpenCode runs inside this project (use `--global` / the global
173+
config to have it everywhere).
174+
175+
What the connection looked like from the agent's side (Code Mode, the
176+
default): the server's tools appeared as `tools.notes.add_note(...)`,
177+
`tools.notes.search_notes(...)` etc. (the `<server>.<tool>` grouping
178+
predicted above), and the server's `instructions` were injected into the
179+
agent's context inside `<mcp_instructions>` — the live agent then read the
180+
real database rows and wrote a note through the server, with the structured
181+
`Note` object coming back as typed JSON. The exact behaviors this doc
182+
predicted all verified: naming, instructions injection, real-data reads.
183+
149184
## What you have now, end to end
150185

151186
A server you built with the official SDK v2 → tested in-process with the

‎mcp-experimentation/opencode.jsonc‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
{
2+
"$schema": "https://opencode.ai/config.json",
3+
// Project-local OpenCode config: registers this repo's notes MCP server
4+
// as a stdio server that OpenCode launches itself (type: "local").
5+
//
6+
// Why the absolute uv path: OpenCode's service process may resolve PATH
7+
// differently from your shell, and this machine has TWO uv installs
8+
// (hermes-managed and Python311). Pinning the one `where.exe uv` lists
9+
// first removes the guesswork.
10+
//
11+
// Why `--directory`: makes the launch independent of which directory
12+
// OpenCode happens to run in (the DB location is anchored to the package,
13+
// so every launch reads/writes the SAME data/notes.db).
14+
//
15+
// Note: backslashes are escaped in JSON — or use forward slashes instead.
16+
// (`opencode mcp add` in v2.1.2 currently can't pass flags like
17+
// `--directory` through `--`, hence this hand-written config.)
18+
"mcp": {
19+
"servers": {
20+
"notes": {
21+
"type": "local",
22+
"command": [
23+
"C:\\Users\\Cikal Merdeka\\AppData\\Local\\hermes\\bin\\uv.exe",
24+
"--directory",
25+
"E:\\NLP Learning\\mcp-experimentation",
26+
"run",
27+
"notes-server"
28+
]
29+
}
30+
}
31+
}
32+
}

0 commit comments

Comments
 (0)