neuronlayer 0.2.7 → 0.2.10
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +2 -2
- package/doc/CLAUDE-CODE-SETUP.md +504 -0
- package/doc/OPENCODE-SETUP.md +425 -0
- package/package.json +3 -2
package/README.md
CHANGED
|
@@ -48,9 +48,9 @@ This registers your project and configures Claude Desktop, Claude Code, OpenCode
|
|
|
48
48
|
| Tool | Setup |
|
|
49
49
|
|------|-------|
|
|
50
50
|
| Claude Desktop | `neuronlayer init` (auto) |
|
|
51
|
-
| Claude Code (CLI) | [`neuronlayer init` (auto)](./
|
|
51
|
+
| Claude Code (CLI) | [`neuronlayer init` (auto)](./doc/CLAUDE-CODE-SETUP.md) |
|
|
52
52
|
| Cursor | `neuronlayer init` (auto) |
|
|
53
|
-
| OpenCode | [`neuronlayer init` (auto)](./
|
|
53
|
+
| OpenCode | [`neuronlayer init` (auto)](./doc/OPENCODE-SETUP.md) |
|
|
54
54
|
| Any MCP Client | Manual config |
|
|
55
55
|
| **Any tool (HTTP)** | `neuronlayer serve` |
|
|
56
56
|
|
|
@@ -0,0 +1,504 @@
|
|
|
1
|
+
# NeuronLayer + Claude Code Setup Guide
|
|
2
|
+
|
|
3
|
+
This guide explains how to configure NeuronLayer as an MCP server for [Claude Code](https://code.claude.com/) (Anthropic's CLI tool).
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## Prerequisites
|
|
8
|
+
|
|
9
|
+
1. **Node.js 18+** installed
|
|
10
|
+
2. **Claude Code** installed (`npm install -g @anthropic-ai/claude-code`)
|
|
11
|
+
3. **NeuronLayer** built (`npm run build`)
|
|
12
|
+
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
## Quick Setup (Recommended)
|
|
16
|
+
|
|
17
|
+
The easiest and most reliable way to configure NeuronLayer for Claude Code is using our automated initialization command.
|
|
18
|
+
|
|
19
|
+
### Step 1: Initialize NeuronLayer
|
|
20
|
+
|
|
21
|
+
Run this command in the root of your project:
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
npx neuronlayer init .
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
This will automatically configure `.mcp.json` in your project with the exact absolute paths and platform-specific commands required for Claude Code to connect smoothly to NeuronLayer.
|
|
28
|
+
|
|
29
|
+
### Step 2: Verify Connection
|
|
30
|
+
|
|
31
|
+
Start Claude Code and check your servers:
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
# Inside Claude Code
|
|
35
|
+
/mcp
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
You should see:
|
|
39
|
+
```
|
|
40
|
+
MCP Servers
|
|
41
|
+
neuronlayer (stdio)
|
|
42
|
+
Status: connected
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
---
|
|
46
|
+
|
|
47
|
+
## Configuration Methods (Advanced)
|
|
48
|
+
|
|
49
|
+
If you prefer not to use the automated `npx neuronlayer init` command, Claude Code provides several ways to configure MCP servers manually.
|
|
50
|
+
|
|
51
|
+
### Method 1: CLI Commands
|
|
52
|
+
|
|
53
|
+
Claude Code provides CLI commands to manage MCP servers:
|
|
54
|
+
|
|
55
|
+
```bash
|
|
56
|
+
# Add a server
|
|
57
|
+
claude mcp add --transport stdio neuronlayer -- node /absolute/path/to/dist/index.js --project .
|
|
58
|
+
|
|
59
|
+
# List all servers
|
|
60
|
+
claude mcp list
|
|
61
|
+
|
|
62
|
+
# Get server details
|
|
63
|
+
claude mcp get neuronlayer
|
|
64
|
+
|
|
65
|
+
# Remove a server
|
|
66
|
+
claude mcp remove neuronlayer
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
**Note:** On Windows natively, you MUST wrap the node execution with `cmd /c` to prevent stdin/stdout hanging issues:
|
|
70
|
+
```bash
|
|
71
|
+
claude mcp add --transport stdio neuronlayer -- cmd /c node C:\absolute\path\to\dist\index.js --project .
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
### Method 2: Project Configuration (`.mcp.json`)
|
|
75
|
+
|
|
76
|
+
If you want to create `.mcp.json` in your project root manually:
|
|
77
|
+
|
|
78
|
+
```json
|
|
79
|
+
{
|
|
80
|
+
"mcpServers": {
|
|
81
|
+
"neuronlayer": {
|
|
82
|
+
"type": "stdio",
|
|
83
|
+
"command": "node",
|
|
84
|
+
"args": ["/absolute/path/to/neuronlayer/dist/index.js", "--project", "."],
|
|
85
|
+
"env": {}
|
|
86
|
+
}
|
|
87
|
+
}
|
|
88
|
+
}
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
*For Windows, use `["cmd", "/c", "node", "C:\\absolute\\path\\to\\dist\\index.js", "--project", "."]` in the command and args fields as appropriate depending on your node integration.*
|
|
92
|
+
|
|
93
|
+
---
|
|
94
|
+
|
|
95
|
+
## Configuration Scopes
|
|
96
|
+
|
|
97
|
+
| Scope | Storage Location | Use Case |
|
|
98
|
+
|-------|------------------|----------|
|
|
99
|
+
| `local` (default) | `~/.claude.json` | Personal, current project only |
|
|
100
|
+
| `project` | `.mcp.json` | Shared with team via version control |
|
|
101
|
+
| `user` | `~/.claude.json` | Personal, available across all projects |
|
|
102
|
+
|
|
103
|
+
```bash
|
|
104
|
+
# The automated init command uses Project scope by default
|
|
105
|
+
npx neuronlayer init .
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
---
|
|
109
|
+
|
|
110
|
+
## Platform-Specific Setup
|
|
111
|
+
|
|
112
|
+
### Windows (Native)
|
|
113
|
+
|
|
114
|
+
On native Windows (not WSL), use the `cmd /c` wrapper for proper execution:
|
|
115
|
+
|
|
116
|
+
```bash
|
|
117
|
+
# Using CLI
|
|
118
|
+
claude mcp add --transport stdio neuronlayer -- cmd /c node C:\path\to\neuronlayer\dist\index.js --project .
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
**In `.mcp.json`:**
|
|
122
|
+
|
|
123
|
+
```json
|
|
124
|
+
{
|
|
125
|
+
"mcpServers": {
|
|
126
|
+
"neuronlayer": {
|
|
127
|
+
"type": "stdio",
|
|
128
|
+
"command": "cmd",
|
|
129
|
+
"args": ["/c", "node", "C:\\path\\to\\neuronlayer\\dist\\index.js", "--project", "."],
|
|
130
|
+
"env": {}
|
|
131
|
+
}
|
|
132
|
+
}
|
|
133
|
+
}
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
### Windows (WSL)
|
|
137
|
+
|
|
138
|
+
WSL works like Linux:
|
|
139
|
+
|
|
140
|
+
```bash
|
|
141
|
+
claude mcp add --transport stdio neuronlayer -- node /path/to/neuronlayer/dist/index.js --project .
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
### macOS / Linux
|
|
145
|
+
|
|
146
|
+
```bash
|
|
147
|
+
claude mcp add --transport stdio neuronlayer -- node /path/to/neuronlayer/dist/index.js --project .
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
**In `.mcp.json`:**
|
|
151
|
+
|
|
152
|
+
```json
|
|
153
|
+
{
|
|
154
|
+
"mcpServers": {
|
|
155
|
+
"neuronlayer": {
|
|
156
|
+
"type": "stdio",
|
|
157
|
+
"command": "node",
|
|
158
|
+
"args": ["/Users/you/neuronlayer/dist/index.js", "--project", "."],
|
|
159
|
+
"env": {}
|
|
160
|
+
}
|
|
161
|
+
}
|
|
162
|
+
}
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
---
|
|
166
|
+
|
|
167
|
+
## After npm Publish
|
|
168
|
+
|
|
169
|
+
Once NeuronLayer is published to npm, setup becomes simpler:
|
|
170
|
+
|
|
171
|
+
### CLI Command
|
|
172
|
+
|
|
173
|
+
```bash
|
|
174
|
+
# Install globally
|
|
175
|
+
npm install -g neuronlayer
|
|
176
|
+
|
|
177
|
+
# Add to Claude Code
|
|
178
|
+
claude mcp add --transport stdio neuronlayer -- neuronlayer --project .
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
### Using npx
|
|
182
|
+
|
|
183
|
+
```bash
|
|
184
|
+
# Without installation
|
|
185
|
+
claude mcp add --transport stdio neuronlayer -- npx -y neuronlayer --project .
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
**Windows (with npx):**
|
|
189
|
+
|
|
190
|
+
```bash
|
|
191
|
+
claude mcp add --transport stdio neuronlayer -- cmd /c npx -y neuronlayer --project .
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
### Project `.mcp.json`
|
|
195
|
+
|
|
196
|
+
```json
|
|
197
|
+
{
|
|
198
|
+
"mcpServers": {
|
|
199
|
+
"neuronlayer": {
|
|
200
|
+
"type": "stdio",
|
|
201
|
+
"command": "npx",
|
|
202
|
+
"args": ["-y", "neuronlayer", "--project", "."],
|
|
203
|
+
"env": {}
|
|
204
|
+
}
|
|
205
|
+
}
|
|
206
|
+
}
|
|
207
|
+
```
|
|
208
|
+
|
|
209
|
+
---
|
|
210
|
+
|
|
211
|
+
## Environment Variables
|
|
212
|
+
|
|
213
|
+
### NeuronLayer Configuration
|
|
214
|
+
|
|
215
|
+
| Variable | Default | Description |
|
|
216
|
+
|----------|---------|-------------|
|
|
217
|
+
| `NEURONLAYER_MAX_TOKENS` | 6000 | Maximum tokens for context assembly |
|
|
218
|
+
| `NEURONLAYER_DEBUG` | false | Enable debug logging |
|
|
219
|
+
|
|
220
|
+
```bash
|
|
221
|
+
claude mcp add --transport stdio \
|
|
222
|
+
--env NEURONLAYER_MAX_TOKENS=8000 \
|
|
223
|
+
--env NEURONLAYER_DEBUG=true \
|
|
224
|
+
neuronlayer -- node dist/index.js --project .
|
|
225
|
+
```
|
|
226
|
+
|
|
227
|
+
### Claude Code MCP Settings
|
|
228
|
+
|
|
229
|
+
| Variable | Default | Description |
|
|
230
|
+
|----------|---------|-------------|
|
|
231
|
+
| `MCP_TIMEOUT` | 60000 | Server startup timeout (ms) |
|
|
232
|
+
| `MAX_MCP_OUTPUT_TOKENS` | 25000 | Max tokens from MCP tools |
|
|
233
|
+
|
|
234
|
+
```bash
|
|
235
|
+
# Start Claude Code with custom MCP settings
|
|
236
|
+
MCP_TIMEOUT=120000 MAX_MCP_OUTPUT_TOKENS=50000 claude
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
---
|
|
240
|
+
|
|
241
|
+
## Available MCP Tools
|
|
242
|
+
|
|
243
|
+
Once connected, Claude Code can use these NeuronLayer tools:
|
|
244
|
+
|
|
245
|
+
### Core Tools
|
|
246
|
+
|
|
247
|
+
| Tool | Description |
|
|
248
|
+
|------|-------------|
|
|
249
|
+
| `get_context` | Get relevant codebase context for a query |
|
|
250
|
+
| `search_codebase` | Semantic search across all files |
|
|
251
|
+
| `record_decision` | Save an architectural decision |
|
|
252
|
+
| `get_file_context` | Get content of a specific file |
|
|
253
|
+
| `get_project_summary` | Overview of project structure |
|
|
254
|
+
|
|
255
|
+
### Symbol & Dependency Tools
|
|
256
|
+
|
|
257
|
+
| Tool | Description |
|
|
258
|
+
|------|-------------|
|
|
259
|
+
| `get_symbol` | Find functions, classes, types by name |
|
|
260
|
+
| `get_dependencies` | See imports/exports for a file |
|
|
261
|
+
| `get_file_summary` | Get compressed file summary (10x smaller) |
|
|
262
|
+
|
|
263
|
+
### Living Documentation Tools
|
|
264
|
+
|
|
265
|
+
| Tool | Description |
|
|
266
|
+
|------|-------------|
|
|
267
|
+
| `generate_docs` | Generate documentation for a file or architecture |
|
|
268
|
+
| `get_architecture` | Get project architecture overview |
|
|
269
|
+
| `get_component_doc` | Get detailed documentation for a component |
|
|
270
|
+
| `get_changelog` | Get changelog of recent changes |
|
|
271
|
+
| `validate_docs` | Check for outdated docs |
|
|
272
|
+
| `what_happened` | Query recent project activity |
|
|
273
|
+
|
|
274
|
+
### Context Health Tools
|
|
275
|
+
|
|
276
|
+
| Tool | Description |
|
|
277
|
+
|------|-------------|
|
|
278
|
+
| `get_context_health` | Check context health and drift score |
|
|
279
|
+
| `trigger_compaction` | Manually trigger context compaction |
|
|
280
|
+
| `mark_critical` | Mark content as critical (never compress) |
|
|
281
|
+
|
|
282
|
+
### Confidence & Intelligence Tools
|
|
283
|
+
|
|
284
|
+
| Tool | Description |
|
|
285
|
+
|------|-------------|
|
|
286
|
+
| `get_confidence` | Get confidence score for code suggestion |
|
|
287
|
+
| `check_conflicts` | Check if code conflicts with past decisions |
|
|
288
|
+
| `what_changed` | Query what changed in the codebase |
|
|
289
|
+
| `why_broke` | Diagnose why something broke |
|
|
290
|
+
| `suggest_fix` | Get fix suggestions for an error |
|
|
291
|
+
|
|
292
|
+
### Architecture Tools
|
|
293
|
+
|
|
294
|
+
| Tool | Description |
|
|
295
|
+
|------|-------------|
|
|
296
|
+
| `validate_pattern` | Validate code against established patterns |
|
|
297
|
+
| `suggest_existing` | Find existing functions that match intent |
|
|
298
|
+
| `learn_pattern` | Teach a new pattern to the system |
|
|
299
|
+
| `list_patterns` | List all learned patterns |
|
|
300
|
+
|
|
301
|
+
### Test Awareness Tools
|
|
302
|
+
|
|
303
|
+
| Tool | Description |
|
|
304
|
+
|------|-------------|
|
|
305
|
+
| `get_related_tests` | Get tests related to a file or function |
|
|
306
|
+
| `check_tests` | Check if a code change would break tests |
|
|
307
|
+
| `suggest_test_update` | Get suggested test updates for a change |
|
|
308
|
+
| `get_test_coverage` | Get test coverage for a file |
|
|
309
|
+
|
|
310
|
+
---
|
|
311
|
+
|
|
312
|
+
## Example Usage
|
|
313
|
+
|
|
314
|
+
Once configured, try these prompts in Claude Code:
|
|
315
|
+
|
|
316
|
+
```
|
|
317
|
+
> Search for authentication code in this project
|
|
318
|
+
|
|
319
|
+
> What architectural decisions have been made?
|
|
320
|
+
|
|
321
|
+
> Show me the project summary
|
|
322
|
+
|
|
323
|
+
> Find the function that handles user login
|
|
324
|
+
|
|
325
|
+
> What files import the database module?
|
|
326
|
+
|
|
327
|
+
> What changed in the last 24 hours?
|
|
328
|
+
|
|
329
|
+
> Why might the login test be failing?
|
|
330
|
+
|
|
331
|
+
> Record a decision: We chose SQLite for local storage because it's embedded and requires no separate server
|
|
332
|
+
|
|
333
|
+
> Get the architecture overview of this project
|
|
334
|
+
|
|
335
|
+
> Check if this code follows our patterns: async function fetchUser(id) { ... }
|
|
336
|
+
```
|
|
337
|
+
|
|
338
|
+
---
|
|
339
|
+
|
|
340
|
+
## Troubleshooting
|
|
341
|
+
|
|
342
|
+
### "Connection closed" on Windows
|
|
343
|
+
|
|
344
|
+
Ensure you're using the `cmd /c` wrapper:
|
|
345
|
+
|
|
346
|
+
```bash
|
|
347
|
+
# Wrong
|
|
348
|
+
claude mcp add --transport stdio neuronlayer -- node dist/index.js --project .
|
|
349
|
+
|
|
350
|
+
# Correct
|
|
351
|
+
claude mcp add --transport stdio neuronlayer -- cmd /c node dist/index.js --project .
|
|
352
|
+
```
|
|
353
|
+
|
|
354
|
+
### "Server not found" or "ENOENT"
|
|
355
|
+
|
|
356
|
+
1. Verify the path to `dist/index.js` is correct and absolute
|
|
357
|
+
2. Ensure NeuronLayer is built: `npm run build`
|
|
358
|
+
3. Check Node.js is in your PATH
|
|
359
|
+
|
|
360
|
+
### "MCP server not connected"
|
|
361
|
+
|
|
362
|
+
1. Run `claude mcp list` to check configuration
|
|
363
|
+
2. Run `/mcp` inside Claude Code to see status
|
|
364
|
+
3. Check for errors in the server output
|
|
365
|
+
|
|
366
|
+
### "Configuration is invalid"
|
|
367
|
+
|
|
368
|
+
Ensure your JSON is valid and `command` is a string (not array):
|
|
369
|
+
|
|
370
|
+
```json
|
|
371
|
+
// Correct
|
|
372
|
+
{
|
|
373
|
+
"type": "stdio",
|
|
374
|
+
"command": "node",
|
|
375
|
+
"args": ["dist/index.js", "--project", "."]
|
|
376
|
+
}
|
|
377
|
+
|
|
378
|
+
// Wrong
|
|
379
|
+
{
|
|
380
|
+
"type": "stdio",
|
|
381
|
+
"command": ["node", "dist/index.js"]
|
|
382
|
+
}
|
|
383
|
+
```
|
|
384
|
+
|
|
385
|
+
### Server Takes Too Long to Start
|
|
386
|
+
|
|
387
|
+
Increase the MCP timeout:
|
|
388
|
+
|
|
389
|
+
```bash
|
|
390
|
+
MCP_TIMEOUT=120000 claude
|
|
391
|
+
```
|
|
392
|
+
|
|
393
|
+
Or set in `.mcp.json`:
|
|
394
|
+
|
|
395
|
+
```json
|
|
396
|
+
{
|
|
397
|
+
"mcpServers": {
|
|
398
|
+
"neuronlayer": {
|
|
399
|
+
"type": "stdio",
|
|
400
|
+
"command": "node",
|
|
401
|
+
"args": ["dist/index.js", "--project", "."],
|
|
402
|
+
"env": {},
|
|
403
|
+
"timeout": 120000
|
|
404
|
+
}
|
|
405
|
+
}
|
|
406
|
+
}
|
|
407
|
+
```
|
|
408
|
+
|
|
409
|
+
### View Debug Logs
|
|
410
|
+
|
|
411
|
+
```bash
|
|
412
|
+
# Run Claude Code with debug logging
|
|
413
|
+
claude --log-level DEBUG
|
|
414
|
+
```
|
|
415
|
+
|
|
416
|
+
---
|
|
417
|
+
|
|
418
|
+
## Importing from Claude Desktop
|
|
419
|
+
|
|
420
|
+
If you already have NeuronLayer configured in Claude Desktop:
|
|
421
|
+
|
|
422
|
+
```bash
|
|
423
|
+
# Import all servers from Claude Desktop
|
|
424
|
+
claude mcp add-from-claude-desktop
|
|
425
|
+
|
|
426
|
+
# Select neuronlayer from the list
|
|
427
|
+
|
|
428
|
+
# Verify import
|
|
429
|
+
claude mcp list
|
|
430
|
+
```
|
|
431
|
+
|
|
432
|
+
---
|
|
433
|
+
|
|
434
|
+
## Data Storage
|
|
435
|
+
|
|
436
|
+
NeuronLayer stores data locally:
|
|
437
|
+
|
|
438
|
+
```
|
|
439
|
+
~/.neuronlayer/
|
|
440
|
+
├── registry.json # Project registry
|
|
441
|
+
└── projects/
|
|
442
|
+
└── {project-name}-{hash}/
|
|
443
|
+
├── neuronlayer.db # SQLite database
|
|
444
|
+
└── tier1.json # Working context
|
|
445
|
+
```
|
|
446
|
+
|
|
447
|
+
---
|
|
448
|
+
|
|
449
|
+
## Comparison: Claude Desktop vs Claude Code
|
|
450
|
+
|
|
451
|
+
| Feature | Claude Desktop | Claude Code |
|
|
452
|
+
|---------|----------------|-------------|
|
|
453
|
+
| Config Location | `~/.claude/claude_desktop_config.json` | `~/.claude.json` or `.mcp.json` |
|
|
454
|
+
| Add Server | Manual JSON edit | CLI commands or JSON |
|
|
455
|
+
| Project Scope | No | Yes (`.mcp.json`) |
|
|
456
|
+
| User Scope | Yes | Yes |
|
|
457
|
+
| Local Scope | N/A | Yes (default) |
|
|
458
|
+
| Env Var Expansion | No | Yes (`${VAR}` syntax) |
|
|
459
|
+
|
|
460
|
+
---
|
|
461
|
+
|
|
462
|
+
## Links
|
|
463
|
+
|
|
464
|
+
- [Claude Code Documentation](https://code.claude.com/docs/)
|
|
465
|
+
- [Claude Code MCP Guide](https://code.claude.com/docs/en/mcp)
|
|
466
|
+
- [Claude Code Settings](https://code.claude.com/docs/en/settings)
|
|
467
|
+
- [MCP Protocol Specification](https://modelcontextprotocol.io/)
|
|
468
|
+
- [NeuronLayer Documentation](./INDEX.md)
|
|
469
|
+
|
|
470
|
+
---
|
|
471
|
+
|
|
472
|
+
## Quick Reference
|
|
473
|
+
|
|
474
|
+
### Minimum Setup
|
|
475
|
+
|
|
476
|
+
```bash
|
|
477
|
+
# One-liner setup
|
|
478
|
+
claude mcp add --transport stdio neuronlayer -- node /path/to/neuronlayer/dist/index.js --project .
|
|
479
|
+
```
|
|
480
|
+
|
|
481
|
+
### Full `.mcp.json` Example
|
|
482
|
+
|
|
483
|
+
```json
|
|
484
|
+
{
|
|
485
|
+
"mcpServers": {
|
|
486
|
+
"neuronlayer": {
|
|
487
|
+
"type": "stdio",
|
|
488
|
+
"command": "node",
|
|
489
|
+
"args": [
|
|
490
|
+
"/path/to/neuronlayer/dist/index.js",
|
|
491
|
+
"--project",
|
|
492
|
+
"."
|
|
493
|
+
],
|
|
494
|
+
"env": {
|
|
495
|
+
"NEURONLAYER_MAX_TOKENS": "8000"
|
|
496
|
+
}
|
|
497
|
+
}
|
|
498
|
+
}
|
|
499
|
+
}
|
|
500
|
+
```
|
|
501
|
+
|
|
502
|
+
---
|
|
503
|
+
|
|
504
|
+
*Last updated: February 2026*
|
|
@@ -0,0 +1,425 @@
|
|
|
1
|
+
# NeuronLayer + OpenCode Setup Guide
|
|
2
|
+
|
|
3
|
+
This guide explains how to configure NeuronLayer as an MCP server for [OpenCode](https://opencode.ai).
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## Prerequisites
|
|
8
|
+
|
|
9
|
+
1. **Node.js 18+** installed
|
|
10
|
+
2. **OpenCode** installed (`npm install -g opencode`)
|
|
11
|
+
3. **NeuronLayer** built (`npm run build`)
|
|
12
|
+
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
## Quick Setup (Recommended)
|
|
16
|
+
|
|
17
|
+
The easiest and most reliable way to configure NeuronLayer for OpenCode is using our automated initialization command.
|
|
18
|
+
|
|
19
|
+
### Step 1: Initialize NeuronLayer
|
|
20
|
+
|
|
21
|
+
Run this command in the root of your project:
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
npx neuronlayer init .
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
This will automatically detect your operating system and generate the correct `opencode.json` configuration file with the exact absolute paths required for OpenCode to connect to NeuronLayer.
|
|
28
|
+
|
|
29
|
+
### Step 2: Start OpenCode
|
|
30
|
+
|
|
31
|
+
```bash
|
|
32
|
+
opencode
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
### Step 3: Verify Connection
|
|
36
|
+
|
|
37
|
+
Inside OpenCode, type:
|
|
38
|
+
```
|
|
39
|
+
/mcp
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
You should see:
|
|
43
|
+
```
|
|
44
|
+
MCP Servers
|
|
45
|
+
neuronlayer (local)
|
|
46
|
+
Status: connected
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
Or from your terminal:
|
|
50
|
+
```bash
|
|
51
|
+
opencode mcp list
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
---
|
|
55
|
+
|
|
56
|
+
## Manual Configuration (Advanced)
|
|
57
|
+
|
|
58
|
+
If you prefer to configure OpenCode manually, create an `opencode.json` file in your project root.
|
|
59
|
+
|
|
60
|
+
**IMPORTANT:** You must use **absolute paths** for reliable operation, and on Windows you must use `cmd` to wrap the Node execution.
|
|
61
|
+
|
|
62
|
+
**Windows Example:**
|
|
63
|
+
```json
|
|
64
|
+
{
|
|
65
|
+
"$schema": "https://opencode.ai/config.json",
|
|
66
|
+
"mcp": {
|
|
67
|
+
"neuronlayer": {
|
|
68
|
+
"type": "local",
|
|
69
|
+
"command": ["cmd", "/c", "node", "C:\\Users\\YOUR_USERNAME\\path\\to\\neuronlayer\\dist\\index.js", "--project", "C:\\Users\\YOUR_USERNAME\\path\\to\\your\\project"],
|
|
70
|
+
"enabled": true
|
|
71
|
+
}
|
|
72
|
+
}
|
|
73
|
+
}
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
**macOS/Linux Example:**
|
|
77
|
+
```json
|
|
78
|
+
{
|
|
79
|
+
"$schema": "https://opencode.ai/config.json",
|
|
80
|
+
"mcp": {
|
|
81
|
+
"neuronlayer": {
|
|
82
|
+
"type": "local",
|
|
83
|
+
"command": ["node", "/home/user/neuronlayer/dist/index.js", "--project", "/home/user/myproject"],
|
|
84
|
+
"enabled": true
|
|
85
|
+
}
|
|
86
|
+
}
|
|
87
|
+
}
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
---
|
|
91
|
+
|
|
92
|
+
## Global Setup
|
|
93
|
+
|
|
94
|
+
For system-wide availability, create the config in your home directory:
|
|
95
|
+
|
|
96
|
+
**Windows:** `%USERPROFILE%\.config\opencode\opencode.json`
|
|
97
|
+
**macOS/Linux:** `~/.config/opencode/opencode.json`
|
|
98
|
+
|
|
99
|
+
```json
|
|
100
|
+
{
|
|
101
|
+
"$schema": "https://opencode.ai/config.json",
|
|
102
|
+
"mcp": {
|
|
103
|
+
"neuronlayer": {
|
|
104
|
+
"type": "local",
|
|
105
|
+
"command": ["node", "/absolute/path/to/neuronlayer/dist/index.js", "--project", "."],
|
|
106
|
+
"enabled": true
|
|
107
|
+
}
|
|
108
|
+
}
|
|
109
|
+
}
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
---
|
|
113
|
+
|
|
114
|
+
## After npm Publish
|
|
115
|
+
|
|
116
|
+
Once NeuronLayer is published to npm, setup becomes simpler:
|
|
117
|
+
|
|
118
|
+
### Using npx
|
|
119
|
+
|
|
120
|
+
```json
|
|
121
|
+
{
|
|
122
|
+
"$schema": "https://opencode.ai/config.json",
|
|
123
|
+
"mcp": {
|
|
124
|
+
"neuronlayer": {
|
|
125
|
+
"type": "local",
|
|
126
|
+
"command": ["npx", "-y", "neuronlayer", "--project", "."],
|
|
127
|
+
"enabled": true
|
|
128
|
+
}
|
|
129
|
+
}
|
|
130
|
+
}
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
### Global Install
|
|
134
|
+
|
|
135
|
+
```bash
|
|
136
|
+
npm install -g neuronlayer
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
```json
|
|
140
|
+
{
|
|
141
|
+
"$schema": "https://opencode.ai/config.json",
|
|
142
|
+
"mcp": {
|
|
143
|
+
"neuronlayer": {
|
|
144
|
+
"type": "local",
|
|
145
|
+
"command": ["neuronlayer", "--project", "."],
|
|
146
|
+
"enabled": true
|
|
147
|
+
}
|
|
148
|
+
}
|
|
149
|
+
}
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
---
|
|
153
|
+
|
|
154
|
+
## Configuration Reference
|
|
155
|
+
|
|
156
|
+
| Field | Type | Required | Description |
|
|
157
|
+
|-------|------|----------|-------------|
|
|
158
|
+
| `type` | `"local"` \| `"remote"` | Yes | Server type |
|
|
159
|
+
| `command` | `string[]` | Yes (local) | Command array (NOT a string) |
|
|
160
|
+
| `enabled` | `boolean` | Yes | Must be `true` to connect |
|
|
161
|
+
| `environment` | `object` | No | Environment variables |
|
|
162
|
+
|
|
163
|
+
### Example with Environment Variables
|
|
164
|
+
|
|
165
|
+
```json
|
|
166
|
+
{
|
|
167
|
+
"$schema": "https://opencode.ai/config.json",
|
|
168
|
+
"mcp": {
|
|
169
|
+
"neuronlayer": {
|
|
170
|
+
"type": "local",
|
|
171
|
+
"command": ["node", "C:\\path\\to\\neuronlayer\\dist\\index.js", "--project", "."],
|
|
172
|
+
"enabled": true,
|
|
173
|
+
"environment": {
|
|
174
|
+
"NEURONLAYER_MAX_TOKENS": "8000",
|
|
175
|
+
"NEURONLAYER_DEBUG": "true"
|
|
176
|
+
}
|
|
177
|
+
}
|
|
178
|
+
}
|
|
179
|
+
}
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
---
|
|
183
|
+
|
|
184
|
+
## Available Tools (51 Total)
|
|
185
|
+
|
|
186
|
+
Once connected, OpenCode's AI can use all NeuronLayer tools:
|
|
187
|
+
|
|
188
|
+
### Core Tools (5)
|
|
189
|
+
| Tool | Description |
|
|
190
|
+
|------|-------------|
|
|
191
|
+
| `get_context` | Get relevant codebase context for a query |
|
|
192
|
+
| `search_codebase` | Semantic search across all files |
|
|
193
|
+
| `record_decision` | Save an architectural decision |
|
|
194
|
+
| `get_file_context` | Get content of a specific file |
|
|
195
|
+
| `get_project_summary` | Overview of project structure |
|
|
196
|
+
|
|
197
|
+
### Symbol & Dependency Tools (3)
|
|
198
|
+
| Tool | Description |
|
|
199
|
+
|------|-------------|
|
|
200
|
+
| `get_symbol` | Find functions, classes, types by name |
|
|
201
|
+
| `get_dependencies` | See imports/exports for a file |
|
|
202
|
+
| `get_file_summary` | Get compressed file summary (10x smaller) |
|
|
203
|
+
|
|
204
|
+
### Learning Tools (3)
|
|
205
|
+
| Tool | Description |
|
|
206
|
+
|------|-------------|
|
|
207
|
+
| `get_predicted_files` | Files predicted to be relevant |
|
|
208
|
+
| `get_learning_stats` | Usage statistics |
|
|
209
|
+
| `mark_context_useful` | Feedback for learning |
|
|
210
|
+
|
|
211
|
+
### Multi-Project Tools (6)
|
|
212
|
+
| Tool | Description |
|
|
213
|
+
|------|-------------|
|
|
214
|
+
| `list_projects` | List all registered projects |
|
|
215
|
+
| `switch_project` | Switch active project |
|
|
216
|
+
| `search_all_projects` | Search across all projects |
|
|
217
|
+
| `discover_projects` | Find projects on system |
|
|
218
|
+
| `record_decision_with_author` | Decision with author attribution |
|
|
219
|
+
| `update_decision_status` | Update decision lifecycle |
|
|
220
|
+
| `export_decisions_to_adr` | Export to ADR markdown files |
|
|
221
|
+
|
|
222
|
+
### Feature Context Tools (4)
|
|
223
|
+
| Tool | Description |
|
|
224
|
+
|------|-------------|
|
|
225
|
+
| `get_active_context` | Get current work session context |
|
|
226
|
+
| `set_feature_context` | Start tracking a feature |
|
|
227
|
+
| `list_recent_contexts` | List recent work sessions |
|
|
228
|
+
| `switch_feature_context` | Switch to previous session |
|
|
229
|
+
|
|
230
|
+
### Living Documentation Tools (7)
|
|
231
|
+
| Tool | Description |
|
|
232
|
+
|------|-------------|
|
|
233
|
+
| `generate_docs` | Generate documentation |
|
|
234
|
+
| `get_architecture` | Get project architecture overview |
|
|
235
|
+
| `get_component_doc` | Get detailed component docs |
|
|
236
|
+
| `get_changelog` | Get changelog of recent changes |
|
|
237
|
+
| `validate_docs` | Check for outdated docs |
|
|
238
|
+
| `what_happened` | Query recent project activity |
|
|
239
|
+
| `find_undocumented` | Find code lacking docs |
|
|
240
|
+
|
|
241
|
+
### Context Rot Prevention Tools (4)
|
|
242
|
+
| Tool | Description |
|
|
243
|
+
|------|-------------|
|
|
244
|
+
| `get_context_health` | Check context health |
|
|
245
|
+
| `trigger_compaction` | Manually compact context |
|
|
246
|
+
| `mark_critical` | Mark content as critical |
|
|
247
|
+
| `get_critical_context` | Get critical items |
|
|
248
|
+
|
|
249
|
+
### Confidence Scoring Tools (3)
|
|
250
|
+
| Tool | Description |
|
|
251
|
+
|------|-------------|
|
|
252
|
+
| `get_confidence` | Get confidence score for code |
|
|
253
|
+
| `list_sources` | List sources for a suggestion |
|
|
254
|
+
| `check_conflicts` | Check for decision conflicts |
|
|
255
|
+
|
|
256
|
+
### Change Intelligence Tools (4)
|
|
257
|
+
| Tool | Description |
|
|
258
|
+
|------|-------------|
|
|
259
|
+
| `what_changed` | Query what changed |
|
|
260
|
+
| `why_broke` | Diagnose why something broke |
|
|
261
|
+
| `find_similar_bugs` | Find similar bugs from history |
|
|
262
|
+
| `suggest_fix` | Get fix suggestions |
|
|
263
|
+
|
|
264
|
+
### Architecture Enforcement Tools (7)
|
|
265
|
+
| Tool | Description |
|
|
266
|
+
|------|-------------|
|
|
267
|
+
| `validate_pattern` | Validate code against patterns |
|
|
268
|
+
| `suggest_existing` | Find existing functions |
|
|
269
|
+
| `learn_pattern` | Teach a new pattern |
|
|
270
|
+
| `list_patterns` | List all patterns |
|
|
271
|
+
| `get_pattern` | Get pattern details |
|
|
272
|
+
| `add_pattern_example` | Add example to pattern |
|
|
273
|
+
| `get_architecture_stats` | Get architecture statistics |
|
|
274
|
+
|
|
275
|
+
### Test Awareness Tools (4)
|
|
276
|
+
| Tool | Description |
|
|
277
|
+
|------|-------------|
|
|
278
|
+
| `get_related_tests` | Get tests for a file/function |
|
|
279
|
+
| `check_tests` | Check if change breaks tests |
|
|
280
|
+
| `suggest_test_update` | Get test update suggestions |
|
|
281
|
+
| `get_test_coverage` | Get test coverage |
|
|
282
|
+
|
|
283
|
+
---
|
|
284
|
+
|
|
285
|
+
## Troubleshooting
|
|
286
|
+
|
|
287
|
+
### "MCP server failed" or won't connect
|
|
288
|
+
|
|
289
|
+
**Most common cause:** Relative paths don't work reliably.
|
|
290
|
+
|
|
291
|
+
```json
|
|
292
|
+
// ❌ WRONG - Relative path
|
|
293
|
+
"command": ["node", "dist/index.js", "--project", "."]
|
|
294
|
+
|
|
295
|
+
// ✅ CORRECT - Absolute path
|
|
296
|
+
"command": ["node", "C:\\Users\\you\\neuronlayer\\dist\\index.js", "--project", "."]
|
|
297
|
+
```
|
|
298
|
+
|
|
299
|
+
### "Configuration is invalid"
|
|
300
|
+
|
|
301
|
+
Ensure `command` is an array of strings:
|
|
302
|
+
|
|
303
|
+
```json
|
|
304
|
+
// ❌ WRONG - Single string
|
|
305
|
+
"command": "node dist/index.js --project ."
|
|
306
|
+
|
|
307
|
+
// ✅ CORRECT - Array of strings
|
|
308
|
+
"command": ["node", "dist/index.js", "--project", "."]
|
|
309
|
+
```
|
|
310
|
+
|
|
311
|
+
### Server starts but immediately fails
|
|
312
|
+
|
|
313
|
+
**Check if NeuronLayer runs manually first:**
|
|
314
|
+
|
|
315
|
+
```bash
|
|
316
|
+
node C:\path\to\neuronlayer\dist\index.js --project C:\path\to\your\project
|
|
317
|
+
```
|
|
318
|
+
|
|
319
|
+
If you see errors, the issue is with NeuronLayer itself, not OpenCode.
|
|
320
|
+
|
|
321
|
+
**Common errors:**
|
|
322
|
+
- "Cannot find module" - Run `npm run build` first
|
|
323
|
+
- "ENOENT" - Path is wrong
|
|
324
|
+
- Database errors - Delete `~/.neuronlayer/projects/` and retry
|
|
325
|
+
|
|
326
|
+
### "No tools available" after connecting
|
|
327
|
+
|
|
328
|
+
1. Verify connection with `/mcp` inside OpenCode
|
|
329
|
+
2. Ensure `enabled: true` is set in config
|
|
330
|
+
3. Restart OpenCode after config changes
|
|
331
|
+
|
|
332
|
+
### Check Server Startup Manually
|
|
333
|
+
|
|
334
|
+
Test if NeuronLayer starts correctly:
|
|
335
|
+
|
|
336
|
+
```bash
|
|
337
|
+
# Windows
|
|
338
|
+
node C:\path\to\neuronlayer\dist\index.js --project C:\path\to\project
|
|
339
|
+
|
|
340
|
+
# macOS/Linux
|
|
341
|
+
node /path/to/neuronlayer/dist/index.js --project /path/to/project
|
|
342
|
+
```
|
|
343
|
+
|
|
344
|
+
You should see:
|
|
345
|
+
```
|
|
346
|
+
NeuronLayer starting...
|
|
347
|
+
Project: /path/to/project
|
|
348
|
+
Indexing started...
|
|
349
|
+
Indexing complete: XX files indexed
|
|
350
|
+
NeuronLayer MCP server started
|
|
351
|
+
```
|
|
352
|
+
|
|
353
|
+
### View Debug Logs
|
|
354
|
+
|
|
355
|
+
Run OpenCode with debug logging:
|
|
356
|
+
|
|
357
|
+
```bash
|
|
358
|
+
opencode --log-level DEBUG
|
|
359
|
+
```
|
|
360
|
+
|
|
361
|
+
### Reset NeuronLayer Data
|
|
362
|
+
|
|
363
|
+
If you have persistent issues, clear the data:
|
|
364
|
+
|
|
365
|
+
```bash
|
|
366
|
+
# Windows
|
|
367
|
+
rmdir /s %USERPROFILE%\.neuronlayer
|
|
368
|
+
|
|
369
|
+
# macOS/Linux
|
|
370
|
+
rm -rf ~/.neuronlayer
|
|
371
|
+
```
|
|
372
|
+
|
|
373
|
+
---
|
|
374
|
+
|
|
375
|
+
## Example Usage in OpenCode
|
|
376
|
+
|
|
377
|
+
Once configured, try these prompts:
|
|
378
|
+
|
|
379
|
+
```
|
|
380
|
+
> Search for authentication code in this project
|
|
381
|
+
|
|
382
|
+
> What architectural decisions have been made?
|
|
383
|
+
|
|
384
|
+
> Show me the project summary
|
|
385
|
+
|
|
386
|
+
> Find the function that handles user login
|
|
387
|
+
|
|
388
|
+
> What changed yesterday?
|
|
389
|
+
|
|
390
|
+
> Why did the tests break?
|
|
391
|
+
|
|
392
|
+
> Check if this code follows our patterns: async function fetchData() { ... }
|
|
393
|
+
|
|
394
|
+
> Get tests related to src/auth/login.ts
|
|
395
|
+
|
|
396
|
+
> Record a decision: We chose SQLite because it requires no server setup
|
|
397
|
+
```
|
|
398
|
+
|
|
399
|
+
---
|
|
400
|
+
|
|
401
|
+
## Data Storage
|
|
402
|
+
|
|
403
|
+
NeuronLayer stores data in:
|
|
404
|
+
|
|
405
|
+
```
|
|
406
|
+
~/.neuronlayer/
|
|
407
|
+
├── registry.json # Project registry
|
|
408
|
+
└── projects/
|
|
409
|
+
└── {project-name}-{hash}/
|
|
410
|
+
├── neuronlayer.db # SQLite database
|
|
411
|
+
└── tier1.json # Working context
|
|
412
|
+
```
|
|
413
|
+
|
|
414
|
+
---
|
|
415
|
+
|
|
416
|
+
## Links
|
|
417
|
+
|
|
418
|
+
- [OpenCode Documentation](https://opencode.ai/docs/)
|
|
419
|
+
- [MCP Protocol](https://modelcontextprotocol.io/)
|
|
420
|
+
- [NeuronLayer API Reference](./API.md)
|
|
421
|
+
- [NeuronLayer Architecture](./ARCHITECTURE.md)
|
|
422
|
+
|
|
423
|
+
---
|
|
424
|
+
|
|
425
|
+
*Last updated: February 2026*
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "neuronlayer",
|
|
3
|
-
"version": "0.2.
|
|
3
|
+
"version": "0.2.10",
|
|
4
4
|
"description": "MCP server that gives AI assistants persistent understanding of your codebase",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "dist/index.js",
|
|
@@ -9,7 +9,8 @@
|
|
|
9
9
|
},
|
|
10
10
|
"files": [
|
|
11
11
|
"dist/**",
|
|
12
|
-
"wasm/**"
|
|
12
|
+
"wasm/**",
|
|
13
|
+
"doc/**"
|
|
13
14
|
],
|
|
14
15
|
"scripts": {
|
|
15
16
|
"build": "node esbuild.config.js",
|