mcp-neo4j-cypher clean up (#18)

* update readme, remove IT, move changelog to root
* Update CHANGELOG.txt
* make changelog markdown file

* add integration tests, update readme
* Update pr-mcp-neo4j-cypher.yml

* add ruff to dev deps, developing PR workflow

* formatting, fix wf

Author: a-s-g93

.github/workflows/pr-mcp-neo4j-cypher.yml

@@ -0,0 +1,47 @@
+name: MCP Neo4j Cypher Tests
+
+on:
+  push:
+    branches: [ main, master ]
+    paths:
+      - 'servers/mcp-neo4j-cypher/**'
+  pull_request:
+    branches: [ main, master ]
+    paths:
+      - 'servers/mcp-neo4j-cypher/**'
+  workflow_dispatch:  # Allows manual triggering of the workflow
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v3
+    
+    - name: Set up Python 3.12
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.12'
+    
+    - name: Install UV
+      run: |
+        curl -LsSf https://astral.sh/uv/install.sh | sh
+        echo "$HOME/.cargo/bin" >> $GITHUB_PATH
+    
+    - name: Install dependencies
+      run: |
+        cd servers/mcp-neo4j-cypher
+        uv venv
+        uv pip install -e ".[dev]"
+
+    - name: Check format and linting
+      run: |
+        cd servers/mcp-neo4j-cypher
+        uv run ruff check --select I . --fix
+        uv run ruff check --fix .
+        uv run ruff format .
+    
+    - name: Run tests
+      run: |
+        cd servers/mcp-neo4j-cypher
+        ./test.sh

servers/mcp-neo4j-cypher/src/mcp_neo4j_cypher/CHANGELOG.txt renamed to servers/mcp-neo4j-cypher/CHANGELOG.md

@@ -7,10 +7,13 @@
 * Refactor mcp-neo4j-cypher to use the FastMCP class
 * Implement Neo4j async driver
 * Tool responses now return JSON serialized results
+* Update README with new config options 
+* Update integration tests
 
 ### Added
 
 * Add support for environment variables
+* Add Github workflow to test and format mcp-neo4j-cypher
 
 
 ## v0.1.1

servers/mcp-neo4j-cypher/README.md

@@ -15,44 +15,40 @@ The server offers these core tools:
    - Execute Cypher read queries to read data from the database
    - Input: 
      - `query` (string): The Cypher query to execute
-   - Returns: Query results as array of objects
+     - `params` (dictionary, optional): Parameters to pass to the Cypher query
+   - Returns: Query results as JSON serialized array of objects
 
 - `write-neo4j-cypher`
    - Execute updating Cypher queries
    - Input:
      - `query` (string): The Cypher update query
-   - Returns: A result summary counter with `{ nodes_updated: number, relationships_created: number, ... }`
+     - `params` (dictionary, optional): Parameters to pass to the Cypher query
+   - Returns: A JSON serialized result summary counter with `{ nodes_updated: number, relationships_created: number, ... }`
 
 #### 🕸️ Schema Tools
 - `get-neo4j-schema`
    - Get a list of all nodes types in the graph database, their attributes with name, type and relationships to other node types
    - No input required
-   - Returns: List of node label with two dictionaries one for attributes and one for relationships
+   - Returns: JSON serialized list of node labels with two dictionaries: one for attributes and one for relationships
 
 ## 🔧 Usage with Claude Desktop
 
 ### 💾 Released Package
 
 Can be found on PyPi https://pypi.org/project/mcp-neo4j-cypher/
 
-Add the server to your `claude_desktop_config.json` with configuration of:
-
-* db-url
-* username
-* password
-
-
-Alternatively, you can set environment variables:
+Add the server to your `claude_desktop_config.json` with configuration through environment variables:
 
 ```json
 "mcpServers": {
   "neo4j-aura": {
     "command": "uvx",
     "args": [ "mcp-neo4j-cypher==0.1.2" ],
     "env": {
-      "NEO4J_URL": "bolt://localhost:7687",
+      "NEO4J_URI": "bolt://localhost:7687",
       "NEO4J_USERNAME": "neo4j",
-      "NEO4J_PASSWORD": "<your-password>"
+      "NEO4J_PASSWORD": "<your-password>",
+      "NEO4J_DATABASE": "neo4j"
     }
   }
 }
@@ -66,17 +62,17 @@ Here is an example connection for the movie database with Movie, Person (Actor,
     "movies-neo4j": {
       "command": "uvx",
       "args": ["mcp-neo4j-cypher==0.1.2"],
-          "env": {
-      "NEO4J_URL": "neo4j+s://demo.neo4jlabs.com",
-      "NEO4J_USERNAME": "recommendations",
-      "NEO4J_PASSWORD": "recommendations"
-    }
+      "env": {
+        "NEO4J_URI": "neo4j+s://demo.neo4jlabs.com",
+        "NEO4J_USERNAME": "recommendations",
+        "NEO4J_PASSWORD": "recommendations"
+      }
     }   
   }
 }
 ```
 
-Syntax with `--db-url`, `--username` and `--password` was supported but will be removed in future versions:
+Syntax with `--db-url`, `--username` and `--password` command line arguments is still supported but environment variables are preferred:
 
 <details>
   <summary>Legacy Syntax</summary>
@@ -124,7 +120,7 @@ Here is an example connection for the movie database with Movie, Person (Actor,
     "args": [
       "run",
       "--rm",
-      "-e", "NEO4J_URL=bolt://host.docker.internal:7687",
+      "-e", "NEO4J_URI=bolt://host.docker.internal:7687",
       "-e", "NEO4J_USERNAME=neo4j",
       "-e", "NEO4J_PASSWORD=<your-password>",
       "mcp/neo4j-cypher:0.1.2"
@@ -164,6 +160,17 @@ source .venv/bin/activate  # On Unix/macOS
 uv pip install -e ".[dev]"
 ```
 
+3. Run Integration Tests
+
+**CLOSE ANY LOCAL NEO4J DATABASES BEFORE RUNNING TESTS**
+* Tests will deploy a local docker container containing the test Neo4j instance. 
+* However if a Neo4j database is running locally, then the test driver may connect here instead. 
+* **This will result in you local Neo4j database having its contents erased.**
+
+```bash
+./tests.sh
+```
+
 ### 🔧 Development Configuration
 
 ```json
@@ -175,7 +182,7 @@ uv pip install -e ".[dev]"
       "--directory", "parent_of_servers_repo/servers/mcp-neo4j-cypher/src",
       "run", "mcp-neo4j-cypher"],
     "env": {
-      "NEO4J_URL": "bolt://localhost",
+      "NEO4J_URI": "bolt://localhost",
       "NEO4J_USERNAME": "neo4j",
       "NEO4J_PASSWORD": "<your-password>"
     }
@@ -192,7 +199,7 @@ Build and run the Docker container:
 docker build -t mcp/neo4j-cypher:latest .
 
 # Run the container
-docker run -e NEO4J_URL="bolt://host.docker.internal:7687" \
+docker run -e NEO4J_URI="bolt://host.docker.internal:7687" \
           -e NEO4J_USERNAME="neo4j" \
           -e NEO4J_PASSWORD="your-password" \
           mcp/neo4j-cypher:latest

servers/mcp-neo4j-cypher/pyproject.toml

@@ -15,7 +15,12 @@ requires = ["hatchling"]
 build-backend = "hatchling.build"
 
 [tool.uv]
-dev-dependencies = ["pyright>=1.1.389", "pytest>=7.0.0", "pytest-asyncio>=0.20.3"]
+dev-dependencies = [
+    "pyright>=1.1.389",
+ "pytest>=7.0.0",
+ "pytest-asyncio>=0.20.3",
+ "ruff>=0.11.5",
+]
 
 [project.scripts]
 mcp-neo4j-cypher = "mcp_neo4j_cypher:main"

servers/mcp-neo4j-cypher/src/mcp_neo4j_cypher/__init__.py

@@ -1,8 +1,9 @@
-from . import server
-import asyncio
 import argparse
+import asyncio
 import os
 
+from . import server
+
 
 def main():
     """Main entry point for the package."""
@@ -22,8 +23,5 @@ def main():
         )
     )
 
-    # asyncio.run(server.main())
-
 
-# Optionally expose other important items at package level
 __all__ = ["main", "server"]

servers/mcp-neo4j-cypher/src/mcp_neo4j_cypher/server.py

@@ -1,21 +1,23 @@
+import json
 import logging
+import re
+import sys
+import time
+from typing import Any, Optional
+
 import mcp.types as types
 from mcp.server.fastmcp import FastMCP
-from pydantic import Field
-from typing import Any
 from neo4j import (
+    AsyncDriver,
     AsyncGraphDatabase,
     AsyncResult,
     AsyncTransaction,
     GraphDatabase,
 )
 from neo4j.exceptions import DatabaseError
-import time
-import re
-import os
-from typing import Optional
-import sys
-import json
+from pydantic import Field
+
+logger = logging.getLogger("mcp_neo4j_cypher")
 
 
 def healthcheck(db_url: str, username: str, password: str, database: str) -> None:
@@ -78,26 +80,9 @@ def _is_write_query(query: str) -> bool:
     )
 
 
-def main(
-    db_url: str,
-    username: str,
-    password: str,
-    database: str,
-) -> None:
-    logger = logging.getLogger("mcp_neo4j_cypher")
-    logger.info("Starting MCP neo4j Server")
-
-    neo4j_driver = AsyncGraphDatabase.driver(
-        db_url,
-        auth=(
-            username,
-            password,
-        ),
-    )
-
+def create_mcp_server(neo4j_driver: AsyncDriver, database: str = "neo4j") -> FastMCP:
     mcp: FastMCP = FastMCP("mcp-neo4j-cypher", dependencies=["neo4j", "pydantic"])
 
-    @mcp.tool()
     async def get_neo4j_schema() -> list[types.TextContent]:
         """List all node, their attributes and their relationships to other nodes in the neo4j database"""
 
@@ -111,9 +96,7 @@ async def get_neo4j_schema() -> list[types.TextContent]:
 """
 
         try:
-            async with neo4j_driver.session(
-                database=os.getenv("NEO4J_DATABASE", "neo4j")
-            ) as session:
+            async with neo4j_driver.session(database=database) as session:
                 results_json_str = await session.execute_read(
                     _read, get_schema_query, dict()
                 )
@@ -126,7 +109,6 @@ async def get_neo4j_schema() -> list[types.TextContent]:
             logger.error(f"Database error retrieving schema: {e}")
             return [types.TextContent(type="text", text=f"Error: {e}")]
 
-    @mcp.tool()
     async def read_neo4j_cypher(
         query: str = Field(..., description="The Cypher query to execute."),
         params: Optional[dict[str, Any]] = Field(
@@ -139,9 +121,7 @@ async def read_neo4j_cypher(
             raise ValueError("Only MATCH queries are allowed for read-query")
 
         try:
-            async with neo4j_driver.session(
-                database=os.getenv("NEO4J_DATABASE", "neo4j")
-            ) as session:
+            async with neo4j_driver.session(database=database) as session:
                 results_json_str = await session.execute_read(_read, query, params)
 
                 logger.debug(f"Read query returned {len(results_json_str)} rows")
@@ -154,7 +134,6 @@ async def read_neo4j_cypher(
                 types.TextContent(type="text", text=f"Error: {e}\n{query}\n{params}")
             ]
 
-    @mcp.tool()
     async def write_neo4j_cypher(
         query: str = Field(..., description="The Cypher query to execute."),
         params: Optional[dict[str, Any]] = Field(
@@ -167,11 +146,11 @@ async def write_neo4j_cypher(
             raise ValueError("Only write queries are allowed for write-query")
 
         try:
-            async with neo4j_driver.session(
-                database=os.getenv("NEO4J_DATABASE", "neo4j")
-            ) as session:
+            async with neo4j_driver.session(database=database) as session:
                 raw_results = await session.execute_write(_write, query, params)
-                counters_json_str = json.dumps(raw_results._summary.counters.__dict__, default=str)
+                counters_json_str = json.dumps(
+                    raw_results._summary.counters.__dict__, default=str
+                )
 
             logger.debug(f"Write query affected {counters_json_str}")
 
@@ -183,6 +162,31 @@ async def write_neo4j_cypher(
                 types.TextContent(type="text", text=f"Error: {e}\n{query}\n{params}")
             ]
 
+    mcp.add_tool(get_neo4j_schema)
+    mcp.add_tool(read_neo4j_cypher)
+    mcp.add_tool(write_neo4j_cypher)
+
+    return mcp
+
+
+def main(
+    db_url: str,
+    username: str,
+    password: str,
+    database: str,
+) -> None:
+    logger.info("Starting MCP neo4j Server")
+
+    neo4j_driver = AsyncGraphDatabase.driver(
+        db_url,
+        auth=(
+            username,
+            password,
+        ),
+    )
+
+    mcp = create_mcp_server(neo4j_driver, database)
+
     healthcheck(db_url, username, password, database)
 
     mcp.run(transport="stdio")

servers/mcp-neo4j-cypher/test.sh

@@ -1 +1,3 @@
-uv run --env-file ../.env pytest tests/test_neo4j_cypher_integration.py
+docker compose -f tests/integration/docker-compose.yml up -d
+uv run pytest tests/integration -s 
+docker compose -f tests/integration/docker-compose.yml stop