Skip to content

Commit cb23b2b

Browse files
committed
docs(memory): add WSL2 troubleshooting guide for npx stdout JSON parse errors
Explains why `npx -y @modelcontextprotocol/server-memory` causes "Unexpected non-whitespace character after JSON at position 127" errors in WSL2, and provides two workarounds: global npm install and direct node invocation. Fixes modelcontextprotocol#3013.
1 parent f424458 commit cb23b2b

1 file changed

Lines changed: 53 additions & 0 deletions

File tree

‎src/memory/README.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -236,6 +236,59 @@ Alternatively, you can add the configuration to a file called `.vscode/mcp.json`
236236
}
237237
```
238238

239+
### Troubleshooting: WSL2 JSON parse errors
240+
241+
When running the server via `npx -y @modelcontextprotocol/server-memory` inside WSL2, you may encounter errors like:
242+
243+
```
244+
Unexpected non-whitespace character after JSON at position 127
245+
```
246+
247+
This is caused by `npx` writing package resolution output to stdout before handing off to the server. Since MCP's stdio transport uses stdout exclusively for JSON-RPC messages, those extra bytes corrupt the stream. The server code itself is not at fault.
248+
249+
**Fix — Option A: Global install (recommended)**
250+
251+
```sh
252+
npm install -g @modelcontextprotocol/server-memory
253+
```
254+
255+
Then update your `.vscode/mcp.json`:
256+
257+
```json
258+
{
259+
"servers": {
260+
"memory": {
261+
"command": "mcp-server-memory",
262+
"args": []
263+
}
264+
}
265+
}
266+
```
267+
268+
**Fix — Option B: Run `node` directly**
269+
270+
```sh
271+
# Install once to get the package into the npx cache
272+
npx -y @modelcontextprotocol/server-memory
273+
# Find the installed path
274+
npm root -g
275+
```
276+
277+
Then reference the entry point directly in `.vscode/mcp.json`:
278+
279+
```json
280+
{
281+
"servers": {
282+
"memory": {
283+
"command": "node",
284+
"args": ["/path/to/global/node_modules/@modelcontextprotocol/server-memory/dist/index.js"]
285+
}
286+
}
287+
}
288+
```
289+
290+
Both options bypass `npx` at server startup, eliminating the stdout pollution.
291+
239292
### System Prompt
240293

241294
The prompt for utilizing memory depends on the use case. Changing the prompt will help the model determine the frequency and types of memories created.

0 commit comments

Comments
 (0)