aixier/magic-garden-neo4j-server

Magic Garden Neo4j MCP Server

A Model Context Protocol (MCP) server for Neo4j graph database operations, designed for the Magic Garden AI children's education platform.

Features

Implemented Tools (26/64 - 40% Complete)

User Management (5 tools)

• user_create - Create new user accounts with password hashing
• user_authenticate - Authenticate users and generate tokens
• user_profile_get - Get user profiles with statistics
• user_update - Update user information
• user_delete - Delete users with cascade options

Record Management (5 tools)

• record_create - Create records with vector embeddings
• record_update - Update record properties
• record_search - Multi-condition search with pagination
• record_similarity_search - Vector similarity search
• record_batch_operation - Batch operations with transactions

Conversation Management (7 tools)

• conversation_create - Create new conversations
• conversation_update - Update conversation metadata
• message_create - Add messages to conversations
• message_update - Update message content
• conversation_history_get - Retrieve conversation history
• conversation_search - Search conversations with filters
• conversation_analysis - Analyze conversation patterns

Installation

# Clone the repository
git clone https://github.com/yourusername/magic-garden-neo4j-server.git
cd magic-garden-neo4j-server

# Install dependencies
pip install -r requirements.txt

Configuration

Environment Variables

Create a .env file with:

NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=your-password
NEO4J_DATABASE=neo4j
LOG_LEVEL=INFO

Claude Desktop Configuration

Add to Claude Desktop settings:

{
  "mcpServers": {
    "magic-garden-neo4j": {
      "command": "python",
      "args": ["-m", "magic_garden_neo4j_server"],
      "cwd": "/path/to/magic-garden-neo4j-server",
      "env": {
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USER": "neo4j",
        "NEO4J_PASSWORD": "your-password"
      }
    }
  }
}

Cursor Configuration

For Cursor IDE integration, add to .cursor/mcp-settings.json:

{
  "servers": [
    {
      "name": "magic-garden-neo4j",
      "command": "python",
      "args": ["-m", "magic_garden_neo4j_server"],
      "env": {
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USER": "neo4j",
        "NEO4J_PASSWORD": "your-password"
      }
    }
  ]
}

Usage

Starting the Server

# Direct execution
python -m magic_garden_neo4j_server

# With environment variables
NEO4J_URI=bolt://localhost:7687 python -m magic_garden_neo4j_server

Example Tool Usage

Create a User

{
  "tool": "user_create",
  "arguments": {
    "username": "alice",
    "password": "secure123",
    "nickname": "Alice",
    "age": 8
  }
}

Create a Record

{
  "tool": "record_create",
  "arguments": {
    "user_id": "user_abc123",
    "title": "My Drawing",
    "image_url": "https://example.com/image.jpg",
    "mood_color": "happy_yellow",
    "embedding": [0.1, 0.2, 0.3, ...]
  }
}

Start a Conversation

{
  "tool": "conversation_create",
  "arguments": {
    "user_id": "user_abc123",
    "title": "Story Time",
    "conversation_type": "story"
  }
}

Architecture

magic-garden-neo4j-server/
├── src/
│   ├── __init__.py
│   ├── server.py           # MCP server implementation
│   ├── neo4j_manager.py    # Neo4j connection management
│   ├── tool_registry.py    # Tool registration system
│   ├── tools/
│   │   ├── base.py         # Base tool class
│   │   ├── user_tools.py   # User management tools
│   │   ├── record_tools.py # Record management tools
│   │   ├── conversation_tools.py # Conversation tools
│   │   └── ...             # Other tool modules
│   └── utils/
│       ├── errors.py       # Error handling
│       ├── logger.py       # Logging configuration
│       └── validators.py   # Input validation
├── requirements.txt
├── README.md
└── .env.example

Development Status

Completed (40%)

• ✅ Core infrastructure (8 tasks)
• ✅ User management (5 tools)
• ✅ Record management (5 tools)
• ✅ Conversation management (7 tools)

In Progress (60%)

• 🚧 Intelligent analysis tools (7 tools)
• 🚧 Vector service tools (7 tools)
• 🚧 Report generation tools (7 tools)
• 🚧 Advanced query tools (7 tools)
• 🚧 Transaction management tools (7 tools)

License

MIT

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Support

For issues and questions, please open an issue on GitHub.