Neo4j connection (#170)

Author: danstarns

agents/available-connections.mdx

@@ -150,6 +150,19 @@ agent card for the full list.
       <span className="text-lg font-semibold">Neo4j AuraDB</span>
     </div>
     Fully managed graph database.
+     <div className="mt-4 flex items-center justify-between">
+      <span className="inline-flex items-center px-2.5 py-0.5 rounded-full text-xs font-medium bg-gray-100 text-gray-800">
+        3 tools
+      </span>
+
+      <a
+        href="/agents/connections/neo4j"
+        className="px-3 py-1 bg-gray-100 hover:bg-gray-200 dark:bg-gray-700 dark:hover:bg-gray-600 dark:text-gray-200 rounded"
+      >
+        Details
+      </a>
+    </div>
+
   </Card>
   <Card>
     <div className="flex items-center gap-2">

agents/connections/neo4j.mdx

@@ -0,0 +1,280 @@
+---
+title: Using Neo4j with Hypermode
+sidebarTitle: Neo4j
+description: Connect your Hypermode agent to Neo4j for graph database operations
+---
+
+<div className="flex items-center gap-3 mb-6">
+  <img
+    src="/images/agents/connections/icons/neo4j-auradb.png"
+    alt="Neo4j"
+    width={48}
+    height={48}
+  />
+  <div>
+    <h2 className="text-2xl font-bold m-0">Neo4j</h2>
+    <p className="text-gray-600 m-0">
+      Graph database platform for connected data
+    </p>
+  </div>
+</div>
+
+## Overview
+
+Neo4j is a powerful graph database that excels at managing highly connected data
+and complex relationships. This guide will walk you through connecting your
+Hypermode agent to Neo4j.
+
+## Prerequisites
+
+Before connecting Neo4j to Hypermode, you'll need:
+
+1. A [Neo4j account](https://neo4j.com/)
+2. A Neo4j instance (we'll use Neo4j Sandbox for this guide)
+3. A [Hypermode workspace](https://hypermode.com/)
+
+## Setting up Neo4j
+
+### Step 1: Create a Neo4j Sandbox
+
+First, you need to go to https://sandbox.neo4j.com/ and create an account. When
+you get to making a database, select a blank sandbox.
+
+![Create blank sandbox](/images/connections/neo4j/blank-sandbox.png)
+
+<Note>
+  Neo4j Sandbox provides free temporary instances perfect for testing. For
+  production use, consider Neo4j Aura or a self-hosted instance.
+</Note>
+
+### Step 2: Get your connection details
+
+Once created (it may take a moment), you can navigate to the HTTP tab and grab
+the URL. Note you will have to modify this to use the Neo4j HTTP v2 endpoint:
+
+- Remove `/db/neo4j/tx/commit`
+- Replace it with `/db/neo4j/query/v2`
+
+For example:
+
+- Original: `http://52.54.53.148:7474/db/neo4j/tx/commit`
+- Modified: `http://52.54.53.148:7474/db/neo4j/query/v2`
+
+![http tab](/images/connections/neo4j/neo4j-http-connection.png)
+
+### Step 3: Get authentication credentials
+
+Save this URL and then move to the connection details to grab the username and
+password.
+
+![Connection details](/images/connections/neo4j/neo4j-user-password.png)
+
+Now we've got the URL, username, and password we can create a new agent in
+Hypermode.
+
+## Creating your Neo4j agent
+
+### Step 1: Create a new agent
+
+From the Hypermode interface, create a new agent:
+
+1. Click the agent dropdown menu
+2. Select "Create new Agent"
+
+![Navigate to create agent](/images/connections/neo4j/navigate-create-agent.png)
+
+### Step 2: Configure agent settings
+
+Use these recommended settings for your Neo4j agent:
+
+- **Agent Name**: GraphExplorer
+- **Agent Title**: Neo4j Graph Analysis Agent
+- **Description**: Analyzes graph relationships and patterns in Neo4j
+- **Instructions**: You have a connection to a Neo4j graph database. You can
+  create nodes with any labels and properties, create relationships of any type,
+  and run Cypher queries. Neo4j is schemaless, so you can dynamically add data
+  without predefined structures.
+- **Model**: GPT-4.1
+
+![Create agent modal](/images/connections/neo4j/create-agent-modal.png)
+
+### Step 3: View your agent profile
+
+Once created, navigate to your agent's settings page:
+
+![Agent profile](/images/connections/neo4j/agent-profile.png)
+
+## Connecting to Neo4j
+
+### Step 1: Add the Neo4j connection
+
+Navigate to the **Connections** tab and add Neo4j:
+
+1. Click "Add connection"
+2. Search for "Neo4j" in the available connections
+
+![Add Neo4j connection](/images/connections/neo4j/add-neo4j-connection.png)
+
+### Step 2: Configure credentials
+
+Enter your Neo4j credentials:
+
+- **URL**: Your modified HTTP v2 endpoint
+  (`http://52.54.53.148:7474/db/neo4j/query/v2`)
+- **Username**: Your Neo4j username (usually `neo4j`)
+- **Password**: Your Neo4j password
+
+![Neo4j connection modal](/images/connections/neo4j/neo4j-connection-modal.png)
+
+<Warning>
+  Ensure you're using the HTTP v2 endpoint format. The connection will fail with
+  the default transaction endpoint.
+</Warning>
+
+## Understanding Neo4j's schemaless nature
+
+Unlike traditional databases, Neo4j doesn't require you to define schemas
+upfront. This means:
+
+- **Flexible node creation**: Add nodes with any labels and properties on the
+  fly
+- **Dynamic relationships**: Create relationships of any type between nodes
+- **Evolving data models**: Your graph structure can grow and change organically
+- **No migrations needed**: Add new node types or properties without schema
+  updates
+
+This flexibility makes Neo4j perfect for:
+
+- Exploratory data analysis
+- Rapidly evolving data models
+- Complex, heterogeneous datasets
+- Real-world relationship modeling
+
+## Example graph model
+
+Here's a simple example of how nodes and relationships work in Neo4j:
+
+![Neo4j Graph Model](/images/connections/neo4j/model.png)
+
+This model shows:
+
+- **Nodes**: Person, Company, and Product (represented as circles)
+- **Relationships**: WORKS_AT, MAKER_OF, BY_COMPANY (represented as arrows)
+- Each node can have properties (like name, age, price)
+- Relationships can also have properties (like since, role)
+
+## Testing the connection
+
+### Test 1: Create your first nodes
+
+Start a new thread with your agent and create some nodes dynamically:
+
+```text
+Create nodes for this scenario:
+- A Person named "Alice" who is 28 years old
+- A Company named "TechCorp" founded in 2020
+- A Product named "GraphApp" with a price of $99
+```
+
+![Create nodes result](/images/connections/neo4j/create-nodes-result.png)
+
+### Test 2: Create relationships
+
+Now connect your nodes based on our model:
+
+```text
+Create these relationships:
+- Alice WORKS_AT TechCorp (since 2021)
+- Alice is MAKER_OF GraphApp
+- GraphApp is BY_COMPANY TechCorp
+```
+
+![Create relationships result](/images/connections/neo4j/create-relationships-result.png)
+
+### Test 3: Visualize in Neo4j Browser
+
+After your agent creates the data, switch to Neo4j Browser to see the results:
+
+1. **Click the "Open" button** in your Neo4j Sandbox
+2. **Run the visualization query**:
+
+```cypher
+   MATCH (n) RETURN n
+```
+
+![graph in browser](/images/connections/neo4j/neo4j-browser-graph-view.png)
+
+### Test 4: Query your graph
+
+Back in your agent thread, use Cypher to explore your data:
+
+```text
+Run a Cypher query to find all products made by people who work at TechCorp, showing the full relationship path.
+```
+
+![Query result](/images/connections/neo4j/cypher-query-result.png)
+
+## Example: Building a dynamic knowledge graph
+
+Here's how to leverage Neo4j's schemaless nature to build a flexible knowledge
+graph:
+
+```text
+Let's expand our graph with more data:
+1. Add another Person "Bob" who also works at TechCorp
+2. Add a new Company "StartupInc"
+3. Add Products "DataTool" and "AIAssistant"
+4. Create relationships showing Bob made DataTool, and StartupInc made AIAssistant
+5. Add a COMPETES_WITH relationship between the two companies
+```
+
+Your agent can dynamically add:
+
+- New node types as you discover them
+- Properties specific to each entity
+- Relationships that make sense in context
+- No need to predefine any structure!
+
+## What you can do
+
+With your Neo4j connection and its three core tools, your agent can:
+
+- **Create Node**: Dynamically add entities with any labels and properties
+- **Create Relationship**: Connect nodes with typed relationships and properties
+- **Run Cypher Query**: Perform complex graph operations including:
+  - Pattern matching and traversal
+  - Aggregations and analytics
+  - Graph algorithms
+  - Data updates and deletions
+  - Schema-free exploration
+
+## Troubleshooting
+
+### Common issues
+
+#### Connection refused error
+
+- Verify you're using the HTTP v2 endpoint format
+- Check if your sandbox is still active (they expire after 3 days)
+- Ensure the URL includes the correct port (usually 7474)
+
+#### Authentication failed
+
+- Confirm username and password are correct
+- Sandbox passwords are auto-generated - copy carefully
+- Try resetting the password in the sandbox console
+
+#### Tool execution errors
+
+- Check the
+  [MCP Neo4j documentation](https://mcp.pipedream.com/app/neo4j_auradb) for
+  correct parameter formats
+- Ensure node IDs exist before creating relationships
+- Verify Cypher syntax in your queries
+
+## Learn more
+
+- [Neo4j Documentation](https://neo4j.com/docs/)
+- [Cypher Query Language](https://neo4j.com/docs/cypher-manual/current/)
+- [MCP Neo4j AuraDB Server](https://mcp.pipedream.com/app/neo4j_auradb)
+- [Graph Data Science Library](https://neo4j.com/docs/graph-data-science/current/)

docs.json

@@ -69,7 +69,8 @@
                     "group": "Available Connections",
                     "pages": [
                       "agents/available-connections",
-                      "agents/connections/supabase"
+                      "agents/connections/supabase",
+                      "agents/connections/neo4j"
                     ]
                   }
                 ]