@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 CHANGED
@@ -1,40 +1,35 @@
1
- # Neo4j Knowledge Graph MCP Server
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
- **Maintained by** [Henry Chong](https://github.com/henrychong-ai)
11
+ <p align="center">
12
+ <strong>Maintained by</strong> <a href="https://github.com/henrychong-ai">Henry Chong</a>
13
+ </p>
6
14
 
7
- [![npm version](https://img.shields.io/npm/v/@henrychong-ai/mcp-neo4j-knowledge-graph)](https://www.npmjs.com/package/@henrychong-ai/mcp-neo4j-knowledge-graph)
8
- [![CI](https://github.com/henrychong-ai/mcp-neo4j-knowledge-graph/actions/workflows/ci-cd.yml/badge.svg)](https://github.com/henrychong-ai/mcp-neo4j-knowledge-graph/actions/workflows/ci-cd.yml)
9
- [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
10
- [![Node.js](https://img.shields.io/badge/Node.js-%3E%3D24-green)](https://nodejs.org/)
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
- ## 🚀 Quick Start with Claude Code
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
- **Expected time:** 10-15 minutes
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
- ### Manual Setup
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
@@ -13,7 +13,7 @@ export function setupServer(knowledgeGraphManager) {
13
13
  // Create server instance
14
14
  const server = new Server({
15
15
  name: 'mcp-neo4j-knowledge-graph',
16
- version: '1.0.0',
16
+ version: '2.2.3',
17
17
  }, {
18
18
  capabilities: {
19
19
  tools: {},
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@henrychong-ai/mcp-neo4j-knowledge-graph",
3
- "version": "2.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.2",
70
- "@types/node": "^24.10.9",
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.18",
72
+ "@vitest/coverage-v8": "^4.1.0",
73
73
  "husky": "^9.1.7",
74
74
  "lint-staged": "^16.3.2",
75
- "oxlint": "^1.48.0",
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.18"
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.11.10",
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
  },
@@ -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.