@henrychong-ai/mcp-neo4j-knowledge-graph 2.2.2 → 2.2.4
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 +22 -29
- package/dist/server/setup.js +1 -1
- package/package.json +9 -7
- package/SETUP_AUTOMATION.md +0 -731
package/README.md
CHANGED
|
@@ -1,40 +1,35 @@
|
|
|
1
|
-
|
|
1
|
+
<p align="center">
|
|
2
|
+
<img src="https://assets.henrychong.com/mcp-neo4j-knowledge-graph/logo-readme.png" alt="Neo4j Knowledge Graph MCP Server" width="800">
|
|
3
|
+
</p>
|
|
2
4
|
|
|
5
|
+
<h1 align="center">Neo4j Knowledge Graph MCP Server</h1>
|
|
6
|
+
|
|
7
|
+
<p align="center">
|
|
3
8
|
Scalable, high-performance knowledge graph memory system with semantic retrieval, contextual recall, and temporal awareness. Provides any LLM client supporting MCP (e.g., Claude Desktop, Cursor, GitHub Copilot) with resilient, adaptive, and persistent long-term ontological memory.
|
|
9
|
+
</p>
|
|
4
10
|
|
|
5
|
-
|
|
11
|
+
<p align="center">
|
|
12
|
+
<strong>Maintained by</strong> <a href="https://github.com/henrychong-ai">Henry Chong</a>
|
|
13
|
+
</p>
|
|
6
14
|
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
15
|
+
<p align="center">
|
|
16
|
+
<a href="https://www.npmjs.com/package/@henrychong-ai/mcp-neo4j-knowledge-graph"><img src="https://img.shields.io/npm/v/@henrychong-ai/mcp-neo4j-knowledge-graph" alt="npm version"></a>
|
|
17
|
+
<a href="https://github.com/henrychong-ai/mcp-neo4j-knowledge-graph/actions/workflows/ci-cd.yml"><img src="https://github.com/henrychong-ai/mcp-neo4j-knowledge-graph/actions/workflows/ci-cd.yml/badge.svg" alt="CI"></a>
|
|
18
|
+
<a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
|
|
19
|
+
<a href="https://nodejs.org/"><img src="https://img.shields.io/badge/Node.js-%3E%3D24-green" alt="Node.js"></a>
|
|
20
|
+
</p>
|
|
11
21
|
|
|
12
22
|
---
|
|
13
23
|
|
|
14
|
-
##
|
|
15
|
-
|
|
16
|
-
**Already have Claude Code running?** Paste this into your session:
|
|
17
|
-
|
|
18
|
-
```
|
|
19
|
-
Read and execute the setup guide at henrychong.com/mcp-neo4j-kg/setup
|
|
20
|
-
```
|
|
21
|
-
|
|
22
|
-
Claude Code will guide you through:
|
|
23
|
-
|
|
24
|
-
- ✓ Prerequisites check (Node.js, Docker)
|
|
25
|
-
- ✓ Neo4j database setup
|
|
26
|
-
- ✓ Configuration and environment variables
|
|
27
|
-
- ✓ Integration with Claude Desktop/Code
|
|
28
|
-
- ✓ Testing and verification
|
|
24
|
+
## Quick Start
|
|
29
25
|
|
|
30
|
-
|
|
31
|
-
**No prior installation needed** - the automation handles everything!
|
|
26
|
+
Get up and running in ~10 minutes:
|
|
32
27
|
|
|
33
|
-
|
|
28
|
+
1. [Install Node.js](#installation) (v24+) and [start Neo4j](#storage-backend) (Docker or Desktop)
|
|
29
|
+
2. [Configure your MCP client](#configuration) (Claude Desktop, Claude Code, Cursor, etc.)
|
|
30
|
+
3. [Test the setup](#testing-your-setup) by creating your first entity
|
|
34
31
|
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
If you prefer manual installation, see the detailed sections below for:
|
|
32
|
+
**Sections:**
|
|
38
33
|
|
|
39
34
|
- [Installation](#installation) - npm/npx setup
|
|
40
35
|
- [Neo4j Setup](#storage-backend) - Docker or local database
|
|
@@ -43,8 +38,6 @@ If you prefer manual installation, see the detailed sections below for:
|
|
|
43
38
|
- [Claude Code](#integration-with-claude-code) - CLI client setup
|
|
44
39
|
- [Testing](#testing-your-setup) - Verification steps
|
|
45
40
|
|
|
46
|
-
**Expected manual setup time:** 10-15 minutes
|
|
47
|
-
|
|
48
41
|
---
|
|
49
42
|
|
|
50
43
|
## Installation
|
package/dist/server/setup.js
CHANGED
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@henrychong-ai/mcp-neo4j-knowledge-graph",
|
|
3
|
-
"version": "2.2.
|
|
3
|
+
"version": "2.2.4",
|
|
4
4
|
"description": "Neo4j-based knowledge graph MCP server with temporal versioning and semantic search",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"author": "Henry Chong <henry@henrychong.ai>",
|
|
@@ -66,17 +66,17 @@
|
|
|
66
66
|
"zod": "^4.3.6"
|
|
67
67
|
},
|
|
68
68
|
"devDependencies": {
|
|
69
|
-
"@biomejs/biome": "^2.4.
|
|
70
|
-
"@types/node": "^
|
|
69
|
+
"@biomejs/biome": "^2.4.6",
|
|
70
|
+
"@types/node": "^25.4.0",
|
|
71
71
|
"@types/node-cron": "^3.0.11",
|
|
72
|
-
"@vitest/coverage-v8": "^4.0
|
|
72
|
+
"@vitest/coverage-v8": "^4.1.0",
|
|
73
73
|
"husky": "^9.1.7",
|
|
74
74
|
"lint-staged": "^16.3.2",
|
|
75
|
-
"oxlint": "^1.
|
|
75
|
+
"oxlint": "^1.53.0",
|
|
76
76
|
"shx": "^0.4.0",
|
|
77
77
|
"tsx": "^4.21.0",
|
|
78
78
|
"typescript": "^5.9.3",
|
|
79
|
-
"vitest": "^4.0
|
|
79
|
+
"vitest": "^4.1.0"
|
|
80
80
|
},
|
|
81
81
|
"packageManager": "pnpm@10.30.0",
|
|
82
82
|
"engines": {
|
|
@@ -87,7 +87,9 @@
|
|
|
87
87
|
"@isaacs/brace-expansion": ">=5.0.1",
|
|
88
88
|
"rollup": ">=4.59.0",
|
|
89
89
|
"ajv": ">=8.18.0",
|
|
90
|
-
"hono": ">=4.
|
|
90
|
+
"hono": ">=4.12.7",
|
|
91
|
+
"@hono/node-server": ">=1.19.10",
|
|
92
|
+
"express-rate-limit": ">=8.2.2",
|
|
91
93
|
"qs": ">=6.14.2"
|
|
92
94
|
}
|
|
93
95
|
},
|
package/SETUP_AUTOMATION.md
DELETED
|
@@ -1,731 +0,0 @@
|
|
|
1
|
-
# MCP Neo4j Knowledge Graph - Automated Setup Guide
|
|
2
|
-
|
|
3
|
-
> **FOR CLAUDE CODE**: This is an interactive automation script. You are guiding a user through complete setup of the mcp-neo4j-knowledge-graph MCP server. Follow each section sequentially, prompting the user for input as needed. Be encouraging and clear in your communication.
|
|
4
|
-
|
|
5
|
-
---
|
|
6
|
-
|
|
7
|
-
## Your Role as Setup Assistant
|
|
8
|
-
|
|
9
|
-
You are helping a user set up the Neo4j Knowledge Graph MCP server from scratch. This automation assumes **NO prior setup** - not even Node.js or Docker.
|
|
10
|
-
|
|
11
|
-
**Your Tasks:**
|
|
12
|
-
|
|
13
|
-
1. Check prerequisites and guide installation if needed
|
|
14
|
-
2. Set up Neo4j database (Docker or local)
|
|
15
|
-
3. Generate configuration files
|
|
16
|
-
4. Integrate with Claude Code and/or Claude Desktop
|
|
17
|
-
5. Test the setup
|
|
18
|
-
6. Celebrate success! 🎉
|
|
19
|
-
|
|
20
|
-
**Be patient, encouraging, and clear.** Many users are new to this.
|
|
21
|
-
|
|
22
|
-
---
|
|
23
|
-
|
|
24
|
-
## Section 1: Welcome & Prerequisites Check
|
|
25
|
-
|
|
26
|
-
### 1.1 Welcome Message
|
|
27
|
-
|
|
28
|
-
Say something like:
|
|
29
|
-
|
|
30
|
-
```
|
|
31
|
-
Welcome! I'll guide you through setting up the Neo4j Knowledge Graph MCP server.
|
|
32
|
-
This will take about 10-15 minutes and give you persistent memory capabilities.
|
|
33
|
-
|
|
34
|
-
Let's start by checking your system prerequisites.
|
|
35
|
-
```
|
|
36
|
-
|
|
37
|
-
### 1.2 Check Node.js
|
|
38
|
-
|
|
39
|
-
**RUN:**
|
|
40
|
-
|
|
41
|
-
```bash
|
|
42
|
-
node --version
|
|
43
|
-
```
|
|
44
|
-
|
|
45
|
-
**EVALUATE:**
|
|
46
|
-
|
|
47
|
-
- **If version >= 24.0.0**: ✅ "Great! You have Node.js v[X.X.X] installed."
|
|
48
|
-
- **If version < 24.0.0**: ⚠️ "You have Node.js v[X.X.X], but we need v24.0.0 or higher."
|
|
49
|
-
- **ACTION**: Provide upgrade instructions for their OS
|
|
50
|
-
- **If not found**: ❌ "Node.js is not installed."
|
|
51
|
-
- **ACTION**: Provide installation instructions:
|
|
52
|
-
- **macOS**: `brew install node`
|
|
53
|
-
- **Linux**: Recommend nvm: `curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bash && nvm install --lts`
|
|
54
|
-
- **Windows**: Download from https://nodejs.org/
|
|
55
|
-
|
|
56
|
-
**STOP HERE** if Node.js installation is needed. Ask user to install and run this automation again.
|
|
57
|
-
|
|
58
|
-
### 1.3 Check Docker (for Neo4j)
|
|
59
|
-
|
|
60
|
-
**ASK USER:**
|
|
61
|
-
|
|
62
|
-
```
|
|
63
|
-
For Neo4j database, do you want to use:
|
|
64
|
-
1. Docker (Recommended - easiest setup, works everywhere)
|
|
65
|
-
2. Local installation (More control, requires manual setup)
|
|
66
|
-
|
|
67
|
-
Which do you prefer? (1 or 2)
|
|
68
|
-
```
|
|
69
|
-
|
|
70
|
-
**IF ANSWER = 1 (Docker):**
|
|
71
|
-
|
|
72
|
-
**RUN:**
|
|
73
|
-
|
|
74
|
-
```bash
|
|
75
|
-
docker --version && docker compose version
|
|
76
|
-
```
|
|
77
|
-
|
|
78
|
-
**EVALUATE:**
|
|
79
|
-
|
|
80
|
-
- **If both found**: ✅ "Docker and Docker Compose are installed."
|
|
81
|
-
- **If not found**: ❌ "Docker is not installed."
|
|
82
|
-
- **ACTION**: Provide installation instructions:
|
|
83
|
-
- **macOS**: Download Docker Desktop from https://www.docker.com/products/docker-desktop
|
|
84
|
-
- **Linux**: Follow https://docs.docker.com/engine/install/
|
|
85
|
-
- **Windows**: Download Docker Desktop for Windows
|
|
86
|
-
|
|
87
|
-
**STOP HERE** if Docker installation is needed. Ask user to install and run this automation again.
|
|
88
|
-
|
|
89
|
-
**IF ANSWER = 2 (Local installation):**
|
|
90
|
-
|
|
91
|
-
- Proceed to Section 2B (Local Neo4j)
|
|
92
|
-
|
|
93
|
-
---
|
|
94
|
-
|
|
95
|
-
## Section 2A: Neo4j Setup - Docker Path
|
|
96
|
-
|
|
97
|
-
### 2.1 Detect Operating System
|
|
98
|
-
|
|
99
|
-
**RUN:**
|
|
100
|
-
|
|
101
|
-
```bash
|
|
102
|
-
uname -s
|
|
103
|
-
```
|
|
104
|
-
|
|
105
|
-
This tells you the OS: `Darwin` (macOS), `Linux`, or check for Windows.
|
|
106
|
-
|
|
107
|
-
### 2.2 Ask for Neo4j Password
|
|
108
|
-
|
|
109
|
-
**ASK USER:**
|
|
110
|
-
|
|
111
|
-
```
|
|
112
|
-
Choose a password for your Neo4j database.
|
|
113
|
-
(Or press Enter to use the default: 'your_secure_password_here')
|
|
114
|
-
|
|
115
|
-
Password:
|
|
116
|
-
```
|
|
117
|
-
|
|
118
|
-
**STORE** the password as `NEO4J_PASSWORD` variable for later use.
|
|
119
|
-
|
|
120
|
-
### 2.3 Create docker-compose.yml
|
|
121
|
-
|
|
122
|
-
**TELL USER:**
|
|
123
|
-
|
|
124
|
-
```
|
|
125
|
-
I'm creating a docker-compose.yml file to run Neo4j...
|
|
126
|
-
```
|
|
127
|
-
|
|
128
|
-
**CREATE FILE** `docker-compose.yml` in current directory:
|
|
129
|
-
|
|
130
|
-
```yaml
|
|
131
|
-
services:
|
|
132
|
-
neo4j:
|
|
133
|
-
image: neo4j:5.26-community
|
|
134
|
-
container_name: neo4j-kg
|
|
135
|
-
restart: unless-stopped
|
|
136
|
-
ports:
|
|
137
|
-
- '7474:7474' # Browser UI
|
|
138
|
-
- '7687:7687' # Bolt protocol
|
|
139
|
-
volumes:
|
|
140
|
-
- neo4j_data:/data
|
|
141
|
-
- neo4j_logs:/logs
|
|
142
|
-
environment:
|
|
143
|
-
- NEO4J_AUTH=neo4j/[NEO4J_PASSWORD]
|
|
144
|
-
- NEO4J_PLUGINS=["apoc"]
|
|
145
|
-
- NEO4J_server_memory_heap_initial__size=512M
|
|
146
|
-
- NEO4J_server_memory_heap_max__size=512M
|
|
147
|
-
- NEO4J_server_memory_pagecache_size=256M
|
|
148
|
-
|
|
149
|
-
volumes:
|
|
150
|
-
neo4j_data:
|
|
151
|
-
neo4j_logs:
|
|
152
|
-
```
|
|
153
|
-
|
|
154
|
-
**REPLACE** `[NEO4J_PASSWORD]` with the user's chosen password.
|
|
155
|
-
|
|
156
|
-
### 2.4 Start Neo4j
|
|
157
|
-
|
|
158
|
-
**RUN:**
|
|
159
|
-
|
|
160
|
-
```bash
|
|
161
|
-
docker compose up -d
|
|
162
|
-
```
|
|
163
|
-
|
|
164
|
-
**WAIT** 10 seconds, then **CHECK:**
|
|
165
|
-
|
|
166
|
-
```bash
|
|
167
|
-
docker compose ps
|
|
168
|
-
```
|
|
169
|
-
|
|
170
|
-
**EVALUATE:**
|
|
171
|
-
|
|
172
|
-
- **If shows "running"**: ✅ "Neo4j is running!"
|
|
173
|
-
- **If not running**: ❌ Show logs: `docker compose logs neo4j`
|
|
174
|
-
|
|
175
|
-
### 2.5 Verify Neo4j Access
|
|
176
|
-
|
|
177
|
-
**TELL USER:**
|
|
178
|
-
|
|
179
|
-
```
|
|
180
|
-
Neo4j is starting up... Let me check if it's accessible.
|
|
181
|
-
```
|
|
182
|
-
|
|
183
|
-
**RUN:**
|
|
184
|
-
|
|
185
|
-
```bash
|
|
186
|
-
curl -s http://localhost:7474 > /dev/null && echo "Neo4j Browser accessible" || echo "Not yet accessible"
|
|
187
|
-
```
|
|
188
|
-
|
|
189
|
-
**IF NOT ACCESSIBLE:**
|
|
190
|
-
|
|
191
|
-
- Wait 10 more seconds and try again
|
|
192
|
-
- After 3 attempts, show troubleshooting: `docker compose logs neo4j`
|
|
193
|
-
|
|
194
|
-
**WHEN ACCESSIBLE:**
|
|
195
|
-
|
|
196
|
-
```
|
|
197
|
-
✅ Neo4j is running! You can access the browser at: http://localhost:7474
|
|
198
|
-
Username: neo4j
|
|
199
|
-
Password: [their chosen password]
|
|
200
|
-
```
|
|
201
|
-
|
|
202
|
-
**GO TO:** Section 3 (Environment Configuration)
|
|
203
|
-
|
|
204
|
-
---
|
|
205
|
-
|
|
206
|
-
## Section 2B: Neo4j Setup - Local Installation Path
|
|
207
|
-
|
|
208
|
-
### 2.1 Provide OS-Specific Instructions
|
|
209
|
-
|
|
210
|
-
**FOR macOS:**
|
|
211
|
-
|
|
212
|
-
```bash
|
|
213
|
-
brew install neo4j
|
|
214
|
-
neo4j start
|
|
215
|
-
neo4j-admin set-initial-password [PASSWORD]
|
|
216
|
-
```
|
|
217
|
-
|
|
218
|
-
**FOR Linux:**
|
|
219
|
-
|
|
220
|
-
```
|
|
221
|
-
Follow the official guide at:
|
|
222
|
-
https://neo4j.com/docs/operations-manual/current/installation/linux/
|
|
223
|
-
```
|
|
224
|
-
|
|
225
|
-
**FOR Windows:**
|
|
226
|
-
|
|
227
|
-
```
|
|
228
|
-
Download Neo4j Desktop from:
|
|
229
|
-
https://neo4j.com/download/
|
|
230
|
-
```
|
|
231
|
-
|
|
232
|
-
**ASK USER:** "Have you completed the Neo4j installation? (yes/no)"
|
|
233
|
-
|
|
234
|
-
**IF NO:** Provide help and wait.
|
|
235
|
-
**IF YES:** Continue to verification.
|
|
236
|
-
|
|
237
|
-
### 2.2 Verify Local Neo4j
|
|
238
|
-
|
|
239
|
-
**RUN:**
|
|
240
|
-
|
|
241
|
-
```bash
|
|
242
|
-
neo4j status
|
|
243
|
-
```
|
|
244
|
-
|
|
245
|
-
**OR TRY:**
|
|
246
|
-
|
|
247
|
-
```bash
|
|
248
|
-
curl -s http://localhost:7474
|
|
249
|
-
```
|
|
250
|
-
|
|
251
|
-
**IF ACCESSIBLE:** ✅ Proceed to Section 3
|
|
252
|
-
|
|
253
|
-
---
|
|
254
|
-
|
|
255
|
-
## Section 3: Environment Configuration
|
|
256
|
-
|
|
257
|
-
### 3.1 Ask for OpenAI API Key (Optional)
|
|
258
|
-
|
|
259
|
-
**ASK USER:**
|
|
260
|
-
|
|
261
|
-
```
|
|
262
|
-
Do you have an OpenAI API key for semantic search?
|
|
263
|
-
This enables vector embeddings and semantic similarity.
|
|
264
|
-
|
|
265
|
-
(Optional - you can skip this and add it later)
|
|
266
|
-
|
|
267
|
-
Enter your OpenAI API key (or press Enter to skip):
|
|
268
|
-
```
|
|
269
|
-
|
|
270
|
-
**STORE** as `OPENAI_API_KEY` variable (or empty if skipped).
|
|
271
|
-
|
|
272
|
-
### 3.2 Create .env File (Optional)
|
|
273
|
-
|
|
274
|
-
**TELL USER:**
|
|
275
|
-
|
|
276
|
-
```
|
|
277
|
-
I'm creating a .env file for your configuration...
|
|
278
|
-
```
|
|
279
|
-
|
|
280
|
-
**CREATE FILE** `.env` in current directory:
|
|
281
|
-
|
|
282
|
-
```bash
|
|
283
|
-
# Neo4j Connection
|
|
284
|
-
NEO4J_URI=bolt://localhost:7687
|
|
285
|
-
NEO4J_USERNAME=neo4j
|
|
286
|
-
NEO4J_PASSWORD=[NEO4J_PASSWORD]
|
|
287
|
-
NEO4J_DATABASE=neo4j
|
|
288
|
-
|
|
289
|
-
# OpenAI API (Optional)
|
|
290
|
-
OPENAI_API_KEY=[OPENAI_API_KEY]
|
|
291
|
-
OPENAI_EMBEDDING_MODEL=text-embedding-3-small
|
|
292
|
-
```
|
|
293
|
-
|
|
294
|
-
**NOTE:** This .env file is optional - configuration will be done in MCP client configs instead.
|
|
295
|
-
|
|
296
|
-
---
|
|
297
|
-
|
|
298
|
-
## Section 4: Claude Code Configuration
|
|
299
|
-
|
|
300
|
-
### 4.1 Explain What's Happening
|
|
301
|
-
|
|
302
|
-
**TELL USER:**
|
|
303
|
-
|
|
304
|
-
```
|
|
305
|
-
Now I'm going to configure Claude Code to use this MCP server.
|
|
306
|
-
I'll modify your ~/.claude.json file to add the Neo4j Knowledge Graph server.
|
|
307
|
-
```
|
|
308
|
-
|
|
309
|
-
### 4.2 Check if ~/.claude.json Exists
|
|
310
|
-
|
|
311
|
-
**RUN:**
|
|
312
|
-
|
|
313
|
-
```bash
|
|
314
|
-
[ -f ~/.claude.json ] && echo "exists" || echo "not found"
|
|
315
|
-
```
|
|
316
|
-
|
|
317
|
-
**IF NOT FOUND:**
|
|
318
|
-
**CREATE FILE** `~/.claude.json`:
|
|
319
|
-
|
|
320
|
-
```json
|
|
321
|
-
{
|
|
322
|
-
"mcpServers": {}
|
|
323
|
-
}
|
|
324
|
-
```
|
|
325
|
-
|
|
326
|
-
### 4.3 Backup Existing Config
|
|
327
|
-
|
|
328
|
-
**IF FILE EXISTS:**
|
|
329
|
-
|
|
330
|
-
```bash
|
|
331
|
-
cp ~/.claude.json ~/.claude.json.backup-$(date +%Y%m%d-%H%M%S)
|
|
332
|
-
```
|
|
333
|
-
|
|
334
|
-
**TELL USER:** "I've created a backup of your existing config at ~/.claude.json.backup-[timestamp]"
|
|
335
|
-
|
|
336
|
-
### 4.4 Add MCP Server Configuration
|
|
337
|
-
|
|
338
|
-
**READ** current `~/.claude.json` content.
|
|
339
|
-
|
|
340
|
-
**ADD** this configuration to the `mcpServers` object:
|
|
341
|
-
|
|
342
|
-
```json
|
|
343
|
-
"neo4j-knowledge-graph": {
|
|
344
|
-
"command": "npx",
|
|
345
|
-
"args": ["-y", "@henrychong-ai/mcp-neo4j-knowledge-graph"],
|
|
346
|
-
"env": {
|
|
347
|
-
"NEO4J_URI": "bolt://localhost:7687",
|
|
348
|
-
"NEO4J_USERNAME": "neo4j",
|
|
349
|
-
"NEO4J_PASSWORD": "[NEO4J_PASSWORD]",
|
|
350
|
-
"NEO4J_DATABASE": "neo4j",
|
|
351
|
-
"OPENAI_API_KEY": "[OPENAI_API_KEY]",
|
|
352
|
-
"OPENAI_EMBEDDING_MODEL": "text-embedding-3-small"
|
|
353
|
-
}
|
|
354
|
-
}
|
|
355
|
-
```
|
|
356
|
-
|
|
357
|
-
**REPLACE:**
|
|
358
|
-
|
|
359
|
-
- `[NEO4J_PASSWORD]` with user's password
|
|
360
|
-
- `[OPENAI_API_KEY]` with user's API key (or remove line if not provided)
|
|
361
|
-
|
|
362
|
-
> **Advanced Configuration**: Vector search defaults work out of the box. To customize, add these optional env vars: `NEO4J_VECTOR_INDEX` (default: `entity_embeddings`), `NEO4J_VECTOR_DIMENSIONS` (default: `1536`), `NEO4J_SIMILARITY_FUNCTION` (default: `cosine`).
|
|
363
|
-
|
|
364
|
-
**WRITE** updated config back to `~/.claude.json`
|
|
365
|
-
|
|
366
|
-
**TELL USER:**
|
|
367
|
-
|
|
368
|
-
```
|
|
369
|
-
✅ Claude Code is now configured to use the Neo4j Knowledge Graph!
|
|
370
|
-
```
|
|
371
|
-
|
|
372
|
-
---
|
|
373
|
-
|
|
374
|
-
## Section 5: Claude Desktop Configuration (Optional)
|
|
375
|
-
|
|
376
|
-
### 5.1 Ask User
|
|
377
|
-
|
|
378
|
-
**ASK:**
|
|
379
|
-
|
|
380
|
-
```
|
|
381
|
-
Would you also like to configure Claude Desktop to use this MCP server?
|
|
382
|
-
(yes/no)
|
|
383
|
-
```
|
|
384
|
-
|
|
385
|
-
**IF NO:** Skip to Section 6
|
|
386
|
-
|
|
387
|
-
**IF YES:** Continue
|
|
388
|
-
|
|
389
|
-
### 5.2 Locate Claude Desktop Config
|
|
390
|
-
|
|
391
|
-
**FOR macOS:**
|
|
392
|
-
|
|
393
|
-
```
|
|
394
|
-
~/Library/Application Support/Claude/claude_desktop_config.json
|
|
395
|
-
```
|
|
396
|
-
|
|
397
|
-
**FOR Linux:**
|
|
398
|
-
|
|
399
|
-
```
|
|
400
|
-
~/.config/Claude/claude_desktop_config.json
|
|
401
|
-
```
|
|
402
|
-
|
|
403
|
-
**FOR Windows:**
|
|
404
|
-
|
|
405
|
-
```
|
|
406
|
-
%APPDATA%\Claude\claude_desktop_config.json
|
|
407
|
-
```
|
|
408
|
-
|
|
409
|
-
### 5.3 Backup and Update Config
|
|
410
|
-
|
|
411
|
-
**SAME PROCESS** as Section 4.3-4.4, but for Claude Desktop config file.
|
|
412
|
-
|
|
413
|
-
**TELL USER:**
|
|
414
|
-
|
|
415
|
-
```
|
|
416
|
-
✅ Claude Desktop is now configured!
|
|
417
|
-
You'll need to restart Claude Desktop for changes to take effect.
|
|
418
|
-
```
|
|
419
|
-
|
|
420
|
-
---
|
|
421
|
-
|
|
422
|
-
## Section 6: Verification & Testing
|
|
423
|
-
|
|
424
|
-
### 6.1 Test Neo4j Connection
|
|
425
|
-
|
|
426
|
-
**TELL USER:**
|
|
427
|
-
|
|
428
|
-
```
|
|
429
|
-
Let's verify the setup by testing the Neo4j connection...
|
|
430
|
-
```
|
|
431
|
-
|
|
432
|
-
**RUN:**
|
|
433
|
-
|
|
434
|
-
```bash
|
|
435
|
-
npx -y @henrychong-ai/mcp-neo4j-knowledge-graph --version
|
|
436
|
-
```
|
|
437
|
-
|
|
438
|
-
**IF SUCCESSFUL:** ✅ "MCP server package is accessible via npx!"
|
|
439
|
-
|
|
440
|
-
### 6.2 Explain Next Steps
|
|
441
|
-
|
|
442
|
-
**TELL USER:**
|
|
443
|
-
|
|
444
|
-
```
|
|
445
|
-
Great! Your setup is complete. Here's how to test it:
|
|
446
|
-
|
|
447
|
-
1. In THIS Claude Code session (or a new one), try:
|
|
448
|
-
"Show me the available MCP tools for the knowledge graph"
|
|
449
|
-
|
|
450
|
-
2. Create your first entity:
|
|
451
|
-
"Create an entity named 'Test' of type 'Example' with observation 'Setup test'"
|
|
452
|
-
|
|
453
|
-
3. Verify in Neo4j Browser:
|
|
454
|
-
- Open http://localhost:7474
|
|
455
|
-
- Login with: neo4j / [their password]
|
|
456
|
-
- Run: MATCH (e:Entity) WHERE e.validTo IS NULL RETURN e
|
|
457
|
-
|
|
458
|
-
Would you like me to test it now by creating a sample entity?
|
|
459
|
-
```
|
|
460
|
-
|
|
461
|
-
### 6.3 Create Test Entity (If User Says Yes)
|
|
462
|
-
|
|
463
|
-
**USE MCP TOOL:** `mcp__kg__create_entities`
|
|
464
|
-
|
|
465
|
-
**CREATE:**
|
|
466
|
-
|
|
467
|
-
```json
|
|
468
|
-
{
|
|
469
|
-
"entities": [
|
|
470
|
-
{
|
|
471
|
-
"name": "setup-test",
|
|
472
|
-
"entityType": "test",
|
|
473
|
-
"observations": ["Successfully created during automated setup on [DATE]"]
|
|
474
|
-
}
|
|
475
|
-
]
|
|
476
|
-
}
|
|
477
|
-
```
|
|
478
|
-
|
|
479
|
-
**IF SUCCESSFUL:**
|
|
480
|
-
|
|
481
|
-
```
|
|
482
|
-
🎉 Success! I just created a test entity in your knowledge graph!
|
|
483
|
-
|
|
484
|
-
Try searching for it: "Search the knowledge graph for 'setup-test'"
|
|
485
|
-
```
|
|
486
|
-
|
|
487
|
-
**IF FAILS:**
|
|
488
|
-
Show error and provide troubleshooting steps.
|
|
489
|
-
|
|
490
|
-
---
|
|
491
|
-
|
|
492
|
-
## Section 7: Troubleshooting
|
|
493
|
-
|
|
494
|
-
### Common Issues
|
|
495
|
-
|
|
496
|
-
**Issue: "Cannot connect to Neo4j"**
|
|
497
|
-
|
|
498
|
-
- Check Neo4j is running: `docker compose ps` or `neo4j status`
|
|
499
|
-
- Check port 7687 is accessible: `telnet localhost 7687`
|
|
500
|
-
- View Neo4j logs: `docker compose logs neo4j`
|
|
501
|
-
|
|
502
|
-
**Issue: "MCP tools not available in Claude Code"**
|
|
503
|
-
|
|
504
|
-
- Restart Claude Code session
|
|
505
|
-
- Check ~/.claude.json syntax is valid JSON
|
|
506
|
-
- Verify npx can run the package: `npx -y @henrychong-ai/mcp-neo4j-knowledge-graph --version`
|
|
507
|
-
|
|
508
|
-
**Issue: "Node already exists" error**
|
|
509
|
-
|
|
510
|
-
- This is a Neo4j schema constraint issue
|
|
511
|
-
- See: https://github.com/henrychong-ai/mcp-neo4j-knowledge-graph#troubleshooting
|
|
512
|
-
|
|
513
|
-
---
|
|
514
|
-
|
|
515
|
-
## Section 8: Success & Next Steps
|
|
516
|
-
|
|
517
|
-
### 8.1 Important: Restart Claude Code
|
|
518
|
-
|
|
519
|
-
**TELL USER:**
|
|
520
|
-
|
|
521
|
-
```
|
|
522
|
-
🎉 Setup is complete! However, there's one critical step:
|
|
523
|
-
|
|
524
|
-
⚠️ IMPORTANT: Claude Code needs to restart to load the new MCP server configuration.
|
|
525
|
-
|
|
526
|
-
Here's what to do:
|
|
527
|
-
1. Type "/exit" to exit this session
|
|
528
|
-
2. Type "claude --continue" to resume the session with MCP tools loaded
|
|
529
|
-
3. Once you're back, say "I'm back" or "ready" so I can help you test the MCP tools!
|
|
530
|
-
|
|
531
|
-
Don't worry - I'll be right here when you return. See you in a moment! 👋
|
|
532
|
-
```
|
|
533
|
-
|
|
534
|
-
**WAIT FOR USER TO RESTART AND RETURN**
|
|
535
|
-
|
|
536
|
-
When user returns and says they're back, proceed to Section 8.2
|
|
537
|
-
|
|
538
|
-
### 8.2 Test MCP Tools (After Restart)
|
|
539
|
-
|
|
540
|
-
**TELL USER:**
|
|
541
|
-
|
|
542
|
-
```
|
|
543
|
-
Welcome back! Now let's verify the MCP tools are working.
|
|
544
|
-
|
|
545
|
-
Let me check what tools are available...
|
|
546
|
-
```
|
|
547
|
-
|
|
548
|
-
**TRY TO USE MCP TOOL:** Check if MCP tools are available by attempting to list them or use one.
|
|
549
|
-
|
|
550
|
-
**IF MCP TOOLS ARE AVAILABLE:**
|
|
551
|
-
|
|
552
|
-
```
|
|
553
|
-
✅ Perfect! The MCP tools are loaded. Let's test them:
|
|
554
|
-
```
|
|
555
|
-
|
|
556
|
-
**SUGGEST TESTS:**
|
|
557
|
-
|
|
558
|
-
1. List available tools: "I can see [X] tools available including create_entities, search_nodes, semantic_search..."
|
|
559
|
-
2. Create a test entity if not already done
|
|
560
|
-
3. Search for the entity
|
|
561
|
-
4. View it in Neo4j Browser
|
|
562
|
-
|
|
563
|
-
**IF MCP TOOLS NOT AVAILABLE:**
|
|
564
|
-
|
|
565
|
-
```
|
|
566
|
-
Hmm, the tools aren't showing up yet. Let's troubleshoot:
|
|
567
|
-
|
|
568
|
-
1. Check your ~/.claude.json file has the correct configuration
|
|
569
|
-
2. Try restarting Claude Code one more time
|
|
570
|
-
3. Check for any error messages in the terminal
|
|
571
|
-
|
|
572
|
-
Would you like me to verify your configuration?
|
|
573
|
-
```
|
|
574
|
-
|
|
575
|
-
### 8.3 Optional: Add KG Usage Instructions to Claude User Preferences
|
|
576
|
-
|
|
577
|
-
**AFTER SUCCESSFUL MCP TOOL TEST:**
|
|
578
|
-
|
|
579
|
-
Now that your MCP server is working, you can optionally add Knowledge Graph usage instructions to your Claude user preferences file (~/.claude/CLAUDE.md). This helps Claude Code understand how to best use your knowledge graph.
|
|
580
|
-
|
|
581
|
-
**ASK USER:**
|
|
582
|
-
|
|
583
|
-
```
|
|
584
|
-
Would you like to add Knowledge Graph (KG) usage instructions to your Claude user preferences?
|
|
585
|
-
|
|
586
|
-
This will add helpful guidelines for:
|
|
587
|
-
- When to use semantic_search vs search_nodes
|
|
588
|
-
- Best practices for querying your knowledge graph
|
|
589
|
-
- Token limit warnings and optimization tips
|
|
590
|
-
|
|
591
|
-
Add instructions? (yes/no)
|
|
592
|
-
```
|
|
593
|
-
|
|
594
|
-
**IF NO:**
|
|
595
|
-
|
|
596
|
-
```
|
|
597
|
-
No problem! You can always add these instructions later by asking a future Claude Code session to:
|
|
598
|
-
|
|
599
|
-
"Read and execute the setup guide at henrychong.com/mcp-neo4j-kg/setup and add KG usage instructions to my CLAUDE.md file"
|
|
600
|
-
|
|
601
|
-
The setup guide contains the full instructions ready to add whenever you need them.
|
|
602
|
-
```
|
|
603
|
-
|
|
604
|
-
**CONTINUE TO SECTION 8.4**
|
|
605
|
-
|
|
606
|
-
**IF YES:**
|
|
607
|
-
|
|
608
|
-
#### Check if CLAUDE.md Exists
|
|
609
|
-
|
|
610
|
-
**RUN:**
|
|
611
|
-
|
|
612
|
-
```bash
|
|
613
|
-
[ -f ~/.claude/CLAUDE.md ] && echo "exists" || echo "not found"
|
|
614
|
-
```
|
|
615
|
-
|
|
616
|
-
**IF NOT FOUND:**
|
|
617
|
-
|
|
618
|
-
```
|
|
619
|
-
I'll create a new ~/.claude/CLAUDE.md file with the KG instructions.
|
|
620
|
-
```
|
|
621
|
-
|
|
622
|
-
**IF EXISTS:**
|
|
623
|
-
|
|
624
|
-
```
|
|
625
|
-
I'll add the KG instructions to your existing ~/.claude/CLAUDE.md file.
|
|
626
|
-
First, let me create a backup...
|
|
627
|
-
```
|
|
628
|
-
|
|
629
|
-
**RUN:**
|
|
630
|
-
|
|
631
|
-
```bash
|
|
632
|
-
cp ~/.claude/CLAUDE.md ~/.claude/CLAUDE.md.backup-$(date +%Y%m%d-%H%M%S)
|
|
633
|
-
```
|
|
634
|
-
|
|
635
|
-
#### Add KG Instructions
|
|
636
|
-
|
|
637
|
-
**APPEND** the following to `~/.claude/CLAUDE.md`. If the user provided an OpenAI API key during Section 3, include the full template. If they skipped it, add a note that `semantic_search` requires an OpenAI API key to be configured.
|
|
638
|
-
|
|
639
|
-
```markdown
|
|
640
|
-
---
|
|
641
|
-
|
|
642
|
-
# Knowledge Graph (KG) Usage Instructions
|
|
643
|
-
|
|
644
|
-
## Abbreviation
|
|
645
|
-
- **kg**: References the Neo4j knowledge graph and MCP tools (mcp__kg__search_nodes, mcp__kg__semantic_search, etc.)
|
|
646
|
-
|
|
647
|
-
## Search Methods
|
|
648
|
-
|
|
649
|
-
### semantic_search (Recommended for Exploration)
|
|
650
|
-
|
|
651
|
-
Use `semantic_search` for concept exploration, discovery, and natural language queries.
|
|
652
|
-
Requires OpenAI API key configured in MCP server env vars.
|
|
653
|
-
|
|
654
|
-
**When to use:**
|
|
655
|
-
- Exploring topics without knowing exact terminology
|
|
656
|
-
- Finding related concepts across different domains
|
|
657
|
-
- Natural language queries about abstract ideas
|
|
658
|
-
|
|
659
|
-
**Parameters:** `limit` (default: 10), `min_similarity` (default: 0.6), `entity_types`, `hybrid_search` (default: true)
|
|
660
|
-
|
|
661
|
-
### search_nodes (Precision Method)
|
|
662
|
-
|
|
663
|
-
Use `search_nodes` for exact term matching. Fast, free, no API calls.
|
|
664
|
-
|
|
665
|
-
**When to use:**
|
|
666
|
-
- Known exact terms or technical names
|
|
667
|
-
- Quick existence checks
|
|
668
|
-
- Technical lookups with specific terminology
|
|
669
|
-
|
|
670
|
-
## Best Practices
|
|
671
|
-
|
|
672
|
-
**Hybrid Approach:** Start with `semantic_search` for discovery → refine with `search_nodes` for precision.
|
|
673
|
-
**Escalation:** semantic_search → search_nodes → file search → web search
|
|
674
|
-
|
|
675
|
-
## Critical Constraints
|
|
676
|
-
|
|
677
|
-
- **NEVER use `read_graph()`** — always exceeds 25,000 token MCP response limit (~173k tokens)
|
|
678
|
-
- Use `search_nodes()` or `semantic_search()` instead
|
|
679
|
-
- Apply filters early to reduce response size
|
|
680
|
-
|
|
681
|
-
---
|
|
682
|
-
```
|
|
683
|
-
|
|
684
|
-
#### Verify Addition
|
|
685
|
-
|
|
686
|
-
**RUN:**
|
|
687
|
-
|
|
688
|
-
```bash
|
|
689
|
-
tail -10 ~/.claude/CLAUDE.md
|
|
690
|
-
```
|
|
691
|
-
|
|
692
|
-
**TELL USER:**
|
|
693
|
-
|
|
694
|
-
```
|
|
695
|
-
✅ Knowledge Graph usage instructions added to ~/.claude/CLAUDE.md!
|
|
696
|
-
|
|
697
|
-
A backup of your previous file was saved to:
|
|
698
|
-
~/.claude/CLAUDE.md.backup-[timestamp]
|
|
699
|
-
|
|
700
|
-
These instructions will help Claude Code use your knowledge graph more effectively in future sessions.
|
|
701
|
-
```
|
|
702
|
-
|
|
703
|
-
### 8.4 Final Success Celebration
|
|
704
|
-
|
|
705
|
-
**AFTER SUCCESSFUL MCP TOOL TEST:**
|
|
706
|
-
|
|
707
|
-
**TELL USER:**
|
|
708
|
-
|
|
709
|
-
```
|
|
710
|
-
🎉 Congratulations! Your Neo4j Knowledge Graph MCP server is fully working!
|
|
711
|
-
|
|
712
|
-
You now have:
|
|
713
|
-
✅ Neo4j database running
|
|
714
|
-
✅ MCP server configured in Claude Code
|
|
715
|
-
✅ MCP tools loaded and tested
|
|
716
|
-
[✅ Claude Desktop configured (if they chose this)]
|
|
717
|
-
✅ Test entity created and verified
|
|
718
|
-
|
|
719
|
-
Next steps:
|
|
720
|
-
1. Start building your knowledge graph by creating entities and relations
|
|
721
|
-
2. Use semantic search to find information: "Search for X"
|
|
722
|
-
3. Explore the documentation: https://www.npmjs.com/package/@henrychong-ai/mcp-neo4j-knowledge-graph
|
|
723
|
-
|
|
724
|
-
Happy graphing! 🚀
|
|
725
|
-
```
|
|
726
|
-
|
|
727
|
-
---
|
|
728
|
-
|
|
729
|
-
## End of Automation Script
|
|
730
|
-
|
|
731
|
-
**YOU'RE DONE!** The user now has a fully functional MCP Neo4j Knowledge Graph server.
|