@henrychong-ai/mcp-neo4j-knowledge-graph 1.6.0 → 1.7.0
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 +168 -0
- package/SETUP_AUTOMATION.md +596 -0
- package/package.json +3 -2
package/README.md
CHANGED
|
@@ -8,6 +8,40 @@ Scalable, high-performance knowledge graph memory system with semantic retrieval
|
|
|
8
8
|
|
|
9
9
|
---
|
|
10
10
|
|
|
11
|
+
## 🚀 Quick Start with Claude Code
|
|
12
|
+
|
|
13
|
+
**Already have Claude Code running?** Paste this into your session:
|
|
14
|
+
|
|
15
|
+
```
|
|
16
|
+
Read and execute the setup guide at henrychong.com/mcp-neo4j-kg/setup
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
Claude Code will guide you through:
|
|
20
|
+
- ✓ Prerequisites check (Node.js, Docker)
|
|
21
|
+
- ✓ Neo4j database setup
|
|
22
|
+
- ✓ Configuration and environment variables
|
|
23
|
+
- ✓ Integration with Claude Desktop/Code
|
|
24
|
+
- ✓ Testing and verification
|
|
25
|
+
|
|
26
|
+
**Expected time:** 10-15 minutes
|
|
27
|
+
**No prior installation needed** - the automation handles everything!
|
|
28
|
+
|
|
29
|
+
---
|
|
30
|
+
|
|
31
|
+
### Manual Setup
|
|
32
|
+
|
|
33
|
+
If you prefer manual installation, see the detailed sections below for:
|
|
34
|
+
- [Installation](#installation) - npm/npx setup
|
|
35
|
+
- [Neo4j Setup](#storage-backend) - Docker or local database
|
|
36
|
+
- [Configuration](#configuration) - Environment variables
|
|
37
|
+
- [Claude Desktop](#integration-with-claude-desktop) - MCP client setup
|
|
38
|
+
- [Claude Code](#integration-with-claude-code) - CLI client setup
|
|
39
|
+
- [Testing](#testing-your-setup) - Verification steps
|
|
40
|
+
|
|
41
|
+
**Expected manual setup time:** 10-15 minutes
|
|
42
|
+
|
|
43
|
+
---
|
|
44
|
+
|
|
11
45
|
## Installation
|
|
12
46
|
|
|
13
47
|
### Global Installation with npx (Recommended)
|
|
@@ -325,6 +359,7 @@ for (const entity of entities) {
|
|
|
325
359
|
await createEntities([entity]);
|
|
326
360
|
}
|
|
327
361
|
|
|
362
|
+
|
|
328
363
|
// Batch operation: ~1.5 seconds for 100 entities (33x faster)
|
|
329
364
|
await createEntitiesBatch(entities, {
|
|
330
365
|
maxBatchSize: 100,
|
|
@@ -337,6 +372,45 @@ await createEntitiesBatch(entities, {
|
|
|
337
372
|
- `enableParallel`: Reserved for future parallel chunk processing (embeddings always generated if service available)
|
|
338
373
|
- `onProgress`: Callback for progress tracking
|
|
339
374
|
|
|
375
|
+
**Cost Management:**
|
|
376
|
+
- Incremental approach minimizes API calls
|
|
377
|
+
- Only processes entities without embeddings
|
|
378
|
+
- Typical cost: ~$0.02 per 1M tokens
|
|
379
|
+
- Production cost: ~$0.0025 per daily run (for typical workloads)
|
|
380
|
+
|
|
381
|
+
This automation ensures semantic search remains highly effective as your knowledge graph grows, without requiring manual embedding regeneration.
|
|
382
|
+
|
|
383
|
+
### Query Result Caching (v1.5.0+)
|
|
384
|
+
|
|
385
|
+
Semantic search queries are automatically cached for improved performance:
|
|
386
|
+
|
|
387
|
+
**Cache Configuration:**
|
|
388
|
+
- **LRU (Least Recently Used) Strategy**: Automatically evicts oldest entries when full
|
|
389
|
+
- **Capacity**: 500 unique queries cached simultaneously
|
|
390
|
+
- **TTL (Time-To-Live)**: 5 minutes per cache entry
|
|
391
|
+
- **Size Limit**: 10,000 entities maximum across all cached results
|
|
392
|
+
- **Size Calculation**: Entity count + relation count
|
|
393
|
+
|
|
394
|
+
**Cache Behavior:**
|
|
395
|
+
- **Cache Hits**: Sub-millisecond response for repeated queries
|
|
396
|
+
- **Automatic Invalidation**: Cache cleared on mutations (create_entities, add_observations, delete_entities, etc.)
|
|
397
|
+
- **Intelligent Keying**: Considers query text, limit, similarity threshold, entity types, and hybrid config
|
|
398
|
+
- **Metrics Integration**: Cache hits/misses tracked via Prometheus (when enabled)
|
|
399
|
+
|
|
400
|
+
**Performance Impact:**
|
|
401
|
+
- **First Query**: Normal latency (~100-500ms depending on graph size)
|
|
402
|
+
- **Cached Query**: <1ms response time
|
|
403
|
+
- **Memory Usage**: Minimal - automatically bounded by size limits
|
|
404
|
+
- **Cache Miss Rate**: Typically <10% for conversational workloads
|
|
405
|
+
|
|
406
|
+
**Example Scenarios:**
|
|
407
|
+
- User asks "What programming languages do you know?" → Cache miss (~300ms)
|
|
408
|
+
- User asks "What programming languages do you know?" again → Cache hit (<1ms)
|
|
409
|
+
- User creates new entity → Cache cleared for consistency
|
|
410
|
+
- User asks "What programming languages do you know?" → Cache miss (~300ms, fresh results)
|
|
411
|
+
|
|
412
|
+
This caching layer provides significant performance improvements for repeated or similar queries without any configuration needed.
|
|
413
|
+
|
|
340
414
|
## MCP API Tools
|
|
341
415
|
|
|
342
416
|
The following tools are available to LLM client hosts through the Model Context Protocol:
|
|
@@ -721,6 +795,100 @@ The adaptive search capabilities provide practical benefits:
|
|
|
721
795
|
|
|
722
796
|
For example, when a user asks "What do you know about machine learning?", the system can retrieve conceptually related entities even if they don't explicitly mention "machine learning" - perhaps entities about neural networks, data science, or specific algorithms. But if semantic search yields insufficient results, the system automatically adjusts its approach to ensure useful information is still returned.
|
|
723
797
|
|
|
798
|
+
## Integration with Claude Code
|
|
799
|
+
|
|
800
|
+
### Configuration
|
|
801
|
+
|
|
802
|
+
Add this to your `~/.claude.json`:
|
|
803
|
+
|
|
804
|
+
```json
|
|
805
|
+
{
|
|
806
|
+
"mcpServers": {
|
|
807
|
+
"neo4j-kg": {
|
|
808
|
+
"command": "npx",
|
|
809
|
+
"args": ["-y", "@henrychong-ai/mcp-neo4j-knowledge-graph"],
|
|
810
|
+
"env": {
|
|
811
|
+
"MEMORY_STORAGE_TYPE": "neo4j",
|
|
812
|
+
"NEO4J_URI": "bolt://127.0.0.1:7687",
|
|
813
|
+
"NEO4J_USERNAME": "neo4j",
|
|
814
|
+
"NEO4J_PASSWORD": "your_password_here",
|
|
815
|
+
"NEO4J_DATABASE": "neo4j",
|
|
816
|
+
"NEO4J_VECTOR_INDEX": "entity_embeddings",
|
|
817
|
+
"NEO4J_VECTOR_DIMENSIONS": "1536",
|
|
818
|
+
"NEO4J_SIMILARITY_FUNCTION": "cosine",
|
|
819
|
+
"OPENAI_API_KEY": "your-openai-api-key",
|
|
820
|
+
"OPENAI_EMBEDDING_MODEL": "text-embedding-3-small"
|
|
821
|
+
}
|
|
822
|
+
}
|
|
823
|
+
}
|
|
824
|
+
}
|
|
825
|
+
```
|
|
826
|
+
|
|
827
|
+
### Verify MCP Tools Available
|
|
828
|
+
|
|
829
|
+
In a Claude Code session, the MCP tools will be automatically available. You can verify by asking:
|
|
830
|
+
|
|
831
|
+
```
|
|
832
|
+
Show me the available MCP tools for the knowledge graph
|
|
833
|
+
```
|
|
834
|
+
|
|
835
|
+
You should see tools like:
|
|
836
|
+
- `mcp__kg__create_entities`
|
|
837
|
+
- `mcp__kg__create_relations`
|
|
838
|
+
- `mcp__kg__add_observations`
|
|
839
|
+
- `mcp__kg__search_nodes`
|
|
840
|
+
- `mcp__kg__semantic_search`
|
|
841
|
+
- And more...
|
|
842
|
+
|
|
843
|
+
## Testing Your Setup
|
|
844
|
+
|
|
845
|
+
### Step 1: Create Your First Entity
|
|
846
|
+
|
|
847
|
+
In Claude Desktop or Claude Code, say:
|
|
848
|
+
|
|
849
|
+
```
|
|
850
|
+
Use the knowledge graph to create an entity named "Python"
|
|
851
|
+
of type "Programming Language" with the observation
|
|
852
|
+
"General-purpose, high-level programming language known for readability"
|
|
853
|
+
```
|
|
854
|
+
|
|
855
|
+
### Step 2: Search for the Entity
|
|
856
|
+
|
|
857
|
+
```
|
|
858
|
+
Search the knowledge graph for "Python"
|
|
859
|
+
```
|
|
860
|
+
|
|
861
|
+
Claude should find your entity using the `mcp__kg__search_nodes` tool.
|
|
862
|
+
|
|
863
|
+
### Step 3: Add More Observations
|
|
864
|
+
|
|
865
|
+
```
|
|
866
|
+
Add these observations to the Python entity:
|
|
867
|
+
- Created by Guido van Rossum in 1991
|
|
868
|
+
- Popular for data science, web development, and automation
|
|
869
|
+
- Dynamic typing with interpreted execution
|
|
870
|
+
```
|
|
871
|
+
|
|
872
|
+
### Step 4: Verify in Neo4j Browser
|
|
873
|
+
|
|
874
|
+
Open `http://localhost:7474` and run:
|
|
875
|
+
|
|
876
|
+
```cypher
|
|
877
|
+
MATCH (e:Entity {name: "Python"})
|
|
878
|
+
WHERE e.validTo IS NULL
|
|
879
|
+
RETURN e
|
|
880
|
+
```
|
|
881
|
+
|
|
882
|
+
You should see your entity with all observations.
|
|
883
|
+
|
|
884
|
+
### Step 5: Test Semantic Search (If OpenAI API Key Configured)
|
|
885
|
+
|
|
886
|
+
```
|
|
887
|
+
Perform a semantic search for "programming languages for beginners"
|
|
888
|
+
```
|
|
889
|
+
|
|
890
|
+
The Python entity should appear in results based on semantic similarity.
|
|
891
|
+
|
|
724
892
|
## Troubleshooting
|
|
725
893
|
|
|
726
894
|
### Schema Constraint Configuration
|
|
@@ -0,0 +1,596 @@
|
|
|
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
|
+
1. Check prerequisites and guide installation if needed
|
|
13
|
+
2. Set up Neo4j database (Docker or local)
|
|
14
|
+
3. Generate configuration files
|
|
15
|
+
4. Integrate with Claude Code and/or Claude Desktop
|
|
16
|
+
5. Test the setup
|
|
17
|
+
6. Celebrate success! 🎉
|
|
18
|
+
|
|
19
|
+
**Be patient, encouraging, and clear.** Many users are new to this.
|
|
20
|
+
|
|
21
|
+
---
|
|
22
|
+
|
|
23
|
+
## Section 1: Welcome & Prerequisites Check
|
|
24
|
+
|
|
25
|
+
### 1.1 Welcome Message
|
|
26
|
+
|
|
27
|
+
Say something like:
|
|
28
|
+
|
|
29
|
+
```
|
|
30
|
+
Welcome! I'll guide you through setting up the Neo4j Knowledge Graph MCP server.
|
|
31
|
+
This will take about 10-15 minutes and give you persistent memory capabilities.
|
|
32
|
+
|
|
33
|
+
Let's start by checking your system prerequisites.
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
### 1.2 Check Node.js
|
|
37
|
+
|
|
38
|
+
**RUN:**
|
|
39
|
+
```bash
|
|
40
|
+
node --version
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
**EVALUATE:**
|
|
44
|
+
- **If version >= 20.0.0**: ✅ "Great! You have Node.js v[X.X.X] installed."
|
|
45
|
+
- **If version < 20.0.0**: ⚠️ "You have Node.js v[X.X.X], but we need v20.0.0 or higher."
|
|
46
|
+
- **ACTION**: Provide upgrade instructions for their OS
|
|
47
|
+
- **If not found**: ❌ "Node.js is not installed."
|
|
48
|
+
- **ACTION**: Provide installation instructions:
|
|
49
|
+
- **macOS**: `brew install node`
|
|
50
|
+
- **Linux**: Recommend nvm: `curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash && nvm install 20`
|
|
51
|
+
- **Windows**: Download from https://nodejs.org/
|
|
52
|
+
|
|
53
|
+
**STOP HERE** if Node.js installation is needed. Ask user to install and run this automation again.
|
|
54
|
+
|
|
55
|
+
### 1.3 Check Docker (for Neo4j)
|
|
56
|
+
|
|
57
|
+
**ASK USER:**
|
|
58
|
+
```
|
|
59
|
+
For Neo4j database, do you want to use:
|
|
60
|
+
1. Docker (Recommended - easiest setup, works everywhere)
|
|
61
|
+
2. Local installation (More control, requires manual setup)
|
|
62
|
+
|
|
63
|
+
Which do you prefer? (1 or 2)
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
**IF ANSWER = 1 (Docker):**
|
|
67
|
+
|
|
68
|
+
**RUN:**
|
|
69
|
+
```bash
|
|
70
|
+
docker --version && docker compose version
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
**EVALUATE:**
|
|
74
|
+
- **If both found**: ✅ "Docker and Docker Compose are installed."
|
|
75
|
+
- **If not found**: ❌ "Docker is not installed."
|
|
76
|
+
- **ACTION**: Provide installation instructions:
|
|
77
|
+
- **macOS**: Download Docker Desktop from https://www.docker.com/products/docker-desktop
|
|
78
|
+
- **Linux**: Follow https://docs.docker.com/engine/install/
|
|
79
|
+
- **Windows**: Download Docker Desktop for Windows
|
|
80
|
+
|
|
81
|
+
**STOP HERE** if Docker installation is needed. Ask user to install and run this automation again.
|
|
82
|
+
|
|
83
|
+
**IF ANSWER = 2 (Local installation):**
|
|
84
|
+
- Proceed to Section 2B (Local Neo4j)
|
|
85
|
+
|
|
86
|
+
---
|
|
87
|
+
|
|
88
|
+
## Section 2A: Neo4j Setup - Docker Path
|
|
89
|
+
|
|
90
|
+
### 2.1 Detect Operating System
|
|
91
|
+
|
|
92
|
+
**RUN:**
|
|
93
|
+
```bash
|
|
94
|
+
uname -s
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
This tells you the OS: `Darwin` (macOS), `Linux`, or check for Windows.
|
|
98
|
+
|
|
99
|
+
### 2.2 Ask for Neo4j Password
|
|
100
|
+
|
|
101
|
+
**ASK USER:**
|
|
102
|
+
```
|
|
103
|
+
Choose a password for your Neo4j database.
|
|
104
|
+
(Or press Enter to use the default: 'your_secure_password_here')
|
|
105
|
+
|
|
106
|
+
Password:
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
**STORE** the password as `NEO4J_PASSWORD` variable for later use.
|
|
110
|
+
|
|
111
|
+
### 2.3 Create docker-compose.yml
|
|
112
|
+
|
|
113
|
+
**TELL USER:**
|
|
114
|
+
```
|
|
115
|
+
I'm creating a docker-compose.yml file to run Neo4j...
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
**CREATE FILE** `docker-compose.yml` in current directory:
|
|
119
|
+
|
|
120
|
+
```yaml
|
|
121
|
+
version: '3.8'
|
|
122
|
+
services:
|
|
123
|
+
neo4j:
|
|
124
|
+
image: neo4j:5.26-community
|
|
125
|
+
container_name: neo4j-kg
|
|
126
|
+
restart: unless-stopped
|
|
127
|
+
ports:
|
|
128
|
+
- "7474:7474" # Browser UI
|
|
129
|
+
- "7687:7687" # Bolt protocol
|
|
130
|
+
volumes:
|
|
131
|
+
- neo4j_data:/data
|
|
132
|
+
- neo4j_logs:/logs
|
|
133
|
+
environment:
|
|
134
|
+
- NEO4J_AUTH=neo4j/[NEO4J_PASSWORD]
|
|
135
|
+
- NEO4J_PLUGINS=["apoc"]
|
|
136
|
+
- NEO4J_server_memory_heap_initial__size=512M
|
|
137
|
+
- NEO4J_server_memory_heap_max__size=512M
|
|
138
|
+
- NEO4J_server_memory_pagecache_size=256M
|
|
139
|
+
|
|
140
|
+
volumes:
|
|
141
|
+
neo4j_data:
|
|
142
|
+
neo4j_logs:
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
**REPLACE** `[NEO4J_PASSWORD]` with the user's chosen password.
|
|
146
|
+
|
|
147
|
+
### 2.4 Start Neo4j
|
|
148
|
+
|
|
149
|
+
**RUN:**
|
|
150
|
+
```bash
|
|
151
|
+
docker compose up -d
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
**WAIT** 10 seconds, then **CHECK:**
|
|
155
|
+
```bash
|
|
156
|
+
docker compose ps
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
**EVALUATE:**
|
|
160
|
+
- **If shows "running"**: ✅ "Neo4j is running!"
|
|
161
|
+
- **If not running**: ❌ Show logs: `docker compose logs neo4j`
|
|
162
|
+
|
|
163
|
+
### 2.5 Verify Neo4j Access
|
|
164
|
+
|
|
165
|
+
**TELL USER:**
|
|
166
|
+
```
|
|
167
|
+
Neo4j is starting up... Let me check if it's accessible.
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
**RUN:**
|
|
171
|
+
```bash
|
|
172
|
+
curl -s http://localhost:7474 > /dev/null && echo "Neo4j Browser accessible" || echo "Not yet accessible"
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
**IF NOT ACCESSIBLE:**
|
|
176
|
+
- Wait 10 more seconds and try again
|
|
177
|
+
- After 3 attempts, show troubleshooting: `docker compose logs neo4j`
|
|
178
|
+
|
|
179
|
+
**WHEN ACCESSIBLE:**
|
|
180
|
+
```
|
|
181
|
+
✅ Neo4j is running! You can access the browser at: http://localhost:7474
|
|
182
|
+
Username: neo4j
|
|
183
|
+
Password: [their chosen password]
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
**GO TO:** Section 3 (Environment Configuration)
|
|
187
|
+
|
|
188
|
+
---
|
|
189
|
+
|
|
190
|
+
## Section 2B: Neo4j Setup - Local Installation Path
|
|
191
|
+
|
|
192
|
+
### 2.1 Provide OS-Specific Instructions
|
|
193
|
+
|
|
194
|
+
**FOR macOS:**
|
|
195
|
+
```bash
|
|
196
|
+
brew install neo4j
|
|
197
|
+
neo4j start
|
|
198
|
+
neo4j-admin set-initial-password [PASSWORD]
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
**FOR Linux:**
|
|
202
|
+
```
|
|
203
|
+
Follow the official guide at:
|
|
204
|
+
https://neo4j.com/docs/operations-manual/current/installation/linux/
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
**FOR Windows:**
|
|
208
|
+
```
|
|
209
|
+
Download Neo4j Desktop from:
|
|
210
|
+
https://neo4j.com/download/
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
**ASK USER:** "Have you completed the Neo4j installation? (yes/no)"
|
|
214
|
+
|
|
215
|
+
**IF NO:** Provide help and wait.
|
|
216
|
+
**IF YES:** Continue to verification.
|
|
217
|
+
|
|
218
|
+
### 2.2 Verify Local Neo4j
|
|
219
|
+
|
|
220
|
+
**RUN:**
|
|
221
|
+
```bash
|
|
222
|
+
neo4j status
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
**OR TRY:**
|
|
226
|
+
```bash
|
|
227
|
+
curl -s http://localhost:7474
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
**IF ACCESSIBLE:** ✅ Proceed to Section 3
|
|
231
|
+
|
|
232
|
+
---
|
|
233
|
+
|
|
234
|
+
## Section 3: Environment Configuration
|
|
235
|
+
|
|
236
|
+
### 3.1 Ask for OpenAI API Key (Optional)
|
|
237
|
+
|
|
238
|
+
**ASK USER:**
|
|
239
|
+
```
|
|
240
|
+
Do you have an OpenAI API key for semantic search?
|
|
241
|
+
This enables vector embeddings and semantic similarity.
|
|
242
|
+
|
|
243
|
+
(Optional - you can skip this and add it later)
|
|
244
|
+
|
|
245
|
+
Enter your OpenAI API key (or press Enter to skip):
|
|
246
|
+
```
|
|
247
|
+
|
|
248
|
+
**STORE** as `OPENAI_API_KEY` variable (or empty if skipped).
|
|
249
|
+
|
|
250
|
+
### 3.2 Create .env File (Optional)
|
|
251
|
+
|
|
252
|
+
**TELL USER:**
|
|
253
|
+
```
|
|
254
|
+
I'm creating a .env file for your configuration...
|
|
255
|
+
```
|
|
256
|
+
|
|
257
|
+
**CREATE FILE** `.env` in current directory:
|
|
258
|
+
|
|
259
|
+
```bash
|
|
260
|
+
# Neo4j Connection
|
|
261
|
+
NEO4J_URI=bolt://localhost:7687
|
|
262
|
+
NEO4J_USERNAME=neo4j
|
|
263
|
+
NEO4J_PASSWORD=[NEO4J_PASSWORD]
|
|
264
|
+
NEO4J_DATABASE=neo4j
|
|
265
|
+
|
|
266
|
+
# OpenAI API (Optional)
|
|
267
|
+
OPENAI_API_KEY=[OPENAI_API_KEY]
|
|
268
|
+
OPENAI_EMBEDDING_MODEL=text-embedding-3-small
|
|
269
|
+
```
|
|
270
|
+
|
|
271
|
+
**NOTE:** This .env file is optional - configuration will be done in MCP client configs instead.
|
|
272
|
+
|
|
273
|
+
---
|
|
274
|
+
|
|
275
|
+
## Section 4: Claude Code Configuration
|
|
276
|
+
|
|
277
|
+
### 4.1 Explain What's Happening
|
|
278
|
+
|
|
279
|
+
**TELL USER:**
|
|
280
|
+
```
|
|
281
|
+
Now I'm going to configure Claude Code to use this MCP server.
|
|
282
|
+
I'll modify your ~/.claude.json file to add the Neo4j Knowledge Graph server.
|
|
283
|
+
```
|
|
284
|
+
|
|
285
|
+
### 4.2 Check if ~/.claude.json Exists
|
|
286
|
+
|
|
287
|
+
**RUN:**
|
|
288
|
+
```bash
|
|
289
|
+
[ -f ~/.claude.json ] && echo "exists" || echo "not found"
|
|
290
|
+
```
|
|
291
|
+
|
|
292
|
+
**IF NOT FOUND:**
|
|
293
|
+
**CREATE FILE** `~/.claude.json`:
|
|
294
|
+
```json
|
|
295
|
+
{
|
|
296
|
+
"mcpServers": {}
|
|
297
|
+
}
|
|
298
|
+
```
|
|
299
|
+
|
|
300
|
+
### 4.3 Backup Existing Config
|
|
301
|
+
|
|
302
|
+
**IF FILE EXISTS:**
|
|
303
|
+
```bash
|
|
304
|
+
cp ~/.claude.json ~/.claude.json.backup-$(date +%Y%m%d-%H%M%S)
|
|
305
|
+
```
|
|
306
|
+
|
|
307
|
+
**TELL USER:** "I've created a backup of your existing config at ~/.claude.json.backup-[timestamp]"
|
|
308
|
+
|
|
309
|
+
### 4.4 Add MCP Server Configuration
|
|
310
|
+
|
|
311
|
+
**READ** current `~/.claude.json` content.
|
|
312
|
+
|
|
313
|
+
**ADD** this configuration to the `mcpServers` object:
|
|
314
|
+
|
|
315
|
+
```json
|
|
316
|
+
"neo4j-knowledge-graph": {
|
|
317
|
+
"command": "npx",
|
|
318
|
+
"args": ["-y", "@henrychong-ai/mcp-neo4j-knowledge-graph"],
|
|
319
|
+
"env": {
|
|
320
|
+
"MEMORY_STORAGE_TYPE": "neo4j",
|
|
321
|
+
"NEO4J_URI": "bolt://localhost:7687",
|
|
322
|
+
"NEO4J_USERNAME": "neo4j",
|
|
323
|
+
"NEO4J_PASSWORD": "[NEO4J_PASSWORD]",
|
|
324
|
+
"NEO4J_DATABASE": "neo4j",
|
|
325
|
+
"NEO4J_VECTOR_INDEX": "entity_embeddings",
|
|
326
|
+
"NEO4J_VECTOR_DIMENSIONS": "1536",
|
|
327
|
+
"NEO4J_SIMILARITY_FUNCTION": "cosine",
|
|
328
|
+
"OPENAI_API_KEY": "[OPENAI_API_KEY]",
|
|
329
|
+
"OPENAI_EMBEDDING_MODEL": "text-embedding-3-small"
|
|
330
|
+
}
|
|
331
|
+
}
|
|
332
|
+
```
|
|
333
|
+
|
|
334
|
+
**REPLACE:**
|
|
335
|
+
- `[NEO4J_PASSWORD]` with user's password
|
|
336
|
+
- `[OPENAI_API_KEY]` with user's API key (or remove line if not provided)
|
|
337
|
+
|
|
338
|
+
**WRITE** updated config back to `~/.claude.json`
|
|
339
|
+
|
|
340
|
+
**TELL USER:**
|
|
341
|
+
```
|
|
342
|
+
✅ Claude Code is now configured to use the Neo4j Knowledge Graph!
|
|
343
|
+
```
|
|
344
|
+
|
|
345
|
+
---
|
|
346
|
+
|
|
347
|
+
## Section 5: Claude Desktop Configuration (Optional)
|
|
348
|
+
|
|
349
|
+
### 5.1 Ask User
|
|
350
|
+
|
|
351
|
+
**ASK:**
|
|
352
|
+
```
|
|
353
|
+
Would you also like to configure Claude Desktop to use this MCP server?
|
|
354
|
+
(yes/no)
|
|
355
|
+
```
|
|
356
|
+
|
|
357
|
+
**IF NO:** Skip to Section 6
|
|
358
|
+
|
|
359
|
+
**IF YES:** Continue
|
|
360
|
+
|
|
361
|
+
### 5.2 Locate Claude Desktop Config
|
|
362
|
+
|
|
363
|
+
**FOR macOS:**
|
|
364
|
+
```
|
|
365
|
+
~/Library/Application Support/Claude/claude_desktop_config.json
|
|
366
|
+
```
|
|
367
|
+
|
|
368
|
+
**FOR Linux:**
|
|
369
|
+
```
|
|
370
|
+
~/.config/Claude/claude_desktop_config.json
|
|
371
|
+
```
|
|
372
|
+
|
|
373
|
+
**FOR Windows:**
|
|
374
|
+
```
|
|
375
|
+
%APPDATA%\Claude\claude_desktop_config.json
|
|
376
|
+
```
|
|
377
|
+
|
|
378
|
+
### 5.3 Backup and Update Config
|
|
379
|
+
|
|
380
|
+
**SAME PROCESS** as Section 4.3-4.4, but for Claude Desktop config file.
|
|
381
|
+
|
|
382
|
+
**TELL USER:**
|
|
383
|
+
```
|
|
384
|
+
✅ Claude Desktop is now configured!
|
|
385
|
+
You'll need to restart Claude Desktop for changes to take effect.
|
|
386
|
+
```
|
|
387
|
+
|
|
388
|
+
---
|
|
389
|
+
|
|
390
|
+
## Section 6: Verification & Testing
|
|
391
|
+
|
|
392
|
+
### 6.1 Test Neo4j Connection
|
|
393
|
+
|
|
394
|
+
**TELL USER:**
|
|
395
|
+
```
|
|
396
|
+
Let's verify the setup by testing the Neo4j connection...
|
|
397
|
+
```
|
|
398
|
+
|
|
399
|
+
**RUN:**
|
|
400
|
+
```bash
|
|
401
|
+
npx -y @henrychong-ai/mcp-neo4j-knowledge-graph --version
|
|
402
|
+
```
|
|
403
|
+
|
|
404
|
+
**IF SUCCESSFUL:** ✅ "MCP server package is accessible via npx!"
|
|
405
|
+
|
|
406
|
+
### 6.2 Explain Next Steps
|
|
407
|
+
|
|
408
|
+
**TELL USER:**
|
|
409
|
+
```
|
|
410
|
+
Great! Your setup is complete. Here's how to test it:
|
|
411
|
+
|
|
412
|
+
1. In THIS Claude Code session (or a new one), try:
|
|
413
|
+
"Show me the available MCP tools for the knowledge graph"
|
|
414
|
+
|
|
415
|
+
2. Create your first entity:
|
|
416
|
+
"Create an entity named 'Test' of type 'Example' with observation 'Setup test'"
|
|
417
|
+
|
|
418
|
+
3. Verify in Neo4j Browser:
|
|
419
|
+
- Open http://localhost:7474
|
|
420
|
+
- Login with: neo4j / [their password]
|
|
421
|
+
- Run: MATCH (e:Entity) WHERE e.validTo IS NULL RETURN e
|
|
422
|
+
|
|
423
|
+
Would you like me to test it now by creating a sample entity?
|
|
424
|
+
```
|
|
425
|
+
|
|
426
|
+
### 6.3 Create Test Entity (If User Says Yes)
|
|
427
|
+
|
|
428
|
+
**USE MCP TOOL:** `mcp__kg__create_entities`
|
|
429
|
+
|
|
430
|
+
**CREATE:**
|
|
431
|
+
```json
|
|
432
|
+
{
|
|
433
|
+
"entities": [
|
|
434
|
+
{
|
|
435
|
+
"name": "Setup_Test",
|
|
436
|
+
"entityType": "Test",
|
|
437
|
+
"observations": ["Successfully created during automated setup on [DATE]"]
|
|
438
|
+
}
|
|
439
|
+
]
|
|
440
|
+
}
|
|
441
|
+
```
|
|
442
|
+
|
|
443
|
+
**IF SUCCESSFUL:**
|
|
444
|
+
```
|
|
445
|
+
🎉 Success! I just created a test entity in your knowledge graph!
|
|
446
|
+
|
|
447
|
+
Try searching for it: "Search the knowledge graph for 'Setup_Test'"
|
|
448
|
+
```
|
|
449
|
+
|
|
450
|
+
**IF FAILS:**
|
|
451
|
+
Show error and provide troubleshooting steps.
|
|
452
|
+
|
|
453
|
+
---
|
|
454
|
+
|
|
455
|
+
## Section 7: Troubleshooting
|
|
456
|
+
|
|
457
|
+
### Common Issues
|
|
458
|
+
|
|
459
|
+
**Issue: "Cannot connect to Neo4j"**
|
|
460
|
+
- Check Neo4j is running: `docker compose ps` or `neo4j status`
|
|
461
|
+
- Check port 7687 is accessible: `telnet localhost 7687`
|
|
462
|
+
- View Neo4j logs: `docker compose logs neo4j`
|
|
463
|
+
|
|
464
|
+
**Issue: "MCP tools not available in Claude Code"**
|
|
465
|
+
- Restart Claude Code session
|
|
466
|
+
- Check ~/.claude.json syntax is valid JSON
|
|
467
|
+
- Verify npx can run the package: `npx -y @henrychong-ai/mcp-neo4j-knowledge-graph --version`
|
|
468
|
+
|
|
469
|
+
**Issue: "Node already exists" error**
|
|
470
|
+
- This is a Neo4j schema constraint issue
|
|
471
|
+
- See: https://github.com/henrychong-ai/mcp-neo4j-knowledge-graph#troubleshooting
|
|
472
|
+
|
|
473
|
+
---
|
|
474
|
+
|
|
475
|
+
## Section 8: Success & Next Steps
|
|
476
|
+
|
|
477
|
+
### 8.1 Important: Restart Claude Code
|
|
478
|
+
|
|
479
|
+
**TELL USER:**
|
|
480
|
+
```
|
|
481
|
+
🎉 Setup is complete! However, there's one critical step:
|
|
482
|
+
|
|
483
|
+
⚠️ IMPORTANT: Claude Code needs to restart to load the new MCP server configuration.
|
|
484
|
+
|
|
485
|
+
Here's what to do:
|
|
486
|
+
1. Type "/exit" to exit this session
|
|
487
|
+
2. Type "claude --continue" to resume the session with MCP tools loaded
|
|
488
|
+
3. Once you're back, say "I'm back" or "ready" so I can help you test the MCP tools!
|
|
489
|
+
|
|
490
|
+
Don't worry - I'll be right here when you return. See you in a moment! 👋
|
|
491
|
+
```
|
|
492
|
+
|
|
493
|
+
**WAIT FOR USER TO RESTART AND RETURN**
|
|
494
|
+
|
|
495
|
+
When user returns and says they're back, proceed to Section 8.2
|
|
496
|
+
|
|
497
|
+
### 8.2 Test MCP Tools (After Restart)
|
|
498
|
+
|
|
499
|
+
**TELL USER:**
|
|
500
|
+
```
|
|
501
|
+
Welcome back! Now let's verify the MCP tools are working.
|
|
502
|
+
|
|
503
|
+
Let me check what tools are available...
|
|
504
|
+
```
|
|
505
|
+
|
|
506
|
+
**TRY TO USE MCP TOOL:** Check if MCP tools are available by attempting to list them or use one.
|
|
507
|
+
|
|
508
|
+
**IF MCP TOOLS ARE AVAILABLE:**
|
|
509
|
+
```
|
|
510
|
+
✅ Perfect! The MCP tools are loaded. Let's test them:
|
|
511
|
+
```
|
|
512
|
+
|
|
513
|
+
**SUGGEST TESTS:**
|
|
514
|
+
1. List available tools: "I can see [X] tools available including create_entities, search_nodes, semantic_search..."
|
|
515
|
+
2. Create a test entity if not already done
|
|
516
|
+
3. Search for the entity
|
|
517
|
+
4. View it in Neo4j Browser
|
|
518
|
+
|
|
519
|
+
**IF MCP TOOLS NOT AVAILABLE:**
|
|
520
|
+
```
|
|
521
|
+
Hmm, the tools aren't showing up yet. Let's troubleshoot:
|
|
522
|
+
|
|
523
|
+
1. Check your ~/.claude.json file has the correct configuration
|
|
524
|
+
2. Try restarting Claude Code one more time
|
|
525
|
+
3. Check for any error messages in the terminal
|
|
526
|
+
|
|
527
|
+
Would you like me to verify your configuration?
|
|
528
|
+
```
|
|
529
|
+
|
|
530
|
+
### 8.3 Final Success Celebration
|
|
531
|
+
|
|
532
|
+
**AFTER SUCCESSFUL MCP TOOL TEST:**
|
|
533
|
+
|
|
534
|
+
**TELL USER:**
|
|
535
|
+
```
|
|
536
|
+
🎉 Congratulations! Your Neo4j Knowledge Graph MCP server is fully working!
|
|
537
|
+
|
|
538
|
+
You now have:
|
|
539
|
+
✅ Neo4j database running
|
|
540
|
+
✅ MCP server configured in Claude Code
|
|
541
|
+
✅ MCP tools loaded and tested
|
|
542
|
+
[✅ Claude Desktop configured (if they chose this)]
|
|
543
|
+
✅ Test entity created and verified
|
|
544
|
+
|
|
545
|
+
Next steps:
|
|
546
|
+
1. Start building your knowledge graph by creating entities and relations
|
|
547
|
+
2. Use semantic search to find information: "Search for X"
|
|
548
|
+
3. Explore the documentation: https://www.npmjs.com/package/@henrychong-ai/mcp-neo4j-knowledge-graph
|
|
549
|
+
|
|
550
|
+
Happy graphing! 🚀
|
|
551
|
+
```
|
|
552
|
+
|
|
553
|
+
### 8.4 Save Setup Summary
|
|
554
|
+
|
|
555
|
+
**CREATE FILE** `mcp-neo4j-setup-summary.txt`:
|
|
556
|
+
|
|
557
|
+
```
|
|
558
|
+
MCP Neo4j Knowledge Graph - Setup Summary
|
|
559
|
+
==========================================
|
|
560
|
+
Date: [CURRENT DATE/TIME]
|
|
561
|
+
|
|
562
|
+
Neo4j:
|
|
563
|
+
- URI: bolt://localhost:7687
|
|
564
|
+
- Username: neo4j
|
|
565
|
+
- Password: [NEO4J_PASSWORD]
|
|
566
|
+
- Browser: http://localhost:7474
|
|
567
|
+
|
|
568
|
+
Configuration:
|
|
569
|
+
- Claude Code: ~/.claude.json ✅
|
|
570
|
+
- Claude Desktop: [YES/NO]
|
|
571
|
+
|
|
572
|
+
OpenAI Semantic Search: [ENABLED/SKIPPED]
|
|
573
|
+
|
|
574
|
+
Backups:
|
|
575
|
+
- ~/.claude.json.backup-[timestamp]
|
|
576
|
+
|
|
577
|
+
To restart Neo4j (Docker):
|
|
578
|
+
docker compose restart neo4j
|
|
579
|
+
|
|
580
|
+
To stop Neo4j (Docker):
|
|
581
|
+
docker compose stop neo4j
|
|
582
|
+
|
|
583
|
+
To view logs:
|
|
584
|
+
docker compose logs -f neo4j
|
|
585
|
+
|
|
586
|
+
Documentation:
|
|
587
|
+
https://www.npmjs.com/package/@henrychong-ai/mcp-neo4j-knowledge-graph
|
|
588
|
+
```
|
|
589
|
+
|
|
590
|
+
**TELL USER:** "I've saved a setup summary to mcp-neo4j-setup-summary.txt"
|
|
591
|
+
|
|
592
|
+
---
|
|
593
|
+
|
|
594
|
+
## End of Automation Script
|
|
595
|
+
|
|
596
|
+
**YOU'RE DONE!** The user now has a fully functional MCP Neo4j Knowledge Graph server.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@henrychong-ai/mcp-neo4j-knowledge-graph",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.7.0",
|
|
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>",
|
|
@@ -30,7 +30,8 @@
|
|
|
30
30
|
"claude"
|
|
31
31
|
],
|
|
32
32
|
"files": [
|
|
33
|
-
"dist"
|
|
33
|
+
"dist",
|
|
34
|
+
"SETUP_AUTOMATION.md"
|
|
34
35
|
],
|
|
35
36
|
"scripts": {
|
|
36
37
|
"build": "tsc && shx chmod +x dist/*.js",
|